httpd.js

Go to the documentation of this file.

/* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et: */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is the httpd.js server.
 *
 * The Initial Developer of the Original Code is
 * Mozilla Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2006
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Darin Fisher (v1, netwerk/test/TestServ.js)
 *   Christian Biesinger (v2, netwerk/test/unit/head_http_server.js)
 *   Jeff Walden <jwalden+code@mit.edu> (v3, netwerk/test/httpserver/httpd.js)
 *   Robert Sayre <sayrer@gmail.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/*
 * An implementation of an HTTP server both as a loadable script and as an XPCOM
 * component.  See the accompanying README file for user documentation on
 * httpd.js.
 */

const Cc = Components.classes;
const Ci = Components.interfaces;
const Cr = Components.results;
const Cu = Components.utils;
const CC = Components.Constructor;

const PR_UINT32_MAX = Math.pow(2, 32) - 1;

const EXPORTED_SYMBOLS = ["server", "nsHttpServer", "HttpError"];

var DEBUG = false; // non-const *only* so tweakable in server tests

var gGlobalObject = this;

function NS_ASSERT(cond, msg)
{
  if (DEBUG && !cond)
  {
    dumpn("###!!!");
    dumpn("###!!! ASSERTION" + (msg ? ": " + msg : "!"));
    dumpn("###!!! Stack follows:");

    var stack = new Error().stack.split(/\n/);
    dumpn(stack.map(function(val) { return "###!!!   " + val; }).join("\n"));
    
    throw Cr.NS_ERROR_ABORT;
  }
}

function HttpError(code, description)
{
  this.code = code;
  this.description = description;
}
HttpError.prototype =
{
  toString: function()
  {
    return this.code + " " + this.description;
  }
};

const HTTP_400 = new HttpError(400, "Bad Request");
const HTTP_401 = new HttpError(401, "Unauthorized");
const HTTP_402 = new HttpError(402, "Payment Required");
const HTTP_403 = new HttpError(403, "Forbidden");
const HTTP_404 = new HttpError(404, "Not Found");
const HTTP_405 = new HttpError(405, "Method Not Allowed");
const HTTP_406 = new HttpError(406, "Not Acceptable");
const HTTP_407 = new HttpError(407, "Proxy Authentication Required");
const HTTP_408 = new HttpError(408, "Request Timeout");
const HTTP_409 = new HttpError(409, "Conflict");
const HTTP_410 = new HttpError(410, "Gone");
const HTTP_411 = new HttpError(411, "Length Required");
const HTTP_412 = new HttpError(412, "Precondition Failed");
const HTTP_413 = new HttpError(413, "Request Entity Too Large");
const HTTP_414 = new HttpError(414, "Request-URI Too Long");
const HTTP_415 = new HttpError(415, "Unsupported Media Type");
const HTTP_416 = new HttpError(416, "Requested Range Not Satisfiable");
const HTTP_417 = new HttpError(417, "Expectation Failed");

const HTTP_500 = new HttpError(500, "Internal Server Error");
const HTTP_501 = new HttpError(501, "Not Implemented");
const HTTP_502 = new HttpError(502, "Bad Gateway");
const HTTP_503 = new HttpError(503, "Service Unavailable");
const HTTP_504 = new HttpError(504, "Gateway Timeout");
const HTTP_505 = new HttpError(505, "HTTP Version Not Supported");

function array2obj(arr)
{
  var obj = {};
  for (var i = 0; i < arr.length; i++)
    obj[arr[i]] = arr[i];
  return obj;
}

function range(x, y)
{
  var arr = [];
  for (var i = x; i <= y; i++)
    arr.push(i);
  return arr;
}

const HTTP_ERROR_CODES = array2obj(range(400, 417).concat(range(500, 505)));


const HIDDEN_CHAR = "^";

const HEADERS_SUFFIX = HIDDEN_CHAR + "headers" + HIDDEN_CHAR;

const SJS_TYPE = "sjs";


function dumpn(str)
{
  if (DEBUG)
    dump(str + "\n");
}

function dumpStack()
{
  // peel off the frames for dumpStack() and Error()
  var stack = new Error().stack.split(/\n/).slice(2);
  stack.forEach(dumpn);
}


var gThreadManager = null;

var gRootPrefBranch = null;
function getRootPrefBranch()
{
  if (!gRootPrefBranch)
  {
    gRootPrefBranch = Cc["@mozilla.org/preferences-service;1"]
                        .getService(Ci.nsIPrefBranch);
  }
  return gRootPrefBranch;
}

const ServerSocket = CC("@mozilla.org/network/server-socket;1",
                        "nsIServerSocket",
                        "init");
const BinaryInputStream = CC("@mozilla.org/binaryinputstream;1",
                             "nsIBinaryInputStream",
                             "setInputStream");
const BinaryOutputStream = CC("@mozilla.org/binaryoutputstream;1",
                             "nsIBinaryOutputStream",
                             "setOutputStream");
const ScriptableInputStream = CC("@mozilla.org/scriptableinputstream;1",
                                 "nsIScriptableInputStream",
                                 "init");
const Pipe = CC("@mozilla.org/pipe;1",
                "nsIPipe",
                "init");
const FileInputStream = CC("@mozilla.org/network/file-input-stream;1",
                           "nsIFileInputStream",
                           "init");
const ConverterInputStream = CC("@mozilla.org/intl/converter-input-stream;1",
                                "nsIConverterInputStream",
                                "init");
const WritablePropertyBag = CC("@mozilla.org/hash-property-bag;1",
                               "nsIWritablePropertyBag2");
const SupportsString = CC("@mozilla.org/supports-string;1",
                          "nsISupportsString");


function toDateString(date)
{
  //
  // rfc1123-date = wkday "," SP date1 SP time SP "GMT"
  // date1        = 2DIGIT SP month SP 4DIGIT
  //                ; day month year (e.g., 02 Jun 1982)
  // time         = 2DIGIT ":" 2DIGIT ":" 2DIGIT
  //                ; 00:00:00 - 23:59:59
  // wkday        = "Mon" | "Tue" | "Wed"
  //              | "Thu" | "Fri" | "Sat" | "Sun"
  // month        = "Jan" | "Feb" | "Mar" | "Apr"
  //              | "May" | "Jun" | "Jul" | "Aug"
  //              | "Sep" | "Oct" | "Nov" | "Dec"
  //

  const wkdayStrings = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
  const monthStrings = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
                        "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

  function toTime(date)
  {
    var hrs = date.getUTCHours();
    var rv  = (hrs < 10) ? "0" + hrs : hrs;
    
    var mins = date.getUTCMinutes();
    rv += ":";
    rv += (mins < 10) ? "0" + mins : mins;

    var secs = date.getUTCSeconds();
    rv += ":";
    rv += (secs < 10) ? "0" + secs : secs;

    return rv;
  }

  function toDate1(date)
  {
    var day = date.getUTCDate();
    var month = date.getUTCMonth();
    var year = date.getUTCFullYear();

    var rv = (day < 10) ? "0" + day : day;
    rv += " " + monthStrings[month];
    rv += " " + year;

    return rv;
  }

  date = new Date(date);

  const fmtString = "%wkday%, %date1% %time% GMT";
  var rv = fmtString.replace("%wkday%", wkdayStrings[date.getUTCDay()]);
  rv = rv.replace("%time%", toTime(date));
  return rv.replace("%date1%", toDate1(date));
}

function printObj(o, showMembers)
{
  var s = "******************************\n";
  s +=    "o = {\n";
  for (var i in o)
  {
    if (typeof(i) != "string" ||
        (showMembers || (i.length > 0 && i[0] != "_")))
      s+= "      " + i + ": " + o[i] + ",\n";
  }
  s +=    "    };\n";
  s +=    "******************************";
  dumpn(s);
}

