Recommendation: GSI CLEP (v1)
Structured RPC protocol for chat and link messages that adds region-, prim-, and script-scope targeting; channel-separated domains; and cross-border routing support
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 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 Chat/Link_message Encoding Protocol (CLEP) is a protocol for flexible and targeted inter-script communication in Lua and Linden Scripting Language (LSL).
Lua-style syntax is used throughout this document, but all specifications also apply to the equivalent LSL functions and event callbacks.
CLEP defines a structured JSON message format sent over chat, link message, HTTP, or email. CLEP also defines a standardized method for converting strings into hashed negative integer channels for chat listeners. CLEP defines these channels as domains. It is RECOMMENDED to use unique domains wherever possible, such as prim UUIDs, to optimize server-side channel separation (see FAQ for details).
An outgoing CLEP message MUST be a JSON object with the following parameters:
| Key | Required? | Type | Value |
|---|---|---|---|
utime |
REQUIRED | os.time() in Lua llGetUnixTime() in LSL |
MUST be the Unix time when the message was created (marshalled). |
domain |
REQUIRED | string | MUST be any string signifying the CLEP domain. Listeners SHOULD drop messages that do not match a domain they are listening to. |
id |
REQUIRED | uuid cast as JSON string | MUST be ll.GenerateKey() or some other unique UUID. |
method |
REQUIRED | {string} | MUST be an array of any strings signifying a specific operation, such as {"File", "Write"}. Methods are canonically described using dot notation, such as File.Write. |
source -> region |
RECOMMENDED | string | If included, MUST be ll.GetRegionName(). If omitted, message SHALL NOT be forwarded via cross-region relays. |
source -> prim |
RECOMMENDED | uuid cast as JSON string | If included, MUST be ll.GetKey(). If omitted, message SHALL NOT be forwarded via any relays. |
source -> script |
RECOMMENDED | string | If included, MUST be ll.GetScriptName(). If omitted, message SHALL NOT be responded to. |
target -> region |
OPTIONAL | string | If included, MUST be the name of the region in which the targeted script(s) exist. If omitted, message SHALL NOT be target-routed via cross-region relays. |
target -> prim |
OPTIONAL | uuid cast as JSON string | If included, MUST be the uuid of the prim in which the targeted script(s) exist. If omitted, message SHALL NOT be forwarded via any relays. |
target -> root |
OPTIONAL | uuid cast as JSON string | If included, MUST be the uuid of the root prim of the linkset in which the targeted script(s) exist. SHOULD NOT be used in conjunction with target -> prim. |
target -> link |
OPTIONAL | number | If included, MUST be the link number or LINK_* constant targeting the prim(s) of the same linkset in which the targeted script(s) exist. MUST NOT be used in conjunction with target -> prim. |
target -> script |
OPTIONAL | string | If included, MUST be the name of the targeted script(s). |
params |
OPTIONAL | any | MAY be any valid JSON, such as a string, object, et cetera. |
result |
OPTIONAL | any | MAY be any valid JSON. If this message is a request (not a response), this pair MUST BE omitted. |
When CLEP messages are sent via chat, they SHOULD be sent on the channel generated by the CHUF as applied to the CLEP domain. In other words, the actual channel number SHOULD be derived by passing the domain string through the CHUF.
Why are channels hashed? Isn't it better to have a pre-shared channel?
See the CHUF specification for more information on channel hashing.
Is CLEP vulnerable to the Year 2038 problem?
LSL scripts will report a negative timestamp starting January 19, 2038 because LSL integers are 32-bit. There is currently no workaround for this in LSL. Lua scripts checking timestamps may need to compensate for Y2038-affected timestamps from LSL scripts, such as when verifying SNEP signatures, but Lua numbers are natively 64-bit and are not affected by Y2038.
This recommendation was authored by Nelson Jenkins on behalf of GSI.