LlHTTPRequest

2015-11-07T12:36:12Z

RenateIsabella Resident: Additional info about http request throttling

{{LSL_Function
|func=llHTTPRequest
|func_id=230
|func_energy=10.0
|func_sleep=0.0
|func_desc=Sends an HTTP request to the specified URL with the body of the request and parameters.
|sort=HTTPRequest
|func_footnote=
|return_type=key|return_subtype=handle
|return_text=identifying the HTTP request made.
|p1_type=string|p1_name=url|p1_desc=A valid HTTP/HTTPS URL.
|p2_type=list|p2_subtype=instructions|p2_name=parameters|p2_desc=configuration parameters, specified as HTTP_* flag-value pairs
[ parameter1, value1, parameter2, value2, . . . parameterN, valueN]
|p3_type=string|p3_name=body|p3_desc=Contents of the request.
|constants={{LSL_Constants_HTTP}}
{{LSL_Constants/HTTP_Headers}}
|spec
|caveats=
*If there is a space in '''url''', the [[http_response]] status code will be 499.
*The corresponding [[http_response]] event will be triggered in all scripts in the [[prim]], not just in the requesting script.
*Requests must fully complete after 60 seconds, or else the response will be thrown away and the [[http_response]] status code will be 499.
*The response body is limited to 2048 bytes by default, see [[HTTP_BODY_MAXLENGTH]] above to increase it. If the response is longer, it will be truncated.
*Requests are throttled on a per [[object]] basis (not per prim or script).
**Requests are throttled at approximately 25 requests per 20 seconds. This is to support a sustained rate of 1 per second or a max burst of up to 25 every 40 seconds (2x the interval for max burst), smaller bursts are recommended. (Edit: rcently (November 2015) scripts with considerably lower request frequencies than 25 per 20 seconds have been known to fail and it seems the limit has been reduced significantly. There doesn't seem to be any official statement about what the new limit is nor if it's a permanent change. For now it's recommended to keep the number of requests as low as possible and test scripts using llHTTPReqest throughly.)
**[[NULL_KEY]] is returned if the request is throttled.
***See [http://forums-archive.secondlife.com/139/72/108960/1.html this thread] and [http://forums-archive.secondlife.com/139/2c/109571/1.html this thread] for more details.
*Cannot be used to load textures or images from the internet, for more information see [[Web Textures]].
*If the accessed site is relying on the LSL script to report L$ transactions, then it '''must''' check the X-SecondLife-Shard header to see if the script is running on the beta grid.
* Some servers will return a 405 error if you send POST to a file that can't accept metadata, such as a text or HTML file. Make sure you use the GET method to ensure success in any environment.
* While the HTTP status code from the server is provided to the script, redirect codes such as 302 will result in the redirect being automatically and transparently followed ONLY IF the [[HTTP_METHOD]] is GET, with the resulting response being returned. If the [[HTTP_METHOD]] is anything other then GET then you'll get back an http_response with a status code of 302, but without any way to view the headers, you can't know where you were being redirected to unless that was also included in the body.
* The following applies when making a request to a script using HTTP-In:
**When appending a query string to a cap URL there '''MUST''' be a trailing slash between the cap guid and the query string token <code>"?"</code>. For example: [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}] will return a 500 HTTP status {{Wikipedia|List_of_HTTP_status_codes#5xx_Server_Error|Server Error code}}, but [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}{{HoverTextStyle|style=color:blue;|/|2={{String|x-path-info}} = {{String|/}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}] will succeed.
* X-SecondLife-Owner-Name may return "(Loading...)" instead of owner name (still true, 18th of July, 2011)
* Requests made at approx 0625 SLT may fail with a 503 status code, with "ERROR: The requested URL could not be retrieved", and "(111) Connection refused" in the body of the response. This has been confirmed as expected behaviour by Kelly, due to the nightly maint & log rotation. It does reliably impact object to object HTTP at that time, and quite probably may impact object to/from web around the same time. The interruption in service is fairly brief, and the precise timing may vary as LL adjust their nightly maint processes, or due to server load.
|examples=
<source lang="lsl2">
key http_request_id;

default
{
state_entry()
{
http_request_id = llHTTPRequest("url", [], "");
}

http_response(key request_id, integer status, list metadata, string body)
{
if (request_id != http_request_id) return;// exit if unknown

vector COLOR_BLUE = <0.0, 0.0, 1.0>;
float OPAQUE = 1.0;

llSetText(body, COLOR_BLUE, OPAQUE);
}
}
</source>

Example PHP test script:
<source lang="php">
<?php header("content-type: text/plain; charset=utf-8"); ?>
Headers received:
<?php

/**
* @author Wouter Hobble
* @copyright 2008
*/

foreach ($_SERVER as $k => $v)
{
if( substr($k, 0, 5) == 'HTTP_')
{
print "\n". $k. "\t". $v;
}
}
?>
</source>

example wrapper script Both capturing apache headers and global methodes
<source lang="php">
<?PHP
// Author Waster Skronski.
// General Public License (GPL).
// Mind that some headers are not included because they're either useless or unreliable.

$USE_APACHE_HEADERS = TRUE;// switch to false if you need cgi methods

if ($USE_APACHE_HEADERS)
{
$headers = apache_request_headers();
$objectgrid = $headers["X-SecondLife-Shard"];
$objectname = $headers["X-SecondLife-Object-Name"];
$objectkey = $headers["X-SecondLife-Object-Key"];
$objectpos = $headers["X-SecondLife-Local-Position"];
$ownerkey = $headers["X-SecondLife-Owner-Key"];
$ownername = $headers["X-SecondLife-Owner-Name"];
$regiondata = $headers["X-SecondLife-Region"];
$regiontmp = explode ("(",$regiondata); // cut cords off
$regionpos = explode (")",$regiontmp[1]);
$regionname = substr($regiontmp[0],0,-1); // cut last space from simname
} else {
$db = $GLOBALS;
$headers = $db['HTTP_ENV_VARS'];
$objectgrid = $headers["HTTP_X_SECONDLIFE_SHARD"];
$objectname = $headers["HTTP_X_SECONDLIFE_OBJECT_NAME"];
$objectkey = $headers["HTTP_X_SECONDLIFE_OBJECT_KEY"];
$ownerkey = $headers["HTTP_X_SECONDLIFE_OWNER_KEY"];
$objectpos = $headers["HTTP_X_SECONDLIFE_LOCAL_POSITION"];
$ownername = $headers["HTTP_X_SECONDLIFE_OWNER_NAME"];
$regiondata = $headers["HTTP_X_SECONDLIFE_REGION"];
$regiontmp = explode ("(",$regiondata);
$regionpos = explode (")",$regiontmp[1]);
$regionname = substr($regiontmp[0],0,-1);
}
?>
</source>

Example wrapper script for GoDaddy.com Linux PHP servers (fix made by Thomas Conover):

<source lang="php">
// FETCH HEADERS START

if (!function_exists('apache_request_headers'))
{
function apache_request_headers() {
foreach($_SERVER as $key=>$value) {
if (substr($key,0,5)=="HTTP_") {
$key=str_replace(" ","-",ucwords(strtolower(str_replace("_"," ",substr($key,5)))));
$out[$key]=$value;
}else{
$out[$key]=$value;
}
}
return $out;
}
}
// Mind that some headers are not included because they're either useless or unreliable. X-Secondlife-Local-Position
$headers = apache_request_headers();
$objectgrid = $headers["X-Secondlife-Shard"];
$objectname = $headers["X-Secondlife-Object-Name"];
$objectkey = $headers["X-Secondlife-Object-Key"];
$objectpos = $headers["X-Secondlife-Local-Position"];
$ownerkey = $headers["X-Secondlife-Owner-Key"];
$ownername = $headers["X-Secondlife-Owner-Name"];
$regiondata = $headers["X-Secondlife-Region"];
$regiontmp = explode ("(",$regiondata); // cut cords off
$regionname = substr($regiontmp[0],0,-1); // cut last space from simname
$regiontmp = explode (")",$regiontmp[1]);
$regionpos = $regiontmp[0];

// FETCH HEADERS END
</source>

<div style="display:none;"><source lang="lsl2"></source></div>
|helpers
|also_header
|also_events={{LSL DefineRow||[[http_response]]}}
|also_functions={{LSL DefineRow||[[llEscapeURL]]}}
{{LSL DefineRow||[[llHTTPResponse]]}}
{{LSL DefineRow||[[llUnescapeURL]]}}
|also_articles={{LSL DefineRow||[[Simulator IP Addresses]]}}
|also_footer
|notes=If for some reason while using the function [[llHTTPRequest]] or the event [[http_response]] you are unable to parse a known good RSS feed or some other form of web contents, you will need to work around it outside of SecondLife. This is unlikely to change in the near future since checking the headers requires more overhead at the simulator level.

You may find that some web servers return either a null or a nonsensical result when [[llHTTPRequest]] is used, even though the same URL in a PC web browser returns the expected result. This may be due to the fact that the [[llHTTPRequest]] User Agent string is not recognised by some web servers as it does not contain "Mozilla", which would identify it as a web browser instead of, for example, a Shoutcast or an RSS client. A workaround is to append " HTTP/1.0\nUser-Agent: LSL Script (Mozilla Compatible)\n\n" or similar to the URL string, which will kludge the HTTP request to look like it originates from a web browser. This is also true when the PHP relays on $_COOKIE. Neither can the function [[llHTTPRequest]] set a cookie nor can the event [[http_request]] retrieve them.

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. "HTTP_X_SECONDLIFE_OBJECT_NAME". PHP $_SERVER variables do this as well.

Apache can include the headers in its logs, using the CustomLog and LogFormat directives. See [http://httpd.apache.org/docs/2.0/mod/mod_log_config.html#formats the docs] for details on the syntax.

|mode
|deprecated
|permission
|cat1=HTTP
|cat2=XML-RPC
|cat3=Communications
|cat4=HTTP/Client
}}

Second Life Wiki - User contributions [en]

LlHTTPRequest