This doc explains the ideal on how the MonkeyScript system will be layered in terms of web development.

See layers-web-diagram.svg for a diagram showing a chart detailing what structures are built on top of each other.

Responder

Responders are a special type of class which handles web requests using methods. One typically is created using:

   1 new Responder({
   2         POST: function(request) { ...some code to run on post request... },
   3         GET: function(request) { ...some code to run on get request... },
   4 });

Typically you have one method per request method type and if you do not sepecify a HEAD then the system will just run the GET method and discard the body. Normally the code do to that which is the main entry point to the responder is ".request()". Instead of specifing individual methods you can also just specify a single .request method by passing a single function to the responder constructor as so.

   1 new Responder(function(request) {
   2         ... code to run on all types of request ...
   3         ... use request.method == 'UCNAME' to differentiate ...
   4 });

Responders may be used in a multi-request or a single-request context. This is the primary level of abstraction that allow methods like HTTP, FastCGI, and server embedding methods to work pluggably.

Multi-Request Process; Responder

In a multi-request process a responder is the only method of responding to requests. Every simpler method of response is built on top of a lower-level multi-process responder. The big difference between a multi-request responder and other responders and response methods is that a multi-request responder is executed raw with the same execution level as the script itself. Thus there are is no memory sandboxing for separate requests, however at the same time you have full access to the ability to share anything you want between requests. As well because a multi-request responder is a non-stop process daemon you can also run background tasks in another thread in the process. For example MediaWiki (PHP) which runs a few items of a job que with each request could instead use a separate thread to slowly run the job que inbetween requests.

Single-Request Responder

The single-request responder is basically coded almost exactly the same as the Multi-Request Responder (more work needs to be done to determine the small differences). The big difference is that the single-request responder only handles a single request. Starting at this level because a persistant process is no longer necessary backends other than protocols like FastCGI, such as an Apache mod_monkeyscript may be used to run the script. MonkeyScript supports it's own method of using either FastCGI or HTTP as the pluggable backend and running a special process to handle the requests similar to running a Mongrel server for RoR, or using php-cgi for PHP. MonkeyScript handles this as well as request safety by running the single-request responder inside of a sandbox.

Request Script

A request script still shares a good bit of similarity with responders. A request script is basically an entire script run as a single-request responder, it shares the same memory restrictions. The primary difference is that in a request script all the "request" methods are imported into the scope. So instead of request.write('foo'); in a request script you would simply write('foo');. As well many of the methods like print, println, and echo are remapped to write to the request rather than stdout.

Per-File Request Script

A per-file request script is the same as a request script however with a difference in what gets executed. In a normal request script there is a single core request script and all requests get piped through it. The difference with per-file is how like in php you have individual files inside your DocumentRoot and depending on the url queried for a different script may be run. Most other simpler formats build on the per-file method.

Output stream embed

Embedding into the output stream is where we start to depart from normal JS. Output stream embedding is similar to the technique used in php and ruby's .rhtml

Effectively the script is basically one big string stream to write, like a .php and .rhtml file you can stick JS code inside of some tags.

(Any of these can be written with <js? instead of <? if you want. Unlike in php a global config will not control enforcement of this, if it is desireable to allow interoperability with non-js (ie PHP) code for some strange reason (doing that can be considiered quite insecure since one interpreter's output text can become considered code run by the other interpreter, a user ouputted string containing <? ?> could become code executed on the server resulting in a extremely dangerous injection vector) then the application itself should turn off the short syntax.

<? run some code ?>
<?= evaluate and print the return ?>
<?...= evaluate and print the return using a filter format ?>
Filter formats:
  <?h=...?>  Escape html
  <?u=...?>  urlencode

((Or maybe we should use something else, posibilities:))
<(foo)>    I kinda like the way it looks for evaulating and pringing, just think <(sometext)> can be thrown wherever you need it.
<?=foo?>   Above syntax, php&rhtml like
<$...$>    Dollars? Anyone used them?
<@...@>    
<!...!>
<~...~>
<%...%>    ASP uses these, probably want to avoid
<&...&>
<*...*>
<^...^>
<:...:>
<|...|> 

Note that XML itself also uses <?...?> so something different may be a good idea.