/* ***** 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 MozJSHTTP 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 at netwerk/test/TestServ.js)
 *   Christian Biesinger (v2 at netwerk/test/unit/head_http_server.js)
 *   Jeff Walden <jwalden+code@mit.edu> (v3 complete rewrite)
 *
 * 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
 * MozJSHTTP.
 */

const Cc = Components.classes;
const Ci = Components.interfaces;
const Cr = Components.results;

/**
 * A magic return value used to signal that a request was handled correctly.
 */
const EXIT = ["request-handled"];

/** Constructs an HTTP error object. */
function httpError(code, description)
{
  this.code = code;
  this.description = description;
}

/**
 * Errors thrown to trigger specific HTTP server responses.
 */
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");

/** Creates a hash with fields corresponding to the values in arr. */
function array2obj(arr)
{
  var obj = {};
  for (var i = 0; i < arr.length; i++)
    obj[arr[i]] = arr[i];
  return obj;
}

/** Returns an array of the integers x through y, inclusive. */
function range(x, y)
{
  var arr = [];
  for (var i = x; i <= y; i++)
    arr.push(i);
  return arr;
}

/** An object (hash) whose fields are the numbers of all HTTP error codes. */
const HTTP_ERROR_CODES = array2obj(range(400, 417).concat(range(500, 505)));

/**
 * Returns true if debugging is enabled, false otherwise.
 */
function debugEnabled()
{
  return true; // this code's pretty new and has no good set of tests (yet)
}

/** dump(str) with a trailing "\n" */
function dumpn(str)
{
  if (debugEnabled())
    dump(str + "\n");
}


/**
 * Returns the RFC 822/1123 representation of a date.
 *
 * @param date
 *   the date, in milliseconds from midnight (00:00:00), January 1, 1970 GMT
 * @returns
 *   the string specifying the given date
 */
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"];

  /**
   * Processes a date and returns the encoded UTC time as a string according to
   * the format specified in RFC 2616.
   *
   * @param date
   *   the date as a JavaScript Date object
   * @returns
   *   a string of the form "HH:MM:SS", ranging from "00:00:00" to "23:59:59"
   */
  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;
  }

  /**
   * Processes a date and returns the encoded UTC date as a string according to
   * the date1 format specified in RFC 2616.
   *
   * @param date
   *   the date as a JavaScript Date object
   * @returns
   *   a string of the form "HH:MM:SS", ranging from "00:00:00" to "23:59:59"
   */
  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));
}

/**
 * Prints out a human-readable representation of the object o and its fields,
 * omitting those whose names begin with "_" if showMembers != true (to ignore
 * hidden properties exposed via getters/setters).
 */
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);
}

/**
 * Instantiates a new HTTP server.
 */
function nsHttpServer()
{
  /** The port on which this server listens. */
  this._port = undefined;

  /** The socket associated with this. */
  this._socket = null;

  /** The handler used to process requests to this server. */
  this._handler = new ServerHandler(this);

  /**
   * Indicates when the server is to be shut down at the end of the request.
   */
  this._doQuit = false;

  /**
   * True if the socket in this is closed (and closure notifications have been
   * sent and processed if the socket was ever opened), false otherwise.
   */
  this._socketClosed = true;
}
nsHttpServer.prototype =
{
  // NSISERVERSOCKETLISTENER

  /**
   * This function signals that a new connection has been accepted.  It is the
   * method through which all requests must be handled, and by the end of this
   * method any and all response requests must be sent.
   *
   * @see nsIServerSocketListener.onSocketAccepted
   */
  onSocketAccepted: function(serverSocket, transport)
  {
    dumpn(">>> accepted connection on " + transport.host + ":" + transport.port);

    transport = transport.QueryInterface(Ci.nsITransport);
    var input = transport.openInputStream(Ci.nsITransport.OPEN_BLOCKING, 0, 0);
    var output = transport.openOutputStream(Ci.nsITransport.OPEN_BLOCKING, 0, 0);

    this._processConnection(serverSocket.port, input, output);
  },

  /**
   * Called when the socket associated with this is closed.
   *
   * @see nsIServerSocketListener.onStopListening
   */
  onStopListening: function(serverSocket, status)
  {
    dumpn(">>> shutting down server");
    this._socketClosed = true;
  },

  // NSIHTTPSERVER

  //
  // see nsIHttpServer.init
  //
  init: function(port)
  {
    this._port = port;
  },

  //
  // see nsIHttpServer.start
  //
  start: function()
  {
    if (this._socket)
      throw Cr.NS_ERROR_FAILURE;
    if (this._port === undefined)
      throw Cr.NS_ERROR_NOT_INITIALIZED;

    this._doQuit = this._socketClosed = false;

    var socket = Cc["@mozilla.org/network/server-socket;1"]
                   .createInstance(Ci.nsIServerSocket);
    socket.init(this._port,
                true,       // loopback only
                -1);        // default number of pending connections

    dumpn(">>> listening on port " + socket.port);
    socket.asyncListen(this);
    this._socket = socket;
  },

  //
  // see nsIHttpServer.stop
  //
  stop: function()
  {
    if (!this._socket)
      return;

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

    // spin an event loop and wait for the socket-close notification, if we can
    if ("@mozilla.org/thread-manager;1" in Cc)
    {
      var thr = Cc["@mozilla.org/thread-manager;1"]
                  .getService(Ci.nsIThreadManager)
                  .currentThread;
      while (!this._socketClosed)
        thr.processNextEvent(true);
    }
  },

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

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

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

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

  //
  // see nsIHttpServer.setBasePath
  //
  setBasePath: function(lp)
  {
    if (lp &&
        (!lp.exists() || !lp.isDirectory()))
      throw Cr.NS_ERROR_INVALID_ARG;

    this._handler.basePath = lp;
  },

  // 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

  /**
   * Returns true iff this server is not running.
   */
  isStopped: function()
  {
    return this._socketClosed;
  },
  
  // PRIVATE IMPLEMENTATION

  /**
   * Processes an incoming request in inStream served through the given port and
   * writes the response to outStream.
   *
   * @param port
   *   the port on which the request was served
   * @param inStream
   *   an nsIInputStream containing the incoming request
   * @param outStream
   *   the nsIOutputStream to which the response should be written
   */
  _processConnection: function(port, inStream, outStream)
  {
    var metadata = new RequestMetadata();
    metadata.port = port;
    metadata.init(inStream);

    try
    {
      var error = this._handler.handleRequest(outStream, metadata);
      if (error !== EXIT)
        throw new Error("handleRequest returned a non-EXIT value!");
    }
    catch (e)
    {
      dumpn(">>> internal error, shutting down server: " + e);
      dumpn("*** stack trace: " + e.stack);
      this._doQuit = true;
    }

    // close streams
    inStream.close();
    outStream.close();

    // handle possible server quit
    if (this._doQuit)
      this.stop();
  },

  /**
   * Requests that the server be shut down when possible.
   */
  _requestQuit: function()
  {
    dumpn(">>> requesting a quit");
    this._doQuit = true;
  }

};


