update API docs for HTTP client and server-related classes

sdk/lib/io/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 37 matching lines @@
   static const int BAD_GATEWAY = 502;
   static const int SERVICE_UNAVAILABLE = 503;
   static const int GATEWAY_TIMEOUT = 504;
   static const int HTTP_VERSION_NOT_SUPPORTED = 505;
   // Client generated status code.
   static const int NETWORK_CONNECT_TIMEOUT_ERROR = 599;
 }
 
 
 /**
- * A server that delivers content, such as web pages, using
- * the HTTP protocol.
+ * A server that delivers content, such as web pages, using the HTTP protocol.
  *
- * The [HttpServer] is a [Stream] of [HttpRequest]s. Each
- * [HttpRequest] has an associated [HttpResponse] object as its
- * [HttpRequest.response] member, and the server responds to a request by
- * writing to that [HttpResponse] object.
+ * The HttpServer is a [Stream] that provides [HttpRequest] objects. Each
+ * HttpRequest has an associated [HttpResponse] object.
+ * The server responds to a request by writing to that HttpResponse object.
+ * The following example shows how to bind an HttpServer to an IPv6
+ * [InternetAddress] on port 80 (the standard port for HTTP servers)
+ * and how to listen for requests.
+ * Port 80 is the default HTTP port. However, on most systems accessing
+ * this requires super-user privileges. For local testing consider
+ * using a non-reserved port (above 1023).

[Anders Johnsen, 2014/03/27 12:29:36]

1023 is a funny number :) Maybe say 1024 and above?

[mem, 2014/03/28 17:52:00]

Done.

  *
- * Incomplete requests where all or parts of the header is missing, are
- * ignored and no exceptions or [HttpRequest] objects are generated for them.
- * Likewise, when writing to a [HttpResponse], any [Socket] exceptions are
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       HttpServer
+ *           .bind(InternetAddress.ANY_IP_V6, 80)
+ *           .then((server) {
+ *             server.listen((HttpRequest request) {
+ *               request.response.write('Hello, world!');
+ *               request.response.close();
+ *             });
+ *           });
+ *     }
+ *
+ * Incomplete requests, in which all or part of the header is missing, are
+ * ignored, and no exceptions or HttpRequest objects are generated for them.
+ * Likewise, when writing to an HttpResponse, any [Socket] exceptions are
  * ignored and any future writes are ignored.
  *
- * The [HttpRequest] exposes the request headers, and provides the request body,
- * if it exists, as a stream of data. If the body is unread, it'll be drained
- * when the [HttpResponse] is being written to or closed.
+ * The HttpRequest exposes the request headers and provides the request body,
+ * if it exists, as a Stream of data. If the body is unread, it is drained
+ * when the server writes to the HttpResponse or closes it.
  *
- * The following example shows how to bind a [HttpServer] to a IPv6
- * [InternetAddress] on port 80, and listening to requests.
+ * ## Bind with a secure HTTPS connection
  *
- *     HttpServer.bind(InternetAddress.ANY_IP_V6, 80).then((server) {
- *       server.listen((HttpRequest request) {
- *         // Handle requests.
- *       });
- *     });
+ * Use [bindSecure] to create an HTTPS server.
+ *
+ * The server presents a certificate to the client. In the following
+ * example, the certificate is named `localhost_cert` and comes from 
+ * the database found in the `pkcert` directory

[Anders Johnsen, 2014/03/27 12:29:36]

. after directory.

[mem, 2014/03/28 17:52:00]

Done.

+ * This certificate is used by Dart for testing purposes.

[Anders Johnsen, 2014/03/27 12:29:36]

I don't think we need this line. It should be obvious to the reader, that
examples are guidelines, not real-world deployable scripts.

[mem, 2014/03/28 17:52:00]

Done.

+ * 
+ *     import 'dart:io';
+ *     import "dart:isolate";
+ *
+ *     main() {
+ *       var testPkcertDatabase = Platform.script.resolve('pkcert')
+ *                                        .toFilePath();
+ *       SecureSocket.initialize(database: testPkcertDatabase,
+ *                               password: 'dartdart');
+ *
+ *       HttpServer
+ *           .bindSecure(InternetAddress.ANY_IP_V6,
+ *                       443,
+ *                       certificateName: 'localhost_cert')
+ *           .then((server) {
+ *             server.listen((HttpRequest request) {
+ *               request.response.write('Hello, world!');
+ *               request.response.close();
+ *             });
+ *           });
+ *     }
+ *
+ * The certificate database is managed using the Mozilla certutil tool (see
+ * [NSS Tools certutil](https://developer.mozilla.org/en-US/docs/NSS/tools/NSS_Tools_certutil)).
+ * Dart uses the NSS library to handle SSL and Mozilla

[Anders Johnsen, 2014/03/27 12:29:36]

I'm reading the 'and' wrong here. Would this be better?

Dart uses the NSS library to handle SSL, and the Mozilla certutil must be used
to manipulate the certificate database.

[mem, 2014/03/28 17:52:00]

Done.

+ * certutil must be used to manipulate the certificate database.
+ *
+ * ## Connect to a socket

[Anders Johnsen, 2014/03/27 12:29:36]

a server socket

[mem, 2014/03/28 17:52:00]

Done.

+ *
+ * You can use the [listenOn] constructor to attach an HTTP server to
+ * a [ServerSocket].
+ *
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       ServerSocket.bind(InternetAddress.ANY_IP_V6, 80)
+ *         .then((serverSocket) {
+ *           HttpServer httpserver = new HttpServer.listenOn(serverSocket);
+ *           serverSocket.listen((Socket socket) {
+ *             socket.write('Hello, client.');
+ *           });
+ *         });
+ *     }
+ *
+ * ## Other resources
+ *
+ * * HttpServer is a Stream. Refer to the [Stream] class for information
+ * about the streaming qualities of an HttpServer.

[Anders Johnsen, 2014/03/27 12:29:36]

We could consider to specify, that pausing the subscription of the stream, will
apply pausing on the OS level (it's a good thing :).

[mem, 2014/03/28 17:52:00]

Done.

+ * 
+ * * The [http_server](https://pub.dartlang.org/packages/http_server)
+ * package on pub.dartlang.org contains a set of high-level classes that,
+ * together with this class, makes it easy to provide content through HTTP
+ * servers.
  */
 abstract class HttpServer implements Stream<HttpRequest> {
   /**
    * Set and get the default value of the `Server` header for all responses
    * generated by this [HttpServer]. By default, it's disabled.
    *
    * If the serverHeader is set to `null`, no default `Server` header will be
    * added to each response.
    */
   String serverHeader;
@@ skipping 161 matching lines @@
   /**
    * Number of connections which are preparing to close. Note: These
    * connections are also part of the [:active:] count as they might
    * still be sending data to the client before finally closing.
    */
   int closing = 0;
 }
 
 
 /**
- * Access to the HTTP headers for requests and responses. In some
- * situations the headers will be immutable and the mutating methods
- * will then throw exceptions.
+ * Headers for HTTP requests and responses.
+ *
+ * In some situations the headers are immutable,

[Søren Gjesse, 2014/03/27 10:09:55]

We could go into the details on when headers are immutable

  1. HttpRequest and HttpClientResponse always have immutable headers
  2. HttpResponse and HttpClientRequest have immutable headers from
     when the body is written to.

[mem, 2014/03/28 17:52:00]

Done.

+ * in which case the mutating methods throw exceptions.
  *
  * For all operations on HTTP headers the header name is
  * case-insensitive.
+ *
+ * To set the value of a header use the `set()` method:
+ *
+ *     request.headers.set(HttpHeaders.CACHE_CONTROL,
+                           'max-age=3600, must-revalidate');
+ *
+ * To retrieve the value of a header use the `value()` method:
+ *
+ *     print(request.headers.value(HttpHeaders.USER_AGENT));
+ *
+ * An HttpHeaders object holds a list of values for each name
+ * as the standard allows. In most cases a name holds only a single value,
+ * The most common mode of operation is to use `set()` for setting a value,
+ * and `value()` for retrieving a value.
  */
 abstract class HttpHeaders {
   static const ACCEPT = "accept";
   static const ACCEPT_CHARSET = "accept-charset";
   static const ACCEPT_ENCODING = "accept-encoding";
   static const ACCEPT_LANGUAGE = "accept-language";
   static const ACCEPT_RANGES = "accept-ranges";
   static const AGE = "age";
   static const ALLOW = "allow";
   static const AUTHORIZATION = "authorization";
@@ skipping 472 matching lines @@
  * which listens for HTTP requests on a specific host and port.
  * For each request received, the HttpServer, which is a [Stream],
  * generates an `HttpRequest` object and adds it to the stream.
  *
  * An `HttpRequest` object delivers the body content of the request
  * as a stream of byte lists.
  * The object also contains information about the request,
  * such as the method, URI, and headers.
  *
  * In the following code, an HttpServer listens
- * for HTTP requests and, within the callback function,
- * uses the `HttpRequest` object's `method` property to dispatch requests.
+ * for HTTP requests. When the server receives a request,
+ * it uses the HttpRequest object's `method` property to dispatch requests.
  *
  *     final HOST = InternetAddress.LOOPBACK_IP_V4;
- *     final PORT = 4040;
+ *     final PORT = 80;
  *
  *     HttpServer.bind(HOST, PORT).then((_server) {
  *       _server.listen((HttpRequest request) {
  *         switch (request.method) {
  *           case 'GET':
  *             handleGetRequest(request);
  *             break;
  *           case 'POST':
  *             ...
  *         }
  *       },
  *       onError: handleError);    // listen() failed.
  *     }).catchError(handleError);
  *
- * Listen to the `HttpRequest` stream to handle the
- * data and be notified once the entire body is received.
- * An `HttpRequest` object contains an [HttpResponse] object,
- * to which the server can write its response.
- * For example, here's a skeletal callback function
- * that responds to a request:
+ * An HttpRequest object provides access to the associated [HttpResponse]
+ * object through the response property.
+ * The server writes its response to the body of the HttpResponse object.
+ * For example, here's a function that responds to a request:
  *
  *     void handleGetRequest(HttpRequest req) {
  *       HttpResponse res = req.response;
  *       var body = [];
  *       req.listen((List<int> buffer) => body.add(buffer),
  *         onDone: () {
  *           res.write('Received ${body.length} for request ');
  *           res.write(' ${req.method}: ${req.uri.path}');
  *           res.close();
  *         },
@@ skipping 89 matching lines @@
    *
    * If the [contentLength] of the body isn't 0, and the body isn't being read,
    * any write calls on the [HttpResponse] automatically drain the request
    * body.
    */
   HttpResponse get response;
 }
 
 
 /**
- * An [HttpResponse] represents the headers and data to be returned to
- * a client in response to an HTTP request.
+ * An [HttpResponse] contains the headers and data returned

[Anders Johnsen, 2014/03/27 12:29:36]

contains is a dangerous words, as it makes it sound like it literally holds on
to the data. That's not the case - it's written to the socket when available.

I'm not sure what it should say though... :/

[mem, 2014/03/28 17:52:00]

Done.

+ * from the server to the client in response to an HTTP request.
  *
- * This object has a number of properties for setting up the HTTP
- * header of the response. When the header has been set up the methods
- * from the [IOSink] can be used to write the actual body of the HTTP
- * response. When one of the [IOSink] methods is used for the
- * first time the request header is send. Calling any methods that
- * will change the header after it is sent will throw an exception.
+ * Every HttpRequest object provides access to the associated [HttpResponse]
+ * object through the response property.
+ * The server sends its response to the client by writing to the
+ * body of the HttpResponse object.

[Anders Johnsen, 2014/03/27 12:29:36]

there is no 'body' object. maybe just say

    writin to the HttpResponse object

As the API is HttpResponse.write

[mem, 2014/03/28 17:52:00]

Done.

  *
- * When writing string data through the [IOSink] the encoding used
- * will be determined from the "charset" parameter of the
+ * The HttpResponse object has a number of properties for setting up the HTTP
+ * header of the response. This class implements [IOSink].

[Anders Johnsen, 2014/03/27 12:29:36]

headers

[Anders Johnsen, 2014/03/27 12:29:36]

Maybe move IOSink to the paragraph above, as it's the interface that's used to
write to the HttpResponse.

Or better yet, move the first part of this paragraph below the next ones.

[mem, 2014/03/28 17:52:00]

Done.

[mem, 2014/03/28 17:52:00]

Done.

+ * When the header has been set up, the methods
+ * from IOSink, such as `writeln()`, can be used to write
+ * the body of the HTTP response.
+ * Use the `close()` method to close the response and send it to the client.
+ *
+ *     server.listen((HttpRequest request) {
+ *       request.response.write('Hello, world!');
+ *       request.response.close();
+ *     });
+ *
+ * When one of the IOSink methods is used for the
+ * first time, the request header is sent. Calling any methods that
+ * change the header after it is sent throws an exception.
+
+ * When writing string data through the IOSink, the encoding used
+ * is determined from the "charset" parameter of the
  * "Content-Type" header.
  *
  *     HttpResponse response = ...
  *     response.headers.contentType
  *         = new ContentType("application", "json", charset: "utf-8");
  *     response.write(...);  // Strings written will be UTF-8 encoded.
  *
  * If no charset is provided the default of ISO-8859-1 (Latin 1) will
  * be used.
  *
  *     HttpResponse response = ...
  *     response.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
  *     response.write(...);  // Strings written will be ISO-8859-1 encoded.
  *
- * If an unsupported encoding is used an exception will be thrown if
- * using one of the write methods taking a string.
+ * An exception is thrown if you use an unsupported encoding and the
+ * `write()` method being used takes a string parameter.

[Anders Johnsen, 2014/03/27 12:29:36]

This sentence is weird. write can only be called with a string.

Maybe say something like:

  An exception is thrown if you use the 'write' method while an unsupported
content-type is set.

[mem, 2014/03/28 17:52:00]

Done.

[mem, 2014/03/28 17:52:00]

Done.

  */
 abstract class HttpResponse implements IOSink {
   // TODO(ajohnsen): Add documentation of how to pipe a file to the response.
   /**
    * Gets and sets the content length of the response. If the size of
    * the response is not known in advance set the content length to
    * -1 - which is also the default if not set.
    */
   int contentLength;
 
@@ skipping 70 matching lines @@
    * socket is not available.
    */
   HttpConnectionInfo get connectionInfo;
 }
 
 
 /**
  * A client that receives content, such as web pages, from
  * a server using the HTTP protocol.
  *
- * HttpClient contains a number of methods to send a HTTP request
- * to a HTTP server and receive a HTTP response back.
+ * HttpClient contains a number of methods to send an [HttpClientRequest]
+ * to an Http server and receive an [HttpClientResponse] back.
+ * For example, you can use the [get], [getUrl], [post], and [postUrl] methods
+ * for GET and POST requests, respectively.
  *
- * This is a two-step process, triggered by two futures. When the
- * first future completes with a [HttpClientRequest] the underlying
- * network connection has been established, but no data has yet been
- * sent. The HTTP headers and body can be set on the request, and
- * [:close:] is called to sent it to the server.
+ * ## Making a simple GET request: an example
  *
- * The second future, which is returned by [:close:], completes with
- * an [HttpClientResponse] object when the response is received from
- * the server. This object contains the headers and body of the
- * response.
-
- * The future for [HttpClientRequest] is created by methods such as
- * [getUrl] and [open].
+ * A `getUrl` request is a two-step process, triggered by two [Future]s.
+ * When the first future completes with a [HttpClientRequest], the underlying
+ * network connection has been established, but no data has been sent.
+ * In the callback function for the first future, the HTTP headers and body
+ * can be set on the request. A call to the [close] method sends the
+ * request to the server.

[Anders Johnsen, 2014/03/27 12:29:36]

We send data as soon as the first either write or close.

[mem, 2014/03/28 17:52:00]

Done.

  *
- * When the HTTP response is ready a [HttpClientResponse] object is
- * provided which provides access to the headers and body of the response. The
- * body is available as a stream implemented by [HttpClientResponse].
- * If a body is present, it must be read. Otherwise, it'll lead to a resource
+ * When the HTTP response is received from the server,
+ * the second future, which is returned by close,
+ * completes with an [HttpClientResponse] object.
+ * This object provides access to the headers and body of the response.
+ * The body is available as a stream implemented by HttpClientResponse.
+ * If a body is present, it must be read. Otherwise, it leads to resource
  * leaks. Consider using [HttpClientResponse.drain] if the body is unused.
  *
  *     HttpClient client = new HttpClient();
  *     client.getUrl(Uri.parse("http://www.example.com/"))
  *         .then((HttpClientRequest request) {
- *           // Prepare the request then call close on it to send it.
+ *           // Prepare the request, then call close to send it.

[Søren Gjesse, 2014/03/27 10:09:55]

Maybe we should say what we mean with 'prepare the request'. Which is optionally
add headers and add a body.

[mem, 2014/03/28 17:52:00]

Done.

+ *           ...
  *           return request.close();
  *         })
  *         .then((HttpClientResponse response) {
- *          // Process the response.
+ *           // Process the response.
+ *           ...
  *         });
  *
- * All [HttpClient] requests set the following header by default:
+ * The future for [HttpClientRequest] is created by methods such as
+ * [getUrl] and [open].
+ *
+ * ## Headers
+ *
+ * All HttpClient requests set the following header by default:
  *
  *     Accept-Encoding: gzip
  *
  * This allows the HTTP server to use gzip compression for the body if
  * possible. If this behavior is not desired set the
- * "Accept-Encoding" header to something else.
+ * `Accept-Encoding` header to something else.

[Søren Gjesse, 2014/03/27 10:09:55]

Add:

To just turn off gzip compression of the response just clear this header:

    request.headers.removeAll(HttpHeaders.ACCEPT_ENCODING)

[mem, 2014/03/28 17:52:00]

Done.

  *
- * The [HttpClient] supports persistent connections and caches network
- * connections to reuse then for multiple requests whenever
+ * ## Closing the connection

[Søren Gjesse, 2014/03/27 10:09:55]

connection -> HttpClient

[mem, 2014/03/28 17:52:00]

Done.

+ *
+ * The HttpClient supports persistent connections and caches network
+ * connections to reuse them for multiple requests whenever
  * possible. This means that network connections can be kept open for
- * some time after a request have completed. Use [:HttpClient.close:]
- * to force shut down the [HttpClient] object and close the idle
+ * some time after a request has completed. Use HttpClient.close
+ * to force the HttpClient object to shut down and to close the idle
  * network connections.
  *
+ * ## Turning proxies on and off
+ *
  * By default the HttpClient uses the proxy configuration available
  * from the environment, see [findProxyFromEnvironment]. To turn off
- * the use of proxies all together set the [findProxy] property to
+ * the use of proxies set the [findProxy] property to
  * [:null:].
  *
  *     HttpClient client = new HttpClient();
  *     client.findProxy = null;
  */
 abstract class HttpClient {
   static const int DEFAULT_HTTP_PORT = 80;
   static const int DEFAULT_HTTPS_PORT = 443;
 
   /**
@@ skipping 264 matching lines @@
    * trying to establish a new connection after calling [shutdown]
    * will throw an exception.
    */
   void close({bool force: false});
 }
 
 
 /**
  * HTTP request for a client connection.
  *
- * This object has a number of properties for setting up the HTTP
- * header of the request. When the header has been set up the methods
- * from the [IOSink] can be used to write the actual body of the HTTP
- * request. When one of the [IOSink] methods is used for the first
- * time the request header is send. Calling any methods that will
- * change the header after it is sent will throw an exception.
+ * To set up a request, set the headers using the headers property
+ * provided in this class and write the data to the body of the request.
+ * HttpClientRequest is an [IOSink]. Use the methods from IOSink,
+ * such as writeCharCode(), to write the body of the HTTP
+ * request. When one of the IOSink methods is used for the first
+ * time, the request header is sent. Calling any methods that
+ * change the header after it is sent throws an exception.
  *
  * When writing string data through the [IOSink] the
- * encoding used will be determined from the "charset" parameter of
+ * encoding used is determined from the "charset" parameter of
  * the "Content-Type" header.
  *
  *     HttpClientRequest request = ...
  *     request.headers.contentType
  *         = new ContentType("application", "json", charset: "utf-8");
  *     request.write(...);  // Strings written will be UTF-8 encoded.
  *
- * If no charset is provided the default of ISO-8859-1 (Latin 1) will
+ * If no charset is provided the default of ISO-8859-1 (Latin 1) is
  * be used.
  *
  *     HttpClientRequest request = ...
  *     request.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
  *     request.write(...);  // Strings written will be ISO-8859-1 encoded.
  *
- * If an unsupported encoding is used an exception will be thrown if
- * using one of the write methods taking a string.
+ * An exception is thrown if you use an unsupported encoding and the
+ * `write()` method being used takes a string parameter.
  */
 abstract class HttpClientRequest implements IOSink {
   /**
    * Gets and sets the requested persistent connection state.
    *
    * The default value is [:true:].
    */
   bool persistentConnection;
 
   /**
@@ skipping 66 matching lines @@
 
   /**
    * Get information about the client connection. Returns [:null:] if the socket
    * is not available.
    */
   HttpConnectionInfo get connectionInfo;
 }
 
 
 /**
- * HTTP response for a client connection. The [HttpClientResponse] is a
- * [Stream] of the body content of the response. Listen to the body to handle
- * the data and be notified once the entire body is received.
+ * HTTP response for a client connection.
+
+ * The body of a [HttpClientResponse] object is a
+ * [Stream] of data from the server. Listen to the body to handle
+ * the data and be notified when the entire body is received.
+ *
+ *     new HttpClient().get('localhost', 80, '/file.txt')
+ *          .then((HttpClientRequeset request) => request.close())
+ *          .then((HttpClientResponse response) {
+ *            response.transform(UTF8.decoder).listen((contents) {
+ *              // handle data
+ *            });
+ *          });
  */
 abstract class HttpClientResponse implements Stream<List<int>> {
   /**
    * Returns the status code.
    */
   int get statusCode;
 
   /**
    * Returns the reason phrase associated with the status code.
    */
@@ skipping 170 matching lines @@
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(this.message, this.redirects);
 
   String toString() => "RedirectException: $message";
 
   Uri get uri => redirects.last.location;
 }