Difference between revisions of "LSL Protocol/Restrained Love Open Relay Group/ORG Requirements/0004 draft"

From Second Life Wiki
Jump to navigation Jump to search
Line 139: Line 139:
* A controller MUST, for each Locked session it controls, 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.
* A controller MUST, for each Locked session it controls, 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.


==Core meta-commands==
==Core meta-commands and associated mechanisms==


This section describes meta-commands of the core protocol more precisely. This section may override general requirements above. Suported x-tensions may override both general requirements and this section.
An ORG relay MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.
 
Particular meta-commands definitions and mechanisms may override general requirements above.
 
===!release===
Sent by a controller, this command closes the session.
 
* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
      release,<controller_key>,!release,ok
 
When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.
 
Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.


===ping/!pong===
===ping/!pong===
Line 168: Line 183:


For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.
For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.
===!release===
Sent by a controller, this command closes the session.
* !release obviously opens no session, requires no Auth and is not Locking.
* If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
* On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
* When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
      release,<controller_key>,!release,ok
When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.
Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.


===!version===
===!version===

Revision as of 06:10, 27 June 2011

STATUS: draft

VERSION: 0004

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 metacommand and specifying Marine Kelley's RLVR protocol a bit more that it is now, while of course preserving full compatibility.

For a quick overview of the motivations and general working of this protocol and a few examples, we refer the reader to the original specification page by Marine Kelley.

If you are making furniture, traps, or other RLVR controllers and you are not interested in what optional ORG x-tensions can offer, then you can stick with the original specification by Marine Kelley and still be compatible with ORG relays. However, to have the right to call your controller "ORG compatible", there are still a few light additional requirements such as:

  • using only llRegionSayTo for communications with the relay,
  • not spamming the RLVR channel with messages that do not belong to the protocol,
  • and remain responsive to ping messages at every time if you want the session to remain locked.

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

If you are making a relay, sorry we are afraid you will have to read all this page.

Definition of an ORG device

A RLVR device is compliant with ORG specifications if it implements the consolidated RLVR protocol described below along with the optional ORG x-tensions it announces supporting.

Note in particular that

  • the consolidated protocol is backward compatible with Marine Kelley's RLVR protocol version 1.100 but resolves most loose ends of that document;
  • ORG relays handle controller messages 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);
  • one-to-one chat messages (not using a wildcard) are sent by using llRegionSayTo LSL function;
  • there is an additional meta-command, !x-orgversions for a relay to announce supported x-tensions;
  • each supported x-tension can imply other supported metacommands, ORG x-tensions meta-command all having names starting with prefix "!x-";
  • other proprietary metacommands with prefix "!_-" (replace "_" by any letter that is not "x") can be supported;

Supported x-tensions can constrain the core specification (this document) even more, but cannot alter it or make it less constraining unless as a result of the relay executing a meta-command of this x-tension sent by the controller. Thus, although the protocol is extensible, a controller can always rely on the fact an ORG relay abides by the requirements in this document until it asks the relay to do otherwise.

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.

Consolidated RLVR protocol

A few definitions

  • The Restrained Love Relay (RLVR) protocol implies two partners (SL objects): the relay worn by the avatar commands are intended for, and a controller, which sends commands to the relay.
  • During an execution of the RLVR protocol, a relay and a controller establish a session together. A relay may manage several sessions with several controllers. Likewise, a controller could establish sessions with several relays.
  • The goal of the protocol is to force the relay wearer to make perform actions and to toggle restrictions on their behavior. Both actions and restrictions can be enforced either through use of viewer hooks (Restrained Love API, or RLV) or through LSL scripting.
  • Hence we distinguish between "RLV commands", starting with "@", which are commands following the syntax of the RLV API and which will ultimately be forwarded to the viewer, and "meta-commands", starting with "!", which are meant to be interpreted by LSL functions.
  • Restrictions on a relay wearer are relative to a session. So are most other variables (authorization state, key of the controller, ... ).
  • A session is Opened whenever the relay accepts a RLVR command from a controller.
  • A session is Closed (or released) as soon as the relay forgets every variables and releases all restrictions pertaining to that session.
  • A session is Locked whenever it holds active restrictions.
  • A session is Authed if the controller has been allowed to control the relay (not only store some variables with no consequence). Once authed, no interactive "ask" dialog should pop up anymore concerning this session. Most commands should now normally be accepted (and maybe a few automatically rejected).
  • A controller is called reachable if it can receive messages from the relay and can prove it by answering ping requests from the relay. By "can", it is meant by the method of communication agreed upon by the relay and controller. By default the communication method is chat messages sent by llRegionSayTo. X-tensions such as email and delay can modify what is meant by reachable.

