netwerk/test/httpserver/README@ca08bd8f51b2 (annotated)
netwerk/test/httpserver/README
Wed, 31 Dec 2014 06:55:46 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:46 +0100
- changeset 1
- ca08bd8f51b2
- permissions
- -rw-r--r--
Added tag TORBROWSER_REPLICA for changeset 6474c204b198
| michael@0 | 1 | httpd.js README |
| michael@0 | 2 | =============== |
| michael@0 | 3 | |
| michael@0 | 4 | httpd.js is a small cross-platform implementation of an HTTP/1.1 server in |
| michael@0 | 5 | JavaScript for the Mozilla platform. |
| michael@0 | 6 | |
| michael@0 | 7 | httpd.js may be used as an XPCOM component, as an inline script in a document |
| michael@0 | 8 | with XPCOM privileges, or from the XPCOM shell (xpcshell). Currently, its most- |
| michael@0 | 9 | supported method of use is from the XPCOM shell, where you can get all the |
| michael@0 | 10 | dynamicity of JS in adding request handlers and the like, but component-based |
| michael@0 | 11 | equivalent functionality is planned. |
| michael@0 | 12 | |
| michael@0 | 13 | |
| michael@0 | 14 | Using httpd.js as an XPCOM Component |
| michael@0 | 15 | ------------------------------------ |
| michael@0 | 16 | |
| michael@0 | 17 | First, create an XPT file for nsIHttpServer.idl, using the xpidl tool included |
| michael@0 | 18 | in the Mozilla SDK for the environment in which you wish to run httpd.js. See |
| michael@0 | 19 | <http://developer.mozilla.org/en/docs/XPIDL:xpidl> for further details on how to |
| michael@0 | 20 | do this. |
| michael@0 | 21 | |
| michael@0 | 22 | Next, register httpd.js and nsIHttpServer.xpt in your Mozilla application. In |
| michael@0 | 23 | Firefox, these simply need to be added to the /components directory of your XPI. |
| michael@0 | 24 | Other applications may require use of regxpcom or other techniques; consult the |
| michael@0 | 25 | applicable documentation for further details. |
| michael@0 | 26 | |
| michael@0 | 27 | Finally, create an instance of the server using the following command: |
| michael@0 | 28 | |
| michael@0 | 29 | var server = Components.classes["@mozilla.org/server/jshttp;1"] |
| michael@0 | 30 | .createInstance(Components.interfaces.nsIHttpServer); |
| michael@0 | 31 | |
| michael@0 | 32 | At this point you'll want to initialize the server, since by default it doesn't |
| michael@0 | 33 | serve many useful paths. For more information on this, see the IDL docs for the |
| michael@0 | 34 | nsIHttpServer interface in nsIHttpServer.idl, particularly for |
| michael@0 | 35 | registerDirectory (useful for mapping the contents of directories onto request |
| michael@0 | 36 | paths), registerPathHandler (for setting a custom handler for a specific path on |
| michael@0 | 37 | the server, such as CGI functionality), and registerFile (for mapping a file to |
| michael@0 | 38 | a specific path). |
| michael@0 | 39 | |
| michael@0 | 40 | Finally, you'll want to start (and later stop) the server. Here's some example |
| michael@0 | 41 | code which does this: |
| michael@0 | 42 | |
| michael@0 | 43 | server.start(8080); // port on which server will operate |
| michael@0 | 44 | |
| michael@0 | 45 | // ...server now runs and serves requests... |
| michael@0 | 46 | |
| michael@0 | 47 | server.stop(); |
| michael@0 | 48 | |
| michael@0 | 49 | This server will only respond to requests on 127.0.0.1:8080 or localhost:8080. |
| michael@0 | 50 | If you want it to respond to requests at different hosts (say via a proxy |
| michael@0 | 51 | mechanism), you must use server.identity.add() or server.identity.setPrimary() |
| michael@0 | 52 | to add it. |
| michael@0 | 53 | |
| michael@0 | 54 | |
| michael@0 | 55 | Using httpd.js as an Inline Script or from xpcshell |
| michael@0 | 56 | --------------------------------------------------- |
| michael@0 | 57 | |
| michael@0 | 58 | Using httpd.js as a script or from xpcshell isn't very different from using it |
| michael@0 | 59 | as a component; the only real difference lies in how you create an instance of |
| michael@0 | 60 | the server. To create an instance, do the following: |
| michael@0 | 61 | |
| michael@0 | 62 | var server = new nsHttpServer(); |
| michael@0 | 63 | |
| michael@0 | 64 | You now can use |server| exactly as you would when |server| was created as an |
| michael@0 | 65 | XPCOM component. Note, however, that doing so will trample over the global |
| michael@0 | 66 | namespace, and global values defined in httpd.js will leak into your script. |
| michael@0 | 67 | This may typically be benign, but since some of the global values defined are |
| michael@0 | 68 | constants (specifically, Cc/Ci/Cr as abbreviations for the classes, interfaces, |
| michael@0 | 69 | and results properties of Components), it's possible this trampling could |
| michael@0 | 70 | break your script. In general you should use httpd.js as an XPCOM component |
| michael@0 | 71 | whenever possible. |
| michael@0 | 72 | |
| michael@0 | 73 | |
| michael@0 | 74 | Known Issues |
| michael@0 | 75 | ------------ |
| michael@0 | 76 | |
| michael@0 | 77 | httpd.js makes no effort to time out requests, beyond any the socket itself |
| michael@0 | 78 | might or might not provide. I don't believe it provides any by default, but |
| michael@0 | 79 | I haven't verified this. |
| michael@0 | 80 | |
| michael@0 | 81 | Every incoming request is processed by the corresponding request handler |
| michael@0 | 82 | synchronously. In other words, once the first CRLFCRLF of a request is |
| michael@0 | 83 | received, the entire response is created before any new incoming requests can be |
| michael@0 | 84 | served. I anticipate adding asynchronous handler functionality in bug 396226, |
| michael@0 | 85 | but it may be some time before that happens. |
| michael@0 | 86 | |
| michael@0 | 87 | There is no way to access the body of an incoming request. This problem is |
| michael@0 | 88 | merely a symptom of the previous one, and they will probably both be addressed |
| michael@0 | 89 | at the same time. |
| michael@0 | 90 | |
| michael@0 | 91 | |
| michael@0 | 92 | Other Goodies |
| michael@0 | 93 | ------------- |
| michael@0 | 94 | |
| michael@0 | 95 | A special testing function, |server|, is provided for use in xpcshell for quick |
| michael@0 | 96 | testing of the server; see the source code for details on its use. You don't |
| michael@0 | 97 | want to use this in a script, however, because doing so will block until the |
| michael@0 | 98 | server is shut down. It's also a good example of how to use the basic |
| michael@0 | 99 | functionality of httpd.js, if you need one. |
| michael@0 | 100 | |
| michael@0 | 101 | Have fun! |
