netwerk/test/httpserver/nsIHttpServer.idl@ca08bd8f51b2
netwerk/test/httpserver/nsIHttpServer.idl
Wed, 31 Dec 2014 06:55:46 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:46 +0100
- changeset 1
- ca08bd8f51b2
- permissions
- -rw-r--r--
Added tag TORBROWSER_REPLICA for changeset 6474c204b198
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include "nsISupports.idl"
7 interface nsIInputStream;
8 interface nsIFile;
9 interface nsIOutputStream;
10 interface nsISimpleEnumerator;
12 interface nsIHttpServer;
13 interface nsIHttpServerStoppedCallback;
14 interface nsIHttpRequestHandler;
15 interface nsIHttpRequest;
16 interface nsIHttpResponse;
17 interface nsIHttpServerIdentity;
19 /**
20 * An interface which represents an HTTP server.
21 */
22 [scriptable, uuid(cea8812e-faa6-4013-9396-f9936cbb74ec)]
23 interface nsIHttpServer : nsISupports
24 {
25 /**
26 * Starts up this server, listening upon the given port.
27 *
28 * @param port
29 * the port upon which listening should happen, or -1 if no specific port is
30 * desired
31 * @throws NS_ERROR_ALREADY_INITIALIZED
32 * if this server is already started
33 * @throws NS_ERROR_NOT_AVAILABLE
34 * if the server is not started and cannot be started on the desired port
35 * (perhaps because the port is already in use or because the process does
36 * not have privileges to do so)
37 * @note
38 * Behavior is undefined if this method is called after stop() has been
39 * called on this but before the provided callback function has been
40 * called.
41 */
42 void start(in long port);
44 /**
45 * Shuts down this server if it is running (including the period of time after
46 * stop() has been called but before the provided callback has been called).
47 *
48 * @param callback
49 * an asynchronous callback used to notify the user when this server is
50 * stopped and all pending requests have been fully served
51 * @throws NS_ERROR_NULL_POINTER
52 * if callback is null
53 * @throws NS_ERROR_UNEXPECTED
54 * if this server is not running
55 */
56 void stop(in nsIHttpServerStoppedCallback callback);
58 /**
59 * Associates the local file represented by the string file with all requests
60 * which match request.
61 *
62 * @param path
63 * the path which is to be mapped to the given file; must begin with "/" and
64 * be a valid URI path (i.e., no query string, hash reference, etc.)
65 * @param file
66 * the file to serve for the given path, or null to remove any mapping that
67 * might exist; this file must exist for the lifetime of the server
68 */
69 void registerFile(in string path, in nsIFile file);
71 /**
72 * Registers a custom path handler.
73 *
74 * @param path
75 * the path on the server (beginning with a "/") which is to be handled by
76 * handler; this path must not include a query string or hash component; it
77 * also should usually be canonicalized, since most browsers will do so
78 * before sending otherwise-matching requests
79 * @param handler
80 * an object which will handle any requests for the given path, or null to
81 * remove any existing handler; if while the server is running the handler
82 * throws an exception while responding to a request, an HTTP 500 response
83 * will be returned
84 * @throws NS_ERROR_INVALID_ARG
85 * if path does not begin with a "/"
86 */
87 void registerPathHandler(in string path, in nsIHttpRequestHandler handler);
89 /**
90 * Registers a custom prefix handler.
91 *
92 * @param prefix
93 * the path on the server (beginning and ending with "/") which is to be
94 * handled by handler; this path must not include a query string or hash
95 * component. All requests that start with this prefix will be directed to
96 * the given handler.
97 * @param handler
98 * an object which will handle any requests for the given path, or null to
99 * remove any existing handler; if while the server is running the handler
100 * throws an exception while responding to a request, an HTTP 500 response
101 * will be returned
102 * @throws NS_ERROR_INVALID_ARG
103 * if path does not begin with a "/" or does not end with a "/"
104 */
105 void registerPrefixHandler(in string prefix, in nsIHttpRequestHandler handler);
107 /**
108 * Registers a custom error page handler.
109 *
110 * @param code
111 * the error code which is to be handled by handler
112 * @param handler
113 * an object which will handle any requests which generate the given status
114 * code, or null to remove any existing handler. If the handler throws an
115 * exception during server operation, fallback is to the genericized error
116 * handler (the x00 version), then to 500, using a user-defined error
117 * handler if one exists or the server default handler otherwise. Fallback
118 * will never occur from a user-provided handler that throws to the same
119 * handler as provided by the server, e.g. a throwing user 404 falls back to
120 * 400, not a server-provided 404 that might not throw.
121 * @note
122 * If the error handler handles HTTP 500 and throws, behavior is undefined.
123 */
124 void registerErrorHandler(in unsigned long code, in nsIHttpRequestHandler handler);
126 /**
127 * Maps all requests to paths beneath path to the corresponding file beneath
128 * dir.
129 *
130 * @param path
131 * the absolute path on the server against which requests will be served
132 * from dir (e.g., "/", "/foo/", etc.); must begin and end with a forward
133 * slash
134 * @param dir
135 * the directory to be used to serve all requests for paths underneath path
136 * (except those further overridden by another, deeper path registered with
137 * another directory); if null, any current mapping for the given path is
138 * removed
139 * @throws NS_ERROR_INVALID_ARG
140 * if dir is non-null and does not exist or is not a directory, or if path
141 * does not begin with and end with a forward slash
142 */
143 void registerDirectory(in string path, in nsIFile dir);
145 /**
146 * Associates files with the given extension with the given Content-Type when
147 * served by this server, in the absence of any file-specific information
148 * about the desired Content-Type. If type is empty, removes any extant
149 * mapping, if one is present.
150 *
151 * @throws NS_ERROR_INVALID_ARG
152 * if the given type is not a valid header field value, i.e. if it doesn't
153 * match the field-value production in RFC 2616
154 * @note
155 * No syntax checking is done of the given type, beyond ensuring that it is
156 * a valid header field value. Behavior when not given a string matching
157 * the media-type production in RFC 2616 section 3.7 is undefined.
158 * Implementations may choose to define specific behavior for types which do
159 * not match the production, such as for CGI functionality.
160 * @note
161 * Implementations MAY treat type as a trusted argument; users who fail to
162 * generate this string from trusted data risk security vulnerabilities.
163 */
164 void registerContentType(in string extension, in string type);
166 /**
167 * Sets the handler used to display the contents of a directory if
168 * the directory contains no index page.
169 *
170 * @param handler
171 * an object which will handle any requests for directories which
172 * do not contain index pages, or null to reset to the default
173 * index handler; if while the server is running the handler
174 * throws an exception while responding to a request, an HTTP 500
175 * response will be returned. An nsIFile corresponding to the
176 * directory is available from the metadata object passed to the
177 * handler, under the key "directory".
178 */
179 void setIndexHandler(in nsIHttpRequestHandler handler);
181 /** Represents the locations at which this server is reachable. */
182 readonly attribute nsIHttpServerIdentity identity;
184 /**
185 * Retrieves the string associated with the given key in this, for the given
186 * path's saved state. All keys are initially associated with the empty
187 * string.
188 */
189 AString getState(in AString path, in AString key);
191 /**
192 * Sets the string associated with the given key in this, for the given path's
193 * saved state.
194 */
195 void setState(in AString path, in AString key, in AString value);
197 /**
198 * Retrieves the string associated with the given key in this, in
199 * entire-server saved state. All keys are initially associated with the
200 * empty string.
201 */
202 AString getSharedState(in AString key);
204 /**
205 * Sets the string associated with the given key in this, in entire-server
206 * saved state.
207 */
208 void setSharedState(in AString key, in AString value);
210 /**
211 * Retrieves the object associated with the given key in this in
212 * object-valued saved state. All keys are initially associated with null.
213 */
214 nsISupports getObjectState(in AString key);
216 /**
217 * Sets the object associated with the given key in this in object-valued
218 * saved state. The value may be null.
219 */
220 void setObjectState(in AString key, in nsISupports value);
221 };
223 /**
224 * An interface through which a notification of the complete stopping (socket
225 * closure, in-flight requests all fully served and responded to) of an HTTP
226 * server may be received.
227 */
228 [scriptable, function, uuid(925a6d33-9937-4c63-abe1-a1c56a986455)]
229 interface nsIHttpServerStoppedCallback : nsISupports
230 {
231 /** Called when the corresponding server has been fully stopped. */
232 void onStopped();
233 };
235 /**
236 * Represents a set of names for a server, one of which is the primary name for
237 * the server and the rest of which are secondary. By default every server will
238 * contain ("http", "localhost", port) and ("http", "127.0.0.1", port) as names,
239 * where port is what was provided to the corresponding server when started;
240 * however, except for their being removed when the corresponding server stops
241 * they have no special importance.
242 */
243 [scriptable, uuid(a89de175-ae8e-4c46-91a5-0dba99bbd284)]
244 interface nsIHttpServerIdentity : nsISupports
245 {
246 /**
247 * The primary scheme at which the corresponding server is located, defaulting
248 * to 'http'. This name will be the value of nsIHttpRequest.scheme for
249 * HTTP/1.0 requests.
250 *
251 * This value is always set when the corresponding server is running. If the
252 * server is not running, this value is set only if it has been set to a
253 * non-default name using setPrimary. In this case reading this value will
254 * throw NS_ERROR_NOT_INITIALIZED.
255 */
256 readonly attribute string primaryScheme;
258 /**
259 * The primary name by which the corresponding server is known, defaulting to
260 * 'localhost'. This name will be the value of nsIHttpRequest.host for
261 * HTTP/1.0 requests.
262 *
263 * This value is always set when the corresponding server is running. If the
264 * server is not running, this value is set only if it has been set to a
265 * non-default name using setPrimary. In this case reading this value will
266 * throw NS_ERROR_NOT_INITIALIZED.
267 */
268 readonly attribute string primaryHost;
270 /**
271 * The primary port on which the corresponding server runs, defaulting to the
272 * associated server's port. This name will be the value of
273 * nsIHttpRequest.port for HTTP/1.0 requests.
274 *
275 * This value is always set when the corresponding server is running. If the
276 * server is not running, this value is set only if it has been set to a
277 * non-default name using setPrimary. In this case reading this value will
278 * throw NS_ERROR_NOT_INITIALIZED.
279 */
280 readonly attribute long primaryPort;
282 /**
283 * Adds a location at which this server may be accessed.
284 *
285 * @throws NS_ERROR_ILLEGAL_VALUE
286 * if scheme or host do not match the scheme or host productions imported
287 * into RFC 2616 from RFC 2396, or if port is not a valid port number
288 */
289 void add(in string scheme, in string host, in long port);
291 /**
292 * Removes this name from the list of names by which the corresponding server
293 * is known. If name is also the primary name for the server, the primary
294 * name reverts to 'http://127.0.0.1' with the associated server's port.
295 *
296 * @throws NS_ERROR_ILLEGAL_VALUE
297 * if scheme or host do not match the scheme or host productions imported
298 * into RFC 2616 from RFC 2396, or if port is not a valid port number
299 * @returns
300 * true if the given name was a name for this server, false otherwise
301 */
302 boolean remove(in string scheme, in string host, in long port);
304 /**
305 * Returns true if the given name is in this, false otherwise.
306 *
307 * @throws NS_ERROR_ILLEGAL_VALUE
308 * if scheme or host do not match the scheme or host productions imported
309 * into RFC 2616 from RFC 2396, or if port is not a valid port number
310 */
311 boolean has(in string scheme, in string host, in long port);
313 /**
314 * Returns the scheme for the name with the given host and port, if one is
315 * present; otherwise returns the empty string.
316 *
317 * @throws NS_ERROR_ILLEGAL_VALUE
318 * if host does not match the host production imported into RFC 2616 from
319 * RFC 2396, or if port is not a valid port number
320 */
321 string getScheme(in string host, in long port);
323 /**
324 * Designates the given name as the primary name in this and adds it to this
325 * if it is not already present.
326 *
327 * @throws NS_ERROR_ILLEGAL_VALUE
328 * if scheme or host do not match the scheme or host productions imported
329 * into RFC 2616 from RFC 2396, or if port is not a valid port number
330 */
331 void setPrimary(in string scheme, in string host, in long port);
332 };
334 /**
335 * A representation of a handler for HTTP requests. The handler is used by
336 * calling its .handle method with data for an incoming request; it is the
337 * handler's job to use that data as it sees fit to make the desired response.
338 *
339 * @note
340 * This interface uses the [function] attribute, so you can pass a
341 * script-defined function with the functionality of handle() to any
342 * method which has a nsIHttpRequestHandler parameter, instead of wrapping
343 * it in an otherwise empty object.
344 */
345 [scriptable, function, uuid(2bbb4db7-d285-42b3-a3ce-142b8cc7e139)]
346 interface nsIHttpRequestHandler : nsISupports
347 {
348 /**
349 * Processes an HTTP request and initializes the passed-in response to reflect
350 * the correct HTTP response.
351 *
352 * If this method throws an exception, externally observable behavior depends
353 * upon whether is being processed asynchronously. If such is the case, the
354 * output is some prefix (perhaps all, perhaps none, perhaps only some) of the
355 * data which would have been sent if, instead, the response had been finished
356 * at that point. If no data has been written, the response has not had
357 * seizePower() called on it, and it is not being asynchronously created, an
358 * error handler will be invoked (usually 500 unless otherwise specified).
359 *
360 * Some uses of nsIHttpRequestHandler may require this method to never throw
361 * an exception; in the general case, however, this method may throw an
362 * exception (causing an HTTP 500 response to occur, if the above conditions
363 * are met).
364 *
365 * @param request
366 * data representing an HTTP request
367 * @param response
368 * an initially-empty response which must be modified to reflect the data
369 * which should be sent as the response to the request described by metadata
370 */
371 void handle(in nsIHttpRequest request, in nsIHttpResponse response);
372 };
375 /**
376 * A representation of the data included in an HTTP request.
377 */
378 [scriptable, uuid(978cf30e-ad73-42ee-8f22-fe0aaf1bf5d2)]
379 interface nsIHttpRequest : nsISupports
380 {
381 /**
382 * The request type for this request (see RFC 2616, section 5.1.1).
383 */
384 readonly attribute string method;
386 /**
387 * The scheme of the requested path, usually 'http' but might possibly be
388 * 'https' if some form of SSL tunneling is in use. Note that this value
389 * cannot be accurately determined unless the incoming request used the
390 * absolute-path form of the request line; it defaults to 'http', so only
391 * if it is something else can you be entirely certain it's correct.
392 */
393 readonly attribute string scheme;
395 /**
396 * The host of the data being requested (e.g. "localhost" for the
397 * http://localhost:8080/file resource). Note that the relevant port on the
398 * host is specified in this.port. This value is in the ASCII character
399 * encoding.
400 */
401 readonly attribute string host;
403 /**
404 * The port on the server on which the request was received.
405 */
406 readonly attribute unsigned long port;
408 /**
409 * The requested path, without any query string (e.g. "/dir/file.txt"). It is
410 * guaranteed to begin with a "/". The individual components in this string
411 * are URL-encoded.
412 */
413 readonly attribute string path;
415 /**
416 * The URL-encoded query string associated with this request, not including
417 * the initial "?", or "" if no query string was present.
418 */
419 readonly attribute string queryString;
421 /**
422 * A string containing the HTTP version of the request (i.e., "1.1"). Leading
423 * zeros for either component of the version will be omitted. (In other
424 * words, if the request contains the version "1.01", this attribute will be
425 * "1.1"; see RFC 2616, section 3.1.)
426 */
427 readonly attribute string httpVersion;
429 /**
430 * Returns the value for the header in this request specified by fieldName.
431 *
432 * @param fieldName
433 * the name of the field whose value is to be gotten; note that since HTTP
434 * header field names are case-insensitive, this method produces equivalent
435 * results for "HeAdER" and "hEADer" as fieldName
436 * @returns
437 * The result is a string containing the individual values of the header,
438 * usually separated with a comma. The headers WWW-Authenticate,
439 * Proxy-Authenticate, and Set-Cookie violate the HTTP specification,
440 * however, and for these headers only the separator string is '\n'.
441 *
442 * @throws NS_ERROR_INVALID_ARG
443 * if fieldName does not constitute a valid header field name
444 * @throws NS_ERROR_NOT_AVAILABLE
445 * if the given header does not exist in this
446 */
447 string getHeader(in string fieldName);
449 /**
450 * Returns true if a header with the given field name exists in this, false
451 * otherwise.
452 *
453 * @param fieldName
454 * the field name whose existence is to be determined in this; note that
455 * since HTTP header field names are case-insensitive, this method produces
456 * equivalent results for "HeAdER" and "hEADer" as fieldName
457 * @throws NS_ERROR_INVALID_ARG
458 * if fieldName does not constitute a valid header field name
459 */
460 boolean hasHeader(in string fieldName);
462 /**
463 * An nsISimpleEnumerator of nsISupportsStrings over the names of the headers
464 * in this request. The header field names in the enumerator may not
465 * necessarily have the same case as they do in the request itself.
466 */
467 readonly attribute nsISimpleEnumerator headers;
469 /**
470 * A stream from which data appearing in the body of this request can be read.
471 */
472 readonly attribute nsIInputStream bodyInputStream;
473 };
476 /**
477 * Represents an HTTP response, as described in RFC 2616, section 6.
478 */
479 [scriptable, uuid(1acd16c2-dc59-42fa-9160-4f26c43c1c21)]
480 interface nsIHttpResponse : nsISupports
481 {
482 /**
483 * Sets the status line for this. If this method is never called on this, the
484 * status line defaults to "HTTP/", followed by the server's default HTTP
485 * version (e.g. "1.1"), followed by " 200 OK".
486 *
487 * @param httpVersion
488 * the HTTP version of this, as a string (e.g. "1.1"); if null, the server
489 * default is used
490 * @param code
491 * the numeric HTTP status code for this
492 * @param description
493 * a human-readable description of code; may be null if no description is
494 * desired
495 * @throws NS_ERROR_INVALID_ARG
496 * if httpVersion is not a valid HTTP version string, statusCode is greater
497 * than 999, or description contains invalid characters
498 * @throws NS_ERROR_NOT_AVAILABLE
499 * if this response is being processed asynchronously and data has been
500 * written to this response's body, or if seizePower() has been called on
501 * this
502 */
503 void setStatusLine(in string httpVersion,
504 in unsigned short statusCode,
505 in string description);
507 /**
508 * Sets the specified header in this.
509 *
510 * @param name
511 * the name of the header; must match the field-name production per RFC 2616
512 * @param value
513 * the value of the header; must match the field-value production per RFC
514 * 2616
515 * @param merge
516 * when true, if the given header already exists in this, the values passed
517 * to this function will be merged into the existing header, per RFC 2616
518 * header semantics (except for the Set-Cookie, WWW-Authenticate, and
519 * Proxy-Authenticate headers, which will treat each such merged header as
520 * an additional instance of the header, for real-world compatibility
521 * reasons); when false, replaces any existing header of the given name (if
522 * any exists) with a new header with the specified value
523 * @throws NS_ERROR_INVALID_ARG
524 * if name or value is not a valid header component
525 * @throws NS_ERROR_NOT_AVAILABLE
526 * if this response is being processed asynchronously and data has been
527 * written to this response's body, or if seizePower() has been called on
528 * this
529 */
530 void setHeader(in string name, in string value, in boolean merge);
532 /**
533 * A stream to which data appearing in the body of this response (or in the
534 * totality of the response if seizePower() is called) should be written.
535 * After this response has been designated as being processed asynchronously,
536 * or after seizePower() has been called on this, subsequent writes will no
537 * longer be buffered and will be written to the underlying transport without
538 * delaying until the entire response is constructed. Write-through may or
539 * may not be synchronous in the implementation, and in any case particular
540 * behavior may not be observable to the HTTP client as intermediate buffers
541 * both in the server socket and in the client may delay written data; be
542 * prepared for delays at any time.
543 *
544 * @throws NS_ERROR_NOT_AVAILABLE
545 * if accessed after this response is fully constructed
546 */
547 readonly attribute nsIOutputStream bodyOutputStream;
549 /**
550 * Writes a string to the response's output stream. This method is merely a
551 * convenient shorthand for writing the same data to bodyOutputStream
552 * directly.
553 *
554 * @note
555 * This method is only guaranteed to work with ASCII data.
556 * @throws NS_ERROR_NOT_AVAILABLE
557 * if called after this response has been fully constructed
558 */
559 void write(in string data);
561 /**
562 * Signals that this response is being constructed asynchronously. Requests
563 * are typically completely constructed during nsIHttpRequestHandler.handle;
564 * however, responses which require significant resources (time, memory,
565 * processing) to construct can be created and sent incrementally by calling
566 * this method during the call to nsIHttpRequestHandler.handle. This method
567 * only has this effect when called during nsIHttpRequestHandler.handle;
568 * behavior is undefined if it is called at a later time. It may be called
569 * multiple times with no ill effect, so long as each call occurs before
570 * finish() is called.
571 *
572 * @throws NS_ERROR_UNEXPECTED
573 * if not initially called within a nsIHttpRequestHandler.handle call or if
574 * called after this response has been finished
575 * @throws NS_ERROR_NOT_AVAILABLE
576 * if seizePower() has been called on this
577 */
578 void processAsync();
580 /**
581 * Seizes complete control of this response (and its connection) from the
582 * server, allowing raw and unfettered access to data being sent in the HTTP
583 * response. Once this method has been called the only property which may be
584 * accessed without an exception being thrown is bodyOutputStream, and the
585 * only methods which may be accessed without an exception being thrown are
586 * write(), finish(), and seizePower() (which may be called multiple times
587 * without ill effect so long as all calls are otherwise allowed).
588 *
589 * After a successful call, all data subsequently written to the body of this
590 * response is written directly to the corresponding connection. (Previously-
591 * written data is silently discarded.) No status line or headers are sent
592 * before doing so; if the response handler wishes to write such data, it must
593 * do so manually. Data generation completes only when finish() is called; it
594 * is not enough to simply call close() on bodyOutputStream.
595 *
596 * @throws NS_ERROR_NOT_AVAILABLE
597 * if processAsync() has been called on this
598 * @throws NS_ERROR_UNEXPECTED
599 * if finish() has been called on this
600 */
601 void seizePower();
603 /**
604 * Signals that construction of this response is complete and that it may be
605 * sent over the network to the client, or if seizePower() has been called
606 * signals that all data has been written and that the underlying connection
607 * may be closed. This method may only be called after processAsync() or
608 * seizePower() has been called. This method is idempotent.
609 *
610 * @throws NS_ERROR_UNEXPECTED
611 * if processAsync() or seizePower() has not already been properly called
612 */
613 void finish();
614 };
