Recommendation: GSI LEP (v1)
Hierarchical request-response protocol for LSL link_message events
The Global Scripting Institute (GSI) is an informal organization of Second Life® users that design and test standards for efficient, flexible, and readable scripts in Second Life. "Second Life®" and "Second Life Grid™" are trademarks of Linden Research, Inc., d/b/a Linden Lab. The Global Scripting Institute and its catalog are not affiliated with with or sponsored by Linden Research.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The link_message Extension Protocol (LEP) is a message protocol for llMessageLinked/link_message in Linden Scripting Language (LSL).
LEP transmits messages that meet the following criteria:
LEP uses llMessageLinked to pass a set of bitwise flags as an integer; a list prepended with a structured metadata header, dumped to a string; and a string of arbitrary data, cast to a key. LEP takes advantage of an intentionally-maintained bug in llMessageLinked that allows any string, including non-UUIDs, in the key parameter.
The flags and metadata included in each LEP message permits other scripts to identify the source, target, and type of message to rapidly discard unwanted link_message events.
LEP messages MUST be constructed as follows:
llMessageLinked( target_link, flags, llDumpList2String( [ llGetScriptName(), target_script ] + parameters, "\n" ), data );
| Placeholder | Type | Description |
|---|---|---|
target_link |
integer | MUST be the target link number or any LINK_* constant. |
flags |
integer | MUST be all message flags applicable to the message, combined using bitwise OR. |
target_script |
string | MUST be one of the following:
|
parameters |
list | MUST be a hierarchical series of commands and/or parameters (for example, ["file", "open", "somefile.txt"]). The list MUST NOT contain any newline ("\n") characters. A hierarchical list is used here in lieu of arbitrary data so that recipients can quickly route the message through an if-else or if-return tree for better organization and performance. |
data |
string | MAY be any value. |
Valid flags:
| Name | Value | Description |
|---|---|---|
| TYPE_REQUEST | 0x1 | Requests that the target send a response. Recipient SHOULD respond with TYPE_RESPONSE. |
| TYPE_RESPONSE | 0x2 | If a script is responding to a TYPE_REQUEST message, it MUST include this flag and MUST NOT include TYPE_REQUEST. If this flag is included, the sender SHOULD use the same parameters as the request's so that the requester can clearly understand what the response is to. The sender MAY, however, append additional elements to the end of parameters with response data, if desired. |
| STATUS_ERROR | 0x4 | If a script is responding to a TYPE_REQUEST message, it SHOULD include this flag if the request was nominally unsuccessful for any reason. If this flag is included, the sender MUST prepend a string element to the start of parameters. This string MUST be one of the following:
|
Implementations MAY create constants (ideally preprocessor constants) to use these flags; names are provided for reference later in this recommendation.
LEP-aware scripts MUST process incoming link_message events by running the below checks. If a check fails, the script SHOULD immediately release the event with return to reduce script time (or run additional code to interpret non-LEP messages). The script MAY log this dropped message.
flags contains required flags (for example, if the script only needs to process errors, check that flags & STATUS_ERROR).list of at least 2 elements.list is the name of a known script.list is contained in the recipient script's name (for example, a script named "New Script" would accept "Scr" by checking that llSubStringIndex( llGetScriptName(), llList2String( list, 1 )) != -1).After a message passes these checks, recipient SHOULD process the message as desired. For performance, it is RECOMMENDED to iterate through the remaining elements of list, if any, through an if-else or if-return tree.
I need to pass a newline in the parameters list. Can I use a different llDumpList2String separator?
The implementation MUST use "\n" to be in compliance with the LEP specification.
Why doesn't LEP use the CLEP Message Serialization Function?
Processing serialized lists is slow. LEP is designed to prioritize fast message metadata processing.
Why is the metadata added to the string instead of the key?
Typecasting is not free. If the message is discarded while processing the metadata, data is never typecast from key to string.
LEP was authored by Nelson Jenkins on behalf of GSI.