function nsHttpServer()
{
  if (!gThreadManager)
    gThreadManager = Cc["@mozilla.org/thread-manager;1"].getService();

  this._port = undefined;

  this._socket = null;

  this._handler = new ServerHandler(this);

  this._identity = new ServerIdentity();

  this._doQuit = false;

  this._socketClosed = true;

  this._connectionGen = 0;

  this._connections = {};
}
nsHttpServer.prototype =
{
  // NSISERVERSOCKETLISTENER

  onSocketAccepted: function(socket, trans)
  {
    dumpn("*** onSocketAccepted(socket=" + socket + ", trans=" + trans + ")");

    dumpn(">>> new connection on " + trans.host + ":" + trans.port);

    const SEGMENT_SIZE = 8192;
    const SEGMENT_COUNT = 1024;
    try
    {
      var input = trans.openInputStream(0, SEGMENT_SIZE, SEGMENT_COUNT)
                       .QueryInterface(Ci.nsIAsyncInputStream);
      var output = trans.openOutputStream(Ci.nsITransport.OPEN_BLOCKING, 0, 0);
    }
    catch (e)
    {
      dumpn("*** error opening transport streams: " + e);
      trans.close(Cr.NS_BINDING_ABORTED);
      return;
    }

    var connectionNumber = ++this._connectionGen;

    try
    {
      var conn = new Connection(input, output, this, socket.port, trans.port,
                                connectionNumber);
      var reader = new RequestReader(conn);

      // XXX add request timeout functionality here!

      // Note: must use main thread here, or we might get a GC that will cause
      //       threadsafety assertions.  We really need to fix XPConnect so that
      //       you can actually do things in multi-threaded JS.  :-(
      input.asyncWait(reader, 0, 0, gThreadManager.mainThread);
    }
    catch (e)
    {
      // Assume this connection can't be salvaged and bail on it completely;
      // don't attempt to close it so that we can assert that any connection
      // being closed is in this._connections.
      dumpn("*** error in initial request-processing stages: " + e);
      trans.close(Cr.NS_BINDING_ABORTED);
      return;
    }

    this._connections[connectionNumber] = conn;
    dumpn("*** starting connection " + connectionNumber);
  },

  onStopListening: function(socket, status)
  {
    dumpn(">>> shutting down server on port " + socket.port);
    this._socketClosed = true;
    if (!this._hasOpenConnections())
    {
      dumpn("*** no open connections, notifying async from onStopListening");

      // Notify asynchronously so that any pending teardown in stop() has a
      // chance to run first.
      var self = this;
      var stopEvent =
        {
          run: function()
          {
            dumpn("*** _notifyStopped async callback");
            self._notifyStopped();
          }
        };
      gThreadManager.currentThread
                    .dispatch(stopEvent, Ci.nsIThread.DISPATCH_NORMAL);
    }
  },

  // NSIHTTPSERVER

  //
  // see nsIHttpServer.start
  //
  start: function(port)
  {
    if (this._socket)
      throw Cr.NS_ERROR_ALREADY_INITIALIZED;

    this._port = port;
    this._doQuit = this._socketClosed = false;

    // The listen queue needs to be long enough to handle
    // network.http.max-connections-per-server concurrent connections,
    // plus a safety margin in case some other process is talking to
    // the server as well.
    var prefs = getRootPrefBranch();
    var maxConnections =
      prefs.getIntPref("network.http.max-connections-per-server") + 5;

    try
    {
      var socket = new ServerSocket(this._port,
                                    true, // loopback only
                                    maxConnections);
      dumpn(">>> listening on port " + socket.port + ", " + maxConnections +
            " pending connections");
      socket.asyncListen(this);
      this._identity._initialize(port, true);
      this._socket = socket;
    }
    catch (e)
    {
      dumpn("!!! could not start server on port " + port + ": " + e);
      throw Cr.NS_ERROR_NOT_AVAILABLE;
    }
  },

  //
  // see nsIHttpServer.stop
  //
  stop: function(callback)
  {
    if (!callback)
      throw Cr.NS_ERROR_NULL_POINTER;
    if (!this._socket)
      throw Cr.NS_ERROR_UNEXPECTED;

    this._stopCallback = typeof callback === "function"
                       ? callback
                       : function() { callback.onStopped(); };

    dumpn(">>> stopping listening on port " + this._socket.port);
    this._socket.close();
    this._socket = null;

    // We can't have this identity any more, and the port on which we're running
    // this server now could be meaningless the next time around.
    this._identity._teardown();

    this._doQuit = false;

    // socket-close notification and pending request completion happen async
  },

  //
  // see nsIHttpServer.registerFile
  //
  registerFile: function(path, file)
  {
    if (file && (!file.exists() || file.isDirectory()))
      throw Cr.NS_ERROR_INVALID_ARG;

    this._handler.registerFile(path, file);
  },

  //
  // see nsIHttpServer.registerDirectory
  //
  registerDirectory: function(path, directory)
  {
    // XXX true path validation!
    if (path.charAt(0) != "/" ||
        path.charAt(path.length - 1) != "/" ||
        (directory &&
         (!directory.exists() || !directory.isDirectory())))
      throw Cr.NS_ERROR_INVALID_ARG;

    // XXX determine behavior of non-existent /foo/bar when a /foo/bar/ mapping
    //     exists!

    this._handler.registerDirectory(path, directory);
  },

  //
  // see nsIHttpServer.registerPathHandler
  //
  registerPathHandler: function(path, handler)
  {
    this._handler.registerPathHandler(path, handler);
  },

  //
  // see nsIHttpServer.registerPrefixHandler
  //
  registerPrefixHandler: function(prefix, handler)
  {
    this._handler.registerPrefixHandler(prefix, handler);
  },

  //
  // see nsIHttpServer.registerErrorHandler
  //
  registerErrorHandler: function(code, handler)
  {
    this._handler.registerErrorHandler(code, handler);
  },

  //
  // see nsIHttpServer.setIndexHandler
  //
  setIndexHandler: function(handler)
  {
    this._handler.setIndexHandler(handler);
  },

  //
  // see nsIHttpServer.registerContentType
  //
  registerContentType: function(ext, type)
  {
    this._handler.registerContentType(ext, type);
  },

  //
  // see nsIHttpServer.serverIdentity
  //
  get identity()
  {
    return this._identity;
  },

  //
  // see nsIHttpServer.getState
  //
  getState: function(path, k)
  {
    return this._handler._getState(path, k);
  },

  //
  // see nsIHttpServer.setState
  //
  setState: function(path, k, v)
  {
    return this._handler._setState(path, k, v);
  },

  //
  // see nsIHttpServer.getSharedState
  //
  getSharedState: function(k)
  {
    return this._handler._getSharedState(k);
  },

  //
  // see nsIHttpServer.setSharedState
  //
  setSharedState: function(k, v)
  {
    return this._handler._setSharedState(k, v);
  },

  //
  // see nsIHttpServer.getObjectState
  //
  getObjectState: function(k)
  {
    return this._handler._getObjectState(k);
  },

  //
  // see nsIHttpServer.setObjectState
  //
  setObjectState: function(k, v)
  {
    return this._handler._setObjectState(k, v);
  },


  // NSISUPPORTS

  //
  // see nsISupports.QueryInterface
  //
  QueryInterface: function(iid)
  {
    if (iid.equals(Ci.nsIHttpServer) ||
        iid.equals(Ci.nsIServerSocketListener) ||
        iid.equals(Ci.nsISupports))
      return this;

    throw Cr.NS_ERROR_NO_INTERFACE;
  },


  // NON-XPCOM PUBLIC API

  isStopped: function()
  {
    return this._socketClosed && !this._hasOpenConnections();
  },

  // PRIVATE IMPLEMENTATION

  _hasOpenConnections: function()
  {
    //
    // If we have any open connections, they're tracked as numeric properties on
    // |this._connections|.  The non-standard __count__ property could be used
    // to check whether there are any properties, but standard-wise, even
    // looking forward to ES5, there's no less ugly yet still O(1) way to do
    // this.
    //
    for (var n in this._connections)
      return true;
    return false;
  },

  _notifyStopped: function()
  {
    NS_ASSERT(this._stopCallback !== null, "double-notifying?");
    NS_ASSERT(!this._hasOpenConnections(), "should be done serving by now");

    //
    // NB: We have to grab this now, null out the member, *then* call the
    //     callback here, or otherwise the callback could (indirectly) futz with
    //     this._stopCallback by starting and immediately stopping this, at
    //     which point we'd be nulling out a field we no longer have a right to
    //     modify.
    //
    var callback = this._stopCallback;
    this._stopCallback = null;
    try
    {
      callback();
    }
    catch (e)
    {
      // not throwing because this is specified as being usually (but not
      // always) asynchronous
      dump("!!! error running onStopped callback: " + e + "\n");
    }
  },

  _connectionClosed: function(connection)
  {
    NS_ASSERT(connection.number in this._connections,
              "closing a connection " + this + " that we never added to the " +
              "set of open connections?");
    NS_ASSERT(this._connections[connection.number] === connection,
              "connection number mismatch?  " +
              this._connections[connection.number]);
    delete this._connections[connection.number];

    // Fire a pending server-stopped notification if it's our responsibility.
    if (!this._hasOpenConnections() && this._socketClosed)
      this._notifyStopped();
  },

  _requestQuit: function()
  {
    dumpn(">>> requesting a quit");
    dumpStack();
    this._doQuit = true;
  }
};


//
// RFC 2396 section 3.2.2:
//
// host        = hostname | IPv4address
// hostname    = *( domainlabel "." ) toplabel [ "." ]
// domainlabel = alphanum | alphanum *( alphanum | "-" ) alphanum
// toplabel    = alpha | alpha *( alphanum | "-" ) alphanum
// IPv4address = 1*digit "." 1*digit "." 1*digit "." 1*digit
//

const HOST_REGEX =
  new RegExp("^(?:" +
               // *( domainlabel "." )
               "(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)*" +
               // toplabel
               "[a-z](?:[a-z0-9-]*[a-z0-9])?" +
             "|" +
               // IPv4 address 
               "\\d+\\.\\d+\\.\\d+\\.\\d+" +
             ")$",
             "i");


function ServerIdentity()
{
  this._primaryScheme = "http";

  this._primaryHost = "127.0.0.1"

  this._primaryPort = -1;

  this._defaultPort = -1;

  this._locations = { "xlocalhost": {} };
}
ServerIdentity.prototype =
{
  _initialize: function(port, addSecondaryDefault)
  {
    if (this._primaryPort !== -1)
      this.add("http", "localhost", port);
    else
      this.setPrimary("http", "localhost", port);
    this._defaultPort = port;

    // Only add this if we're being called at server startup
    if (addSecondaryDefault)
      this.add("http", "127.0.0.1", port);
  },

  _teardown: function()
  {
    // Not the default primary location, nothing special to do here
    this.remove("http", "127.0.0.1", this._defaultPort);

    // This is a *very* tricky bit of reasoning here; make absolutely sure the
    // tests for this code pass before you commit changes to it.
    if (this._primaryScheme == "http" &&
        this._primaryHost == "localhost" &&
        this._primaryPort == this._defaultPort)
    {
      // Make sure we don't trigger the readding logic in .remove(), then remove
      // the default location.
      var port = this._defaultPort;
      this._defaultPort = -1;
      this.remove("http", "localhost", port);

      // Ensure a server start triggers the setPrimary() path in ._initialize()
      this._primaryPort = -1;
    }
    else
    {
      // No reason not to remove directly as it's not our primary location
      this.remove("http", "localhost", this._defaultPort);
    }
  },

  //
  // see nsIHttpServerIdentity.primaryScheme
  //
  get primaryScheme()
  {
    if (this._primaryPort === -1)
      throw Cr.NS_ERROR_NOT_INITIALIZED;
    return this._primaryScheme;
  },

  //
  // see nsIHttpServerIdentity.primaryHost
  //
  get primaryHost()
  {
    if (this._primaryPort === -1)
      throw Cr.NS_ERROR_NOT_INITIALIZED;
    return this._primaryHost;
  },

  //
  // see nsIHttpServerIdentity.primaryPort
  //
  get primaryPort()
  {
    if (this._primaryPort === -1)
      throw Cr.NS_ERROR_NOT_INITIALIZED;
    return this._primaryPort;
  },

  //
  // see nsIHttpServerIdentity.add
  //
  add: function(scheme, host, port)
  {
    this._validate(scheme, host, port);
    
    var entry = this._locations["x" + host];
    if (!entry)
      this._locations["x" + host] = entry = {};

    entry[port] = scheme;
  },

  //
  // see nsIHttpServerIdentity.remove
  //
  remove: function(scheme, host, port)
  {
    this._validate(scheme, host, port);

    var entry = this._locations["x" + host];
    if (!entry)
      return false;

    var present = port in entry;
    delete entry[port];

    if (this._primaryScheme == scheme &&
        this._primaryHost == host &&
        this._primaryPort == port &&
        this._defaultPort !== -1)
    {
      // Always keep at least one identity in existence at any time, unless
      // we're in the process of shutting down (the last condition above).
      this._primaryPort = -1;
      this._initialize(this._defaultPort, false);
    }

    return present;
  },

  //
  // see nsIHttpServerIdentity.has
  //
  has: function(scheme, host, port)
  {
    this._validate(scheme, host, port);

    return "x" + host in this._locations &&
           scheme === this._locations["x" + host][port];
  },
  
  //
  // see nsIHttpServerIdentity.has
  //
  getScheme: function(host, port)
  {
    this._validate("http", host, port);

    var entry = this._locations["x" + host];
    if (!entry)
      return "";

    return entry[port] || "";
  },
  
  //
  // see nsIHttpServerIdentity.setPrimary
  //
  setPrimary: function(scheme, host, port)
  {
    this._validate(scheme, host, port);

    this.add(scheme, host, port);

    this._primaryScheme = scheme;
    this._primaryHost = host;
    this._primaryPort = port;
  },

  _validate: function(scheme, host, port)
  {
    if (scheme !== "http" && scheme !== "https")
    {
      dumpn("*** server only supports http/https schemes: '" + scheme + "'");
      dumpStack();
      throw Cr.NS_ERROR_ILLEGAL_VALUE;
    }
    if (!HOST_REGEX.test(host))
    {
      dumpn("*** unexpected host: '" + host + "'");
      throw Cr.NS_ERROR_ILLEGAL_VALUE;
    }
    if (port < 0 || port > 65535)
    {
      dumpn("*** unexpected port: '" + port + "'");
      throw Cr.NS_ERROR_ILLEGAL_VALUE;
    }
  }
};


function Connection(input, output, server, port, outgoingPort, number)
{
  dumpn("*** opening new connection " + number + " on port " + outgoingPort);

  this.input = input;

  this.output = output;

  this.server = server;

  this.port = port;

  this._outgoingPort = outgoingPort;

  this.number = number;

  this.request = null;

  this._closed = this._processed = false;
}
Connection.prototype =
{
  close: function()
  {
    dumpn("*** closing connection " + this.number +
          " on port " + this._outgoingPort);

    this.input.close();
    this.output.close();
    this._closed = true;

    var server = this.server;
    server._connectionClosed(this);

    // If an error triggered a server shutdown, act on it now
    if (server._doQuit)
      server.stop(function() { /* not like we can do anything better */ });
  },

  process: function(request)
  {
    NS_ASSERT(!this._closed && !this._processed);

    this._processed = true;

    this.request = request;
    this.server._handler.handleResponse(this);
  },

  processError: function(code, request)
  {
    NS_ASSERT(!this._closed && !this._processed);

    this._processed = true;
    this.request = request;
    this.server._handler.handleError(code, this);
  },

  toString: function()
  {
    return "<Connection(" + this.number +
           (this.request ? ", " + this.request.path : "") +"): " +
           (this._closed ? "closed" : "open") + ">";
  }
};



