gecko/netwerk/test/httpserver/nsIHttpServer.idl

/* ***** 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):
 *   Jeff Walden <jwalden+code@mit.edu>          (original author)
 *   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 ***** */

#include "nsIPropertyBag.idl"

interface nsIInputStream;
interface nsILocalFile;
interface nsIOutputStream;
interface nsISimpleEnumerator;

interface nsIHttpServer;
interface nsIHttpRequestHandler;
interface nsIHttpRequestMetadata;
interface nsIHttpResponse;
interface nsIHttpServerIdentity;

/**
 * An interface which represents an HTTP server.
 */
[scriptable, uuid(DEEDE3E3-B813-4F3F-9C70-948E5700C410)]
interface nsIHttpServer : nsISupports
{
  /**
   * Starts up this server, listening upon the given port.  This method may
   * throw if the process does not have sufficient privileges to open a socket
   * for the given port, and it also throws when called upon a server which has
   * already been started.
   *
   * @param port
   *   the port upon which listening should happen, or -1 if no specific port is
   *   desired
   */
  void start(in long port);

  /**
   * Shuts down this server if it is running; if it is not, this method is a
   * no-op.
   *
   * This method will do its best to return after the socket in this
   * server has been closed and all pending requests have completed being
   * served, but this may or may not actually happen, since in some
   * implementations this may not actually be possible.  Implementations which
   * can make this promise should make it explicit in implementation
   * documentation.
   */
  void stop();

  /**
   * Associates the local file represented by the string file with all requests
   * which match request.
   *
   * @param path
   *   the path which is to be mapped to the given file; must begin with "/" and
   *   be a valid URI path (i.e., no query string, hash reference, etc.)
   * @param file
   *   the file to serve for the given path, or null to remove any mapping that
   *   might exist; this file must exist for the lifetime of the server
   */
  void registerFile(in string path, in nsILocalFile file);

  /**
   * Registers a custom path handler.
   *
   * @param path
   *   the path on the server (beginning with a "/") which is to be handled by
   *   handler; this path must not include a query string or hash component; it
   *   also should usually be canonicalized, since most browsers will do so
   *   before sending otherwise-matching requests
   * @param handler
   *   an object which will handle any requests for the given path, or null to
   *   remove any existing handler; if while the server is running the handler
   *   throws an exception while responding to a request, an HTTP 500 response
   *   will be returned
   * @throws NS_ERROR_INVALID_ARG
   *   if path does not begin with a "/"
   */
  void registerPathHandler(in string path, in nsIHttpRequestHandler handler);

  /**
   * Registers a custom error page handler.
   *
   * @param code
   *   the error code which is to be handled by handler
   * @param handler
   *   an object which will handle any requests which generate the given status
   *   code, or null to remove any existing handler.  If the handler throws an
   *   exception during server operation, fallback is to the genericized error
   *   handler (the x00 version), then to 500, using a user-defined error
   *   handler if one exists or the server default handler otherwise.  Fallback
   *   will never occur from a user-provided handler that throws to the same
   *   handler as provided by the server, e.g. a throwing user 404 falls back to
   *   400, not a server-provided 404 that might not throw.
   * @note
   *   If the error handler handles HTTP 500 and throws, behavior is undefined.
   */
  void registerErrorHandler(in unsigned long code, in nsIHttpRequestHandler handler);

  /**
   * Maps all requests to paths beneath path to the corresponding file beneath
   * dir.
   *
   * @param path
   *   the absolute path on the server against which requests will be served
   *   from dir (e.g., "/", "/foo/", etc.); must begin and end with a forward
   *   slash
   * @param dir
   *   the directory to be used to serve all requests for paths underneath path
   *   (except those further overridden by another, deeper path registered with
   *   another directory); if null, any current mapping for the given path is
   *   removed
   * @throws NS_ERROR_INVALID_ARG
   *   if dir is non-null and does not exist or is not a directory, or if path
   *   does not begin with and end with a forward slash
   */
  void registerDirectory(in string path, in nsILocalFile dir);

