MetaCrate/crates/libremetaverse-rlv/README.md

Native RLV protocol layer

libremetaverse-rlv implements the protocol and pure state boundary for the Restrained Love Viewer support in the pinned LibreMetaverse snapshot. The side-effect-free parser converts one bounded chat message into typed commands. Independent, thread-safe managers then store restrictions and evaluate inventory, folder locks, camera limits, blacklists, and permissions without performing network I/O. Command execution, viewer callbacks, replies, and GridClient integration remain separate milestone work that consumes this layer.

Message contract

An input begins with @ and contains at most 128 comma-separated commands in at most 64 KiB. A command is either the case-insensitive bare clear command, or has the form behavior[:option]=parameter. The first colon and first equals sign are structural. Empty commands, behavior names, or parameters are rejected.

The parser preserves the original behavior and parameter spelling, option text, sender identity and name, and the exact byte span of each command. It also provides lowercase behavior and parameter fields for protocol dispatch. Option text is never globally trimmed or lowercased: folder paths, query separators, setting values, role names, and other opaque strings retain their bytes. Only an individual typed field applies the conversion required by the reference, such as case-insensitive attachment aliases or .NET-style whitespace trimming for a number.

Parameters select one of three families:

• force produces a typed RlvAction with validated UUID, numeric, folder, attachment, wearable, setting, group, and teleport operands.
• n/add and y/rem produce typed add/remove restrictions. The complete table of 119 behavior spellings is exposed as RLV_RESTRICTION_NAMES.
• a nonzero signed decimal channel produces a typed RlvQuery, including camera, inventory, outfit, path, status, version, group, and environment variants.

Aliases remain explicit. FarTouch canonicalizes to TouchFar in a mapped RlvRestriction, while OriginalBehavior retains FarTouch. The 56 pinned attachment spellings and 16 wearable spellings are case-insensitive but are not whitespace-normalized. root maps to the avatar-center attachment point, matching the reference. Secure restriction exception rules and value-sensitive equality/hash behavior are implemented by the native mapped RlvRestriction; RlvCommon implements the last-recognized attachment tag rule used for inventory item names.

Errors and resource limits

RlvParseError reports a stable RlvParseErrorKind, zero-based command index, and half-open byte span. Categories distinguish missing prefix or separators, empty fields, unknown actions/restrictions/queries, invalid UUIDs, numbers and typed options, zero query channels, and resource-limit failures. Parsing is linear in the message size after bounded command counting. It performs no I/O, does not wait, and does not retain references to caller input.

The focused malformed corpus includes deterministic deletion, replacement, and insertion mutations of actions, restrictions, queries, UUIDs, aliases, and multi-command messages. Every mutation must return a value or a positioned error without panicking. The limits apply before large parser allocations.

State, inventory, and permission contract

RlvSharedFolder and RlvInventoryItem preserve the reference semantics of their C# counterparts. InventoryMap walks a bounded shared-inventory tree and publishes immutable dictionary/list membership snapshots. Path lookup handles hidden/private prefixes, exact names containing forward slashes, and the reference implementation's longest matching segment rule. Lookup by item, attached prim, attachment point, and wearable type does not call a client or inventory service.

RlvRestrictionManager deduplicates exact restrictions, retains deterministic insertion order, removes all state for selected object sources, and rebuilds immutable locked-folder snapshots when either restrictions or inventory changes. Recursive and non-recursive attach/detach locks support sender-item, attachment, wearable, and path targets plus their exception variants. Update handlers run only after manager locks are released, so callbacks can safely query the manager again. Poisoned synchronization primitives recover their owned state instead of making later reads fail.

RlvPermissionsService evaluates simple restrictions, secure and explicit target rules, permissive exception precedence, IM/chat/channel behavior, teleport limits, edit/touch/hover decisions, shared and unshared wear, and folder attachment locks. Camera aggregation applies the reference min/max, clamping, averaging, alias, texture, and lock rules. The case-insensitive blacklist returns a sorted snapshot. These providers are deterministic, thread-safe, and contain no network or callback dependencies.

Reproducible verification

Run the issue-owned checks with one build job:

CARGO_BUILD_JOBS=1 cargo test -p libremetaverse-rlv --locked
CARGO_BUILD_JOBS=1 cargo test -p libremetaverse-compat-tests --test rlv_common_semantics --locked
CARGO_BUILD_JOBS=1 cargo test -p libremetaverse-compat-tests --test rlv_inventory_map_semantics --locked
CARGO_BUILD_JOBS=1 cargo clippy -p libremetaverse-rlv --all-targets --locked -- -D warnings
RUSTDOCFLAGS='-D warnings' CARGO_BUILD_JOBS=1 cargo doc -p libremetaverse-rlv --no-deps --locked
python3 tools/check_milestone_10_issue_78.py
python3 tools/check_milestone_10_issue_79.py

These commands are cross-platform. The Gitea workflow runs the audit and workspace compile on ubuntu-latest.