function readBytes(inputStream, count)
{
  return new BinaryInputStream(inputStream).readByteArray(count);
}



const READER_IN_REQUEST_LINE = 0;
const READER_IN_HEADERS      = 1;
const READER_IN_BODY         = 2;
const READER_FINISHED        = 3;


function RequestReader(connection)
{
  this._connection = connection;

  this._data = new LineData();

  this._contentLength = 0;

  this._state = READER_IN_REQUEST_LINE;

  this._metadata = new Request(connection.port);

  this._lastHeaderName = this._lastHeaderValue = undefined;
}
RequestReader.prototype =
{
  // NSIINPUTSTREAMCALLBACK

  onInputStreamReady: function(input)
  {
    dumpn("*** onInputStreamReady(input=" + input + ") on thread " +
          gThreadManager.currentThread + " (main is " +
          gThreadManager.mainThread + ")");
    dumpn("*** this._state == " + this._state);

    // Handle cases where we get more data after a request error has been
    // discovered but *before* we can close the connection.
    var data = this._data;
    if (!data)
      return;

    try
    {
      data.appendBytes(readBytes(input, input.available()));
    }
    catch (e)
    {
      if (e.result !== Cr.NS_BASE_STREAM_CLOSED)
      {
        dumpn("*** WARNING: unexpected error when reading from socket; will " +
              "be treated as if the input stream had been closed");
        dumpn("*** WARNING: actual error was: " + e);
      }

      // We've lost a race -- input has been closed, but we're still expecting
      // to read more data.  available() will throw in this case, and since
      // we're dead in the water now, destroy the connection.
      dumpn("*** onInputStreamReady called on a closed input, destroying " +
            "connection");
      this._connection.close();
      return;
    }

    switch (this._state)
    {
      default:
        NS_ASSERT(false, "invalid state: " + this._state);
        break;

      case READER_IN_REQUEST_LINE:
        if (!this._processRequestLine())
          break;
        /* fall through */

      case READER_IN_HEADERS:
        if (!this._processHeaders())
          break;
        /* fall through */

      case READER_IN_BODY:
        this._processBody();
    }

    if (this._state != READER_FINISHED)
      input.asyncWait(this, 0, 0, gThreadManager.currentThread);
  },

  //
  // see nsISupports.QueryInterface
  //
  QueryInterface: function(aIID)
  {
    if (aIID.equals(Ci.nsIInputStreamCallback) ||
        aIID.equals(Ci.nsISupports))
      return this;

    throw Cr.NS_ERROR_NO_INTERFACE;
  },


  // PRIVATE API

  _processRequestLine: function()
  {
    NS_ASSERT(this._state == READER_IN_REQUEST_LINE);

    // Servers SHOULD ignore any empty line(s) received where a Request-Line
    // is expected (section 4.1).
    var data = this._data;
    var line = {};
    var readSuccess;
    while ((readSuccess = data.readLine(line)) && line.value == "")
      dumpn("*** ignoring beginning blank line...");

    // if we don't have a full line, wait until we do
    if (!readSuccess)
      return false;

    // we have the first non-blank line
    try
    {
      this._parseRequestLine(line.value);
      this._state = READER_IN_HEADERS;
      return true;
    }
    catch (e)
    {
      this._handleError(e);
      return false;
    }
  },

  _processHeaders: function()
  {
    NS_ASSERT(this._state == READER_IN_HEADERS);

    // XXX things to fix here:
    //
    // - need to support RFC 2047-encoded non-US-ASCII characters

    try
    {
      var done = this._parseHeaders();
      if (done)
      {
        var request = this._metadata;

        // XXX this is wrong for requests with transfer-encodings applied to
        //     them, particularly chunked (which by its nature can have no
        //     meaningful Content-Length header)!
        this._contentLength = request.hasHeader("Content-Length")
                            ? parseInt(request.getHeader("Content-Length"), 10)
                            : 0;
        dumpn("_processHeaders, Content-length=" + this._contentLength);

        this._state = READER_IN_BODY;
      }
      return done;
    }
    catch (e)
    {
      this._handleError(e);
      return false;
    }
  },

  _processBody: function()
  {
    NS_ASSERT(this._state == READER_IN_BODY);

    // XXX handle chunked transfer-coding request bodies!

    try
    {
      if (this._contentLength > 0)
      {
        var data = this._data.purge();
        var count = Math.min(data.length, this._contentLength);
        dumpn("*** loading data=" + data + " len=" + data.length +
              " excess=" + (data.length - count));

        var bos = new BinaryOutputStream(this._metadata._bodyOutputStream);
        bos.writeByteArray(data, count);
        this._contentLength -= count;
      }

      dumpn("*** remaining body data len=" + this._contentLength);
      if (this._contentLength == 0)
      {
        this._validateRequest();
        this._state = READER_FINISHED;
        this._handleResponse();
        return true;
      }
      
      return false;
    }
    catch (e)
    {
      this._handleError(e);
      return false;
    }
  },

  _validateRequest: function()
  {
    NS_ASSERT(this._state == READER_IN_BODY);

    dumpn("*** _validateRequest");

    var metadata = this._metadata;
    var headers = metadata._headers;

    // 19.6.1.1 -- servers MUST report 400 to HTTP/1.1 requests w/o Host header
    var identity = this._connection.server.identity;
    if (metadata._httpVersion.atLeast(nsHttpVersion.HTTP_1_1))
    {
      if (!headers.hasHeader("Host"))
      {
        dumpn("*** malformed HTTP/1.1 or greater request with no Host header!");
        throw HTTP_400;
      }

      // If the Request-URI wasn't absolute, then we need to determine our host.
      // We have to determine what scheme was used to access us based on the
      // server identity data at this point, because the request just doesn't
      // contain enough data on its own to do this, sadly.
      if (!metadata._host)
      {
        var host, port;
        var hostPort = headers.getHeader("Host");
        var colon = hostPort.indexOf(":");
        if (colon < 0)
        {
          host = hostPort;
          port = "";
        }
        else
        {
          host = hostPort.substring(0, colon);
          port = hostPort.substring(colon + 1);
        }

        // NB: We allow an empty port here because, oddly, a colon may be
        //     present even without a port number, e.g. "example.com:"; in this
        //     case the default port applies.
        if (!HOST_REGEX.test(host) || !/^\d*$/.test(port))
        {
          dumpn("*** malformed hostname (" + hostPort + ") in Host " +
                "header, 400 time");
          throw HTTP_400;
        }

        // If we're not given a port, we're stuck, because we don't know what
        // scheme to use to look up the correct port here, in general.  Since
        // the HTTPS case requires a tunnel/proxy and thus requires that the
        // requested URI be absolute (and thus contain the necessary
        // information), let's assume HTTP will prevail and use that.
        port = +port || 80;

        var scheme = identity.getScheme(host, port);
        if (!scheme)
        {
          dumpn("*** unrecognized hostname (" + hostPort + ") in Host " +
                "header, 400 time");
          throw HTTP_400;
        }

        metadata._scheme = scheme;
        metadata._host = host;
        metadata._port = port;
      }
    }
    else
    {
      NS_ASSERT(metadata._host === undefined,
                "HTTP/1.0 doesn't allow absolute paths in the request line!");

      metadata._scheme = identity.primaryScheme;
      metadata._host = identity.primaryHost;
      metadata._port = identity.primaryPort;
    }

    NS_ASSERT(identity.has(metadata._scheme, metadata._host, metadata._port),
              "must have a location we recognize by now!");
  },

  _handleError: function(e)
  {
    // Don't fall back into normal processing!
    this._state = READER_FINISHED;

    var server = this._connection.server;
    if (e instanceof HttpError)
    {
      var code = e.code;
    }
    else
    {
      dumpn("!!! UNEXPECTED ERROR: " + e +
            (e.lineNumber ? ", line " + e.lineNumber : ""));

      // no idea what happened -- be paranoid and shut down
      code = 500;
      server._requestQuit();
    }

    // make attempted reuse of data an error
    this._data = null;

    this._connection.processError(code, this._metadata);
  },

  _handleResponse: function()
  {
    NS_ASSERT(this._state == READER_FINISHED);

    // We don't need the line-based data any more, so make attempted reuse an
    // error.
    this._data = null;

    this._connection.process(this._metadata);
  },


  // PARSING

  _parseRequestLine: function(line)
  {
    NS_ASSERT(this._state == READER_IN_REQUEST_LINE);

    dumpn("*** _parseRequestLine('" + line + "')");

    var metadata = this._metadata;

    // clients and servers SHOULD accept any amount of SP or HT characters
    // between fields, even though only a single SP is required (section 19.3)
    var request = line.split(/[ \t]+/);
    if (!request || request.length != 3)
      throw HTTP_400;

    metadata._method = request[0];

    // get the HTTP version
    var ver = request[2];
    var match = ver.match(/^HTTP\/(\d+\.\d+)$/);
    if (!match)
      throw HTTP_400;

    // determine HTTP version
    try
    {
      metadata._httpVersion = new nsHttpVersion(match[1]);
      if (!metadata._httpVersion.atLeast(nsHttpVersion.HTTP_1_0))
        throw "unsupported HTTP version";
    }
    catch (e)
    {
      // we support HTTP/1.0 and HTTP/1.1 only
      throw HTTP_501;
    }


    var fullPath = request[1];
    var serverIdentity = this._connection.server.identity;

    var scheme, host, port;

    if (fullPath.charAt(0) != "/")
    {
      // No absolute paths in the request line in HTTP prior to 1.1
      if (!metadata._httpVersion.atLeast(nsHttpVersion.HTTP_1_1))
        throw HTTP_400;

      try
      {
        var uri = Cc["@mozilla.org/network/io-service;1"]
                    .getService(Ci.nsIIOService)
                    .newURI(fullPath, null, null);
        fullPath = uri.path;
        scheme = uri.scheme;
        host = metadata._host = uri.asciiHost;
        port = uri.port;
        if (port === -1)
        {
          if (scheme === "http")
            port = 80;
          else if (scheme === "https")
            port = 443;
          else
            throw HTTP_400;
        }
      }
      catch (e)
      {
        // If the host is not a valid host on the server, the response MUST be a
        // 400 (Bad Request) error message (section 5.2).  Alternately, the URI
        // is malformed.
        throw HTTP_400;
      }

      if (!serverIdentity.has(scheme, host, port) || fullPath.charAt(0) != "/")
        throw HTTP_400;
    }

    var splitter = fullPath.indexOf("?");
    if (splitter < 0)
    {
      // _queryString already set in ctor
      metadata._path = fullPath;
    }
    else
    {
      metadata._path = fullPath.substring(0, splitter);
      metadata._queryString = fullPath.substring(splitter + 1);
    }

    metadata._scheme = scheme;
    metadata._host = host;
    metadata._port = port;
  },

  _parseHeaders: function()
  {
    NS_ASSERT(this._state == READER_IN_HEADERS);

    dumpn("*** _parseHeaders");

    var data = this._data;

    var headers = this._metadata._headers;
    var lastName = this._lastHeaderName;
    var lastVal = this._lastHeaderValue;

    var line = {};
    while (true)
    {
      NS_ASSERT(!((lastVal === undefined) ^ (lastName === undefined)),
                lastName === undefined ?
                  "lastVal without lastName?  lastVal: '" + lastVal + "'" :
                  "lastName without lastVal?  lastName: '" + lastName + "'");

      if (!data.readLine(line))
      {
        // save any data we have from the header we might still be processing
        this._lastHeaderName = lastName;
        this._lastHeaderValue = lastVal;
        return false;
      }

      var lineText = line.value;
      var firstChar = lineText.charAt(0);

      // blank line means end of headers
      if (lineText == "")
      {
        // we're finished with the previous header
        if (lastName)
        {
          try
          {
            headers.setHeader(lastName, lastVal, true);
          }
          catch (e)
          {
            dumpn("*** e == " + e);
            throw HTTP_400;
          }
        }
        else
        {
          // no headers in request -- valid for HTTP/1.0 requests
        }

        // either way, we're done processing headers
        this._state = READER_IN_BODY;
        return true;
      }
      else if (firstChar == " " || firstChar == "\t")
      {
        // multi-line header if we've already seen a header line
        if (!lastName)
        {
          // we don't have a header to continue!
          throw HTTP_400;
        }

        // append this line's text to the value; starts with SP/HT, so no need
        // for separating whitespace
        lastVal += lineText;
      }
      else
      {
        // we have a new header, so set the old one (if one existed)
        if (lastName)
        {
          try
          {
            headers.setHeader(lastName, lastVal, true);
          }
          catch (e)
          {
            dumpn("*** e == " + e);
            throw HTTP_400;
          }
        }

        var colon = lineText.indexOf(":"); // first colon must be splitter
        if (colon < 1)
        {
          // no colon or missing header field-name
          throw HTTP_400;
        }

        // set header name, value (to be set in the next loop, usually)
        lastName = lineText.substring(0, colon);
        lastVal = lineText.substring(colon + 1);
      } // empty, continuation, start of header
    } // while (true)
  }
};


