Revision as of 06:57, 11 January 2014

LSL Portal

Introduction

This is the counterpart to llHTTPRequest. While llHTTPRequest enables LSL scripts to request data from HTTP-accessible sources, HTTP-in enables outside sources to request data from LSL scripts in Second Life. The key difference is that llHTTPRequest exchanges data when the script in SL wants; HTTP-in allows outside sources to determine when they need to communicate with LSL scripts in SL.

Prior to HTTP-in, similar functionality could be achieved by polling with llHTTPRequest, llEmail and XML-RPC. All three are cumbersome and the latter two have serious scalability bottlenecks.

It is important to note that LSL HTTP servers cannot use llSetContentType with CONTENT_TYPE_HTML for an llHTTPResponse except in very limited circumstances. See Other Limitations for details.

Uses

Easily get data from LSL scripts to outside viewers, LSL scripts or servers.
- Web front end for a visitor counter or other statistics accumulator.
Easily get data into LSL scripts from outside viewers, LSL scripts or servers.
- A store with a web front end that communicates to an in-world object to exchange L$ and inventory items.
- Inworld game for which an external program handles the primary game logic that needs to manipulate inworld items.
HUD UI when used with llSetContentType. See HTML HUD Demo.

Gory Technical Details follow. Or jump straight to the Script Examples.

Script API

Events

http_request(key id, string method, string body)

Event triggered when an URL is hit:

id is unique to this request
Supported methods are "GET", "POST", "PUT", "DELETE"
body: The body of the request.

Event also triggered with response to llRequestURL and llRequestSecureURL

id matches the key returned by llRequestURL or llRequestSecureURL
method == URL_REQUEST_GRANTED for success, URL_REQUEST_DENIED for failure to get an URL
body is the public URL. If unable to get a public URL body will be empty.

changed(integer change)

CHANGED_REGION_START: New changed event triggered on region startup.
CHANGED_REGION: New changed event triggered when crossing regions or teleporting. Please read CHANGED_REGION for more info.
CHANGED_TELEPORT: New changed event triggered when the avatar teleports. Please read CHANGED_TELEPORT for more info.

Functions

Function: key llRequestURL( );


345	Function ID
0.0	Forced Delay
10.0	Energy

Requests one HTTP:// url for use by the script. The http_request event is triggered with the result of the request. HTTP-in uses port 12046.
Returns a key that is the handle used for identifying the result in the http_request event.

Function: key llRequestSecureURL( );


346	Function ID
0.0	Forced Delay
10.0	Energy

Requests one HTTPS:// (SSL) url for use by the script. The http_request event is triggered with the result of the request. HTTPS-in uses port 12043.
Returns a key that is the handle used for identifying the result in the http_request event.

Function: llReleaseURL( string url );


347	Function ID
0.0	Forced Delay
10.0	Energy

Releases the specified URL, it will no longer be usable.

• string

url

–

URL to release

Function: llHTTPResponse( key request_id, integer status, string body );


348	Function ID
0.0	Forced Delay
10.0	Energy

Responds to request_id with status and body.

• key	request_id	–	A valid HTTP request key
• integer	status	–	HTTP_Status (200, 400, 404, etc)
• string	body	–	Contents of the response.

The response need not be made inside the http_request event but if it does not happen in a timely fashion the request will time out (within 25 seconds).

Function: integer llGetFreeURLs( );


344	Function ID
0.0	Forced Delay
10.0	Energy

Returns an integer that is the number of available URLs.

Function: string llGetHTTPHeader( key request_id, string header );


349	Function ID
0.0	Forced Delay
10.0	Energy

Returns a string that is the value for header for request_id.

• key	request_id	–	A valid HTTP request keyA valid HTTP request key
• string	header	–	Lower case header value name

Returns an empty string if the header is not found or if the headers can no longer be accessed. Headers can only be accessed before llHTTPResponse is called and with-in the first 30 seconds after the http_request event is queued.

Generated Headers

These headers are automatically generated by the simulator, they were not actually sent by the requesting client. They supply information about the request to make parsing easier.