Reminder of the protocol syntax and related notations

RLVR protocol consists of messages exchanged on channel -1812221819 (called RLVR channel) using the LSL function llRegionSayTo.

A controller only sends messages (commands) whose syntax is described by the non-terminal <c_msg>. A relay only sends messages (acknowledgements) whose syntax is described by the non-terminal <r_msg>.

<c_msg> ::= IDENT "," KEY "," <commands>
<r_msg> ::= IDENT "," KEY "," <command> "," ACK
<commands> ::= <command> | <command> "|" <commands>
<command> ::= <rlvcommand> | <metacommand>
<rlvcommand> ::= "@" RLVCOMMAND
<metacommand> ::= "!" METACOMMANDNAME <metacommandarguments>
<metacommandarguments> ::= "" | "/" ARG <metacommandarguments>

where we explicit the different terminal tokens:

IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

Relay requirements

These requirements do apply by default but the behavior of the relay may be modified as a result of having executed some metacommand defined in an optional x-tension.

Syntactical considerations

Requirements:

  • 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 and considering the 3rd item of the ","-list as a "|"-list of <command>s, then for every <command>:

  • if the <command> is neither a valid <rlvcommand> or <metacommand>, the relay must ignore it and process the next <command>'s;
  • if the <command> is a <rlvcommand> or a <metacommand>, the relay MUST send an acknowledgement message back to the controller.
  • an acknowledgement message is a <r_msg> (see above) such that
  • IDENT is the same as IDENT in the <c_msg> being processed
  • KEY is the key of the controller who sent the <c_msg>
  • <command> is the subcommand being processed
  • ACK is a string called acknowledgement value. By default the acknowledgement value is "ok" if the relay will execute the <command >, "ko" otherwise;
  • 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) using the LSL function llRegionSayTo.


Remarks:

  • Many meta-commands may have other acknowledgements than "ok" or "ko" (or none, for !pong). Their definitions supersede this specification.
  • Note that unknown meta-commands cannot be executed and thus wil be acknowledged by "ko".
  • Known meta-commands which are sent with not enough parameters or parameters with types incompatible with those in the definition known by the relay also cannot be executed and will also be acknowledged by "ko". (ex: the relay knows !x-who/key, but receives !x-who/integer/string).

Command handling

Requirements:

  • If a <rlvcommand> is acknowledged with value "ok", the relay ensures the viewer is affected the same way as if the LSL instruction llOwnerSay(<rlvcommand>) was executed by a script in a primitive that handles only one controller.
  • When processing a <metacommand>, if the relay knows at least one definition of '!'+METACOMMANDNAME for which the received <metacommandarguments> provide enough parameters, then it will be handled according to the definition handling the most parameters among the latter. Extra parameters are ignored.
  • When acknowledging a <metacommand> by anything else than "ko", the relay commits itself to execute it.

Remarks:

  • For first requirement, it must be understood that the reference behavior is that the relay would have if it had one controller per prim. However handling several controllers from one unique prim is possible but requires taking care that different controllers do not interfere with each other, releasing each other's restrictions, for instance.
  • For the second requirement, the word "handled" means that if the meta-command with these parameters is known, then requirements in known definition cannot be ignored. Sometimes, this can imply that the meta-command cannot be refused, for instance.

Session related requirements:

  • Closing a session clears all RLV restrictions that belong only to that session, clears all session variables and disables all behaviors relative to that session.
  • Sessions that are not locked MUST be released after a reasonable timeout.
  • Relay implementations MAY require an authed session for all <rlvcommand>'s, except @xxx=<channel_number>, @clear[=xxx] and @xxx=y/rem commands, which MUST always be accepted.
  • @xxx=n/add <rlvcommand>'s, after being accepted, add a restriction and therefore Lock the session.
  • Some metacommands described in x-tensions can also add restrictions and therefore Lock the session.
  • !release, !version, !implversion, !x-orgversions and !x-.../clear[/...] commands are always accepted.
  • !pong reactivates an existing session but never requires further auth, provided it is sent by the device to which ping was sent. The relay MUST resend to the viewer all stored restrictions belonging to the controlling device if they are not already active.
  • Unless specified otherwise (see !x-who), no command can trigger an interactive dialog unless
  • they require an Authed session
  • and no session is currently open or it is open but not Authed yet.
  • When releasing a Locked session, a relay MUST release all restrictions belonging to the device controlling the session.
  • On the following events, a relay MUST release a locked session:
  • when the relay notices the controller has become unreachable,
  • wren the relay sends "release,<controller_key>,!release,ok" (due to acknowledging !release sent by the controller, or due to safewording triggered from the relay side).
  • A relay MUST provide a mechanism for checking that every controlling device is reachable. It is not specified whether this checking process should be automatic or manually triggered.
  • The absence of active restriction unlocks the session (and eventually releases it).
  • A relay MUST remove restrictions from a session when (and only in these cases):
  • either the session controller specifically asks for the restriction to be released ("@restriction=y" "@restriction=rem", "@clear=restriction" for RLV restrictions, and "!x-restriction/clear/..." for LSL restrictions),
  • or the session closed (for instance !release coming from the device, or safeword).