/**
 * Gets a content-type for the given file, as best as it is possible to do so.
 *
 * @param file
 *   the nsIFile for which to get a file type
 * @returns
 *   the best content-type which can be determined for the file
 */
function getTypeFromFile(file)
{
  try
  {
    var type = Cc["@mozilla.org/uriloader/external-helper-app-service;1"]
                 .getService(Ci.nsIMIMEService)
                 .getTypeFromFile(file);
  }
  catch (e)
  {
    type = "application/octet-stream";
  }
  return type;
}



/**
 * Creates a request-handling function for an nsIHttpRequestHandler object.
 */
function createHandlerFunc(handler)
{
  return function(metadata, response) { handler.handle(metadata, response); };
}


/**
 * An object which handles requests for a server, executing default and
 * overridden behaviors as instructed by the code which uses and manipulates it.
 * Default behavior includes a small set of built-in paths and some support for
 * HTTP error pages for various codes, with fallback to HTTP 500 if those codes
 * fail for any reason.
 *
 * @param srv
 *   the nsHttpServer in which this handler is being used
 */
function ServerHandler(srv)
{
  // FIELDS

  /**
   * The nsHttpServer instance associated with this handler.
   */
  this._server = srv;

  /**
   * Private field storing the base path of the server.  This value should never
   * be directly modified, but it can be used as a handy optimization in cases
   * where the base path is needed but will not be mutated.
   */
  this._basePath = null;

  /** Set to true to shut down the server. */
  this._quitRequested = false;

  /**
   * Custom request handlers for the server in which this resides.  Path-handler
   * pairs are stored as property-value pairs in this property.
   *
   * @see also ServerHandler.prototype._defaultPaths
   */
  this._overridePaths = {};

  /**
   * Custom request handlers for the error handlers in the server in which this
   * resides.  Path-handler pairs are stored as property-value pairs in this
   * property.
   *
   * @see also ServerHandler.prototype._defaultErrors
   */
  this._overrideErrors = {};
}
ServerHandler.prototype =
{
  // PUBLIC API

  /**
   * Handles a request to this server, responding to the request appropriately
   * and initiating server shutdown if necessary.  If the request metadata
   * specifies an error code, the appropriate error response will be sent.
   *
   * @param outStream
   *   an nsIOutputStream to which a response should be written
   * @param metadata
   *   request metadata as generated from the initial request
   * @returns EXIT
   *   when all processing for the request has finished, including if necessary
   *   initiating a server shutdown either in response to any unknown internal
   *   error or in response to a request which intentionally initiates a server
   *   shutdown
   */
  handleRequest: function(outStream, metadata)
  {
    var finished = false;
    var response = new Response();

    // handle any existing error codes
    if (metadata.errorCode)
    {
      dumpn("*** errorCode == " + metadata.errorCode);
      this._handleError(metadata, response);
      return this._end(response, outStream);
    }

    // this handler's server may be shut down by making a request with a query
    // string of "quit=1" -- make this behavior configurable?
    this._quitRequested = metadata.queryString == "quit=1";

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

    try
    {
      // explicit paths first, then files from underneath the set basepath, then
      // (if the file doesn't exist) built-in server default paths
      if (path in this._overridePaths)
        this._overridePaths[path](metadata, response);
      else
      {
        try
        {
          this._handleDefault(metadata, response);
        }
        catch (e)
        {
          response.destroy();
          response = new Response();

          // XXX we really shouldn't have any default paths -- just a / filler
          if (e instanceof httpError && e.code == 404)
          {
            if (path in this._defaultPaths)
              this._defaultPaths[path](metadata, response);
            else
              throw HTTP_404;
          }
          else
            throw e;
        }
      }
    }
    catch (e2)
    {
      if (!(e2 instanceof httpError))
      {
        dumpn("*** internal error: e2 == " + e2);
        throw e2;
      }

      var errorCode = e2.code;
      dumpn("*** errorCode == " + errorCode);

      response.destroy();
      response = new Response();

      metadata.errorCode = errorCode;
      this._handleError(metadata, response);
    }

    return this._end(response, outStream);
  },

  /**
   * Associates a file with a server path so that it is returned by future
   * requests to that path.
   *
   * @param path
   *   the path on the server, which must begin with a "/"
   * @param file
   *   the nsILocalFile representing the file to be served; must be a directory
   */
  registerFile: function(path, file)
  {
    dumpn("*** registering '" + path + "' as mapping to " + file.path);
    const PR_RDONLY = 0x01;

    file = file.clone();

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

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

        try
        {
          try
          {
            response.setHeader("Last-Modified",
                               toDateString(file.lastModifiedTime),
                               false);
          }
          catch (e) { }

          response.setHeader("Content-Type", getTypeFromFile(file), false);

          var fis = Cc["@mozilla.org/network/file-input-stream;1"]
                      .createInstance(Ci.nsIFileInputStream);
          fis.init(file, PR_RDONLY, 0444, Ci.nsIFileInputStream.CLOSE_ON_EOF);
          response.bodyOutputStream.writeFrom(fis, file.fileSize);
          fis.close();
        }
        catch (e)
        {
          // something happened -- destroy the response and rethrow
          response.destroy();
          throw e;
        }
      };
  },

  //
  // see nsIHttpServer.registerPathHandler
  //
  registerPathHandler: function(path, handler)
  {
    // XXX path validation!

    // for convenience, handler can be a function if this is run from xpcshell
    if (typeof(handler) == "function")
      this._overridePaths[path] = handler;
    else
      this._overridePaths[path] = createHandlerFunc(handler);
  },

  /**
   * Registers a custom error page handler.
   *
   * @param err
   *   the valid HTTP error code which is to be handled by handler
   * @param handler
   *   an nsIHttpRequestHandler which will handle the request or a function
   *   which handles requests; error handlers must not throw exceptions
   */
  registerErrorHandler: function(err, handler)
  {
    if (!(err in HTTP_ERROR_CODES))
      dumpn("*** WARNING: registering non-HTTP/1.1 error code " +
            "(" + err + ") handler -- was this intentional?");

    // for convenience, handler can be a function if this is run from xpcshell
    if (typeof(handler) == "function")
      this._overrideErrors[err] = handler;
    else
      this._overrideErrors[err] = createHandlerFunc(handler);
  },

  /**
   * The base path for all requests, allowing for requests to be mapped to a
   * file system location; this property is an nsILocalFile.  Note that setting
   * this property will internally clone and normalize the passed-in file.
   * Getting this property will return a clone of the stored file, so the values
   * returned from accessing this may be safely modified without any cloning.
   */
  set basePath(lp)
  {
    this._basePath = lp.clone();
    this._basePath.normalize();
    return lp;
  },
  get basePath()
  {
    return this._basePath ? this._basePath.clone() : null;
  },

  // PRIVATE API

  /**
   * Handles a request which maps to a file in the local filesystem (if a base
   * path has already been set; otherwise the 404 error is thrown).
   *
   * @param metadata
   *   request-related data as a RequestMetadata object
   * @param response
   *   an uninitialized Response to the given request which must be initialized
   *   by a request handler
   * @throws HTTP_###
   *   if an HTTP error occurred (usually HTTP_404)
   */
  _handleDefault: function(metadata, response)
  {
    // if no base path has been set, then this is a 404
    if (!this._basePath)
      throw HTTP_404;

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

      var path = metadata.path;
      if (path.charAt(0) != "/")
        throw "request path does not start with '/'!";

      path = path.substring(1);

      // XXX Bugs to file:
      // 1. .appendRelativePath on Linux is buggy wrt. "..".
      // 2. .contains on Linux is buggy and does string comparisons without
      //    normalizing
      // 3. .normalize() requires that the file exist on Linux (IDL changes?)

      var file = this.basePath;
      var parentFolder = file.parent;
      var baseIsRoot = (parentFolder == null);

      var comps = path.split("/");
      for (var i = 0; i < comps.length; i++)
      {
        var comp = comps[i];

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

        if (!baseIsRoot && file.equals(parentFolder))
          throw HTTP_403;
        if (file.exists() && file.isSymlink() && !file.equals(this._basePath))
          throw HTTP_501;
      }

      // the file might not exist at this point -- deal
      if (file.exists() && file.isDirectory())
      {
        file.append("index.html");  // make configurable?
        if (!file.exists() ||
            file.isDirectory() ||
            (file.isSymlink() && !file.equals(this._basePath)))
          throw HTTP_501;  // directory listings ftw!
      }

      if (!file.exists())
        throw HTTP_404;


      // finally...

      dumpn("*** handling '/" + path + "' as mapping to " + file.path);

      // set headers
      response.setHeader("Content-Type", getTypeFromFile(file), false);

      try
      {
        response.setHeader("Last-Modified",
                           toDateString(file.lastModifiedTime),
                           false);
      }
      catch (e) { }

      // write file data to the stream
      var fis = Cc["@mozilla.org/network/file-input-stream;1"]
                  .createInstance(Ci.nsIFileInputStream);
      const PR_RDONLY = 0x01;
      fis.init(file, PR_RDONLY, 0444, Ci.nsIFileInputStream.CLOSE_ON_EOF);
      response.bodyOutputStream.writeFrom(fis, file.fileSize);
      fis.close();
    }
    catch (e)
    {
      // something failed, so destroy the Response and rethrow
      response.destroy();
      throw e;
    }
  },

  /**
   * Handles a request which generates the given error code, using the
   * user-defined error handler if one has been set, gracefully falling back to
   * the x00 status code if the code has no handler, and failing to status code
   * 500 if all else fails.
   *
   * @param metadata
   *   metadata for the request, which will often be incomplete since this is an
   *   error -- must have its .errorCode set for the desired error
   * @param response
   *   an uninitialized Response should be initialized when this method
   *   completes with information which represents the desired error code in the
   *   ideal case or a fallback code in abnormal circumstances (i.e., 500 is a
   *   fallback for 505, per HTTP specs)
   */
  _handleError: function(metadata, response)
  {
    if (!metadata)
      throw Cr.NS_ERROR_NULL_POINTER;

    var errorCode = metadata.errorCode;
    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
      if (errorCode in this._overrideErrors)
        this._overrideErrors[errorCode](metadata, response);
      else if (errorCode in this._defaultErrors)
        this._defaultErrors[errorCode](metadata, response);
      else 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)
    {
      response.destroy();
      response = new Response();

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

      try
      {
        if (500 in this._overrideErrors)
          this._overrideErrors[500](metadata, response);
        else
          this._defaultErrors[500](metadata, response);
      }
      catch (e2)
      {
        response.destroy();

        dumpn("*** multiple errors in default error handlers!");
        dumpn("*** e == " + e + ", e2 == " + e2);
        throw e2;
      }
    }
  },

  /**
   * Called when all processing necessary for the current request has completed
   * and response headers and data have been determined.  This method takes
   * those headers and data, sends them to the HTTP client, and halts further
   * processing.  It will also send a quit message to the server if necessary.
   *
   * @param response
   *   a Response object representing the desired response
   * @param outStream
   *   a stream to which the response should be written
   * @returns EXIT
   *   every time the method is called
   */
  _end:  function(response, outStream)
  {
    try
    {
      // post-processing
      response.setHeader("Connection", "close", false);
      response.setHeader("Server", "MozJSHTTP", false);
      response.setHeader("Date", toDateString(Date.now()), false);

      var bodyStream = response.bodyInputStream
                               .QueryInterface(Ci.nsIInputStream);
      var available = bodyStream.available();
      response.setHeader("Content-Length", available, false);


      // construct and send response

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

      // headers
      var head = response.headers;
      var headEnum = head.enumerator;
      while (headEnum.hasMoreElements())
      {
        var fieldName = headEnum.getNext()
                                .QueryInterface(Ci.nsISupportsString)
                                .data;
        preamble += fieldName + ": " + head.getHeader(fieldName) + "\r\n";
      }

      // end request-line/headers
      preamble += "\r\n";
      outStream.write(preamble, preamble.length);

      // body
      outStream.writeFrom(bodyStream, available);
      bodyStream.close();

      if (this._quitRequested)
        this._server._requestQuit();
    }
    finally
    {
      // all done with response
      response.destroy();
    }

    return EXIT;
  },

  // FIELDS

  /**
   * This object contains the default handlers for the various HTTP error codes.
   */
  _defaultErrors:
  {
    400: function(metadata, response)
    {
      // explicit 1.1 here since the request is malformed and might not have
      // defined a HTTP version
      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);
    },
    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 supports HTTP/1.0 and HTTP/1.1 connections.</p>\
                    </body>\
                  </html>";
      response.bodyOutputStream.write(body, body.length);
    }
  },

  /**
   * Contains handlers for the default set of URIs contained in this server.
   */
  _defaultPaths:
  {
    "/": function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 200, "OK");
      response.setHeader("Content-Type", "text/html", false);

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

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

    "/auth": function(metadata, response)
    {
      var body;

      // btoa("guest:guest"), but that function is not available here
      var expectedHeader = "Basic Z3Vlc3Q6Z3Vlc3Q=";
      if (metadata.hasHeader("Authorization") &&
          metadata.getHeader("Authorization") == expectedHeader)
      {
        response.setStatusLine(metadata.httpVersion, 200, "OK, authorized");
        response.setHeader("WWW-Authenticate", 'Basic realm="secret"', false);

        body = "success";
      }
      else
      {
        // didn't know guest:guest, failure
        response.setStatusLine(metadata.httpVersion, 401, "Unauthorized");
        response.setHeader("WWW-Authenticate", 'Basic realm="secret"', false);

        body = "failed";
      }

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

    "/redirect": function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 301, "Moved Permanently");
      response.setHeader("Location",
                         "http://localhost:" + metadata.port + "/",
                         false);

      var body = "Moved\n";
      response.bodyOutputStream.write(body, body.length);
    },

    "/redirectfile": function(metadata, response)
    {
      response.setStatusLine(metadata.httpVersion, 301, "Moved Permanently");
      response.setHeader("Content-Type", "text/plain", false);
      response.setHeader("Location", "file:///etc/", false);

      var body = "Attempted to move to a file URI, but failed.\n";
      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 (semantically equivalent, slightly reformatted):\n\n";
      body += metadata.method + " " + encodeURI(metadata.path);

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

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

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


// 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

/**
 * Represents a response to an HTTP request, encapsulating all details of that
 * response.  This includes all headers, the HTTP version, status code and
 * explanation, and the entity itself.
 */
function Response()
{
  // FIELDS

  /**
   * The HTTP version of this response; defaults to 1.1 if not set by the
   * handler.
   */
  this._httpVersion = new nsHttpVersion("1.1");

  /**
   * The HTTP code of this response; defaults to 200.
   */
  this._httpCode = 200;

  /**
   * The description of the HTTP code in this response; defaults to "OK".
   */
  this._httpCodeDescription = "OK";

  /**
   * An nsIHttpHeaders object in which the headers in this response should be
   * stored.
   */
  this._headers = new nsHttpHeaders();

  /**
   * Set to true when this has its .destroy() method called; further actions on
   * this will then fail.
   */
  this._destroyed = false;

  /**
   * Flipped when this.bodyOutputStream is closed; prevents the file from being
   * reopened after it has data written to it and has been closed.
   */
  this._outputProcessed = false;
}
Response.prototype =
{
  // PUBLIC CONSTRUCTION API

  //
  // see nsIHttpResponse.bodyOutputStream
  //
  get bodyOutputStream()
  {
    this._ensureAlive();

    if (!this._bodyOutputStream && !this._outputProcessed)
    {
      // We'd use nsIPipe here, but then we encounter problems with the size of the
      // socket buffer (it fills up, at which point writing to it hangs waiting for
      // someone to read from it, except that won't happen because reading and
      // writing happens on the same thread -- not a problem with tempfiles)
      var tempFile = Cc["@mozilla.org/file/directory_service;1"]
                       .getService(Components.interfaces.nsIProperties)
                       .get("TmpD", Ci.nsIFile);
      tempFile.append("" + Math.random());
      tempFile.createUnique(Ci.nsIFile.NORMAL_FILE_TYPE, 0644);
      this._tempFile = tempFile; // cache for lazily constructing input stream

      const PR_WRONLY = 0x02;
      var fos = Cc["@mozilla.org/network/file-output-stream;1"]
                  .createInstance(Ci.nsIFileOutputStream);
      fos.init(this._tempFile, PR_WRONLY, 0644, 0);
      var bos = Cc["@mozilla.org/network/buffered-output-stream;1"]
                  .createInstance(Ci.nsIBufferedOutputStream);
      bos.init(fos, 8192); // buffer size is somewhat arbitrary

      this._bodyOutputStream = bos;
    }

    return this._bodyOutputStream;
  },

  //
  // see nsIHttpResponse.setStatusLine
  //
  setStatusLine: function(httpVersion, code, description)
  {
    this._ensureAlive();

    if (httpVersion)
      this._httpVersion = new nsHttpVersion(httpVersion);
    else
      this._httpVersion = new nsHttpVersion("1.1");

    if (code >= 0 && code < 1000)
      this._httpCode = code;
    else
      throw Cr.NS_ERROR_INVALID_ARG;

    this._httpDescription = description;
  },

  //
  // see nsIHttpResponse.setHeader
  //
  setHeader: function(name, value, merge)
  {
    this._ensureAlive();

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

  // POST-CONSTRUCTION API (not exposed externally)

  /**
   * The HTTP version number of this, as a string (e.g. "1.1").
   */
  get httpVersion()
  {
    return this._httpVersion.toString();
  },

  /**
   * The HTTP status code of this response, as a string of three characters per
   * RFC 2616.
   */
  get httpCode()
  {
    var codeString = (this._httpCode < 10 ? "0" : "") +
                     (this._httpCode < 100 ? "0" : "") +
                     this._httpCode;
    return codeString;
  },

  /**
   * The description of the HTTP status code of this response, if any.
   */
  get httpDescription()
  {
    return this._httpDescription;
  },

  /**
   * The headers in this request, as an object implementing nsIHttpHeaders.
   */
  get headers()
  {
    this._ensureAlive();

    return this._headers;
  },

  /**
   * A stream containing the data stored in the body of this request, which is
   * the data written to this.bodyOutputStream.  Accessing this property will
   * prevent further writes to bodyOutputStream and will remove that property
   * from this, so the only time this should be accessed should be after this
   * Response has been fully processed by a request handler.
   */
  get bodyInputStream()
  {
    this._ensureAlive();

    if (this._bodyOutputStream)
    {
      this._bodyOutputStream.close(); // flushes buffered data
      this._bodyOutputStream = null;  // don't try closing again
    }
    if (!this._bodyInputStream && !this._outputProcessed)
    {
      const PR_RDWR = 0x04;
      var bis = Cc["@mozilla.org/network/file-input-stream;1"]
                  .createInstance(Ci.nsIFileInputStream);
      bis.init(this._tempFile, PR_RDWR, 0444,
               Ci.nsIFileInputStream.DELETE_ON_CLOSE || Ci.nsIFileInputStream.CLOSE_ON_EOF);
      delete this._tempFile;

      this._bodyInputStream = bis;
      this._outputProcessed = true;
    }
    return this._bodyInputStream;
  },

  /**
   * Destroys all resources held by this.  After this method is called, no other
   * method or property on this must be accessed.  Although in many situations
   * resources may be automagically cleaned up, it is highly recommended that
   * this method be called whenever a Response is no longer used, both as a
   * precaution and because some implementations may not do so.
   */
  destroy: function()
  {
    if (this._destroyed)
      return;

    if (this._bodyOutputStream)
    {
      this._bodyOutputStream.close();
      this._bodyOutputStream = null;
    }
    if (this._bodyInputStream)
    {
      this._bodyInputStream.close();
      this._bodyInputStream = null;
    }
    if (this._tempFile)
    {
      try
      {
        this._tempFile.remove(true);
      }
      catch (e) { }
      this._tempFile = null;
    }

    this._destroyed = true;
  },

  // PRIVATE IMPLEMENTATION

  /** Ensures that this hasn't had its .destroy() method called. */
  _ensureAlive: function()
  {
    if (this._destroyed)
      throw Cr.NS_ERROR_FAILURE;
  }
};


/**
 * A container for utility functions used with HTTP headers.
 */
const headerUtils =
{
  /**
   * Normalizes fieldName (by converting it to lowercase) and ensures it is a
   * valid header field name (although not necessarily one specified in RFC
   * 2616).
   *
   * @throws
   *   if fieldName does not match the field-name production in RFC 2616
   * @returns
   *   fieldName converted to lowercase if it is a valid header, for characters
   *   where case conversion is possible
   */
  normalizeFieldName: function(fieldName)
  {
     for (var i = 0, sz = fieldName.length; i < sz; i++)
       if (!IS_TOKEN_ARRAY[fieldName.charCodeAt(i)])
         throw fieldName + " is not a valid header field name!";

     return fieldName.toLowerCase();
  },

  /**
   * Ensures that fieldValue is a valid header field value (although not
   * necessarily as specified in RFC 2616 if the corresponding field name is
   * part of the HTTP protocol), normalizes the value if it is, and
   * returns the normalized value.
   *
   * @param fieldValue
   *   a value to be normalized as an HTTP header field value
   * @throws
   *   if fieldValue does not match the field-value production in RFC 2616
   * @returns
   *   fieldValue as a normalized HTTP header field value
   */
  normalizeFieldValue: function(fieldValue)
  {
     // not strictly accurate, but good enough for a start
     return /^[ \t]*(.+?)[ \t]*$/.exec(fieldValue)[1];
  }
};



/**
 * Converts the given string into a string which is safe for use in an HTML
 * context.
 *
 * @param str
 *   the string to make HTML-safe
 * @returns
 *   an HTML-safe version of str
 */
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;
}


/**
 * Constructs an object representing an HTTP version (see section 3.1).
 *
 * @param versoionString
 *   a string of the form "#.#", where # is an non-negative decimal integer with
 *   or without leading zeros
 * @throws
 *   if versionString does not specify a valid HTTP version number
 */
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 =
{
  /**
   * The major version number of this, as a number
   */
  major: undefined,

  /**
   * The minor version number of this, as a number.
   */
  minor: undefined,

  /**
   * Returns the standard string representation of the HTTP version represented
   * by this (e.g., "1.1").
   */
  toString: function ()
  {
    return this.major + "." + this.minor;
  },

  /**
   * Returns true if this represents the same HTTP version as otherVersion,
   * false otherwise.
   */
  equals: function (otherVersion)
  {
    return this.major == otherVersion.major &&
           this.minor == otherVersion.minor;
  }
};

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


/**
 * An object which stores HTTP headers for a request or response.
 *
 * Note that since headers are case-insensitive, this object converts headers to
 * lowercase before storing them.  This allows the getHeader and hasHeader
 * methods to work correctly for any case of a header, but it means that the
 * values returned by .enumerator may not be equal case-sensitively to the
 * values passed to setHeader when adding headers to this.
 */
function nsHttpHeaders()
{
  /**
   * A hash of headers, with header field names as the keys and header field
   * values as the values.  Header field names are case-insensitive, but upon
   * insertion here they are normalized such that the first letter is
   * capitalized and all other letters are lowercase.  Header field values are
   * normalized upon insertion to contain no leading or trailing whitespace.
   *
   * Note also that per RFC 2616, section 4.2, two headers with the same name in
   * a message may be treated as one header with the same field name and a field
   * value consisting of the separate field values joined together with a "," in
   * their original order.  This hash stores multiple headers with the same name
   * in this manner.
   */
  this._headers = {};
}
nsHttpHeaders.prototype =
{
  /**
   * Sets the header represented by name and value in this.
   *
   * @param name
   *   the header name
   * @param value
   *   the header value
   * @throws NS_ERROR_NOT_AVAILABLE
   *   if name or value is not a valid header component
   */
  setHeader: function(fieldName, fieldValue, merge)
  {
    var name = headerUtils.normalizeFieldName(fieldName);
    var value = headerUtils.normalizeFieldValue(fieldValue);

    if (merge && name in this._headers)
      this._headers[name] = this._headers[name] + "," + value;
    else
      this._headers[name] = value;
  },

  /**
   * Returns the value for the header specified by this.
   *
   * @returns
   *   the field value for the given header, possibly with non-semantic changes
   *   (i.e., leading/trailing whitespace stripped, whitespace runs replaced
   *   with spaces, etc.) at the option of the implementation
   * @throws
   *   if the given header does not exist in this or if the given string does
   *   not constitute a valid header field name
   */
  getHeader: function(fieldName)
  {
    var name = headerUtils.normalizeFieldName(fieldName);

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

  /**
   * Returns true if a header with the given field name exists in this, false
   * otherwise.
   *
   * @param fieldName
   *   the field name whose existence is to be determined in this
   * @throws
   *   if the given string does not constitute a valid header field name
   */
  hasHeader: function(fieldName)
  {
    var name = headerUtils.normalizeFieldName(fieldName);
    return (name in this._headers);
  },

  /**
   * Returns a new enumerator over the field names of the headers in this, as
   * nsISupportsStrings.  The names returned will be in lowercase, regardless of
   * how they were input using setHeader (header names are case-insensitive per
   * RFC 2616).
   */
  get enumerator()
  {
    var headers = [];
    for (var i in this._headers)
    {
      var supports = Cc["@mozilla.org/supports-string;1"]
                       .createInstance(Ci.nsISupportsString);
      supports.data = i;
      headers.push(supports);
    }

    return new nsSimpleEnumerator(headers);
  }
};


/**
 * Constructs an nsISimpleEnumerator for the given array of items.
 *
 * @param items
 *   the array of items, which must all implement nsISupports
 */
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;
  }
};


