LSL Protocol/Restrained Love Open Relay Group/ORG Requirements

STATUS: ready

VERSION: 0003

Summary

This page is a list of requirements for a relay or an in-world device to have the right to be called "ORG compliant". It is mostly about adding support for an ORG-centered informational meta-command and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

If you are making in-world devices and are not interested in optional ORG x-tensions, you can skip most of this page, as your requirements amount to the following:

Do not let your device spam the RLVR channel with commands that are not syntactically correct with respect to RLVR protocol.
Never let your device be stuck in a state where no future event can unlock a currently locked relay.

If you are interested in ORG x-tensions, then you should also read the part about !x-orgversions.

If you are a relay maker, sorry we are afraid you will have to read all the page!

Definition of an ORG device

A RLVR device is compliant with ORG specifications if

it implements Marine Kelley's RLVR protocol version 1.100
it handles rely commands whose second field is ffffffff-ffff-ffff-ffff-ffffffffffff exactly the same as if it was the key of the wearer (NULL_KEY is a wildcard)
it implements the !x-orgversions meta-command as defined below
it implements the protocol fixes below
all meta-commands it supports are of the following types:

meta-commands in RLVR protocol, behaving as described in RLVR specifications
meta-commands, whose names start with "!x-", behaving as described in ORG specifications
proprietary or experimental meta-commands, whose names start with "!_-" (replace "_" by any letter that is not "x")

Note that as soon as a RLVR controlling device makes use of a command defined in an ORG x-tension, then the specification of this x-tension MAY override one or several requirements of the core specification (this document). An x-tension that is not triggered by a specific command that it defines can only add more constraints, never override existing requirements. Indeed a controlling device has no way to know what requirements an unknown x-tension could override.

ORG devices may be advertised by the use of the ORG logo for advertising compliance with ORG requirements. ORG devices makers are encouraged to do so.

!x-orgversions

This meta-command purpose it two-fold. First it allows a controlling device to ask a relay for the list of ORG x-tensions it supports, second it is similar to !version in RLVR protocol, as its reply gives the versions of the ORG core specification and ORG x-tensions that are implemented in the relay.

C<->R
  ->   query,rUUID,!x-orgversions
 <-    query,cUUID,!x-orgversions,ORG=0001/who=001/email=005

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several meta-commands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

Requirements for a relay:

The support of this meta-command is mandatory for an ORG relay.
It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.

Requirements for a controlling device: None. It is however recommended to use !x-orgversions when it makes sense for avoiding sending unsupported and useless meta-commands later.

ORG RLVR fixes

Marine Kelley's specification for RLVR protocol gives too much room for interpretation and incompatibilities between supposedly compliant devices. This is why in this section we add further requirements for RLVR+ORG devices.

Preliminaries/Reminders

Here we establish some notations related to RLVR protocol.

Here is the RLVR device message grammar (as it already is, nothing new):

<r_msg> ::= IDENT','KEY','<command>','ACK;
<d_msg> ::= IDENT','KEY','<commands>;
<commands> ::= <command> | <command>'|'<commands>;
<command> ::= <rlv-command> | <meta-command>;
<rlv-command> ::= '@'RLV-COMMAND;
<meta-command> ::= '!'META-COMMAND_NAME<meta-command arguments>;
<meta-command arguments> ::=  | '/'ARG<meta-command arguments>;

where the following tokens were used:

IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLV-COMMAND: any string without ","
META-COMMAND_NAME: any string without "/" and ","
ARG: any string without "/" and ","

Furthermore we give the following definitions:

A controlling device is always considered to be "reachable" if it is within shout range of the relay, as long it does not fail to answer a ping request from the relay. A controlling device is usually considered to be "unreachable" if it is out of shout range of the relay, but x-tensions such as !x-email or proprietary enhancements may modify the notion of "unreachability".

The following actions are considered locking a relay:

a restricting command followed by a "ok" acknowledgement
a ping/pong exchange with this relay

The following actions are considered unlocking a relay:

the controlling device becoming unreachable.
the relay sends "release,KEY,!release,ok"
the controlling device sends a !release

A relay is locked by a controller if their last interaction of the above types was locking.

General Relay requirements

The relay must behave the following way by default (unless at some point a meta-command explicitly requires another behavior):

A relay MUST provide a mechanism for checking that every controlling device is reachable, and releasing it if it is not. It is not specified whether this checking process should be automatic or manually triggered.
A relay MUST NOT send anything on RLVR channel that is not a valid <r_msg>.
A relay MUST ignore any message on RLVR channel that is not a ","-list of 3 items and whose second item is not the key of the avatar wearing the relay or ffffffff-ffff-ffff-ffff-ffffffffffff.
When the relay receives a message meeting the above conditions, considering the 3rd item as a "|"-list of <command>s, then for every <command>:

if the <command> is a <rlv-command>, the relay MUST acknowledge it, either by "ok", and transmit the command as such to the viewer with llOwnerSay("@"+RLV-COMMAND), or by "ko" and not transmit it.
if the <command> is a <meta-command>

if the META-COMMAND_NAME is !pong, no acknowledgement is expected. The relay MUST reinstate all stored restrictions belonging to the controlling device if they weren't already active.
if the META-COMMAND_NAME is unknown or is not provided with enough arguments for at least one definition of the meta-command, the relay MUST acknowledge by "ko"
else if the relay knows the META-COMMAND_NAME with at least one definition having less or as many arguments as received in <meta-command arguments>, it MUST acknowledge it by "ok" and choose among possible definitions the one that uses the most arguments. Then if the number of arguments of this definition is n, it MUST execute it using only the n first arguments of <meta-command arguments>, ignoring the trailing arguments if any.

if the <command> is neither, then the relay MUST ignore it (no acknowledgement whatsoever)
every acknowledgement or message sent by the relay to one given controlling device must be issued by the same prim (so that the controlling device can restrict its listener to one source key)

A relay MUST release all restrictions belonging to a controlling device when an unlocking action relative to this device happens (whether if it is just before or just after is irrelevant, as long as the relay does not wait for any further event).
A relay MUST never release a restriction outside one of those 2 cases:

the controlling device the restriction comes from specifically asks for the restriction to be released ("@restriction=y", "@clear=restriction")
the relay is being unlocked with respect to the device the restriction belongs to (for instance !release coming from the device, or safe-word)

General controlling device requirements

A controlling device MUST not send anything on RLVR channel that is not a valid <d_msg>.
A controlling device MUST, at any time when a relay is locked, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.