Controller requirements

  • A controller MUST not send anything on RLVR channel that is not a valid <c_msg>.
  • A controller MUST, for each Locked session it controls, 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.

Core meta-commands and associated mechanisms

An ORG relay MUST at least support the meta-commands !release, !pong, !version, !implversion and !x-orgversions described below and implement their associated mechanisms.

Particular meta-commands definitions and mechanisms may override general requirements above.

!release

Sent by a controller, this command closes the session.

  • !release obviously opens no session, requires no Auth and is not Locking.
  • If there is an actual session to close !release MUST be accepted by the relay and acknowledeged by "ok".
  • On accepting !release, the relay erases all data pertaining to the session and disables all restrictions of the session.
  • When a relay decides to close a session on its own (user safeword, for instance) and it is not due to the controller being unreachable, the relay must send the following acknowledgement message:
      release,<controller_key>,!release,ok

When receiving the latter message, the controller should act accordingly, for instance by resetting itself and making itself ready for the next session.

Note that !release is not the same as @clear. @clear is interpreted by the relay as a RLV command and, as such, can only clear RLV restrictions. If RLV restrictions were the only restrictions of the session, then the session will be closed, but some x-tensions also define pure LSL based restrictions.

ping/!pong

The ping/!pong mechanism exists so that relays can check presence and responsiveness of a controller. This was primarily meant to be used on relay wearer relog, in order to reactivate all restrictions so that sessions persist on relog if the controller still exists and is ready to continue the session.

!pong cannot require auth and does not lock a session

We call ping message a message from the relay, having the following syntax:

ping,<controller_key>,ping,ping

We call !pong message a message from the controller, having the following syntax:

ping,<relay_key>,!pong

Relay side

  • A relay SHOULD NOT send an acknowledgement in response to !pong.
  • A ping message can be sent any time by the relay to a known controller (in contrary to other acknowlegement messages that are always replies to controller commands).
  • On wearer relog, for each existing Locked session, the relay must send a ping message to the session controller.
  • When a !pong message is received from a controller, if it was a reply to a previous ping message:
  1. if the session RLV restrictions contain unsit and the avatar was sitting on some object when the restriction was applied, then the relay MUST force the avatar to sit back on the same object (if still existing);
  2. the relay MUST make sure all restrictions belonging to the session are made active again.
  • If a ping message is sent and is not answered by the controller, then the relay closes the session.

Controller side

  • Unless it does not matter that the relay could close the session (or for another reason, the controller knows the relay will not close it), a controller SHOULD listen to ping messages and answer any ping message with a !pong message.
  • A controller should ignore ping requests from relays it is not ready to handle.

For instance, if the controller is a furniture which is already in use by another relay wearer, it would be inconsistant to let the pinging relay restore the restrictions without letting its wearer sit on the furniture. Or if the controller is not stateless and the state for the pinging relay has not been saved before, resuming the session from the initial state might be inconsistant.

!version

The purpose of this meta-command is to query the version of the RLVR protocol supported by a relay.

  • !version opens no session (and requires no auth, neither can lock a session)
  • A relay MUST always acknowledge !version with the version number of the RLVR protocol it supports ("1100" here, since ORG 0004 includes RLVR 1.100).

Note this is the most common command for a controller to scan for nearby relays, as non-ORG relays also accept this command and answer it the way described above.

!implversion

The purpose of this meta-command is to query the name and version of the relay implementation.

  • !implversion opens no session (and requires no auth, neither can lock a session)
  • A relay MUST always acknowledge !implversion with its implementation version string... which can be any string.

It is recommended this string includes the following elements:

  • the relay name/brand/identifier,
  • the version number of that relay name/brand/identifier,
  • at the beginning, the string prefix "ORG=0004/"

The latter is convenient for checking for ORG compatibility using a command even non-ORG relay should understand.

!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=0004/who=002/email=006

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 metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

Requirements for a relay:

  • The support of this metacommand 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.
  • If several incompatible versions of an x-tension are supported, they must be listed ordered by version number. Ex: ORG=0004/who=002/email=005/email=006. If versions are backward compatible, it is necessary to report only the last one.

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