  /**
   * Associates files with the given extension with the given Content-Type when
   * served by this server, in the absence of any file-specific information
   * about the desired Content-Type.  If type is empty, removes any extant
   * mapping, if one is present.
   *
   * @throws NS_ERROR_INVALID_ARG
   *   if the given type is not a valid header field value, i.e. if it doesn't
   *   match the field-value production in RFC 2616
   * @note
   *   No syntax checking is done of the given type, beyond ensuring that it is
   *   a valid header field value.  Behavior when not given a string matching
   *   the media-type production in RFC 2616 section 3.7 is undefined.
   *   Implementations may choose to define specific behavior for types which do
   *   not match the production, such as for CGI functionality.
   * @note
   *   Implementations MAY treat type as a trusted argument; users who fail to
   *   generate this string from trusted data risk security vulnerabilities.
   */
  void registerContentType(in string extension, in string type);

  /**
   * Sets the handler used to display the contents of a directory if
   * the directory contains no index page.
   *
   * @param handler
   *   an object which will handle any requests for directories which
   *   do not contain index pages, or null to reset to the default
   *   index handler; if while the server is running the handler
   *   throws an exception while responding to a request, an HTTP 500
   *   response will be returned.  An nsIFile corresponding to the
   *   directory is available from the metadata object passed to the
   *   handler, under the key "directory".
   */
  void setIndexHandler(in nsIHttpRequestHandler handler);

  /** Represents the locations at which this server is reachable. */
  readonly attribute nsIHttpServerIdentity identity;

  /**
   * Retrieves the string associated with the given key in this, for the given
   * path's saved state.  All keys are initially associated with the empty
   * string.
   */
  AString getState(in AString path, in AString key);

  /**
   * Sets the string associated with the given key in this, for the given path's
   * saved state.
   */
  void setState(in AString path, in AString key, in AString value);

  /**
   * Retrieves the string associated with the given key in this, in
   * entire-server saved state.  All keys are initially associated with the
   * empty string.
   */
  AString getSharedState(in AString key);

  /**
   * Sets the string associated with the given key in this, in entire-server
   * saved state.
   */
  void setSharedState(in AString key, in AString value);
};

/**
 * Represents a set of names for a server, one of which is the primary name for
 * the server and the rest of which are secondary.  By default every server will
 * contain ("http", "localhost", port) and ("http", "127.0.0.1", port) as names,
 * where port is what was provided to the corresponding server when started;
 * however, except for their being removed when the corresponding server stops
 * they have no special importance.
 */
[scriptable, uuid(a89de175-ae8e-4c46-91a5-0dba99bbd284)]
interface nsIHttpServerIdentity : nsISupports
{
  /**
   * The primary scheme at which the corresponding server is located, defaulting
   * to 'http'.  This name will be the value of nsIHttpRequestMetadata.scheme
   * for HTTP/1.0 requests.
   *
   * This value is always set when the corresponding server is running.  If the
   * server is not running, this value is set only if it has been set to a
   * non-default name using setPrimary.  In this case reading this value will
   * throw NS_ERROR_NOT_INITIALIZED.
   */
  readonly attribute string primaryScheme;

  /**
   * The primary name by which the corresponding server is known, defaulting to
   * 'localhost'.  This name will be the value of nsIHttpRequestMetadata.host
   * for HTTP/1.0 requests.
   *
   * This value is always set when the corresponding server is running.  If the
   * server is not running, this value is set only if it has been set to a
   * non-default name using setPrimary.  In this case reading this value will
   * throw NS_ERROR_NOT_INITIALIZED.
   */
  readonly attribute string primaryHost;

  /**
   * The primary port on which the corresponding server runs, defaulting to the
   * associated server's port.  This name will be the value of
   * nsIHttpRequestMetadata.port for HTTP/1.0 requests.
   *
   * This value is always set when the corresponding server is running.  If the
   * server is not running, this value is set only if it has been set to a
   * non-default name using setPrimary.  In this case reading this value will
   * throw NS_ERROR_NOT_INITIALIZED.
   */
  readonly attribute long primaryPort;

