/* ***** 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 (original author) * Robert Sayre * * 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 nsIHttpServerStoppedCallback; interface nsIHttpRequestHandler; interface nsIHttpRequest; interface nsIHttpResponse; interface nsIHttpServerIdentity; /** * An interface which represents an HTTP server. */ [scriptable, uuid(71ecfba5-15cf-457f-9642-4b33f6e9baf4)] interface nsIHttpServer : nsISupports { /** * Starts up this server, listening upon the given port. * * @param port * the port upon which listening should happen, or -1 if no specific port is * desired * @throws NS_ERROR_ALREADY_INITIALIZED * if this server is already started * @throws NS_ERROR_NOT_AVAILABLE * if the server is not started and cannot be started on the desired port * (perhaps because the port is already in use or because the process does * not have privileges to do so) * @note * Behavior is undefined if this method is called after stop() has been * called on this but before the provided callback function has been * called. */ void start(in long port); /** * Shuts down this server if it is running (including the period of time after * stop() has been called but before the provided callback has been called). * * @param callback * an asynchronous callback used to notify the user when this server is * stopped and all pending requests have been fully served * @throws NS_ERROR_NULL_POINTER * if callback is null * @throws NS_ERROR_UNEXPECTED * if this server is not running */ void stop(in nsIHttpServerStoppedCallback callback); /** * 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); /** * Retrieves the object associated with the given key in this in * object-valued saved state. All keys are initially associated with null. */ nsISupports getObjectState(in AString key); /** * Sets the object associated with the given key in this in object-valued * saved state. The value may be null. */ void setObjectState(in AString key, in nsISupports value); }; /** * An interface through which a notification of the complete stopping (socket * closure, in-flight requests all fully served and responded to) of an HTTP * server may be received. */ [scriptable, function, uuid(925a6d33-9937-4c63-abe1-a1c56a986455)] interface nsIHttpServerStoppedCallback : nsISupports { /** Called when the corresponding server has been fully stopped. */ void onStopped(); }; /** * 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 nsIHttpRequest.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 nsIHttpRequest.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 * nsIHttpRequest.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 an HTTP request and initializes the passed-in response to reflect * the correct HTTP response. * * If this method throws an exception, externally observable behavior depends * upon whether is being processed asynchronously. If such is the case, the * output is some prefix (perhaps all, perhaps none, perhaps only some) of the * data which would have been sent if, instead, the response had been finished * at that point. If no data has been written, the response has not had * seizePower() called on it, and it is not being asynchronously created, an * error handler will be invoked (usually 500 unless otherwise specified). * * Some uses of nsIHttpRequestHandler may require this method to never throw * an exception; in the general case, however, this method may throw an * exception (causing an HTTP 500 response to occur, if the above conditions * are met). * * @param request * 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 nsIHttpRequest request, in nsIHttpResponse response); }; /** * A representation of the data included in an HTTP request. */ [scriptable, uuid(80cbca71-dc51-4fa0-9010-1cec262dbd4a)] interface nsIHttpRequest : 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 result is a string containing the individual values of the header, * usually separated with a comma. The headers WWW-Authenticate, * Proxy-Authenticate, and Set-Cookie violate the HTTP specification, * however, and for these headers only the separator string is '\n'. * * @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(1acd16c2-dc59-42fa-9160-4f26c43c1c21)] 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 * @throws NS_ERROR_NOT_AVAILABLE * if this response is being processed asynchronously and data has been * written to this response's body, or if seizePower() has been called on * this */ 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 (except for the Set-Cookie, WWW-Authenticate, and * Proxy-Authenticate headers, which will treat each such merged header as * an additional instance of the header, for real-world compatibility * reasons); when false, replaces any existing header of the given name (if * any exists) with a new header with the specified value * @throws NS_ERROR_INVALID_ARG * if name or value is not a valid header component * @throws NS_ERROR_NOT_AVAILABLE * if this response is being processed asynchronously and data has been * written to this response's body, or if seizePower() has been called on * this */ void setHeader(in string name, in string value, in boolean merge); /** * A stream to which data appearing in the body of this response (or in the * totality of the response if seizePower() is called) should be written. * After this response has been designated as being processed asynchronously, * or after seizePower() has been called on this, subsequent writes will no * longer be buffered and will be written to the underlying transport without * delaying until the entire response is constructed. Write-through may or * may not be synchronous in the implementation, and in any case particular * behavior may not be observable to the HTTP client as intermediate buffers * both in the server socket and in the client may delay written data; be * prepared for delays at any time. * * @throws NS_ERROR_NOT_AVAILABLE * if accessed after this response is fully constructed */ readonly attribute nsIOutputStream bodyOutputStream; /** * Writes a string to the response's output stream. This method is merely a * convenient shorthand for writing the same data to bodyOutputStream * directly. * * @note * This method is only guaranteed to work with ASCII data. * @throws NS_ERROR_NOT_AVAILABLE * if called after this response has been fully constructed */ void write(in string data); /** * Signals that this response is being constructed asynchronously. Requests * are typically completely constructed during nsIHttpRequestHandler.handle; * however, responses which require significant resources (time, memory, * processing) to construct can be created and sent incrementally by calling * this method during the call to nsIHttpRequestHandler.handle. This method * only has this effect when called during nsIHttpRequestHandler.handle; * behavior is undefined if it is called at a later time. It may be called * multiple times with no ill effect, so long as each call occurs before * finish() is called. * * @throws NS_ERROR_UNEXPECTED * if not initially called within a nsIHttpRequestHandler.handle call or if * called after this response has been finished * @throws NS_ERROR_NOT_AVAILABLE * if seizePower() has been called on this */ void processAsync(); /** * Seizes complete control of this response (and its connection) from the * server, allowing raw and unfettered access to data being sent in the HTTP * response. Once this method has been called the only property which may be * accessed without an exception being thrown is bodyOutputStream, and the * only methods which may be accessed without an exception being thrown are * write(), finish(), and seizePower() (which may be called multiple times * without ill effect so long as all calls are otherwise allowed). * * After a successful call, all data subsequently written to the body of this * response is written directly to the corresponding connection. (Previously- * written data is silently discarded.) No status line or headers are sent * before doing so; if the response handler wishes to write such data, it must * do so manually. Data generation completes only when finish() is called; it * is not enough to simply call close() on bodyOutputStream. * * @throws NS_ERROR_NOT_AVAILABLE * if processAsync() has been called on this * @throws NS_ERROR_UNEXPECTED * if finish() has been called on this */ void seizePower(); /** * Signals that construction of this response is complete and that it may be * sent over the network to the client, or if seizePower() has been called * signals that all data has been written and that the underlying connection * may be closed. This method may only be called after processAsync() or * seizePower() has been called. This method is idempotent. * * @throws NS_ERROR_UNEXPECTED * if processAsync() or seizePower() has not already been properly called */ void finish(); };