HTTP server for unit tests

  • Revision slug: Httpd.js/HTTP_server_for_unit_tests
  • Revision title: HTTP server for unit tests
  • Revision id: 374093
  • Created:
  • Creator: victorporof
  • Is current revision? No
  • Comment

Revision Content

This page describes the JavaScript implementation of an HTTP server located in {{ Source("netwerk/test/httpserver/") }}.

Functionality

Here are some of the things you can do with the server:

  • map a directory of files onto an HTTP path on the server, for an arbitrary number of such directories (including nested directories)
  • define custom error handlers for HTTP error codes
  • serve a given file for requests for a specific path, optionally with custom headers and status
  • define custom "CGI" handlers for specific paths using a JavaScript-based API to create the response (headers and actual content)
  • run multiple servers at once on different ports (8080, 8081, 8082, and so on.)

This functionality should be more than enough for you to use it with any test which requires HTTP-provided behavior.

Where you can use it

The server is written primarily for use from xpcshell-based tests, and it can be used as an inline script or as an XPCOM component (assuming you've compiled the server's IDL file and deployed the XPT correctly). The Mochitest framework also uses it to serve its tests, and {{ Source("layout/tools/reftest/README.txt", "reftests") }} can optionally use it when their behavior is dependent upon specific HTTP header values.