  /**
   * Adds a location at which this server may be accessed.
   *
   * @throws NS_ERROR_ILLEGAL_VALUE
   *   if scheme or host do not match the scheme or host productions imported
   *   into RFC 2616 from RFC 2396, or if port is not a valid port number
   */
  void add(in string scheme, in string host, in long port);

  /**
   * Removes this name from the list of names by which the corresponding server
   * is known.  If name is also the primary name for the server, the primary
   * name reverts to 'http://127.0.0.1' with the associated server's port.
   *
   * @throws NS_ERROR_ILLEGAL_VALUE
   *   if scheme or host do not match the scheme or host productions imported
   *   into RFC 2616 from RFC 2396, or if port is not a valid port number
   * @returns
   *   true if the given name was a name for this server, false otherwise
   */
  PRBool remove(in string scheme, in string host, in long port);

  /**
   * Returns true if the given name is in this, false otherwise.
   *
   * @throws NS_ERROR_ILLEGAL_VALUE
   *   if scheme or host do not match the scheme or host productions imported
   *   into RFC 2616 from RFC 2396, or if port is not a valid port number
   */
  PRBool has(in string scheme, in string host, in long port);

  /**
   * Returns the scheme for the name with the given host and port, if one is
   * present; otherwise returns the empty string.
   *
   * @throws NS_ERROR_ILLEGAL_VALUE
   *   if host does not match the host production imported into RFC 2616 from
   *   RFC 2396, or if port is not a valid port number
   */
  string getScheme(in string host, in long port);
  
  /**
   * Designates the given name as the primary name in this and adds it to this
   * if it is not already present.
   *
   * @throws NS_ERROR_ILLEGAL_VALUE
   *   if scheme or host do not match the scheme or host productions imported
   *   into RFC 2616 from RFC 2396, or if port is not a valid port number
   */
  void setPrimary(in string scheme, in string host, in long port);
};

/**
 * A representation of a handler for HTTP requests.  The handler is used by
 * calling its .handle method with data for an incoming request; it is the
 * handler's job to use that data as it sees fit to make the desired response.
 *
 * @note
 *   This interface uses the [function] attribute, so you can pass a
 *   script-defined function with the functionality of handle() to any
 *   method which has a nsIHttpRequestHandler parameter, instead of wrapping
 *   it in an otherwise empty object.
 */
[scriptable, function, uuid(2bbb4db7-d285-42b3-a3ce-142b8cc7e139)]
interface nsIHttpRequestHandler : nsISupports
{
  /**
   * Processes the HTTP request represented by metadata and initializes the
   * passed-in response to reflect the correct HTTP response.
   *
   * Note that in some uses of nsIHttpRequestHandler, this method is required to
   * not throw an exception; in the general case, however, this method may throw
   * an exception (causing an HTTP 500 response to occur).
   *
   * @param metadata
   *   data representing an HTTP request
   * @param response
   *   an initially-empty response which must be modified to reflect the data
   *   which should be sent as the response to the request described by metadata
   */
  void handle(in nsIHttpRequestMetadata metadata, in nsIHttpResponse response);
};


/**
 * A representation of the data included in an HTTP request.
 */
[scriptable, uuid(ed8bdb6b-83e0-43aB-a412-a9863bd79394)]
interface nsIHttpRequestMetadata : nsIPropertyBag
{
  /**
   * The request type for this request (see RFC 2616, section 5.1.1).
   */
  readonly attribute string method;

  /**
   * The scheme of the requested path, usually 'http' but might possibly be
   * 'https' if some form of SSL tunneling is in use.  Note that this value
   * cannot be accurately determined unless the incoming request used the
   * absolute-path form of the request line; it defaults to 'http', so only
   * if it is something else can you be entirely certain it's correct.
   */
  readonly attribute string scheme;

  /**
   * The host of the data being requested (e.g. "localhost" for the
   * http://localhost:8080/file resource).  Note that the relevant port on the
   * host is specified in this.port.  This value is in the ASCII character
   * encoding.
   */
  readonly attribute string host;

  /**
   * The port on the server on which the request was received.
   */
  readonly attribute unsigned long port;