/**
 * Parses a server request into a set of metadata, so far as is possible.  Any
 * detected errors will result in this.errorCode being set to an HTTP error code
 * value.  Users MUST check this value after creation and any external
 * initialization of RequestMetadata objects to ensure that errors are handled
 * correctly.
 *
 * @param input
 *   an nsIInputStream containing the server request
 */
function RequestMetadata(input)
{
  this._method = "";
  this._path = "";
  this._queryString = "";

  /**
   * The headers in this request.
   */
  this._headers = new nsHttpHeaders();

  // initialize all other per-instance variables with default values
  this.port = 0;

  /**
   * The numeric HTTP error, if any, associated with this request.  This value
   * may be set by the constructor but is usually only set by the handler after
   * this has been constructed.  After this has been initialized, this value
   * MUST be checked for errors.
   */
  this.errorCode = 0;
}
RequestMetadata.prototype =
{
  // SERVER METADATA

  /**
   * The port on which the server is running.
   */
  port: 0,

  // 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);
  },

  /**
   * An nsISimpleEnumerator over the headers in this request.  The
   * header field names in the enumerator will be converted to lowercase.
   */
  get headers()
  {
    return this._headers.enumerator;
  },

  // ENTITY

  /**
   * An input stream which contains the body of this request.
   */
  get bodyStream()
  {
    // we want this once we do real request processing; probably requires async
    // stream processing, tho
    return null;
  },

  // PUBLIC CONSTRUCTION API

  errorCode: 0,

  // INITIALIZATION
  init: function(input)
  {
    // XXX this is incredibly un-RFC2616 in every possible way:
    //
    // - probably accepts non-CRLF line endings
    // - no real testing for non-US-ASCII text and throwing in that case
    // - handles POSTs by displaying the URL and throwing away the request entity
    // - headers can be multi-line (section 4.2)
    // - need to support RFC 2047-encoded non-US-ASCII characters
    // - support absolute URLs (requires telling the server its hostname, beyond
    //   just localhost:port and 127.0.0.1:port)
    // - etc.

    // read the input line by line; the first line either tells us the requested
    // path or is empty, in which case the second line contains the path
    var is = Cc["@mozilla.org/intl/converter-input-stream;1"]
               .createInstance(Ci.nsIConverterInputStream);
    is.init(input, "ISO-8859-1", 1024, 0xFFFD);

    var lis = is.QueryInterface(Ci.nsIUnicharLineInputStream);

    // process request line
    var line = {};
    lis.readLine(line);

    // if the server is reading the protocol stream at the beginning of a message
    // and receives a CRLF first, it should ignore the CRLF (section 4.1)
    if (line.value == "")
    {
      dumpn("*** ignoring beginning blank line...");
      lis.readLine(line);
    }

    var request = line.value.split(/ /);
    if (!request || request.length != 3)
    {
      this.errorCode = 400;
      return;
    }

    this._method = request[0];

    // check the HTTP version
    var ver = request[2];
    var match = ver.match(/^HTTP\/(\d+\.\d+)$/);
    if (!match)
    {
      this.errorCode = 400;
      return;
    }

    // reject unrecognized methods
    if (request[0] != "GET" && request[0] != "POST")
    {
      this.errorCode = 501;
      return;
    }

    // determine HTTP version
    try
    {
      this._httpVersion = new nsHttpVersion(match[1]);

      // we support HTTP/1.0 and HTTP/1.1 only
      if (!this._httpVersion.equals(nsHttpVersion.HTTP_1_0) &&
          !this._httpVersion.equals(nsHttpVersion.HTTP_1_1))
        throw "unsupported HTTP version";
    }
    catch (e)
    {
      this.errorCode = 400;
      return;
    }

    try
    {
      var fullPath = decodeURI(request[1]);
    }
    catch (e)
    {
      this.errorCode = 400;
      return;
    }

    var splitPath = fullPath.split(/\?/);
    this._path = splitPath[0];
    this._queryString = splitPath[1] || "";

    // XXX discards the body transmitted with this request!
    var headers = this._headers;
    while (lis.readLine(line), line.value != "")
    {
      var lineText = line.value;
      var colon = lineText.indexOf(":"); // first colon must be splitter
      if (colon < 1)
      {
        // no colon or missing header field-name
        this.errorCode = 400;
        return;
      }

      try
      {
        headers.setHeader(lineText.substring(0, colon),
                          lineText.substring(colon + 1),
                          true);
      }
      catch (e)
      {
        dumpn("*** e == " + e);
        this.errorCode = 400;
        return;
      }
    }

    // 19.6.1.1 -- servers MUST report 400 to HTTP/1.1 requests w/o a Host header
    if (!this._headers.hasHeader("host") &&
        this._httpVersion.equals(nsHttpVersion.HTTP_1_1))
    {
      this.errorCode = 400;
      return;
    }
  }
};