const CR = 0x0D, LF = 0x0A;

function findCRLF(array)
{
  for (var i = array.indexOf(CR); i >= 0; i = array.indexOf(CR, i + 1))
  {
    if (array[i + 1] == LF)
      return i;
  }
  return -1;
}


function LineData()
{
  this._data = [];
}
LineData.prototype =
{
  appendBytes: function(bytes)
  {
    Array.prototype.push.apply(this._data, bytes);
  },

  readLine: function(out)
  {
    var data = this._data;
    var length = findCRLF(data);
    if (length < 0)
      return false;

    //
    // We have the index of the CR, so remove all the characters, including
    // CRLF, from the array with splice, and convert the removed array into the
    // corresponding string, from which we then strip the trailing CRLF.
    //
    // Getting the line in this matter acknowledges that substring is an O(1)
    // operation in SpiderMonkey because strings are immutable, whereas two
    // splices, both from the beginning of the data, are less likely to be as
    // cheap as a single splice plus two extra character conversions.
    //
    var line = String.fromCharCode.apply(null, data.splice(0, length + 2));
    out.value = line.substring(0, length);

    return true;
  },

  purge: function()
  {
    var data = this._data;
    this._data = [];
    return data;
  }
};



function createHandlerFunc(handler)
{
  return function(metadata, response) { handler.handle(metadata, response); };
}


function defaultIndexHandler(metadata, response)
{
  response.setHeader("Content-Type", "text/html", false);

  var path = htmlEscape(decodeURI(metadata.path));

  //
  // Just do a very basic bit of directory listings -- no need for too much
  // fanciness, especially since we don't have a style sheet in which we can
  // stick rules (don't want to pollute the default path-space).
  //

  var body = '<html>\
                <head>\
                  <title>' + path + '</title>\
                </head>\
                <body>\
                  <h1>' + path + '</h1>\
                  <ol style="list-style-type: none">';

  var directory = metadata.getProperty("directory");
  NS_ASSERT(directory && directory.isDirectory());

  var fileList = [];
  var files = directory.directoryEntries;
  while (files.hasMoreElements())
  {
    var f = files.getNext().QueryInterface(Ci.nsIFile);
    var name = f.leafName;
    if (!f.isHidden() &&
        (name.charAt(name.length - 1) != HIDDEN_CHAR ||
         name.charAt(name.length - 2) == HIDDEN_CHAR))
      fileList.push(f);
  }

  fileList.sort(fileSort);

  for (var i = 0; i < fileList.length; i++)
  {
    var file = fileList[i];
    try
    {
      var name = file.leafName;
      if (name.charAt(name.length - 1) == HIDDEN_CHAR)
        name = name.substring(0, name.length - 1);
      var sep = file.isDirectory() ? "/" : "";

      // Note: using " to delimit the attribute here because encodeURIComponent
      //       passes through '.
      var item = '<li><a href="' + encodeURIComponent(name) + sep + '">' +
                   htmlEscape(name) + sep +
                 '</a></li>';

      body += item;
    }
    catch (e) { /* some file system error, ignore the file */ }
  }

  body    += '    </ol>\
                </body>\
              </html>';

  response.bodyOutputStream.write(body, body.length);
}

function fileSort(a, b)
{
  var dira = a.isDirectory(), dirb = b.isDirectory();

  if (dira && !dirb)
    return -1;
  if (dirb && !dira)
    return 1;

  var namea = a.leafName.toLowerCase(), nameb = b.leafName.toLowerCase();
  return nameb > namea ? -1 : 1;
}


function toInternalPath(path, encoded)
{
  if (encoded)
    path = decodeURI(path);

  var comps = path.split("/");
  for (var i = 0, sz = comps.length; i < sz; i++)
  {
    var comp = comps[i];
    if (comp.charAt(comp.length - 1) == HIDDEN_CHAR)
      comps[i] = comp + HIDDEN_CHAR;
  }
  return comps.join("/");
}


function maybeAddHeaders(file, metadata, response)
{
  var name = file.leafName;
  if (name.charAt(name.length - 1) == HIDDEN_CHAR)
    name = name.substring(0, name.length - 1);

  var headerFile = file.parent;
  headerFile.append(name + HEADERS_SUFFIX);

  if (!headerFile.exists())
    return;

  const PR_RDONLY = 0x01;
  var fis = new FileInputStream(headerFile, PR_RDONLY, 0444,
                                Ci.nsIFileInputStream.CLOSE_ON_EOF);

  try
  {
    var lis = new ConverterInputStream(fis, "UTF-8", 1024, 0x0);
    lis.QueryInterface(Ci.nsIUnicharLineInputStream);

    var line = {value: ""};
    var more = lis.readLine(line);

    if (!more && line.value == "")
      return;


    // request line

    var status = line.value;
    if (status.indexOf("HTTP ") == 0)
    {
      status = status.substring(5);
      var space = status.indexOf(" ");
      var code, description;
      if (space < 0)
      {
        code = status;
        description = "";
      }
      else
      {
        code = status.substring(0, space);
        description = status.substring(space + 1, status.length);
      }
    
      response.setStatusLine(metadata.httpVersion, parseInt(code, 10), description);

      line.value = "";
      more = lis.readLine(line);
    }

    // headers
    while (more || line.value != "")
    {
      var header = line.value;
      var colon = header.indexOf(":");

      response.setHeader(header.substring(0, colon),
                         header.substring(colon + 1, header.length),
                         false); // allow overriding server-set headers

      line.value = "";
      more = lis.readLine(line);
    }
  }
  catch (e)
  {
    dumpn("WARNING: error in headers for " + metadata.path + ": " + e);
    throw HTTP_500;
  }
  finally
  {
    fis.close();
  }
}


