gecko-dev/netwerk/test/httpserver
Gregory Szorc e396fc159d Bug 774572 - Part 2: Define JAR_MANIFESTS in moz.build files; r=glandium
Every directory with a jar.mn now has JAR_MANIFESTS defined in its
moz.build file.

We also removed the may_skip special consideration of jar.mn files
because this information is now available during tier traversal by the
reader courtesy of the variables being present in moz.build files.

--HG--
extra : rebase_source : 21049b15e6bd9cf65b0805ccaccc4ba5aae93c98
extra : amend_source : 0b1ea866d725beef92d37c6f6d475369ac002e19
2013-12-10 16:18:11 +09:00
..
test Bug 901990 - Part 2: Upgrade xpcshell manifests; r=ted 2013-09-24 11:50:08 -07:00
Makefile.in Bug 912293 - Remove now redundant boilerplate from Makefile.in. r=gps 2013-09-05 09:01:46 +09:00
README Bug 428009 - Update the HTTP server to require a *correct* host be specified with it, not just *a* host via an absolute URI as Request-URI or a specified Host header. This also gives request handlers proper details about the location to which the request was targeted. r=biesi on the raw socket usage in the test code, r=ted on the build changes, r=sayrer on the server changes 2008-06-07 02:43:15 -04:00
TODO Bug 370245 - Make the HTTP server asynchronously process requests, and pave the way for future improvements to processing. r=biesi, a=bsmedberg on a testing-only change 2007-08-23 15:07:40 -07:00
httpd.js Bug 924259 - Fix error message when httpd.js is already running (r=Waldo) 2013-10-10 10:52:12 -07:00
httpd.manifest Fix packaging of test-only XPT files for crashreporter and httpserver. 2010-06-30 12:42:24 -04:00
jar.mn Bug 616809 Remove CRs from netwerk r=biesi a=jst DONTBUILD 2011-02-06 00:04:14 +00:00
moz.build Bug 774572 - Part 2: Define JAR_MANIFESTS in moz.build files; r=glandium 2013-12-10 16:18:11 +09:00
nsIHttpServer.idl Bug 749930 - Replace uses of nsILocalFile with nsIFile (compiled code only); r=bsmedberg 2012-06-06 14:08:30 +12:00

README

httpd.js README
===============

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

httpd.js 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 httpd.js 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 httpd.js.  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();

This server will only respond to requests on 127.0.0.1:8080 or localhost:8080.
If you want it to respond to requests at different hosts (say via a proxy
mechanism), you must use server.identity.add() or server.identity.setPrimary()
to add it.


Using httpd.js as an Inline Script or from xpcshell
---------------------------------------------------

Using httpd.js 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 httpd.js 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 httpd.js as an XPCOM component
whenever possible.


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

httpd.js makes no effort to time out requests, beyond any the socket itself
might or might not provide.  I don't believe it provides any by default, but
I haven't verified this.

Every incoming request is processed by the corresponding request handler
synchronously.  In other words, once the first CRLFCRLF of a request is
received, the entire response is created before any new incoming requests can be
served.  I anticipate adding asynchronous handler functionality in bug 396226,
but it may be some time before that happens.

There is no way to access the body of an incoming request.  This problem is
merely a symptom of the previous one, and they will probably both be addressed
at the same time.


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 httpd.js, if you need one.

Have fun!