// XPCOM trappings

/**
 * Creates a factory for instances of an object created using the passed-in
 * constructor.
 */
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;
           }
         };
}

/** The XPCOM module containing the HTTP server. */
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:   "MozJSHTTP server",
      factory:     makeFactory(nsHttpServer)
    }
  }
};


/**
 * NSGetModule, so this code can be used as a JS component.  Whether multiple
 * servers can run at once is currently questionable, but the code certainly
 * isn't very far from supporting it.
 */
function NSGetModule(compMgr, fileSpec)
{
  return module;
}


/**
 * Creates a new HTTP server listening for loopback traffic on the given port,
 * starts it, and runs the server until the server processes a shutdown request,
 * spinning an event loop so that events posted by the server's socket are
 * processed.
 *
 * This method is primarily intended for use in running this script from within
 * xpcshell and running a functional HTTP server without having to deal with
 * non-essential details.
 *
 * Note that running multiple servers using variants of this method probably
 * doesn't work, simply due to how the internal event loop is spun and stopped.
 *
 * @note
 *   This method only works with Mozilla 1.9 (i.e., Firefox 3 or trunk code);
 *   you should use this server as a component in Mozilla 1.8.
 * @param port
 *   the port on which the server will run, or -1 if there exists no preference
 *   for a specific port; note that attempting to use some values for this
 *   parameter (particularly those below 1024) may cause this method to throw or
 *   may result in the server being prematurely shut down
 * @param basePath
 *   a local directory from which requests will be served (i.e., if this is
 *   "/home/jwalden/" then a request to /index.html will load
 *   /home/jwalden/index.html); if this is omitted, only the default URLs in
 *   this server implementation will be functional
 */
function server(port, basePath)
{
  if (basePath)
  {
    var lp = Cc["@mozilla.org/file/local;1"]
               .createInstance(Ci.nsILocalFile);
    lp.initWithPath(basePath);
  }

  var srv = new nsHttpServer();
  srv.init(port);
  if (lp)
    srv.setBasePath(lp);
  srv.start();

  var thread = Cc["@mozilla.org/thread-manager;1"]
                 .getService(Ci.nsIThreadManager)
                 .currentThread;
  while (!srv.isStopped())
    thread.processNextEvent(true);

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