function ServerHandler(server)
{
  // FIELDS

  this._server = server;

  this._pathDirectoryMap = new FileMap();

  this._overridePaths = {};
  
  this._overridePrefixes = {};

  this._overrideErrors = {};

  this._mimeMappings = {};

  this._indexHandler = defaultIndexHandler;

  this._state = {};

  this._sharedState = {};

  this._objectState = {};
}
ServerHandler.prototype =
{
  // PUBLIC API

  handleResponse: function(connection)
  {
    var request = connection.request;
    var response = new Response(connection);

    var path = request.path;
    dumpn("*** path == " + path);

    try
    {
      try
      {
        if (path in this._overridePaths)
        {
          // explicit paths first, then files based on existing directory mappings,
          // then (if the file doesn't exist) built-in server default paths
          dumpn("calling override for " + path);
          this._overridePaths[path](request, response);
        }
        else
        {
          let longestPrefix = "";
          for (let prefix in this._overridePrefixes)
          {
            if (prefix.length > longestPrefix.length &&
                path.substr(0, prefix.length) == prefix)
            {
              longestPrefix = prefix;
            }
          }
          if (longestPrefix.length > 0)
          {
            dumpn("calling prefix override for " + longestPrefix);
            this._overridePrefixes[longestPrefix](request, response);
          }
          else
          {
            this._handleDefault(request, response);
          }
        }
      }
      catch (e)
      {
        if (response.partiallySent())
        {
          response.abort(e);
          return;
        }

        if (!(e instanceof HttpError))
        {
          dumpn("*** unexpected error: e == " + e);
          throw HTTP_500;
        }
        if (e.code !== 404)
          throw e;

        dumpn("*** default: " + (path in this._defaultPaths));

        response = new Response(connection);
        if (path in this._defaultPaths)
          this._defaultPaths[path](request, response);
        else
          throw HTTP_404;
      }
    }
    catch (e)
    {
      if (response.partiallySent())
      {
        response.abort(e);
        return;
      }

      var errorCode = "internal";

      try
      {
        if (!(e instanceof HttpError))
          throw e;

        errorCode = e.code;
        dumpn("*** errorCode == " + errorCode);

        response = new Response(connection);
        this._handleError(errorCode, request, response);
        return;
      }
      catch (e2)
      {
        dumpn("*** error handling " + errorCode + " error: " +
              "e2 == " + e2 + ", shutting down server");

        connection.server._requestQuit();
        response.abort(e2);
        return;
      }
    }

    response.complete();
  },

  //
  // see nsIHttpServer.registerFile
  //
  registerFile: function(path, file)
  {
    if (!file)
    {
      dumpn("*** unregistering '" + path + "' mapping");
      delete this._overridePaths[path];
      return;
    }

    dumpn("*** registering '" + path + "' as mapping to " + file.path);
    file = file.clone();

    var self = this;
    this._overridePaths[path] =
      function(request, response)
      {
        if (!file.exists())
          throw HTTP_404;

        response.setStatusLine(request.httpVersion, 200, "OK");
        self._writeFileResponse(request, file, response, 0, file.fileSize);
      };
  },

  //
  // see nsIHttpServer.registerPathHandler
  //
  registerPathHandler: function(path, handler)
  {
    // XXX true path validation!
    if (path.charAt(0) != "/")
      throw Cr.NS_ERROR_INVALID_ARG;

    this._handlerToField(handler, this._overridePaths, path);
  },

  //
  // see nsIHttpServer.registerPrefixHandler
  //
  registerPrefixHandler: function(path, handler)
  {
    // XXX true path validation!
    if (path.charAt(0) != "/" || path.charAt(path.length - 1) != "/")
      throw Cr.NS_ERROR_INVALID_ARG;

    this._handlerToField(handler, this._overridePrefixes, path);
  },

  //
  // see nsIHttpServer.registerDirectory
  //
  registerDirectory: function(path, directory)
  {
    // strip off leading and trailing '/' so that we can use lastIndexOf when
    // determining exactly how a path maps onto a mapped directory --
    // conditional is required here to deal with "/".substring(1, 0) being
    // converted to "/".substring(0, 1) per the JS specification
    var key = path.length == 1 ? "" : path.substring(1, path.length - 1);

    // the path-to-directory mapping code requires that the first character not
    // be "/", or it will go into an infinite loop
    if (key.charAt(0) == "/")
      throw Cr.NS_ERROR_INVALID_ARG;

    key = toInternalPath(key, false);

    if (directory)
    {
      dumpn("*** mapping '" + path + "' to the location " + directory.path);
      this._pathDirectoryMap.put(key, directory);
    }
    else
    {
      dumpn("*** removing mapping for '" + path + "'");
      this._pathDirectoryMap.put(key, null);
    }
  },

  //
  // see nsIHttpServer.registerErrorHandler
  //
  registerErrorHandler: function(err, handler)
  {
    if (!(err in HTTP_ERROR_CODES))
      dumpn("*** WARNING: registering non-HTTP/1.1 error code " +
            "(" + err + ") handler -- was this intentional?");

    this._handlerToField(handler, this._overrideErrors, err);
  },

  //
  // see nsIHttpServer.setIndexHandler
  //
  setIndexHandler: function(handler)
  {
    if (!handler)
      handler = defaultIndexHandler;
    else if (typeof(handler) != "function")
      handler = createHandlerFunc(handler);

    this._indexHandler = handler;
  },

  //
  // see nsIHttpServer.registerContentType
  //
  registerContentType: function(ext, type)
  {
    if (!type)
      delete this._mimeMappings[ext];
    else
      this._mimeMappings[ext] = headerUtils.normalizeFieldValue(type);
  },

  // PRIVATE API

  _handlerToField: function(handler, dict, key)
  {
    // for convenience, handler can be a function if this is run from xpcshell
    if (typeof(handler) == "function")
      dict[key] = handler;
    else if (handler)
      dict[key] = createHandlerFunc(handler);
    else
      delete dict[key];
  },

  _handleDefault: function(metadata, response)
  {
    dumpn("*** _handleDefault()");

    response.setStatusLine(metadata.httpVersion, 200, "OK");

    var path = metadata.path;
    NS_ASSERT(path.charAt(0) == "/", "invalid path: <" + path + ">");

    // determine the actual on-disk file; this requires finding the deepest
    // path-to-directory mapping in the requested URL
    var file = this._getFileForPath(path);

    // the "file" might be a directory, in which case we either serve the
    // contained index.html or make the index handler write the response
    if (file.exists() && file.isDirectory())
    {
      file.append("index.html"); // make configurable?
      if (!file.exists() || file.isDirectory())
      {
        metadata._ensurePropertyBag();
        metadata._bag.setPropertyAsInterface("directory", file.parent);
        this._indexHandler(metadata, response);
        return;
      }
    }

    // alternately, the file might not exist
    if (!file.exists())
      throw HTTP_404;

    var start, end;
    if (metadata._httpVersion.atLeast(nsHttpVersion.HTTP_1_1) &&
        metadata.hasHeader("Range") &&
        this._getTypeFromFile(file) !== SJS_TYPE)
    {
      var rangeMatch = metadata.getHeader("Range").match(/^bytes=(\d+)?-(\d+)?$/);
      if (!rangeMatch)
        throw HTTP_400;

      if (rangeMatch[1] !== undefined)
        start = parseInt(rangeMatch[1], 10);

      if (rangeMatch[2] !== undefined)
        end = parseInt(rangeMatch[2], 10);

      if (start === undefined && end === undefined)
        throw HTTP_400;

      // No start given, so the end is really the count of bytes from the
      // end of the file.
      if (start === undefined)
      {
        start = Math.max(0, file.fileSize - end);
        end   = file.fileSize - 1;
      }

      // start and end are inclusive
      if (end === undefined || end >= file.fileSize)
        end = file.fileSize - 1;

      if (start !== undefined && start >= file.fileSize)
        throw HTTP_416;

      if (end < start)
      {
        response.setStatusLine(metadata.httpVersion, 200, "OK");
        start = 0;
        end = file.fileSize - 1;
      }
      else
      {
        response.setStatusLine(metadata.httpVersion, 206, "Partial Content");
        var contentRange = "bytes " + start + "-" + end + "/" + file.fileSize;
        response.setHeader("Content-Range", contentRange);
      }
    }
    else
    {
      start = 0;
      end = file.fileSize - 1;
    }

    // finally...
    dumpn("*** handling '" + path + "' as mapping to " + file.path + " from " +
          start + " to " + end + " inclusive");
    this._writeFileResponse(metadata, file, response, start, end - start + 1);
  },

  _writeFileResponse: function(metadata, file, response, offset, count)
  {
    const PR_RDONLY = 0x01;

    var type = this._getTypeFromFile(file);
    if (type === SJS_TYPE)
    {
      var fis = new FileInputStream(file, PR_RDONLY, 0444,
                                    Ci.nsIFileInputStream.CLOSE_ON_EOF);

      try
      {
        var sis = new ScriptableInputStream(fis);
        var s = Cu.Sandbox(gGlobalObject);
        s.importFunction(dump, "dump");

        // Define a basic key-value state-preservation API across requests, with
        // keys initially corresponding to the empty string.
        var self = this;
        var path = metadata.path;
        s.importFunction(function getState(k)
        {
          return self._getState(path, k);
        });
        s.importFunction(function setState(k, v)
        {
          self._setState(path, k, v);
        });
        s.importFunction(function getSharedState(k)
        {
          return self._getSharedState(k);
        });
        s.importFunction(function setSharedState(k, v)
        {
          self._setSharedState(k, v);
        });
        s.importFunction(function getObjectState(k, callback)
        {
          callback(self._getObjectState(k));
        });
        s.importFunction(function setObjectState(k, v)
        {
          self._setObjectState(k, v);
        });

        try
        {
          // Alas, the line number in errors dumped to console when calling the
          // request handler is simply an offset from where we load the SJS file.
          // Work around this in a reasonably non-fragile way by dynamically
          // getting the line number where we evaluate the SJS file.  Don't
          // separate these two lines!
          var line = new Error().lineNumber;
          Cu.evalInSandbox(sis.read(file.fileSize), s);
        }
        catch (e)
        {
          dumpn("*** syntax error in SJS at " + file.path + ": " + e);
          throw HTTP_500;
        }

        try
        {
          s.handleRequest(metadata, response);
        }
        catch (e)
        {
          dump("*** error running SJS at " + file.path + ": " +
               e + " on line " +
               (e instanceof Error
               ? e.lineNumber + " in httpd.js"
               : (e.lineNumber - line)) + "\n");
          throw HTTP_500;
        }
      }
      finally
      {
        fis.close();
      }
    }
    else
    {
      try
      {
        response.setHeader("Last-Modified",
                           toDateString(file.lastModifiedTime),
                           false);
      }
      catch (e) { /* lastModifiedTime threw, ignore */ }

      response.setHeader("Content-Type", type, false);
      maybeAddHeaders(file, metadata, response);
      response.setHeader("Content-Length", "" + count, false);

      var fis = new FileInputStream(file, PR_RDONLY, 0444,
                                    Ci.nsIFileInputStream.CLOSE_ON_EOF);

      offset = offset || 0;
      count  = count || file.fileSize;
      NS_ASSERT(offset === 0 || offset < file.fileSize, "bad offset");
      NS_ASSERT(count >= 0, "bad count");
      NS_ASSERT(offset + count <= file.fileSize, "bad total data size");

      try
      {
        if (offset !== 0)
        {
          // Seek (or read, if seeking isn't supported) to the correct offset so
          // the data sent to the client matches the requested range.
          if (fis instanceof Ci.nsISeekableStream)
            fis.seek(Ci.nsISeekableStream.NS_SEEK_SET, offset);
          else
            new ScriptableInputStream(fis).read(offset);
        }
      }
      catch (e)
      {
        fis.close();
        throw e;
      }

      function writeMore()
      {
        gThreadManager.currentThread
                      .dispatch(writeData, Ci.nsIThread.DISPATCH_NORMAL);
      }

      var input = new BinaryInputStream(fis);
      var output = new BinaryOutputStream(response.bodyOutputStream);
      var writeData =
        {
          run: function()
          {
            var chunkSize = Math.min(65536, count);
            count -= chunkSize;
            NS_ASSERT(count >= 0, "underflow");

            try
            {
              var data = input.readByteArray(chunkSize);
              NS_ASSERT(data.length === chunkSize,
                        "incorrect data returned?  got " + data.length +
                        ", expected " + chunkSize);
              output.writeByteArray(data, data.length);
              if (count === 0)
              {
                fis.close();
                response.finish();
              }
              else
              {
                writeMore();
              }
            }
            catch (e)
            {
              try
              {
                fis.close();
              }
              finally
              {
                response.finish();
              }
              throw e;
            }
          }
        };

      writeMore();

      // Now that we know copying will start, flag the response as async.
      response.processAsync();
    }
  },

  _getState: function(path, k)
  {
    var state = this._state;
    if (path in state && k in state[path])
      return state[path][k];
    return "";
  },

  _setState: function(path, k, v)
  {
    if (typeof v !== "string")
      throw new Error("non-string value passed");
    var state = this._state;
    if (!(path in state))
      state[path] = {};
    state[path][k] = v;
  },

  _getSharedState: function(k)
  {
    var state = this._sharedState;
    if (k in state)
      return state[k];
    return "";
  },

  _setSharedState: function(k, v)
  {
    if (typeof v !== "string")
      throw new Error("non-string value passed");
    this._sharedState[k] = v;
  },

  _getObjectState: function(k)
  {
    if (typeof k !== "string")
      throw new Error("non-string key passed");
    return this._objectState[k] || null;
  },

  _setObjectState: function(k, v)
  {
    if (typeof k !== "string")
      throw new Error("non-string key passed");
    if (typeof v !== "object")
      throw new Error("non-object value passed");
    if (v && !("QueryInterface" in v))
    {
      throw new Error("must pass an nsISupports; use wrappedJSObject to ease " +
                      "pain when using the server from JS");
    }

    this._objectState[k] = v;
  },

  _getTypeFromFile: function(file)
  {
    try
    {
      var name = file.leafName;
      var dot = name.lastIndexOf(".");
      if (dot > 0)
      {
        var ext = name.slice(dot + 1);
        if (ext in this._mimeMappings)
          return this._mimeMappings[ext];
      }
      return Cc["@mozilla.org/uriloader/external-helper-app-service;1"]
               .getService(Ci.nsIMIMEService)
               .getTypeFromFile(file);
    }
    catch (e)
    {
      return "application/octet-stream";
    }
  },

  _getFileForPath: function(path)
  {
    // decode and add underscores as necessary
    try
    {
      path = toInternalPath(path, true);
    }
    catch (e)
    {
      throw HTTP_400; // malformed path
    }

    // next, get the directory which contains this path
    var pathMap = this._pathDirectoryMap;

    // An example progression of tmp for a path "/foo/bar/baz/" might be:
    // "foo/bar/baz/", "foo/bar/baz", "foo/bar", "foo", ""
    var tmp = path.substring(1);
    while (true)
    {
      // do we have a match for current head of the path?
      var file = pathMap.get(tmp);
      if (file)
      {
        // XXX hack; basically disable showing mapping for /foo/bar/ when the
        //     requested path was /foo/bar, because relative links on the page
        //     will all be incorrect -- we really need the ability to easily
        //     redirect here instead
        if (tmp == path.substring(1) &&
            tmp.length != 0 &&
            tmp.charAt(tmp.length - 1) != "/")
          file = null;
        else
          break;
      }

      // if we've finished trying all prefixes, exit
      if (tmp == "")
        break;

      tmp = tmp.substring(0, tmp.lastIndexOf("/"));
    }

    // no mapping applies, so 404
    if (!file)
      throw HTTP_404;


    // last, get the file for the path within the determined directory
    var parentFolder = file.parent;
    var dirIsRoot = (parentFolder == null);

    // Strategy here is to append components individually, making sure we
    // never move above the given directory; this allows paths such as
    // "<file>/foo/../bar" but prevents paths such as "<file>/../base-sibling";
    // this component-wise approach also means the code works even on platforms
    // which don't use "/" as the directory separator, such as Windows
    var leafPath = path.substring(tmp.length + 1);
    var comps = leafPath.split("/");
    for (var i = 0, sz = comps.length; i < sz; i++)
    {
      var comp = comps[i];

      if (comp == "..")
        file = file.parent;
      else if (comp == "." || comp == "")
        continue;
      else
        file.append(comp);

      if (!dirIsRoot && file.equals(parentFolder))
        throw HTTP_403;
    }

    return file;
  },

  handleError: function(errorCode, connection)
  {
    var response = new Response(connection);

    dumpn("*** error in request: " + errorCode);

    this._handleError(errorCode, new Request(connection.port), response);
  }, 

  _handleError: function(errorCode, metadata, response)
  {
    if (!metadata)
      throw Cr.NS_ERROR_NULL_POINTER;

    var errorX00 = errorCode - (errorCode % 100);

    try
    {
      if (!(errorCode in HTTP_ERROR_CODES))
        dumpn("*** WARNING: requested invalid error: " + errorCode);

      // RFC 2616 says that we should try to handle an error by its class if we
      // can't otherwise handle it -- if that fails, we revert to handling it as
      // a 500 internal server error, and if that fails we throw and shut down
      // the server

      // actually handle the error
      try
      {
        if (errorCode in this._overrideErrors)
          this._overrideErrors[errorCode](metadata, response);
        else
          this._defaultErrors[errorCode](metadata, response);
      }
      catch (e)
      {
        if (response.partiallySent())
        {
          response.abort(e);
          return;
        }

        // don't retry the handler that threw
        if (errorX00 == errorCode)
          throw HTTP_500;

        dumpn("*** error in handling for error code " + errorCode + ", " +
              "falling back to " + errorX00 + "...");
        response = new Response(response._connection);
        if (errorX00 in this._overrideErrors)
          this._overrideErrors[errorX00](metadata, response);
        else if (errorX00 in this._defaultErrors)
          this._defaultErrors[errorX00](metadata, response);
        else
          throw HTTP_500;
      }
    }
    catch (e)
    {
      if (response.partiallySent())
      {
        response.abort();
        return;
      }

      // we've tried everything possible for a meaningful error -- now try 500
      dumpn("*** error in handling for error code " + errorX00 + ", falling " +
            "back to 500...");

      try
      {
        response = new Response(response._connection);
        if (500 in this._overrideErrors)
          this._overrideErrors[500](metadata, response);
        else
          this._defaultErrors[500](metadata, response);
      }
      catch (e2)
      {
        dumpn("*** multiple errors in default error handlers!");
        dumpn("*** e == " + e + ", e2 == " + e2);
        response.abort(e2);
        return;
      }
    }

    response.complete();
  },

  // FIELDS

  _defaultErrors:
  {
    400: function(metadata, response)
    {
      // none of the data in metadata is reliable, so hard-code everything here
      response.setStatusLine("1.1", 400, "Bad Request");
      response.setHeader("Content-Type", "text/plain", false);

      var body = "Bad request\n";
      response.bodyOutputStream.write(body, body.length);
    },
    403: function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 403, "Forbidden");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>403 Forbidden</title></head>\
                    <body>\
                      <h1>403 Forbidden</h1>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    },
    404: function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 404, "Not Found");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>404 Not Found</title></head>\
                    <body>\
                      <h1>404 Not Found</h1>\
                      <p>\
                        <span style='font-family: monospace;'>" +
                          htmlEscape(metadata.path) +
                       "</span> was not found.\
                      </p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    },
    416: function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion,
                            416,
                            "Requested Range Not Satisfiable");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                   <head>\
                    <title>416 Requested Range Not Satisfiable</title></head>\
                    <body>\
                     <h1>416 Requested Range Not Satisfiable</h1>\
                     <p>The byte range was not valid for the\
                        requested resource.\
                     </p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    },
    500: function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion,
                             500,
                             "Internal Server Error");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>500 Internal Server Error</title></head>\
                    <body>\
                      <h1>500 Internal Server Error</h1>\
                      <p>Something's broken in this server and\
                        needs to be fixed.</p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    },
    501: function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 501, "Not Implemented");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>501 Not Implemented</title></head>\
                    <body>\
                      <h1>501 Not Implemented</h1>\
                      <p>This server is not (yet) Apache.</p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    },
    505: function(metadata, response)
    {
      response.setStatusLine("1.1", 505, "HTTP Version Not Supported");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>505 HTTP Version Not Supported</title></head>\
                    <body>\
                      <h1>505 HTTP Version Not Supported</h1>\
                      <p>This server only supports HTTP/1.0 and HTTP/1.1\
                        connections.</p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    }
  },

  _defaultPaths:
  {
    "/": function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 200, "OK");
      response.setHeader("Content-Type", "text/html", false);

      var body = "<html>\
                    <head><title>httpd.js</title></head>\
                    <body>\
                      <h1>httpd.js</h1>\
                      <p>If you're seeing this page, httpd.js is up and\
                        serving requests!  Now set a base path and serve some\
                        files!</p>\
                    </body>\
                  </html>";

      response.bodyOutputStream.write(body, body.length);
    },

    "/trace": function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 200, "OK");
      response.setHeader("Content-Type", "text/plain", false);

      var body = "Request-URI: " +
                 metadata.scheme + "://" + metadata.host + ":" + metadata.port +
                 metadata.path + "\n\n";
      body += "Request (semantically equivalent, slightly reformatted):\n\n";
      body += metadata.method + " " + metadata.path;

      if (metadata.queryString)
        body +=  "?" + metadata.queryString;
        
      body += " HTTP/" + metadata.httpVersion + "\r\n";

      var headEnum = metadata.headers;
      while (headEnum.hasMoreElements())
      {
        var fieldName = headEnum.getNext()
                                .QueryInterface(Ci.nsISupportsString)
                                .data;
        body += fieldName + ": " + metadata.getHeader(fieldName) + "\r\n";
      }

      response.bodyOutputStream.write(body, body.length);
    }
  }
};


