pjs/netwerk/test/httpserver/README

MozJSHTTP README
================

MozJSHTTP is a small cross-platform implementation of an HTTP/1.1 server in
JavaScript for the Mozilla platform.

MozJSHTTP may be used as an XPCOM component, as an inline script in a document
with XPCOM privileges, or from the XPCOM shell (xpcshell).  Currently, its most-
supported method of use is from the XPCOM shell, where you can get all the
dynamicity of JS in adding request handlers and the like, but component-based
equivalent functionality is planned.


Using MozJSHTTP as an XPCOM Component
-------------------------------------

First, create an XPT file for nsIHttpServer.idl, using the xpidl tool included
in the Mozilla SDK for the environment in which you wish to run MozJSHTTP.  See
<http://developer.mozilla.org/en/docs/XPIDL:xpidl> for further details on how to
do this.

Next, register httpd.js and nsIHttpServer.xpt in your Mozilla application.  In
Firefox, these simply need to be added to the /components directory of your XPI.
Other applications may require use of regxpcom or other techniques; consult the
applicable documentation for further details.

Finally, create an instance of the server using the following command:

  var server = Components.classes["@mozilla.org/server/jshttp;1"]
                         .createInstance(Components.interfaces.nsIHttpServer);

At this point you'll want to initialize the server, since by default it doesn't
serve many useful paths.  For more information on this, see the IDL docs for the
nsIHttpServer interface in nsIHttpServer.idl, particularly for
registerDirectory (useful for mapping the contents of directories onto request
paths), registerPathHandler (for setting a custom handler for a specific path on
the server, such as CGI functionality), and registerFile (for mapping a file to
a specific path).

Finally, you'll want to start (and later stop) the server.  Here's some example
code which does this:

  server.start(8080);  // port on which server will operate

  // ...server now runs and serves requests...

  server.stop();


Using MozJSHTTP as an Inline Script or from xpcshell
----------------------------------------------------

Using MozJSHTTP as a script or from xpcshell isn't very different from using it
as a component; the only real difference lies in how you create an instance of
the server.  To create an instance, do the following:

  var server = new nsHttpServer();

You now can use |server| exactly as you would when |server| was created as an
XPCOM component.  Note, however, that doing so will trample over the global
namespace, and global values defined in MozJSHTTP will leak into your script.
This may typically be benign, but since some of the global values defined are
constants (specifically, Cc/Ci/Cr as abbreviations for the classes, interfaces,
and results properties of Components), it's possible this trampling could
break your script.  In general you should use MozJSHTTP as an XPCOM component
whenever possible.


Known Issues
------------

While MozJSHTTP runs on Mozilla 1.8 and 1.9 platforms, it doesn't run quite as
well on 1.8 due to the absence of some APIs, specifically the threading APIs.
The biggest problem here is that server shutdown (see nsIHttpServer.stop) is not
guaranteed to complete after all pending requests have been served; if you are
using the server in 1.8 code, you should probably wait a few seconds after
calling server.stop() before the host application closes to ensure that all
requests have completed.  Things probably aren't going to break too horribly if
you don't do this, but better safe than sorry.

To be clear: the guarantee that nsIHttpServer.stop says implementations should
make when possible (that .stop returns only when all pending requests have been
serviced) cannot be made in a 1.8 environment; it can be made in a 1.9
environment.  Use 1.9 if this matters to you, or hack around it as described
here.


Other Goodies
-------------

A special testing function, |server|, is provided for use in xpcshell for quick
testing of the server; see the source code for details on its use.  You don't
want to use this in a script, however, because doing so will block until the
server is shut down.  It's also a good example of how to use the basic
functionality of MozJSHTTP, if you need one.

Have fun!