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