function FileMap()
{
  this._map = {};
}
FileMap.prototype =
{
  // PUBLIC API

  put: function(key, value)
  {
    if (value)
      this._map[key] = value.clone();
    else
      delete this._map[key];
  },

  get: function(key)
  {
    var val = this._map[key];
    return val ? val.clone() : null;
  }
};


// Response CONSTANTS

// token       = *<any CHAR except CTLs or separators>
// CHAR        = <any US-ASCII character (0-127)>
// CTL         = <any US-ASCII control character (0-31) and DEL (127)>
// separators  = "(" | ")" | "<" | ">" | "@"
//             | "," | ";" | ":" | "\" | <">
//             | "/" | "[" | "]" | "?" | "="
//             | "{" | "}" | SP  | HT
const IS_TOKEN_ARRAY =
  [0, 0, 0, 0, 0, 0, 0, 0, //   0
   0, 0, 0, 0, 0, 0, 0, 0, //   8
   0, 0, 0, 0, 0, 0, 0, 0, //  16
   0, 0, 0, 0, 0, 0, 0, 0, //  24

   0, 1, 0, 1, 1, 1, 1, 1, //  32
   0, 0, 1, 1, 0, 1, 1, 0, //  40
   1, 1, 1, 1, 1, 1, 1, 1, //  48
   1, 1, 0, 0, 0, 0, 0, 0, //  56

   0, 1, 1, 1, 1, 1, 1, 1, //  64
   1, 1, 1, 1, 1, 1, 1, 1, //  72
   1, 1, 1, 1, 1, 1, 1, 1, //  80
   1, 1, 1, 0, 0, 0, 1, 1, //  88

   1, 1, 1, 1, 1, 1, 1, 1, //  96
   1, 1, 1, 1, 1, 1, 1, 1, // 104
   1, 1, 1, 1, 1, 1, 1, 1, // 112
   1, 1, 1, 0, 1, 0, 1];   // 120


function isCTL(code)
{
  return (code >= 0 && code <= 31) || (code == 127);
}

