Teacup is an open source webserver front end for LSL's HTTP-in + MOAP functionality. It builds on the work of several other people including but not limited to, Kelly Linden, Torley Linden, Tali Rosca, Vegas Silverweb, and special mentions to Kate and/or Edelman Linden. The idea is to make it easy to serve web content from within SL, with a minimum of work or understanding, in the most standards compliant and flexible way possible.
How does it work?
Externally, when Teacup starts, it gets a URL and creates a Micro HTML page, which it bootstraps onto the prim face with a "data:" URN. Once loaded, that page requests a JavaScript library, which loads normally. Once loaded, the library bootstraps the specially prepared ".tsp" HTML content onto the current page, and captures all links targeting other ".tsp" files, so that it can do the same when they are requested. Internally the server broadcasts a message when it gets a page request, and any installed File Service scripts can reply with content, or the server will simply report back that it doesn't have the file requested if it doesn't receive a reply in a set time.
Why all the tea jokes?
Well I happen to like steam punk stuff, and it has a sort of pseudo-Victorian-era feel to it, but in all truth it was sparked by a bit of geek humor. There was an old april fool's joke passed around as an official sounding memo about creating a protocol for controlling coffee pots with HTTP (back before they actually started making net enabled appliances) and part of that proposal was that teapots should return an error response 418 "I'm a teapot" if you tried to make it brew coffee... since these servers are small, and 418 is safe to use internally because it wouldn't normally be encountered, I figured hey, Teapot --> Teacup --> Victorian Imagery --> Steam Punk --> teacup that is it's own teapot --> SIP --> many different types of tea --> Success!
... And thus was born the SIP, Teacup server, and Red Tea File Service (developers are encouraged to keep the theme, but it's not a requirement)
So you don't want to read a bunch of tech babble, you just want to make a website in a prim right? Well I can sympathize so here are some (mostly) easy steps to get you up and running fast...
Optional: Copy the text in the grey box below Code: Region Stats into a script named "Region Stats", save it, and drop it into your rezzed box.
Optional: Copy the text in the grey box below Code: Saucer into a script named "Saucer", save it, and drop it in your rezzed box.
Optional: Copy the text in the grey box below Code: Tea Strainer into a script named "Tea_Strainer", save it, and drop it in your rezzed box.
Copy the text in the grey box below Code: Teacup into a script named "Teacup v0.5", save it, and drop it in your rezzed box.
Click on the top of your box if your webpage isn't already showing.
At this point you may want to rotate and/or resize your box.
If you like, you have my express permission to download (right click, "save as") and edit (with whichever image editor you prefer) the Teacup.png file to use as the default texture of your website prim.
Show it off to your friends with MOAP enabled viewers.
If you run into any problems, simply start a thread with the problem you are having here, and I or some other technical wizard will assist you.
list gLstPndKey; //-- Key queue (pages waiting to be served)
list gLstPndTim; //-- Timeout Value queue (Request Timeout)
//-- These (hopefully) prevent multiple responses if SL sends a timeout.
default{
state_entry(){ //-- Request URL on start up
llRequestURL();
}
on_rez( integer vIntBgn ){ //-- Clear pending and request new URL on rez
gLstPndKey = gLstPndTim = [];
llRequestURL();
}
changed( integer vBitChg ){ //-- Clear pending and re-request URL on region change/restart
if ((CHANGED_REGION_START
Protocols
This section is not required reading for users, it is really only of use to scripters looking understand or extend it.
Server Protocols
Outgoing Messages
The server has only two outgoing message formats. The first is general advertisement, and can be used by any File Service or extension to advertise information about itself.
<source lang="lsl2">llMessageLinked( LINK_SET, TEACUP_MESSAGE, "Message", NULL_KEY );</source>
Where "Message" is anything the script wants to advertise
The server only sends one such message "Teacup URL Changed", and ignores messages sent by other scripts using this format.
When this message is sent, The current Address of the Server is placed in the prims hover text, other scripts may use the following to retrieve it<source lang="lsl2">string vStrAddress = llList2String( llGetLinkPrimitiveParams( SERVER_LINK_NUMBER, [PRIM_TEXT] ), 0 );</source>
The text will either be the servers URL, the text "No URL".
The second Outgoing Message is a file request and has the format
<source lang="lsl2">llMessageLinked( LINK_SET, TEACUP_MESSAGE, REQUEST_PAGE, REQUEST_KEY );</source>
TEACUP_MESSAGE: 418
REQUEST_PAGE: the format is "<page name>?<search string>#ip=<decimal IP Address>&<post data>]
Ex: "index.tsp?#ip=127.0.0.1&" <-- file has no search string or post data
the page name can be parsed with<source lang="lsl2">string vStrPageName = llList2String( llParseStringKeepNulls( REQUEST_PAGE, [], ["?","#"] ), 0 );</source>
REQUEST_KEY: the return key for the requested data.
valid Server Requests can be detected by checking that REQUEST_KEY is a valid key, and that TEACUP_MESSAGE is 418.
Incoming Messages
The server expects it will receive a return message in the following format for any file request made...
<source lang="lsl2">llMessageLinked( REQUEST_SOURCE, RESPONSE_CODE, FILE_TEXT, REQUEST_KEY ); //-- sent from the File Service</source>
REQUEST_SOURCE: The link number of the Teacup server that sent the request
RESPONSE_CODE: the following standard HTTP Response codes are currently recognized
100 "Continue": The server ignores this, make sure you send a normal response code as a follow up (see Saucer for details)
200 "Success": Basic "yes we have it, here you go". anything that returns data can return this
201 "Created": File was created for this request. probably best if the file was created for the request
202 "Accepted": Request acknowledged/received (content optional) probably best for commands that generate in world actions
204 "No Content": We got the request/data, but don't need to return anything. probably best for form data, FILE_TEXT should be blank.
403 "Forbidden": We got the request, but aren't allowed to serve it. Expansion space for per user access (unused as of this writing).
404 "Not Found": The file does not exist. Avoid using this unless you are reasonably sure the file isn't being served from another script.
FILE_TEXT: text of the file that was requested.
REQUEST_KEY: server request key for this file.
Any return should be done within 20 seconds or it's results will be ignored (Mostly an LSL limitation)
Special Ranges and limitations
To promote predictable data flows within a scripted object, The following are "Official" limits for scripts to be included as compatible resources
The 0xx Range is off limits and may not be used (for compatibility with scripts that may use low numbers)
All normal HTTP Response codes and ranges (1xx-5xx) are reserved... do not use them unless they make sense or the server can actually send them properly.
the Range of 6xx codes is reserved for use by File System scripts, limited to no more than 10 per range per script and will be registered by request, first (working script) come, first served. if you reasonably need more than 10, use the 8xx-9xx range
the following 6xx codes are are registered at this time
600 "File Removed" (sent with a file name and NULL_KEY)
601 "File Added" (sent with a file name and NULL_KEY)
7xx codes are reserved for future expansion
8xx-9xx are unregulated, use at your own risk
All Codes must be below 1000 (this is to guarantee safe data transfer for other unrelated scripts)
To Promote Maximum Stability and Flexibility
Any Script that resides in the server prim should expect link messages of up to 40KiB
File Service Scripts should attempt to send files 30KiB or smaller
File Service Scripts should not broadcast any link message larger than 4KiB using LINK_THIS
Responses to requests should be targeted to the Server prim that requested the data for larger data sizes (optimally for ALL responses)
Scripts residing outside of the server prim should expect link messages with up to 4KiB of data (the max the server is able to request with normally)
".tsp" pages with inline scripts should avoid using the following variable/function names
v0, v1, v2, v3 - v9 (these variables are used to: wrap the page for transport, serve as a loading container for pages, handle timeout messages for non-loading pages, and the rest being reserved for future support)
u0, u1, u2, u3 - u9 (these functions handle: watching for ".tsp" links to intercept, setting up the container for new ".tsp" requests, loading the ".tsp" files, and the rest being reserved for future support)
you can request a new page from javascript by calling u1('PageName.tsp');, however you may want to include some random info in the search string if refreshing the same page
Teacup serves a modified html page called a Teacup Server Page (".tsp"), to overcome limitations in the LSL HTTP-in behavior.
if a requested filename ends with ".tsp" it needs to conform to a specific format that is similar but not identical to the contents of a normal html webpage. To convert an html page into a tsp page, the follow actions must take place (an example of all of them may be found in the Red Tea File Service)
The file name should end with ".tsp"
The contents are limited to what's valid inside a normal html "body" tag.
It also requires the following minor changes, made in order:
all backslash characters must be converted to double backslashes (may be applied on a line by line basis)
Red Tea - A very simple SIP back end File Service for a starting point.
Region Stats - A single page Extension that gets live data from the region and refreshes every minute
Saucer - Optional Fast 404 Extension for preventing long timeouts for missing/bad pages
Tea Strainer - Optional Troubleshooting Monitor for checking messages being sent and received.
To Go Cup - Experimental Loader for Internal Browsers on v1x viewers (v1.23, Snowglobe, Cool, Phoenix, Imprudence, Ascent, Singularity, and others without MOAP support)
Known Bugs
inline style elements are not evaluated at load time (inline attributes should work normally)
using JavaScript to write these is a viable workaround at the moment
document/body onload events are not triggered for page loads
images have their own events, and can be used to trigger page load JavaScript
may not support this now that inline scripts work, but it's still under consideration
Fails to load directly to external browsers (VWR-25555)
v2 internal browsers will only load it from the shared media bar "Load URL in browser" button (VWR-25554)
Workaround for v2 is to load it via the shared media button, to the internal browser, then cut and paste into an external browser (should work with everything but IE)
POST from forms is wonky, it forces a page load, which we can only serve text to.
There isn't any way via JavaScript to intecept form POST data, nor a way to call it from the container we use
It may be possible to rework the server to use Frames and detect plain text loads of pages... will look into this.
normal onLoad event for the pages scripts are unsupported
unfortunately the webkit browser is stupid and doesn't obey async/defer script attributes so we have to use onload for the main page
fortunately, scripts will get refreshed in page order, so just calling the code is a viable alternative
Requested Feature Upgrades
see about faking support for defer/async behavior in the tsp inline script tags
this will require supporting page onLoad events
Find a simple way to serve base64 encoded content such as images or sounds.
NEED ASSISTANCE: I can (probably) do it the same way we load pages, but this makes it hard for page writers.
considering a double-tap method where the server js library parses img tags for failures and bootstraps them with a modified name
may be able to partially support this via css, but it's ugly for page writers =(
Change Log / Old Versions
Most Recent Changes are at the top, old version links below.
Code will be considered stable when it reaches 1.0
I have kept this page as a sub page of my user page to denote that it should NOT be edited except to correct errors, add confirmed bugs, or add related resources.
The intent is to ensure executive control is in one person's hands to retain a cohesive vision of it's development.
If you have an improvement suggestion, or request, please use the discussion page.