Sample URL: https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/foo/bar?arg=gra

header	description	example
"x-script-url"	The base url, as originally received from llRequestURL/llRequestSecureURL	https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322
"x-path-info"	Any trailing path information from the requested url	/foo/bar
"x-query-string"	Any query arguments, the text past the first "?" in the url	arg=gra
"x-remote-ip"	IP address of the host that made the request

Common Headers

header	description	example
"user-agent"	The user-agent header as reported by the requester

llHTTPRequest Headers

Headers sent by the simulator in the course of calling llHTTPRequest.
Header	Description	Example data
connection	Connection options	close
cache-control	Maximum response age accepted.	max-age=259200
x-forwarded-for	Used to show the IP address connected to through proxies.	127.0.0.1
via	Shows the recipients and protocols used between the User Agent and the server.	1.1 sim10115.agni.lindenlab.com:3128 (squid/2.7.STABLE9)
content-length	The size of the entity-body, in decimal number of octets.	17
pragma	The message should be forwarded to the server, even if it has a cached version of the data.	no-cache
x-secondlife-shard	The environment the object is in. "Production" is the main grid and "Testing" is the preview grid	Production
x-secondlife-region	The name of the region the object is in, along with the global coordinates of the region's south-west corner	Jin Ho (264448, 233984)
x-secondlife-owner-name	Legacy name of the owner of the object	Zeb Wyler
x-secondlife-owner-key	UUID of the owner of the object	01234567-89ab-cdef-0123-456789abcdef
x-secondlife-object-name	The name of the object containing the script	Object
x-secondlife-object-key	The key of the object containing the script	01234567-89ab-cdef-0123-456789abcdef
x-secondlife-local-velocity	The velocity of the object	0.000000, 0.000000, 0.000000
x-secondlife-local-rotation	The rotation of the object containing the script	0.000000, 0.000000, 0.000000, 1.000000
x-secondlife-local-position	The position of the object within the region	(173.009827, 75.551231, 60.950001)
user-agent	The user-agent header sent by LSL Scripts. Contains Server version.	Second Life LSL/16.05.24.315768 (http://secondlife.com)
content-type	The media type of the entity body.	text/plain; charset=utf-8
accept-charset	Acceptable character sets from the server. Q being the quality expected when sending the different character sets.	utf-8;q=1.0, *;q=0.5
accept	Media types the server will accept.	text/*, application/xhtml+xml, application/atom+xml, application/json, application/xml, application/llsd+xml, application/x-javascript, application/javascript, application/x-www-form-urlencoded, application/rss+xml
accept-encoding	Acceptable content encodings for the server.	deflate, gzip
host	The internet host being requested.	secondlife.com
^{CGI environments may place the headers into variables by capitalizing the entire name, replacing dashes with underscores, and prefixing the name with "HTTP_", e.g. "x-secondlife-object-name" becomes "HTTP_X_SECONDLIFE_OBJECT_NAME". HTTP header names are case insensitive [1]. Some ISPs may modify the case of header names, as was seen in BUG-5094.}

URL Lifetime Limitations

URLs are temporary!
URLs will be lost in the following cases, all detectable by the script events listed with them.
- On object derez/rez: on_rez
- On script save/reset: default state_entry (trickier in multi-state LSL scripts)
- On region cross or TP(attachments): changed event, CHANGED_REGION and CHANGED_TELEPORT. Testing this have it has been found that teleports within a region DO NOT cause a URL to be lost, therefore, you do not need to request a new URL on CHANGED_TELEPORT, because CHANGED_REGION will handle a teleport to a different region. If you choose to request a URL after a teleport, it is recommended to release the old URL to be sure you don't have too many used. (Stone Tremont Aug 8th 2010)
- On region restart: changed event, flag CHANGED_REGION_START
When urls are 'lost' it means that all public urls for that script are gone, new ones will need to be requested and the new urls will not resemble the old ones.
Maintaining persistent URLs will require building or using an external service similar to how Dynamic DNS services work for tying domain names to dynamic IP addresses.

Contributed HTTP-in URL mapping implementations and services:

A Dynamic DNS service running on Google App Engine (contributed as an example) can be found in the forums here.
Yet another one, running on GAE, with password protected and private domains. http://wiki.secondlife.com/wiki/Public_Object_DNS
The SilverDay ObjectDNS is an easy to use dns-mapping-service with many configurable options (password protection, write protection, etc.) and an optional web-interface. The LSL scripts are available here on the wiki (LSL-Script Library/Silverday ObjectDNS).

Resource Limitations

There are a limited number of URLs available in each region, split by land ownership exactly like prim limits.
- Use llGetFreeURLs to get the exact number of available URLs for the script.
- The number of allowed URLs is the same as the number of allowed prims on the parcel the object is over.
  Object owner does not matter, all objects over a parcel will use the resource pool for that parcel.
  
  Like prims, all the parcels owned by the same owner and in the same region share the same pool of resources.
  
  If you have two parcels in a region that each support 100 URLs, then you could use all 200 in object(s) on a single parcel.
- The region's object bonus factor does not apply to available URLs.
  If a parcel has a max of 300 prims in a region with a 2x bonus factor there will only be 150 urls allowed.
Each resident has their own unique pool of available URLs with a max of 38 URLs per resident.
- This is 1 per attachment point, but all 38 could be used by a single attachment for example.
Vehicles are special and lazily moved to resident pools by the following logic:
- Any object that has a resident sitting on it is a 'vehicle'
- Vehicles will use the url resources from the parcel they are over until the cross a parcel border.
  Specifically this prevents anyone from breaking your vending machine by sitting on it and making it a 'vehicle'.
- When any object using URL resources with a resident sitting on it crosses a parcel boundary the resources will switch to the first sitting resident with enough resources. If no sitting agents have enough resources then the resources from the parcel being moved onto will be used. If even then there are not enough resources to use then the vehicle will be blocked from moving.
  In short we do everything we can to find a pool to host the resources needed by the vehicle, but will block movement if we can't.
Parcel Sale: When a parcel is sold such that it changes the total available URLs in the region for either resident (seller or buyer) such that more URLs are being used than are available some objects will be returned.
- The objects returned will be from youngest object to oldest object of those using URLs in each category in order of object category: Temporary, Other, Group, Owner, Selected/Sat upon.
  The only time objects are possibly returned is when parcels change owner, and only if more resources are being used than allowed.
  
  We return youngest temporary objects before older temporary objects before younger 'other' (owned by non-group, non-parcel-owner) objects etc.

Other Limitations

Size of the body of the requests will be limited to 2k bytes.
Size of headers of requests will be limited to 255 bytes per header, not total.
The size of responses to requests is not currently limited, but this is subject to review during testing.
By default the content type of the returned data is always "text/plain; charset=utf-8", this however can be changed via llSetContentType for all subsequent responses via llHTTPResponse.
There is a cap of 64 in flight requests per script. This is based on the maximum number of pending events in LSL. After hitting the 64 request limit, the simulator cap server returns "503 Service Unavailable" to the inbound request.
We may throttle the rate we accept hits at the CAP server level as well. This is possible, but has not yet been decided.
HTML can be used to in-client browser, including media on a prim, with some restrictions. See llSetContentType and CONTENT_TYPE_HTML for further details.
If making a parser, remember that you should probably restrict access to only Linden Lab HTML URLs as to not have your bandwith stolen. See Simulator_IP_Addresses for details.
It is important to note that when appending a query string to a cap URL there MUST be a trailing slash between the cap guid and the query string token "?". For example: https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322?arg=gra will return a 500 HTTP status Server Error code, but https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/?arg=gra will succeed.

Links

Difference between revisions of "LSL HTTP server"

Revision as of 06:57, 11 January 2014

Contents

Introduction

Uses

Script API

Events

Functions

llRequestURL

llRequestSecureURL

llReleaseURL

llHTTPResponse

llGetFreeURLs

llGetHTTPHeader