LSL Protocol/Restrained Love Open Relay Group/http-in

= !x-http =
STATUS: in writing, DO NOT USE IT!
VERSION: 001
Draft1 implemented in Satomi's Multi-Relay HUD 1.00pre, and Satomi's Witchy Remote 1.2pre
Initiate an http-in encapsulated RLVR session.
On ok'ing an !x-http, the relay should make sure it has an LSL http server running, responding as described below. The command should be ignored (or ko'd) by older relays.
Other commands used in this protocol: !x-channel. Full support for !x-channel is also strongly recommended for !x-http support.
==HTTP encapsulation==
Assuming <relay_url> is the url of the relay, the relay controller will send encapsulate requests to the relay through HTTP by sending HTTP requests using method POST, with the following address: <relay_url>?<identifier>,<RLVR command>. Everything after "?" has to be escaped with llEscapeURL. The relay should of course decode the request with llUnescapeURL before handling the RLVR command.
The relay answers (llHTTPResponse, using the same key as the one in the previous http_request event) with a body constituted of lines that are:
* either a RLVR standard response (only without the recipient key): <identifier>,<RLVR command>,<ack> for a relay message.
* or a RL viewer answer (for instance an answer to a @getstatus or @version): <channel>,<viewer answer>
==Protocol scenarii==
Conventions: messages are symbolized by different types of arrows. We suppose the controller (C) is on the left and the relay (R) on the right. An arrow with a c (-c>) is a chat message on RLVR channel (or whatever channel the controller and the relay negotiated before). A right arrow with a h (-h>), is the message after the "?" in a the HTTP request URL from the controller. A left arrow with a h (<h-) is one line in the body of a reply from the relay to the controller HTTP request.
 C(ontroller)<->R(elay)
===HTTP session initiation protocol===
This protocol establishes an authentified http session and transfers whatever restrictions C already had on R if any.
 1 -c> blah,k(R),!x-http
 2 <c- blah,k(C),!x-http,http://sim8867.agni.lindenlab.com:12046/cap/07307f17-dee4-bb85-04c7-340cdfade115/RLVR
Comments:
* After 2, the relay is ready to initiate the session (it is listening to http requests)
* All the complicated auth stuff from x-email has been removed. Hopefully LL will provide a way to check whether an http request really has been made by a precise in-world object (as it is now, HTTP headers can be faked). Let us keep the protocol simple for now, and keep in mind that somebody determined enough could exploit it (but is it worth it?).
===Relaying viewer chat messages:===
 ( -h> bloh,@getxxxx=1234
 <h- bloh,@getxxx=1234,ok )
 <h- 1234,<chat_message>
===Ending HTTP session and going to chat===
 -h> blih,!x-channel/-12345
 <h- blih,!x-channel/-12234,ok
Both relay and controller have to check that their recipient is in chat range. The controller before even trying. The relay before acknowledging. If the latter fails, then the relay should answer:
 <h- blih,!x-channel/-12234,ko
===Testing controller's presence===
For garbage collection purposes, be it on relog, or on regular basis, R might want to check if C is still active. The ping mechanism can be used here.
 <h- ping,ping,ping
 -h> ping,!pong
C can check R's presence by sending any valid message, as acknowledgement by R is required for every RLVR message from C. If the only purpose of the message is presience verification, the following scenario is recommended:
 -h> blah,!x-http
 <h- blah,!x-http,<anything>
===Handover===
!x-handover/K/n should work like in chat session.
===Handing over to self when teleporting===
Use case: the controller is a portable device, like a RLV remote. How can restrictions be carried over when the wearer is teleporting, whereas the key of the controller changed?
Email extension uses a virtual session key instead of the object actual key and appends this key to every message. That could be done here.
Maybe this could also be made optional and more explicit having the !x-handover define a session key to hand commands over to, and a new !x-takeover command taking this key as an argument, telling the relay to complete the handover to the device issuing !x-takeover.
===The relay wearer teleports===
In the current spec, the relay cannot start sending messages to the controller on its own and notice it it has a new URL.
Current implementation of the remote relies on an external pseudo-DNS to retrieve the new relay URL if the previous one does not work anymore.
An alternative would be to have the controller open its own LSL HTTP-IN server on which the relay could post.
==Requirements==
* On !x-http acknowledgement, the relay should start listening to http requests and handle them like RLVR messages.
* Whenever the relay accepts a RLV command with calls for a viewer answer (@blah=1234), the relay must listen to the viewer answer, and forward it via http response to the controller.