function Response(connection)
{
  this._connection = connection;

  this._httpVersion = nsHttpVersion.HTTP_1_1;

  this._httpCode = 200;

  this._httpDescription = "OK";

  this._headers = new nsHttpHeaders();

  this._ended = false;

  this._bodyOutputStream = null;

  this._bodyInputStream = null;

  this._asyncCopier = null;

  this._processAsync = false;

  this._finished = false;

  this._powerSeized = false;
}
Response.prototype =
{
  // PUBLIC CONSTRUCTION API

  //
  // see nsIHttpResponse.bodyOutputStream
  //
  get bodyOutputStream()
  {
    if (this._finished)
      throw Cr.NS_ERROR_NOT_AVAILABLE;

    if (!this._bodyOutputStream)
    {
      var pipe = new Pipe(false, false, Response.SEGMENT_SIZE, PR_UINT32_MAX,
                          null);
      this._bodyOutputStream = pipe.outputStream;
      this._bodyInputStream = pipe.inputStream;
      if (this._processAsync || this._powerSeized)
        this._startAsyncProcessor();
    }

    return this._bodyOutputStream;
  },

  //
  // see nsIHttpResponse.write
  //
  write: function(data)
  {
    if (this._finished)
      throw Cr.NS_ERROR_NOT_AVAILABLE;

    var dataAsString = String(data);
    this.bodyOutputStream.write(dataAsString, dataAsString.length);
  },

  //
  // see nsIHttpResponse.setStatusLine
  //
  setStatusLine: function(httpVersion, code, description)
  {
    if (!this._headers || this._finished || this._powerSeized)
      throw Cr.NS_ERROR_NOT_AVAILABLE;
    this._ensureAlive();

    if (!(code >= 0 && code < 1000))
      throw Cr.NS_ERROR_INVALID_ARG;

    try
    {
      var httpVer;
      // avoid version construction for the most common cases
      if (!httpVersion || httpVersion == "1.1")
        httpVer = nsHttpVersion.HTTP_1_1;
      else if (httpVersion == "1.0")
        httpVer = nsHttpVersion.HTTP_1_0;
      else
        httpVer = new nsHttpVersion(httpVersion);
    }
    catch (e)
    {
      throw Cr.NS_ERROR_INVALID_ARG;
    }

    // Reason-Phrase = *<TEXT, excluding CR, LF>
    // TEXT          = <any OCTET except CTLs, but including LWS>
    //
    // XXX this ends up disallowing octets which aren't Unicode, I think -- not
    //     much to do if description is IDL'd as string
    if (!description)
      description = "";
    for (var i = 0; i < description.length; i++)
      if (isCTL(description.charCodeAt(i)) && description.charAt(i) != "\t")
        throw Cr.NS_ERROR_INVALID_ARG;

    // set the values only after validation to preserve atomicity
    this._httpDescription = description;
    this._httpCode = code;
    this._httpVersion = httpVer;
  },

  //
  // see nsIHttpResponse.setHeader
  //
  setHeader: function(name, value, merge)
  {
    if (!this._headers || this._finished || this._powerSeized)
      throw Cr.NS_ERROR_NOT_AVAILABLE;
    this._ensureAlive();

    this._headers.setHeader(name, value, merge);
  },

  //
  // see nsIHttpResponse.processAsync
  //
  processAsync: function()
  {
    if (this._finished)
      throw Cr.NS_ERROR_UNEXPECTED;
    if (this._powerSeized)
      throw Cr.NS_ERROR_NOT_AVAILABLE;
    if (this._processAsync)
      return;
    this._ensureAlive();

    dumpn("*** processing connection " + this._connection.number + " async");
    this._processAsync = true;

    /*
     * Either the bodyOutputStream getter or this method is responsible for
     * starting the asynchronous processor and catching writes of data to the
     * response body of async responses as they happen, for the purpose of
     * forwarding those writes to the actual connection's output stream.
     * If bodyOutputStream is accessed first, calling this method will create
     * the processor (when it first is clear that body data is to be written
     * immediately, not buffered).  If this method is called first, accessing
     * bodyOutputStream will create the processor.  If only this method is
     * called, we'll write nothing, neither headers nor the non-existent body,
     * until finish() is called.  Since that delay is easily avoided by simply
     * getting bodyOutputStream or calling write(""), we don't worry about it.
     */
    if (this._bodyOutputStream && !this._asyncCopier)
      this._startAsyncProcessor();
  },

  //
  // see nsIHttpResponse.seizePower
  //
  seizePower: function()
  {
    if (this._processAsync)
      throw Cr.NS_ERROR_NOT_AVAILABLE;
    if (this._finished)
      throw Cr.NS_ERROR_UNEXPECTED;
    if (this._powerSeized)
      return;
    this._ensureAlive();

    dumpn("*** forcefully seizing power over connection " +
          this._connection.number + "...");

    // Purge any already-written data without sending it.  We could as easily
    // swap out the streams entirely, but that makes it possible to acquire and
    // unknowingly use a stale reference, so we require there only be one of
    // each stream ever for any response to avoid this complication.
    if (this._asyncCopier)
      this._asyncCopier.cancel(Cr.NS_BINDING_ABORTED);
    this._asyncCopier = null;
    if (this._bodyOutputStream)
    {
      var input = new BinaryInputStream(this._bodyInputStream);
      var avail;
      while ((avail = input.available()) > 0)
        input.readByteArray(avail);
    }

    this._powerSeized = true;
    if (this._bodyOutputStream)
      this._startAsyncProcessor();
  },

  //
  // see nsIHttpResponse.finish
  //
  finish: function()
  {
    if (!this._processAsync && !this._powerSeized)
      throw Cr.NS_ERROR_UNEXPECTED;
    if (this._finished)
      return;

    dumpn("*** finishing connection " + this._connection.number);
    this._startAsyncProcessor(); // in case bodyOutputStream was never accessed
    if (this._bodyOutputStream)
      this._bodyOutputStream.close();
    this._finished = true;
  },


  // POST-CONSTRUCTION API (not exposed externally)

  get httpVersion()
  {
    this._ensureAlive();
    return this._httpVersion.toString();
  },

  get httpCode()
  {
    this._ensureAlive();

    var codeString = (this._httpCode < 10 ? "0" : "") +
                     (this._httpCode < 100 ? "0" : "") +
                     this._httpCode;
    return codeString;
  },

  get httpDescription()
  {
    this._ensureAlive();

    return this._httpDescription;
  },

  get headers()
  {
    this._ensureAlive();

    return this._headers;
  },

  //
  // see nsHttpHeaders.getHeader
  //
  getHeader: function(name)
  {
    this._ensureAlive();

    return this._headers.getHeader(name);
  },

  partiallySent: function()
  {
    dumpn("*** partiallySent()");
    return this._processAsync || this._powerSeized;
  },

  complete: function()
  {
    dumpn("*** complete()");
    if (this._processAsync || this._powerSeized)
    {
      NS_ASSERT(this._processAsync ^ this._powerSeized,
                "can't both send async and relinquish power");
      return;
    }

    NS_ASSERT(!this.partiallySent(), "completing a partially-sent response?");

    this._startAsyncProcessor();

    // Now make sure we finish processing this request!
    if (this._bodyOutputStream)
      this._bodyOutputStream.close();
  },

  abort: function(e)
  {
    dumpn("*** abort(<" + e + ">)");

    // This response will be ended by the processor if one was created.
    var copier = this._asyncCopier;
    if (copier)
    {
      // We dispatch asynchronously here so that any pending writes of data to
      // the connection will be deterministically written.  This makes it easier
      // to specify exact behavior, and it makes observable behavior more
      // predictable for clients.  Note that the correctness of this depends on
      // callbacks in response to _waitForData in WriteThroughCopier happening
      // asynchronously with respect to the actual writing of data to
      // bodyOutputStream, as they currently do; if they happened synchronously,
      // an event which ran before this one could write more data to the
      // response body before we get around to canceling the copier.  We have
      // tests for this in test_seizepower.js, however, and I can't think of a
      // way to handle both cases without removing bodyOutputStream access and
      // moving its effective write(data, length) method onto Response, which
      // would be slower and require more code than this anyway.
      gThreadManager.currentThread.dispatch({
        run: function()
        {
          dumpn("*** canceling copy asynchronously...");
          copier.cancel(Cr.NS_ERROR_UNEXPECTED);
        }
      }, Ci.nsIThread.DISPATCH_NORMAL);
    }
    else
    {
      this.end();
    }
  },

  end: function()
  {
    NS_ASSERT(!this._ended, "ending this response twice?!?!");

    this._connection.close();
    if (this._bodyOutputStream)
      this._bodyOutputStream.close();

    this._finished = true;
    this._ended = true;
  },

  // PRIVATE IMPLEMENTATION

  _sendHeaders: function()
  {
    dumpn("*** _sendHeaders()");

    NS_ASSERT(this._headers);
    NS_ASSERT(!this._powerSeized);

    // request-line
    var statusLine = "HTTP/" + this.httpVersion + " " +
                     this.httpCode + " " +
                     this.httpDescription + "\r\n";

    // header post-processing

    var headers = this._headers;
    headers.setHeader("Connection", "close", false);
    headers.setHeader("Server", "httpd.js", false);
    if (!headers.hasHeader("Date"))
      headers.setHeader("Date", toDateString(Date.now()), false);

    // Any response not being processed asynchronously must have an associated
    // Content-Length header for reasons of backwards compatibility with the
    // initial server, which fully buffered every response before sending it.
    // Beyond that, however, it's good to do this anyway because otherwise it's
    // impossible to test behaviors that depend on the presence or absence of a
    // Content-Length header.
    if (!this._processAsync)
    {
      dumpn("*** non-async response, set Content-Length");

      var bodyStream = this._bodyInputStream;
      var avail = bodyStream ? bodyStream.available() : 0;

      // XXX assumes stream will always report the full amount of data available
      headers.setHeader("Content-Length", "" + avail, false);
    }


    // construct and send response
    dumpn("*** header post-processing completed, sending response head...");

    // request-line
    var preamble = statusLine;

    // headers
    var headEnum = headers.enumerator;
    while (headEnum.hasMoreElements())
    {
      var fieldName = headEnum.getNext()
                              .QueryInterface(Ci.nsISupportsString)
                              .data;
      var values = headers.getHeaderValues(fieldName);
      for (var i = 0, sz = values.length; i < sz; i++)
        preamble += fieldName + ": " + values[i] + "\r\n";
    }

    // end request-line/headers
    preamble += "\r\n";

    var connection = this._connection;
    try
    {
      connection.output.write(preamble, preamble.length);
    }
    catch (e)
    {
      // Connection closed already?  Even if not, failure to write the response
      // means we probably will fail later anyway, so in the interests of
      // avoiding exceptions we'll (possibly) close the connection and return.
      dumpn("*** error writing headers to socket: " + e);
      response.end();
      return;
    }

    // Forbid setting any more headers or modifying the request line.
    this._headers = null;
  },

  _startAsyncProcessor: function()
  {
    dumpn("*** _startAsyncProcessor()");

    // Handle cases where we're being called a second time.  The former case
    // happens when this is triggered both by complete() and by processAsync(),
    // while the latter happens when processAsync() in conjunction with sent
    // data causes abort() to be called.
    if (this._asyncCopier || this._ended)
    {
      dumpn("*** ignoring second call to _startAsyncProcessor");
      return;
    }

    // Send headers if they haven't been sent already.
    if (this._headers)
    {
      if (this._powerSeized)
        this._headers = null;
      else
        this._sendHeaders();
      NS_ASSERT(this._headers === null, "_sendHeaders() failed?");
    }

    var response = this;
    var connection = this._connection;

    // If no body data was written, we're done
    if (!this._bodyInputStream)
    {
      dumpn("*** empty body, response finished");
      response.end();
      return;
    }

    var copyObserver =
      {
        onStartRequest: function(request, context)
        {
          dumpn("*** onStartRequest");
        },

        onStopRequest: function(request, cx, statusCode)
        {
          dumpn("*** onStopRequest [status=0x" + statusCode.toString(16) + "]");

          if (statusCode === Cr.NS_BINDING_ABORTED)
          {
            dumpn("*** terminating copy observer without ending the response");
          }
          else
          {
            if (!Components.isSuccessCode(statusCode))
              dumpn("*** WARNING: non-success statusCode in onStopRequest");

            response.end();
          }
        },

        QueryInterface: function(aIID)
        {
          if (aIID.equals(Ci.nsIRequestObserver) ||
              aIID.equals(Ci.nsISupports))
            return this;

          throw Cr.NS_ERROR_NO_INTERFACE;
        }
      };

    dumpn("*** starting async copier of body data...");
    var copier = this._asyncCopier =
      new WriteThroughCopier(this._bodyInputStream, this._connection.output,
                            copyObserver, null);
  },

  _ensureAlive: function()
  {
    NS_ASSERT(!this._ended, "not handling response lifetime correctly");
  }
};

Response.SEGMENT_SIZE = 8192;

function notImplemented()
{
  throw Cr.NS_ERROR_NOT_IMPLEMENTED;
}

function WriteThroughCopier(input, output, observer, context)
{
  if (!input || !output || !observer)
    throw Cr.NS_ERROR_NULL_POINTER;

  this._input = input;

  this._output = new BinaryOutputStream(output);

  this._observer = observer;

  this._context = context;

  this._completed = false;

  this.loadFlags = 0;
  this.loadGroup = null;
  this.name = "response-body-copy";

  this.status = Cr.NS_OK;

  // start copying
  try
  {
    observer.onStartRequest(this, context);
    this._waitForData();
  }
  catch (e)
  {
    dumpn("!!! error starting copy: " + e);
    this.cancel(Cr.NS_ERROR_UNEXPECTED);
  }
}
WriteThroughCopier.prototype =
{
  cancel: function(status)
  {
    dumpn("*** cancel(" + status.toString(16) + ")");

    if (this._completed)
    {
      dumpn("*** ignoring cancel on already-canceled copier...");
      return;
    }

    this._completed = true;
    this.status = status;

    var self = this;
    var cancelEvent =
      {
        run: function()
        {
          dumpn("*** onStopRequest async callback");
          try
          {
            self._observer.onStopRequest(self, self._context, self.status);
          }
          catch (e)
          {
            NS_ASSERT(false, "how are we throwing an exception here?  " + e);
          }
        }
      };
    gThreadManager.currentThread
                  .dispatch(cancelEvent, Ci.nsIThread.DISPATCH_NORMAL);
  },

  isPending: function()
  {
    return !this._completed;
  },

  suspend: notImplemented,
  resume: notImplemented,

  onInputStreamReady: function(input)
  {
    dumpn("*** onInputStreamReady");
    if (this._completed)
    {
      dumpn("*** ignoring stream-ready callback on a canceled copier...");
      return;
    }

    input = new BinaryInputStream(input);
    try
    {
      var avail = input.available();
      var data = input.readByteArray(avail);
      this._output.writeByteArray(data, data.length);
    }
    catch (e)
    {
      if (e === Cr.NS_BASE_STREAM_CLOSED ||
          e.result === Cr.NS_BASE_STREAM_CLOSED)
      {
        this.cancel(Cr.NS_OK);
      }
      else
      {
        dumpn("!!! error copying from input to output: " + e);
        this.cancel(Cr.NS_ERROR_UNEXPECTED);
      }
      return;
    }

    if (avail === 0)
      this.cancel(Cr.NS_OK);
    else
      this._waitForData();
  },

  _waitForData: function()
  {
    dumpn("*** _waitForData");
    this._input.asyncWait(this, 0, 1, gThreadManager.mainThread);
  },

  QueryInterface: function(iid)
  {
    if (iid.equals(Ci.nsIRequest) ||
        iid.equals(Ci.nsISupports) ||
        iid.equals(Ci.nsIInputStreamCallback))
    {
      return this;
    }

    throw Cr.NS_ERROR_NO_INTERFACE;
  }
};


