1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/test/httpserver/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,101 @@
1.4 +httpd.js README
1.5 +===============
1.6 +
1.7 +httpd.js is a small cross-platform implementation of an HTTP/1.1 server in
1.8 +JavaScript for the Mozilla platform.
1.9 +
1.10 +httpd.js may be used as an XPCOM component, as an inline script in a document
1.11 +with XPCOM privileges, or from the XPCOM shell (xpcshell). Currently, its most-
1.12 +supported method of use is from the XPCOM shell, where you can get all the
1.13 +dynamicity of JS in adding request handlers and the like, but component-based
1.14 +equivalent functionality is planned.
1.15 +
1.16 +
1.17 +Using httpd.js as an XPCOM Component
1.18 +------------------------------------
1.19 +
1.20 +First, create an XPT file for nsIHttpServer.idl, using the xpidl tool included
1.21 +in the Mozilla SDK for the environment in which you wish to run httpd.js. See
1.22 +<http://developer.mozilla.org/en/docs/XPIDL:xpidl> for further details on how to
1.23 +do this.
1.24 +
1.25 +Next, register httpd.js and nsIHttpServer.xpt in your Mozilla application. In
1.26 +Firefox, these simply need to be added to the /components directory of your XPI.
1.27 +Other applications may require use of regxpcom or other techniques; consult the
1.28 +applicable documentation for further details.
1.29 +
1.30 +Finally, create an instance of the server using the following command:
1.31 +
1.32 + var server = Components.classes["@mozilla.org/server/jshttp;1"]
1.33 + .createInstance(Components.interfaces.nsIHttpServer);
1.34 +
1.35 +At this point you'll want to initialize the server, since by default it doesn't
1.36 +serve many useful paths. For more information on this, see the IDL docs for the
1.37 +nsIHttpServer interface in nsIHttpServer.idl, particularly for
1.38 +registerDirectory (useful for mapping the contents of directories onto request
1.39 +paths), registerPathHandler (for setting a custom handler for a specific path on
1.40 +the server, such as CGI functionality), and registerFile (for mapping a file to
1.41 +a specific path).
1.42 +
1.43 +Finally, you'll want to start (and later stop) the server. Here's some example
1.44 +code which does this:
1.45 +
1.46 + server.start(8080); // port on which server will operate
1.47 +
1.48 + // ...server now runs and serves requests...
1.49 +
1.50 + server.stop();
1.51 +
1.52 +This server will only respond to requests on 127.0.0.1:8080 or localhost:8080.
1.53 +If you want it to respond to requests at different hosts (say via a proxy
1.54 +mechanism), you must use server.identity.add() or server.identity.setPrimary()
1.55 +to add it.
1.56 +
1.57 +
1.58 +Using httpd.js as an Inline Script or from xpcshell
1.59 +---------------------------------------------------
1.60 +
1.61 +Using httpd.js as a script or from xpcshell isn't very different from using it
1.62 +as a component; the only real difference lies in how you create an instance of
1.63 +the server. To create an instance, do the following:
1.64 +
1.65 + var server = new nsHttpServer();
1.66 +
1.67 +You now can use |server| exactly as you would when |server| was created as an
1.68 +XPCOM component. Note, however, that doing so will trample over the global
1.69 +namespace, and global values defined in httpd.js will leak into your script.
1.70 +This may typically be benign, but since some of the global values defined are
1.71 +constants (specifically, Cc/Ci/Cr as abbreviations for the classes, interfaces,
1.72 +and results properties of Components), it's possible this trampling could
1.73 +break your script. In general you should use httpd.js as an XPCOM component
1.74 +whenever possible.
1.75 +
1.76 +
1.77 +Known Issues
1.78 +------------
1.79 +
1.80 +httpd.js makes no effort to time out requests, beyond any the socket itself
1.81 +might or might not provide. I don't believe it provides any by default, but
1.82 +I haven't verified this.
1.83 +
1.84 +Every incoming request is processed by the corresponding request handler
1.85 +synchronously. In other words, once the first CRLFCRLF of a request is
1.86 +received, the entire response is created before any new incoming requests can be
1.87 +served. I anticipate adding asynchronous handler functionality in bug 396226,
1.88 +but it may be some time before that happens.
1.89 +
1.90 +There is no way to access the body of an incoming request. This problem is
1.91 +merely a symptom of the previous one, and they will probably both be addressed
1.92 +at the same time.
1.93 +
1.94 +
1.95 +Other Goodies
1.96 +-------------
1.97 +
1.98 +A special testing function, |server|, is provided for use in xpcshell for quick
1.99 +testing of the server; see the source code for details on its use. You don't
1.100 +want to use this in a script, however, because doing so will block until the
1.101 +server is shut down. It's also a good example of how to use the basic
1.102 +functionality of httpd.js, if you need one.
1.103 +
1.104 +Have fun!
