MetaCrate/crates/libremetaverse-rlv/README.md

Native RLV protocol layer

libremetaverse-rlv implements the side-effect-free protocol boundary for the Restrained Love Viewer support in the pinned LibreMetaverse snapshot. The parser converts one bounded chat message into typed commands. It does not mutate restrictions, move the camera, touch inventory, send replies, or invoke callbacks; those stateful responsibilities are 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.

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 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

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