const headerUtils =
{
  normalizeFieldName: function(fieldName)
  {
    if (fieldName == "")
      throw Cr.NS_ERROR_INVALID_ARG;

    for (var i = 0, sz = fieldName.length; i < sz; i++)
    {
      if (!IS_TOKEN_ARRAY[fieldName.charCodeAt(i)])
      {
        dumpn(fieldName + " is not a valid header field name!");
        throw Cr.NS_ERROR_INVALID_ARG;
      }
    }

    return fieldName.toLowerCase();
  },

  normalizeFieldValue: function(fieldValue)
  {
    // field-value    = *( field-content | LWS )
    // field-content  = <the OCTETs making up the field-value
    //                  and consisting of either *TEXT or combinations
    //                  of token, separators, and quoted-string>
    // TEXT           = <any OCTET except CTLs,
    //                  but including LWS>
    // LWS            = [CRLF] 1*( SP | HT )
    //
    // quoted-string  = ( <"> *(qdtext | quoted-pair ) <"> )
    // qdtext         = <any TEXT except <">>
    // quoted-pair    = "\" CHAR
    // CHAR           = <any US-ASCII character (octets 0 - 127)>

    // Any LWS that occurs between field-content MAY be replaced with a single
    // SP before interpreting the field value or forwarding the message
    // downstream (section 4.2); we replace 1*LWS with a single SP
    var val = fieldValue.replace(/(?:(?:\r\n)?[ \t]+)+/g, " ");

    // remove leading/trailing LWS (which has been converted to SP)
    val = val.replace(/^ +/, "").replace(/ +$/, "");

    // that should have taken care of all CTLs, so val should contain no CTLs
    for (var i = 0, len = val.length; i < len; i++)
      if (isCTL(val.charCodeAt(i)))
        throw Cr.NS_ERROR_INVALID_ARG;

    // XXX disallows quoted-pair where CHAR is a CTL -- will not invalidly
    //     normalize, however, so this can be construed as a tightening of the
    //     spec and not entirely as a bug
    return val;
  }
};



function htmlEscape(str)
{
  // this is naive, but it'll work
  var s = "";
  for (var i = 0; i < str.length; i++)
    s += "&#" + str.charCodeAt(i) + ";";
  return s;
}


function nsHttpVersion(versionString)
{
  var matches = /^(\d+)\.(\d+)$/.exec(versionString);
  if (!matches)
    throw "Not a valid HTTP version!";

  this.major = parseInt(matches[1], 10);

  this.minor = parseInt(matches[2], 10);

  if (isNaN(this.major) || isNaN(this.minor) ||
      this.major < 0    || this.minor < 0)
    throw "Not a valid HTTP version!";
}
nsHttpVersion.prototype =
{
  toString: function ()
  {
    return this.major + "." + this.minor;
  },

  equals: function (otherVersion)
  {
    return this.major == otherVersion.major &&
           this.minor == otherVersion.minor;
  },

  atLeast: function(otherVersion)
  {
    return this.major > otherVersion.major ||
           (this.major == otherVersion.major &&
            this.minor >= otherVersion.minor);
  }
};

nsHttpVersion.HTTP_1_0 = new nsHttpVersion("1.0");
nsHttpVersion.HTTP_1_1 = new nsHttpVersion("1.1");


function nsHttpHeaders()
{
  this._headers = {};
}
nsHttpHeaders.prototype =
{
  setHeader: function(fieldName, fieldValue, merge)
  {
    var name = headerUtils.normalizeFieldName(fieldName);
    var value = headerUtils.normalizeFieldValue(fieldValue);

    // The following three headers are stored as arrays because their real-world
    // syntax prevents joining individual headers into a single header using 
    // ",".  See also <http://hg.mozilla.org/mozilla-central/diff/9b2a99adc05e/netwerk/protocol/http/src/nsHttpHeaderArray.cpp#l77>
    if (merge && name in this._headers)
    {
      if (name === "www-authenticate" ||
          name === "proxy-authenticate" ||
          name === "set-cookie") 
      {
        this._headers[name].push(value);
      }
      else 
      {
        this._headers[name][0] += "," + value;
        NS_ASSERT(this._headers[name].length === 1,
            "how'd a non-special header have multiple values?")
      }
    }
    else
    {
      this._headers[name] = [value];
    }
  },

  getHeader: function(fieldName)
  {
    return this.getHeaderValues(fieldName).join("\n");
  },

  getHeaderValues: function(fieldName)
  {
    var name = headerUtils.normalizeFieldName(fieldName);

    if (name in this._headers)
      return this._headers[name];
    else
      throw Cr.NS_ERROR_NOT_AVAILABLE;
  },

  hasHeader: function(fieldName)
  {
    var name = headerUtils.normalizeFieldName(fieldName);
    return (name in this._headers);
  },

  get enumerator()
  {
    var headers = [];
    for (var i in this._headers)
    {
      var supports = new SupportsString();
      supports.data = i;
      headers.push(supports);
    }

    return new nsSimpleEnumerator(headers);
  }
};


function nsSimpleEnumerator(items)
{
  this._items = items;
  this._nextIndex = 0;
}
nsSimpleEnumerator.prototype =
{
  hasMoreElements: function()
  {
    return this._nextIndex < this._items.length;
  },
  getNext: function()
  {
    if (!this.hasMoreElements())
      throw Cr.NS_ERROR_NOT_AVAILABLE;

    return this._items[this._nextIndex++];
  },
  QueryInterface: function(aIID)
  {
    if (Ci.nsISimpleEnumerator.equals(aIID) ||
        Ci.nsISupports.equals(aIID))
      return this;

    throw Cr.NS_ERROR_NO_INTERFACE;
  }
};


function Request(port)
{
  this._method = "";

  this._path = "";

  this._queryString = "";

  this._scheme = "http";

  this._host = undefined;

  this._port = port;

  var bodyPipe = new Pipe(false, false, 0, PR_UINT32_MAX, null);

  this._bodyInputStream = bodyPipe.inputStream;

  this._bodyOutputStream = bodyPipe.outputStream;

  this._headers = new nsHttpHeaders();

  this._bag = null;
}
Request.prototype =
{
  // SERVER METADATA

  //
  // see nsIHttpRequestMetadata.scheme
  //
  get scheme()
  {
    return this._scheme;
  },

  //
  // see nsIHttpRequestMetadata.host
  //
  get host()
  {
    return this._host;
  },

  //
  // see nsIHttpRequestMetadata.port
  //
  get port()
  {
    return this._port;
  },

  // REQUEST LINE

  //
  // see nsIHttpRequestMetadata.method
  //
  get method()
  {
    return this._method;
  },

  //
  // see nsIHttpRequestMetadata.httpVersion
  //
  get httpVersion()
  {
    return this._httpVersion.toString();
  },

  //
  // see nsIHttpRequestMetadata.path
  //
  get path()
  {
    return this._path;
  },

  //
  // see nsIHttpRequestMetadata.queryString
  //
  get queryString()
  {
    return this._queryString;
  },

  // HEADERS

  //
  // see nsIHttpRequestMetadata.getHeader
  //
  getHeader: function(name)
  {
    return this._headers.getHeader(name);
  },

  //
  // see nsIHttpRequestMetadata.hasHeader
  //
  hasHeader: function(name)
  {
    return this._headers.hasHeader(name);
  },

  //
  // see nsIHttpRequestMetadata.headers
  //
  get headers()
  {
    return this._headers.enumerator;
  },

  //
  // see nsIPropertyBag.enumerator
  //
  get enumerator()
  {
    this._ensurePropertyBag();
    return this._bag.enumerator;
  },

  //
  // see nsIHttpRequestMetadata.headers
  //
  get bodyInputStream()
  {
    return this._bodyInputStream;
  },

  //
  // see nsIPropertyBag.getProperty
  //
  getProperty: function(name) 
  {
    this._ensurePropertyBag();
    return this._bag.getProperty(name);
  },
  
  _ensurePropertyBag: function()
  {
    if (!this._bag)
      this._bag = new WritablePropertyBag();
  }
};


// XPCOM trappings

function makeFactory(ctor)
{
  function ci(outer, iid)
  {
    if (outer != null)
      throw Components.results.NS_ERROR_NO_AGGREGATION;
    return (new ctor()).QueryInterface(iid);
  } 

  return {
           createInstance: ci,
           lockFactory: function(lock) { },
           QueryInterface: function(aIID)
           {
             if (Ci.nsIFactory.equals(aIID) ||
                 Ci.nsISupports.equals(aIID))
               return this;
             throw Cr.NS_ERROR_NO_INTERFACE;
           }
         };
}

const module =
{
  // nsISupports
  QueryInterface: function(aIID)
  {
    if (Ci.nsIModule.equals(aIID) ||
        Ci.nsISupports.equals(aIID))
      return this;
    throw Cr.NS_ERROR_NO_INTERFACE;
  },

  // nsIModule
  registerSelf: function(compMgr, fileSpec, location, type)
  {
    compMgr = compMgr.QueryInterface(Ci.nsIComponentRegistrar);
    
    for (var key in this._objects)
    {
      var obj = this._objects[key];
      compMgr.registerFactoryLocation(obj.CID, obj.className, obj.contractID,
                                               fileSpec, location, type);
    }
  },
  unregisterSelf: function (compMgr, location, type)
  {
    compMgr = compMgr.QueryInterface(Ci.nsIComponentRegistrar);

    for (var key in this._objects)
    {
      var obj = this._objects[key];
      compMgr.unregisterFactoryLocation(obj.CID, location);
    }
  },
  getClassObject: function(compMgr, cid, iid)
  {
    if (!iid.equals(Ci.nsIFactory))
      throw Cr.NS_ERROR_NOT_IMPLEMENTED;

    for (var key in this._objects)
    {
      if (cid.equals(this._objects[key].CID))
        return this._objects[key].factory;
    }
    
    throw Cr.NS_ERROR_NO_INTERFACE;
  },
  canUnload: function(compMgr)
  {
    return true;
  },

  // private implementation
  _objects:
  {
    server:
    {
      CID:         Components.ID("{54ef6f81-30af-4b1d-ac55-8ba811293e41}"),
      contractID:  "@mozilla.org/server/jshttp;1",
      className:   "httpd.js server",
      factory:     makeFactory(nsHttpServer)
    }
  }
};


function NSGetModule(compMgr, fileSpec)
{
  return module;
}


function server(port, basePath)
{
  if (basePath)
  {
    var lp = Cc["@mozilla.org/file/local;1"]
               .createInstance(Ci.nsILocalFile);
    lp.initWithPath(basePath);
  }

  // if you're running this, you probably want to see debugging info
  DEBUG = true;

  var srv = new nsHttpServer();
  if (lp)
    srv.registerDirectory("/", lp);
  srv.registerContentType("sjs", SJS_TYPE);
  srv.identity.setPrimary("http", "localhost", port);
  srv.start(port);

  var thread = gThreadManager.currentThread;
  while (!srv.isStopped())
    thread.processNextEvent(true);

  // get rid of any pending requests
  while (thread.hasPendingEvents())
    thread.processNextEvent(true);

  DEBUG = false;
}