This module only depends on Rig. The following call starts up a server:
Httpd start <portnumber> <handler>
All I/O is non-blocking, there can be multiple outstanding requests. Whenever a request comes in, a new namespace for it is set up which can be used as command object due to the use of ensembles. The "handler" given when server is started and called for each request, can then do whatever it likes with this object.
Two "methods" are defined right from the start:
$obj respond result ?status? ?done? => must be called to start a reply
$obj delegate method args... => can be used to define more methods
The request object is prototype-like, not class based, i.e. each request starts off with just the above two methods defined. It is up to the handler to define additional methods, and do so repeatedly for each new request.
Two request methods are called by the Httpd module under specific conditions:
$obj failed status result => called to produce an error page
$obj done => called just before deleting the request obj
If these methods are not present, then calls to them will silently be omitted.
If a request never reaches the point where it is ready to be processed by the handler, then the namespace with the incomplete object is simply deleted again.
Once the handler is called, the object may get a "failed" call, but it will always get a "done" method call. All requests go through these same phases.
A few arrays and variables are pre-defined when the handler gets the request:
${obj}::request => an array with request details: url, proto, etc
${obj}::info => an array with all the input mime headers
${obj}::query => all query data, as read for POST requests
${obj}::headers => dict of headers to be sent back in the response
The Render module is an example of a more advanced use of requests, tying each request to a Mason-like component-based templating engine.
Httpd start port handler ?iface?
Start a new HTTP server on the specified port. The handler will be called with a new object whenever a request comes in. The optional interface argument can be specified to limit on which interface this server will listen.
Httpd stop
Stop all currently running HTTP servers. Current requests will not be affected, and can continue to run to completion.