Ways you might use it

  • application update testing
  • cross-"server" security tests
  • cross-domain security tests, in combination with the right proxy settings (for example, using Proxy AutoConfig)
  • tests where the behavior is dependent on the values of HTTP headers (for example, Content-Type)
  • anything which requires use of files not stored locally
  • open-id : the users could provide their own open id server (they only need it when they're using their browser)
  • micro-blogging : users could host their own micro blog based on standards like RSS/Atom
  • rest APIs : web application could interact with REST or SOAP APIs for many purposes like : file/data storage, social sharing and so on
  • decentralized search engine : i think it could be great if a standard could allow a privileged access to the Firefox awesome bar in oder to search into friends historic/bookmarks. It could maybe be interfaced with Dictionaries and KGen to get a more complete semantic classification of browser history/bookmarks. It could be compatible with the OpenSearch standard.

Using the server

The best and first place you should look for documentation is {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}. It's extremely comprehensive and detailed, and it should be enough to figure out how to make the server do what you want. I also suggest taking a look at the less-comprehensive server {{ Source("netwerk/test/httpserver/README", "README") }}, although the IDL should usually be sufficient.

Running the server

From test suites, the server should be importable as a testing-only JS module:

Cu.import("resource://testing-common/httpd.js");

If you're writing tests for the {{ gecko("1.9.0") }} branch, you should include the following line instead:

do_import_script("netwerk/test/httpserver/httpd.js");

Once you've done that, you can create a new server as follows:

let server = new HttpServer(); // Or nsHttpServer() if you don't use Cu.import.

server.registerDirectory("/", nsILocalFileForBasePath);

const SERVER_PORT = 8080; // or some suitably large number
server.start(SERVER_PORT);

// and when the tests are done, most likely from a callback...
if (testingIn190Branch) // server API changed starting with 191
  server.stop();
else
  server.stop(function() { /* continue execution here */ });

Note that because the server only runs when the xpcshell event loop is spun, you'll have to use do_test_pending(); and do your testing via callbacks, making sure to call do_test_finished(); when the tests finish. Doing so is a little hairy, but since such a test is unlikely to be synchronous anyway it shouldn't be too hard to handle server asynchronicity.

Note: You must make sure to stop the server (the last line above) before your test completes. Failure to do so will result in the "XPConnect is being called on a scope without a Components property" assertion, which will cause your test to fail in debug builds, and you'll make people running tests grumbly because you've broken the tests.

Debugging errors

The server's default error pages don't give much information, partly because the error-dispatch mechanism doesn't currently accommodate doing so and partly because exposing errors in a real server could make it easier to exploit them. If you don't know why the server is acting a particular way, edit {{ Source("netwerk/test/httpserver/httpd.js", "httpd.js") }} and change the value of DEBUG to true. This will cause the server to print information about the processing of requests (and errors encountered doing so) to the console, and it's usually not difficult to determine why problems exist from that output. DEBUG is false by default because the information printed with it set to true unnecessarily obscures tinderbox output.

Header modification for files

The server supports modifying the headers of the files (not request handlers) it serves. To modify the headers for a file, create a sibling file with the first file's name followed by ^headers^. Here's an example of how such a file might look:

HTTP 404 I want a cool HTTP description!
Content-Type: text/plain

The status line is optional; all other lines specify HTTP headers in the standard HTTP format. Any line ending style is accepted, and the file may optionally end in a single blank line, to play nice with Unix text tools like diff and cvs.

Hidden files

Any file which ends with a single ^ is inaccessible when querying the web server; if you try to access such a file you'll get a 404 File Not Found page instead. If for some reason you need to serve a file ending with a ^, just tack another ^ onto the end of the file name and the file will then become available at the single-^ location.

At the moment this feature is basically a way to smuggle header modification for files into the file system without making those files accessible to clients; it remains to be seen whether and how hidden-file capabilities will otherwise be used.

SJS: server-side scripts

Support for server-side scripts is provided through the SJS mechanism. Essentially an SJS is a file with a particular extension, chosen by the creator of the server, which contains a function with the name handleRequest which is called to determine the response the server will generate. That function acts exactly like the handle function on the {{ interface("nsIHttpRequestHandler") }} interface. First, tell the server what extension you're using:

const SJS_EXTENSION = "cgi";
server.registerContentType(SJS_EXTENSION, "sjs");

Now just create an SJS with the extension cgi and write whatever you want. For example:

function handleRequest(request, response)
{
  response.setStatusLine(request.httpVersion, 200, "OK");
  response.write("Hello world!  This request was dynamically " +
                 "generated at " + new Date().toUTCString());
}

Further examples may be found in the Mozilla source tree in existing tests. The request object is an instance of nsIHttpRequestHandler and the response is a nsIHttpResponseHandler.

Storing information across requests (not available in {{ gecko("1.9.0") }})

HTTP is basically a stateless protocol, and the httpd.js server API is for the most part similarly stateless. If you're using the server through the XPCOM interface you can simply store whatever state you want in enclosing environments or global variables. However, if you're using it through an SJS your request is processed in a near-empty environment every time processing occurs. To support stateful SJS behavior, the following functions have been added to the global scope in which a SJS handler executes, providing a simple key-value state storage mechanism:

/*
 * v : T means v is of type T
 * function A() : T means A() has type T
 */

function getState(key : string) : string
function setState(key : string, value : string)
function getSharedState(key : string) : string
function setSharedState(key : string, value : string)
function getObjectState(key : string, callback : function(value : object) : void) // SJS API, XPCOM differs, see below
function setObjectState(key : string, value : object)

A key is a string with arbitrary contents. The corresponding value is also a string, for the non-object-saving functions. For the object-saving functions, it is (wait for it) an object, or also null. Initially all keys are associated with the empty string or with null, depending on whether the function accesses string- or object-valued storage. A stored value persists across requests and across server shutdowns and restarts. The state methods are available both in SJS and, for convenience when working with the server both via XPCOM and via SJS, XPCOM through the {{ interface("nsIHttpServer") }} interface. The variants are designed to support different needs.

{{ warning("Be careful using state: you, the user, are responsible for synchronizing all uses of state through any of the available methods. (This includes the methods that act only on per-path state: you might still run into trouble there if your request handler generates responses asynchronously. Further, any code with access to the server XPCOM component could modify it between requests even if you only ever used or modified that state while generating synchronous responses.) JavaScript's run-to-completion behavior will save you in simple cases, but with anything moderately complex you are playing with fire, and if you do it wrong you will get burned.") }}

getState and setState

getState and setState are designed for the case where a single request handler needs to store information from a first request of it for use in processing a second request of it — say, for example, if you wanted to implement a request handler implementing a counter:

/**
 * Generates a response whose body is "0", "1", "2", and so on. each time a
 * request is made.  (Note that browser caching might make it appear
 * to not quite have that behavior; a Cache-Control header would fix
 * that issue if desired.)
 */
function handleRequest(request, response)
{
  var counter = +getState("counter"); // convert to number; +"" === 0
  response.write("" + counter);
  setState("counter", "" + ++counter);
}

The useful feature of these two methods is that this state doesn't bleed outside the single path at which it resides. For example, if the above SJS were at /counter, the value returned by getState("counter") at some other path would be completely distinct from the counter implemented above. This makes it much simpler to write stateful handlers without state accidentally bleeding between unrelated handlers.

{{ note("State saved by this method is specific to the HTTP path, excluding query string and hash reference. /counter, /counter?foo, and /counter?bar#baz all share the same state for the purposes of these methods. (Indeed, non-shared state would be significantly less useful if it changed when the query string changed!)") }}

{{ gecko_callout_heading("2.0") }}

The predefined __LOCATION__ state contains the native path of the SJS file itself. You can pass the result directly to the {{ ifmethod("nsILocalFile","initWithPath") }}. Example: thisSJSfile.initWithPath(getState('__LOCATION__'));

getSharedState and setSharedState

getSharedState and setSharedState make up the functionality intentionally not supported by getState and setState: state that exists between different paths. If you used the above handler at the paths /sharedCounters/1 and /sharedCounters/2 (changing the state-calls to use shared state, of course), the first load of either handler would return "0", a second load of either handler would return "1", a third load either handler would return "2", and so on. This more powerful functionality allows you to write cooperative handlers that expose and manipulate a piece of shared state. Be careful! One test can screw up another test pretty easily if it's not careful what it does with this functionality.

getObjectState and setObjectState

getObjectState and setObjectState support the remaining functionality not provided by the above methods: storing non-string values (object values or null). These two methods are the same as getSharedState and setSharedState in that state is visible across paths; setObjectState in one handler will expose that value in another handler that uses getObjectState with the same key. (This choice was intentional, because object values already expose mutable state that you have to be careful about using.) This functionality is particularly useful for cooperative request handlers where one request suspends another, and that second request must then be resumed at a later time by a third request. Without object-valued storage you'd need to resort to polling on a string value using either of the previous state APIs; with this, however, you can make precise callbacks exactly when a particular event occurs.

getObjectState in an SJS differs in one important way from getObjectState accessed via XPCOM. In XPCOM the method takes a single string argument and returns the object or null directly. In SJS, however, the process to return the value is slightly different:

function handleRequest(request, response)
{
  var key = request.hasHeader("key")
          ? request.getHeader("key")
          : "unspecified";
  var obj = null;
  getObjectState(key, function(objval)
  {
    // This function is called synchronously with the object value
    // associated with key.
    obj = objval;
  });
  response.write("Keyed object " +
                 (obj && Object.prototype.hasOwnProperty.call(obj, "doStuff")
                 ? "has "
                 : "does not have ") +
                 "a doStuff method.");
}

This idiosyncratic API is a restriction imposed by how sandboxes currently work: external functions added to the sandbox can't return object values when called within the sandbox. However, such functions can accept and call callback functions, so we simply use a callback function here to return the object value associated with the key.

Advanced dynamic response creation (not available in {{ gecko("1.9.0") }})

The default behavior of request handlers is to fully construct the response, return, and only then send the generated data. For certain use cases, however, this is infeasible. For example, a handler which wanted to return an extremely large amount of data (say, over 4GB on a 32-bit system) might run out of memory doing so. Alternatively, precise control over the timing of data transmission might be required so that, for example, one request is received, "paused" while another request is received and completes, and then finished. httpd.js solves this problem by defining a processAsync() method which indicates to the server that the response will be written and finished by the handler. Here's an example of an SJSfile which writes some data, waits five seconds, and then writes some more data and finishes the response:

var timer = null;

function handleRequest(request, response)
{
  response.processAsync();
  response.setHeader("Content-Type", "text/plain", false);
  response.write("hello...");

  timer = Components.classes["@mozilla.org/timer;1"].createInstance(Components.interfaces.nsITimer);
  timer.initWithCallback(function()
  {
    response.write("world!");
    response.finish();
  }, 5 * 1000 /* milliseconds */, Components.interfaces.nsITimer.TYPE_ONE_SHOT);
}

The basic flow is simple: call processAsync to mark the response as being sent asynchronously, write data to the response body as desired, and when complete call finish(). At the moment if you drop such a response on the floor, nothing will ever terminate the connection, and the server cannot be stopped (the stop API is asynchronous and callback-based); in the future a default connection timeout will likely apply, but for now, "don't do that".

Full documentation for processAsync() and its interactions with other methods may, as always, be found in {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}.

Manual, arbitrary response creation (available in {{ gecko("1.9.1") }} and later)

The standard mode of response creation is fully synchronous and is guaranteed to produce syntactically correct responses (excluding headers, which for the most part may be set to arbitrary values). Asynchronous processing enables the introduction of response handling coordinated with external events, but again, for the most part only syntactically correct responses may be generated. The third method of processing removes the correct-syntax property by allowing a response to contain completely arbitrary data through the seizePower() method. After this method is called, any data subsequently written to the response is written directly to the network as the response, skipping headers and making no attempt whatsoever to ensure any formatting of the transmitted data. As with asynchronous processing, the response is generated asynchronously and must be finished manually for the connection to be closed. (Again, nothing will terminate the connection for a response dropped on the floor, so again, "don't do that".) This mode of processing is useful for testing particular data formats that are either not HTTP or which do not match the precise, canonical representation that httpd.js generates. Here's an example of an SJSfile which writes an apparent HTTP response whose status text contains a null byte (not allowed by HTTP/1.1, and attempting to set such status text through httpd.js would throw an exception) and which has a header that spans multiple lines (httpd.js responses otherwise generate only single-line headers):

function handleRequest(request, response)
{
  response.seizePower();
  response.write("HTTP/1.1 200 OK Null byte \u0000 makes this response malformed\r\n" +
                 "X-Underpants-Gnomes-Strategy:\r\n" +
                 " Phase 1: Collect underpants.\r\n" +
                 " Phase 2: ...\r\n" +
                 " Phase 3: Profit!\r\n" +
                 "\r\n" +
                 "FAIL");
  response.finish();
}

While the asynchronous mode is capable of producing certain forms of invalid responses (through setting a bogus Content-Length header prior to the start of body transmission, among others), it must not be used in this manner. No effort will be made to preserve such implementation quirks (indeed, some are even likely to be removed over time): if you want to send malformed data, use seizePower() instead.

Full documentation for seizePower() and its interactions with other methods may, as always, be found in {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}.

Examples

Shorter examples (for tests which only do one test):

  • {{ Source("netwerk/test/unit/test_bug331825.js") }}
  • {{ Source("netwerk/test/unit/test_httpcancel.js") }}
  • {{ Source("netwerk/test/unit/test_cookie_header.js") }}

Longer tests (where you'd need to do multiple async server requests):

  • {{ Source("netwerk/test/httpserver/test/test_setstatusline.js") }}
  • {{ Source("netwerk/test/unit/test_content_sniffer.js") }}
  • {{ Source("netwerk/test/unit/test_authentication.js") }}
  • {{ Source("netwerk/test/unit/test_event_sink.js") }}
  • {{ Source("netwerk/test/httpserver/test/") }}

Examples of modifying HTTP headers in files may be found at {{ Source("netwerk/test/httpserver/test/data/cern_meta/") }}.

Future directions

The server, while very functional, is not yet complete. There are a number of things to fix and features to add, among them support for pipelining, support for incrementally-received requests (rather than buffering the entire body before invoking a request handler), and better conformance to the MUSTs and SHOULDs of HTTP/1.1. If you have suggestions for functionality or find bugs, file them in {{ Enter-bug("Testing", "httpd.js") }} and CC jwalden+bmo.

Revision Source

<p>This page describes the JavaScript implementation of an <a href="/en/HTTP" title="en/HTTP">HTTP</a> server located in {{ Source("netwerk/test/httpserver/") }}.</p>
<h3 id="Functionality" name="Functionality">Functionality</h3>
<p>Here are some of the things you can do with the server:</p>
<ul>
  <li>map a directory of files onto an HTTP path on the server, for an arbitrary number of such directories (including nested directories)</li>
  <li>define custom error handlers for HTTP error codes</li>
  <li>serve a given file for requests for a specific path, optionally with custom headers and status</li>
  <li>define custom "CGI" handlers for specific paths using a JavaScript-based API to create the response (headers and actual content)</li>
  <li>run multiple servers at once on different ports (8080, 8081, 8082, and so on.)</li>
</ul>
<p>This functionality should be more than enough for you to use it with any test which requires HTTP-provided behavior.</p>
<h3 id="Where_you_can_use_it" name="Where_you_can_use_it">Where you can use it</h3>
<p>The server is written primarily for use from <a href="/en/Writing_xpcshell-based_unit_tests" title="en/Writing_xpcshell-based_unit_tests">xpcshell-based tests</a>, and it can be used as an inline script or as an XPCOM component (assuming you've compiled the server's IDL file and deployed the XPT correctly). The <a href="/en/Mochitest" title="en/Mochitest">Mochitest</a> framework also uses it to serve its tests, and {{ Source("layout/tools/reftest/README.txt", "reftests") }} can optionally use it when their behavior is dependent upon specific HTTP header values.</p>
<h3 id="Ways_you_might_use_it" name="Ways_you_might_use_it">Ways you might use it</h3>
<ul>
  <li>application update testing</li>
  <li>cross-"server" security tests</li>
  <li>cross-domain security tests, in combination with the right proxy settings (for example, using <a href="/en/Proxy_AutoConfig" title="en/Proxy_AutoConfig">Proxy AutoConfig</a>)</li>
  <li>tests where the behavior is dependent on the values of HTTP headers (for example, Content-Type)</li>
  <li>anything which requires use of files not stored locally</li>
  <li>open-id : the users could provide their own open id server (they only need it when they're using their browser)</li>
  <li>micro-blogging : users could host their own micro blog based on standards like RSS/Atom</li>
  <li>rest APIs : web application could interact with REST or SOAP APIs for many purposes like : file/data storage, social sharing and so on</li>
  <li>decentralized search engine : i think it could be great if a standard could allow a privileged access to the Firefox awesome bar in oder to search into friends historic/bookmarks. It could maybe be interfaced with Dictionaries and KGen to get a more complete semantic classification of browser history/bookmarks. It could be compatible with the OpenSearch standard.</li>
</ul>
<h3 id="Using_the_server" name="Using_the_server">Using the server</h3>
<p>The best and first place you should look for documentation is {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}. It's extremely comprehensive and detailed, and it should be enough to figure out how to make the server do what you want. I also suggest taking a look at the less-comprehensive server {{ Source("netwerk/test/httpserver/README", "README") }}, although the IDL should usually be sufficient.</p>
<h4 id="Running_the_server" name="Running_the_server">Running the server</h4>
<p>From test suites, the server should be importable as a testing-only JS module:</p>
<pre class="eval">
<span class="brush: js">Cu.import("resource://testing-common/httpd.js");</span></pre>
<p>If you're writing tests for the {{ gecko("1.9.0") }} branch, you should include the following line instead:</p>
<pre class="brush: js">
do_import_script("netwerk/test/httpserver/httpd.js");</pre>
<p>Once you've done that, you can create a new server as follows:</p>
<pre class="brush: js">
let server = new HttpServer(); // Or nsHttpServer() if you don't use Cu.import.

server.registerDirectory("/", nsILocalFileForBasePath);

const SERVER_PORT = 8080; // or some suitably large number
server.start(SERVER_PORT);

// and when the tests are done, most likely from a callback...
if (testingIn190Branch) // server API changed starting with 191
  server.stop();
else
  server.stop(function() { /* continue execution here */ });</pre>
<p>Note that because the server only runs when the xpcshell event loop is spun, you'll have to use <code>do_test_pending();</code> and do your testing via callbacks, making sure to call <code>do_test_finished();</code> when the tests finish. Doing so is a little hairy, but since such a test is unlikely to be synchronous anyway it shouldn't be too hard to handle server asynchronicity.</p>
<div class="note">
  <p>Note: You <strong>must</strong> make sure to stop the server (the last line above) before your test completes. Failure to do so will result in the "XPConnect is being called on a scope without a Components property" assertion, which will cause your test to fail in debug builds, and you'll make people running tests grumbly because you've broken the tests.</p>
</div>
<h4 id="Debugging_errors" name="Debugging_errors">Debugging errors</h4>
<p>The server's default error pages don't give much information, partly because the error-dispatch mechanism doesn't currently accommodate doing so and partly because exposing errors in a real server could make it easier to exploit them. If you don't know why the server is acting a particular way, edit {{ Source("netwerk/test/httpserver/httpd.js", "httpd.js") }} and change the value of <code>DEBUG</code> to <code>true</code>. This will cause the server to print information about the processing of requests (and errors encountered doing so) to the console, and it's usually not difficult to determine why problems exist from that output. <code>DEBUG</code> is <code>false</code> by default because the information printed with it set to <code>true</code> unnecessarily obscures tinderbox output.</p>
<h4 id="Header_modification_for_files" name="Header_modification_for_files">Header modification for files</h4>
<p>The server supports modifying the headers of the files (not request handlers) it serves. To modify the headers for a file, create a sibling file with the first file's name followed by <code>^headers^</code>. Here's an example of how such a file might look:</p>
<pre class="eval">
HTTP 404 I want a cool HTTP description!
Content-Type: text/plain
</pre>
<p>The status line is optional; all other lines specify HTTP headers in the standard HTTP format. Any line ending style is accepted, and the file may optionally end in a single blank line, to play nice with Unix text tools like diff and cvs.</p>
<h4 id="Hidden_files" name="Hidden_files">Hidden files</h4>
<p>Any file which ends with a single <code>^</code> is inaccessible when querying the web server; if you try to access such a file you'll get a <code><a href="/en/HTTP/HTTP_response_codes#404" title="https://developer.mozilla.org/en/HTTP/HTTP_response_codes#404">404 File Not Found</a></code> page instead. If for some reason you need to serve a file ending with a <code>^</code>, just tack another <code>^</code> onto the end of the file name and the file will then become available at the single-<code>^</code> location.</p>
<p>At the moment this feature is basically a way to smuggle header modification for files into the file system without making those files accessible to clients; it remains to be seen whether and how hidden-file capabilities will otherwise be used.</p>
<h4 id="SJS:_server-side_scripts" name="SJS:_server-side_scripts">SJS: server-side scripts</h4>
<p>Support for server-side scripts is provided through the SJS mechanism. Essentially an SJS is a file with a particular extension, chosen by the creator of the server, which contains a function with the name <code>handleRequest</code> which is called to determine the response the server will generate. That function acts exactly like the <code>handle</code> function on the {{ interface("nsIHttpRequestHandler") }} interface. First, tell the server what extension you're using:</p>
<pre class="brush: js">
const SJS_EXTENSION = "cgi";
server.registerContentType(SJS_EXTENSION, "sjs");
</pre>
<p>Now just create an SJS with the extension <code>cgi</code> and write whatever you want. For example:</p>
<pre class="brush: js">
function handleRequest(request, response)
{
  response.setStatusLine(request.httpVersion, 200, "OK");
  response.write("Hello world!  This request was dynamically " +
                 "generated at " + new Date().toUTCString());
}
</pre>
<p>Further examples may be found <a class="external" href="http://mxr.mozilla.org/mozilla/find?text=&amp;kind=text&amp;string=sjs%24">in the Mozilla source tree</a> in existing tests. The request object is an instance of <a href="http://doxygen.db48x.net/mozilla/html/interfacensIHttpRequest.html" title="http://doxygen.db48x.net/mozilla/html/interfacensIHttpRequest.html">nsIHttpRequestHandler</a> and the response is a <a href="http://doxygen.db48x.net/mozilla/html/interfacensIHttpRequest.html" title="http://doxygen.db48x.net/mozilla/html/interfacensIHttpRequest.html">nsIHttpResponseHandler</a>.</p>
<h4 id="Storing_information_across_requests_(not_available_in_.7B.7B_gecko(.221.9.0.22)_.7D.7D)">Storing information across requests (not available in {{ gecko("1.9.0") }})</h4>
<p>HTTP is basically a stateless protocol, and the httpd.js server API is for the most part similarly stateless. If you're using the server through the XPCOM interface you can simply store whatever state you want in enclosing environments or global variables. However, if you're using it through an SJS your request is processed in a near-empty environment every time processing occurs. To support stateful SJS behavior, the following functions have been added to the global scope in which a SJS handler executes, providing a simple key-value state storage mechanism:</p>
<pre class="brush: js">
/*
 * v : T means v is of type T
 * function A() : T means A() has type T
 */

function getState(key : string) : string
function setState(key : string, value : string)
function getSharedState(key : string) : string
function setSharedState(key : string, value : string)
function getObjectState(key : string, callback : function(value : object) : void) // SJS API, XPCOM differs, see below
function setObjectState(key : string, value : object)</pre>
<p>A key is a string with arbitrary contents. The corresponding value is also a string, for the non-object-saving functions. For the object-saving functions, it is (wait for it) an object, or also <code>null</code>. Initially all keys are associated with the empty string or with <code>null</code>, depending on whether the function accesses string- or object-valued storage. A stored value persists across requests and across server shutdowns and restarts. The state methods are available both in SJS and, for convenience when working with the server both via XPCOM and via SJS, XPCOM through the {{ interface("nsIHttpServer") }} interface. The variants are designed to support different needs.</p>
<p>{{ warning("Be careful using state: you, the user, are responsible for synchronizing all uses of state through any of the available methods. (This includes the methods that act only on per-path state: you might still run into trouble there if your request handler generates responses asynchronously. Further, any code with access to the server XPCOM component could modify it between requests even if you only ever used or modified that state while generating synchronous responses.) JavaScript's run-to-completion behavior will save you in simple cases, but with anything moderately complex you are playing with fire, and if you do it wrong you will get burned.") }}</p>
<h5 id="getState_and_setState"><code>getState</code> and <code>setState</code></h5>
<p><code>getState</code> and <code>setState</code> are designed for the case where a single request handler needs to store information from a first request of it for use in processing a second request of it — say, for example, if you wanted to implement a request handler implementing a counter:</p>
<pre class="brush: js">
/**
 * Generates a response whose body is "0", "1", "2", and so on. each time a
 * request is made.  (Note that browser caching might make it appear
 * to not quite have that behavior; a Cache-Control header would fix
 * that issue if desired.)
 */
function handleRequest(request, response)
{
  var counter = +getState("counter"); // convert to number; +"" === 0
  response.write("" + counter);
  setState("counter", "" + ++counter);
}
</pre>
<p>The useful feature of these two methods is that this state doesn't bleed outside the single path at which it resides. For example, if the above SJS were at <code>/counter</code>, the value returned by <code>getState("counter")</code> at some other path would be completely distinct from the counter implemented above. This makes it much simpler to write stateful handlers without state accidentally bleeding between unrelated handlers.</p>
<p>{{ note("State saved by this method is specific to the HTTP path, excluding query string and hash reference. <code>/counter</code>, <code>/counter?foo</code>, and <code>/counter?bar#baz</code> all share the same state for the purposes of these methods. (Indeed, non-shared state would be significantly less useful if it changed when the query string changed!)") }}</p>
<div class="geckoVersionNote">
  <p>{{ gecko_callout_heading("2.0") }}</p>
  <p>The predefined <code>__LOCATION__</code> state contains the native path of the SJS file itself. You can pass the result directly to the {{ ifmethod("nsILocalFile","initWithPath") }}. Example: <code>thisSJSfile.initWithPath(getState('__LOCATION__'));</code></p>
</div>
<h5 id="getSharedState_and_setSharedState"><code>getSharedState</code> and <code>setSharedState</code></h5>
<p><code>getSharedState</code> and <code>setSharedState</code> make up the functionality intentionally not supported by <code>getState</code> and <span style="font-family: monospace;">set</span><code>State</code>: state that exists between different paths. If you used the above handler at the paths <code>/sharedCounters/1</code> and <code>/sharedCounters/2</code> (changing the state-calls to use shared state, of course), the first load of either handler would return "0", a second load of either handler would return "1", a third load either handler would return "2", and so on. This more powerful functionality allows you to write cooperative handlers that expose and manipulate a piece of shared state. Be careful! One test can screw up another test pretty easily if it's not careful what it does with this functionality.</p>
<h5 id="getObjectState_and_setObjectState"><code>getObjectState</code> and <code>setObjectState</code></h5>
<p><code>getObjectState</code> and <code>setObjectState</code> support the remaining functionality not provided by the above methods: storing non-string values (object values or <code>null</code>). These two methods are the same as <code>getSharedState</code> and <code>setSharedState </code>in that state is visible across paths; <code>setObjectState</code> in one handler will expose that value in another handler that uses <code>getObjectState</code> with the same key. (This choice was intentional, because object values already expose mutable state that you have to be careful about using.) This functionality is particularly useful for cooperative request handlers where one request <em>suspends</em> another, and that second request must then be <em>resumed</em> at a later time by a third request. Without object-valued storage you'd need to resort to polling on a string value using either of the previous state APIs; with this, however, you can make precise callbacks exactly when a particular event occurs.</p>
<p><code>getObjectState</code> in an SJS differs in one important way from <code>getObjectState</code> accessed via XPCOM. In XPCOM the method takes a single string argument and returns the object or <code>null</code> directly. In SJS, however, the process to return the value is slightly different:</p>
<pre class="brush: js">
function handleRequest(request, response)
{
  var key = request.hasHeader("key")
          ? request.getHeader("key")
          : "unspecified";
  var obj = null;
  getObjectState(key, function(objval)
  {
    // This function is called synchronously with the object value
    // associated with key.
    obj = objval;
  });
  response.write("Keyed object " +
                 (obj &amp;&amp; Object.prototype.hasOwnProperty.call(obj, "doStuff")
                 ? "has "
                 : "does not have ") +
                 "a doStuff method.");
}
</pre>
<p>This idiosyncratic API is a restriction imposed by how sandboxes currently work: external functions added to the sandbox can't return object values when called within the sandbox. However, such functions can accept and call callback functions, so we simply use a callback function here to return the object value associated with the key.</p>
<h4 id="Advanced_dynamic_response_creation_(not_available_in_.7B.7B_gecko(.221.9.0.22)_.7D.7D)">Advanced dynamic response creation (not available in {{ gecko("1.9.0") }})</h4>
<p>The default behavior of request handlers is to fully construct the response, return, and only then send the generated data. For certain use cases, however, this is infeasible. For example, a handler which wanted to return an extremely large amount of data (say, over 4GB on a 32-bit system) might run out of memory doing so. Alternatively, precise control over the timing of data transmission might be required so that, for example, one request is received, "paused" while another request is received and completes, and then finished. httpd.js solves this problem by defining a <code>processAsync()</code> method which indicates to the server that the response will be written and finished by the handler. Here's an example of an SJSfile which writes some data, waits five seconds, and then writes some more data and finishes the response:</p>
<pre class="brush: js">
var timer = null;

function handleRequest(request, response)
{
  response.processAsync();
  response.setHeader("Content-Type", "text/plain", false);
  response.write("hello...");

  timer = Components.classes["@<a class="linkification-ext external" href="http://mozilla.org/timer;1" title="Linkification: http://mozilla.org/timer;1">mozilla.org/timer;1</a>"].createInstance(Components.interfaces.nsITimer);
  timer.initWithCallback(function()
  {
    response.write("world!");
    response.finish();
  }, 5 * 1000 /* milliseconds */, Components.interfaces.nsITimer.TYPE_ONE_SHOT);
}
</pre>
<p>The basic flow is simple: call <code>processAsync</code> to mark the response as being sent asynchronously, write data to the response body as desired, and when complete call <code>finish()</code>. At the moment if you drop such a response on the floor, nothing will ever terminate the connection, and the server cannot be stopped (the stop API is asynchronous and callback-based); in the future a default connection timeout will likely apply, but for now, "don't do that".</p>
<p>Full documentation for <code>processAsync()</code> and its interactions with other methods may, as always, be found in {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}.</p>
<h4 id="Manual.2C_arbitrary_response_creation_(available_in_.7B.7B_gecko(.221.9.1.22)_.7D.7D_and_later)">Manual, arbitrary response creation (available in {{ gecko("1.9.1") }} and later)</h4>
<p>The standard mode of response creation is fully synchronous and is guaranteed to produce syntactically correct responses (excluding headers, which for the most part may be set to arbitrary values). Asynchronous processing enables the introduction of response handling coordinated with external events, but again, for the most part only syntactically correct responses may be generated. The third method of processing removes the correct-syntax property by allowing a response to contain completely arbitrary data through the <code>seizePower()</code> method. After this method is called, any data subsequently written to the response is written directly to the network as the response, skipping headers and making no attempt whatsoever to ensure any formatting of the transmitted data. As with asynchronous processing, the response is generated asynchronously and must be finished manually for the connection to be closed. (Again, nothing will terminate the connection for a response dropped on the floor, so again, "don't do that".) This mode of processing is useful for testing particular data formats that are either not HTTP or which do not match the precise, canonical representation that httpd.js generates. Here's an example of an SJSfile which writes an apparent HTTP response whose status text contains a null byte (not allowed by HTTP/1.1, and attempting to set such status text through httpd.js would throw an exception) and which has a header that spans multiple lines (httpd.js responses otherwise generate only single-line headers):</p>
<pre class="brush: js">
function handleRequest(request, response)
{
  response.seizePower();
  response.write("HTTP/1.1 200 OK Null byte \u0000 makes this response malformed\r\n" +
                 "X-Underpants-Gnomes-Strategy:\r\n" +
                 " Phase 1: Collect underpants.\r\n" +
                 " Phase 2: ...\r\n" +
                 " Phase 3: Profit!\r\n" +
                 "\r\n" +
                 "FAIL");
  response.finish();
}
</pre>
<p>While the asynchronous mode is capable of producing certain forms of invalid responses (through setting a bogus Content-Length header prior to the start of body transmission, among others), it must not be used in this manner. No effort will be made to preserve such implementation quirks (indeed, some are even likely to be removed over time): if you want to send malformed data, use <code>seizePower()</code> instead.</p>
<p>Full documentation for <code>seizePower()</code> and its interactions with other methods may, as always, be found in {{ Source("netwerk/test/httpserver/nsIHttpServer.idl") }}.</p>
<h3 id="Examples" name="Examples">Examples</h3>
<p>Shorter examples (for tests which only do one test):</p>
<ul>
  <li>{{ Source("netwerk/test/unit/test_bug331825.js") }}</li>
  <li>{{ Source("netwerk/test/unit/test_httpcancel.js") }}</li>
  <li>{{ Source("netwerk/test/unit/test_cookie_header.js") }}</li>
</ul>
<p>Longer tests (where you'd need to do multiple async server requests):</p>
<ul>
  <li>{{ Source("netwerk/test/httpserver/test/test_setstatusline.js") }}</li>
  <li>{{ Source("netwerk/test/unit/test_content_sniffer.js") }}</li>
  <li>{{ Source("netwerk/test/unit/test_authentication.js") }}</li>
  <li>{{ Source("netwerk/test/unit/test_event_sink.js") }}</li>
  <li>{{ Source("netwerk/test/httpserver/test/") }}</li>
</ul>
<p>Examples of modifying HTTP headers in files may be found at {{ Source("netwerk/test/httpserver/test/data/cern_meta/") }}.</p>
<h3 id="Future_directions" name="Future_directions">Future directions</h3>
<p>The server, while very functional, is not yet complete. There are a number of things to fix and features to add, among them support for pipelining, support for incrementally-received requests (rather than buffering the entire body before invoking a request handler), and better conformance to the MUSTs and SHOULDs of HTTP/1.1. If you have suggestions for functionality or find bugs, file them in {{ Enter-bug("Testing", "httpd.js") }} and CC jwalden+bmo.</p>
Revert to this revision