  /**
   * The requested path, without any query string (e.g. "/dir/file.txt").  It is
   * guaranteed to begin with a "/".  The individual components in this string
   * are URL-encoded.
   */
  readonly attribute string path;

  /**
   * The URL-encoded query string associated with this request, not including
   * the initial "?", or "" if no query string was present.
   */
  readonly attribute string queryString;

  /**
   * A string containing the HTTP version of the request (i.e., "1.1").  Leading
   * zeros for either component of the version will be omitted.  (In other
   * words, if the request contains the version "1.01", this attribute will be
   * "1.1"; see RFC 2616, section 3.1.)
   */
  readonly attribute string httpVersion;

  /**
   * Returns the value for the header in this request specified by fieldName.
   *
   * @param fieldName
   *   the name of the field whose value is to be gotten; note that since HTTP
   *   header field names are case-insensitive, this method produces equivalent
   *   results for "HeAdER" and "hEADer" as fieldName
   * @returns
   *   the field value for the given header; note that this value may be
   *   normalized (e.g., leading/trailing whitespace removed from the value [or
   *   from the values which make this up, if the header is a comma-separated
   *   list of values], whitespace runs compressed to single spaces, etc.)
   * @throws NS_ERROR_INVALID_ARG
   *   if fieldName does not constitute a valid header field name
   * @throws NS_ERROR_NOT_AVAILABLE
   *   if the given header does not exist in this
   */
  string getHeader(in string fieldName);

  /**
   * 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; note that
   *   since HTTP header field names are case-insensitive, this method produces
   *   equivalent results for "HeAdER" and "hEADer" as fieldName
   * @throws NS_ERROR_INVALID_ARG
   *   if fieldName does not constitute a valid header field name
   */
  boolean hasHeader(in string fieldName);

  /**
   * An nsISimpleEnumerator of nsISupportsStrings over the names of the headers
   * in this request.  The header field names in the enumerator may not
   * necessarily have the same case as they do in the request itself.
   */
  readonly attribute nsISimpleEnumerator headers;

  /**
   * A stream from which data appearing in the body of this request can be read.
   */
  readonly attribute nsIInputStream bodyInputStream;
};


/**
 * Represents an HTTP response, as described in RFC 2616, section 6.
 */
[scriptable, uuid(a2aaaff7-03bd-43b6-b460-94671e288093)]
interface nsIHttpResponse : nsISupports
{
  /**
   * Sets the status line for this.  If this method is never called on this, the
   * status line defaults to "HTTP/", followed by the server's default HTTP
   * version (e.g. "1.1"), followed by " 200 OK".
   *
   * @param httpVersion
   *   the HTTP version of this, as a string (e.g. "1.1"); if null, the server
   *   default is used
   * @param code
   *   the numeric HTTP status code for this
   * @param description
   *   a human-readable description of code; may be null if no description is
   *   desired
   * @throws NS_ERROR_INVALID_ARG
   *   if httpVersion is not a valid HTTP version string, statusCode is greater
   *   than 999, or description contains invalid characters
   */
  void setStatusLine(in string httpVersion,
                     in unsigned short statusCode,
                     in string description);

  /**
   * Sets the specified header in this.
   *
   * @param name
   *   the name of the header; must match the field-name production per RFC 2616
   * @param value
   *   the value of the header; must match the field-value production per RFC
   *   2616
   * @param merge
   *   when true, if the given header already exists in this, the values passed
   *   to this function will be merged into the existing header, per RFC 2616
   *   header semantics; when false, if the given header already exists in this,
   *   it is overwritten with the passed-in values; if the header doesn't exist
   *   in this, it is set regardless of the value of this parameter
   * @throws NS_ERROR_INVALID_ARG
   *   if name or value is not a valid header component
   */
  void setHeader(in string name, in string value, in boolean merge);

  /**
   * A stream to which data appearing in the body of this response should be
   * written.
   */
  readonly attribute nsIOutputStream bodyOutputStream;

  /**
   * Write a string to the response's output stream.
   *
   * @note
   *   This method is only guaranteed to work with ASCII data.
   */
  void write(in string data);
};