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 generally already in use, so your servers should use a

[Søren Gjesse, 2014/03/25 10:27:26]

Thin this sentence should be something like this:

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).

[mem, 2014/03/25 17:30:49]

Done.

+ * non-reserved port (above 1023).
  *
- * 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 a secure HTTPS connection.

[Søren Gjesse, 2014/03/25 10:27:26]

'create a secure HTTPS connection' -> 'create a HTTPS server'.

[mem, 2014/03/25 17:30:49]

Done.

+ * The client needs to present a value certificate to connect successfully.

[Søren Gjesse, 2014/03/25 10:27:26]

The client does not need to present a certificate unless the optional argument
requestClientCertificate is set to true. I dont we should talk about client
certificates here.

It is the server that needs a certificate to present to the client. This is the
certificate named 'localhost_cert' in the certificate database found in the
'pkcert' directory.

This certificate database is managed using the Mozilla certutil tool (see
https://developer.mozilla.org/en-US/docs/NSS/tools/NSS_Tools_certutil). We
should mention that we use the NSS library to handle SSL and that the Mozilla
certutil must be used to manipulate the certificate database.

[mem, 2014/03/25 17:30:49]

Done.

+ * The code below uses a certificate used by Dart for testing purposes.
+ *
+ *     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,
+ *                       80,

[Søren Gjesse, 2014/03/25 10:27:26]

Use the default HTTPS port 443 here.

[mem, 2014/03/25 17:30:49]

Done.

+ *                       backlog: 5,

[Søren Gjesse, 2014/03/25 10:27:26]

Just remove the backlog optional argument in the sample.

[mem, 2014/03/25 17:30:49]

Done.

+ *                       certificateName: 'localhost_cert')
+ *           .then((server) {
+ *             ReceivePort serverPort = new ReceivePort();

[Søren Gjesse, 2014/03/25 10:27:26]

Please remove the receive port.

[mem, 2014/03/25 17:30:49]

Done.

+ *             server.listen((HttpRequest request) {
+ *               request.response.write('Hello, world!');
+ *               request.response.close();
+ *             });
+ *           });
+ *     }
+ *
+ * ## Connect to a socket
+ *
+ * You can use the [listenOn] constructor to attach an HTTP server to
+ * a [ServerSocket]. By subclassing ServerSocket you can provide

[Søren Gjesse, 2014/03/25 10:27:26]

I don't think we should mention "subclassing ServerSocket" - do we have a
use-case for that?

[mem, 2014/03/25 17:30:49]

Done.

+ * socket specialization.
+ *
+ *     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.
+ * 
+ * * 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,
+ * 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 `add()` method:
+ *
+ *     request.headers.add(HttpHeaders.CONTENT_ENCODING, 'JSON');

[Søren Gjesse, 2014/03/25 10:27:26]

We should probably use a more common header, e.g. HttpHeaders.CONTENT_TYPE or
HttpHeaders.CACHE_CONTROL, e.g.

request.headers.set(HttpHeaders.CACHE_CONTROL, 'max-age=3600, must-revalidate');

also use 'set' instead of 'add'. For most headers setting a single value is the
right thing to do.

+ *
+ * To retrieve the value of a header use the `value()` method:
+ *
+ *     print(request.headers.value(HttpHeaders.FROM));

[Søren Gjesse, 2014/03/25 10:27:26]

I think FROM is not the best choice here - don't think it is set very often. How
about USER_AGENT instead?

[mem, 2014/03/25 17:30:49]

Done.

+ *
+ * Alternatively, you can use the square bracket (`[]`) operator:
+ *     request.headers['FROM'] = john@example.com'

[Søren Gjesse, 2014/03/25 10:27:26]

The operator[] is only for getting the list of values, e.g.

  print(request.headers['FROM'])

however using this always returns a list of values.

I think some additional information on the HttpHeaders object is needed. In that
is holds a list of values for each name as the standard allows. In most cases a
name only holds a single value, so setting using 'set' and retreive using
value() is the most common mode of operation.

[mem, 2014/03/25 17:30:49]

Done.

[mem, 2014/03/25 17:30:49]

Done.

  */
 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,
+ * An HttpRequest object contains an [HttpResponse] object,

[Søren Gjesse, 2014/03/25 10:27:26]

'contains an' provides access to the associated HttpResponse object through the
response property.

[mem, 2014/03/25 17:30:49]

Done.

  * to which the server can write its response.
- * For example, here's a skeletal callback function
- * that responds to a request:
+ * 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
+ * from the server to the client in response to an HTTP request.
  *
+ * Every HttpRequest object contains an HttpResponse object,

[Søren Gjesse, 2014/03/25 10:27:26]

See above.

[mem, 2014/03/25 17:30:49]

Done.

+ * by which the server sends a response to the client.
  * 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.
+ * header of the response. This class implements [IOSink].
+ * 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.
  *
- * When writing string data through the [IOSink] the encoding used
- * will be determined from the "charset" parameter of the
+ *     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.
  */
 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 [HttpServer] and receive an [HttpClientResponse] back.

[Søren Gjesse, 2014/03/25 10:27:26]

[HttpServer] should just be HTTP server, as it can be any server, not just one
implemented in dart:io.

[mem, 2014/03/25 17:30:49]

Done.

[mem, 2014/03/25 17:30:49]

Done.

+ * 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.
+ * A `getUrl` request is a two-step process, triggered by two [Future]s.
+ * When the first future completes with a HttpClientRequest, the underlying

[Søren Gjesse, 2014/03/25 10:27:26]

`` or [] around HttpClientRequest. I cannot remember when [] provides a
functional link - is it only for arguments?

[mem, 2014/03/25 17:30:49]

Done.

+ * 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.
+ *
+ * When the response is received from the server,
+ * the second future, which is returned by close, completes with
+ * an [HttpClientResponse] object.

[Søren Gjesse, 2014/03/25 10:27:26]

Maybe `` instead of [].

[mem, 2014/03/25 17:30:49]

Done.

 
- * The future for [HttpClientRequest] is created by methods such as
- * [getUrl] and [open].
- *
- * 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,

[Søren Gjesse, 2014/03/25 10:27:26]

This seems to be duplicate of the paragraph above.

[mem, 2014/03/25 17:30:49]

Done.

+ * 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/"))

[Søren Gjesse, 2014/03/25 10:27:26]

Let's stick to the 4-space indent specified by the style guide.

[mem, 2014/03/25 17:30:49]

Done.

- *         .then((HttpClientRequest request) {
- *           // Prepare the request then call close on it to send it.
- *           return request.close();
- *         })
- *         .then((HttpClientResponse response) {
- *          // Process the response.
- *         });
+ *           .then((HttpClientRequest request) {
+ *             // Prepare the request, then call close to send it.
+ *             ...
+ *             return request.close();
+ *           })
+ *           .then((HttpClientResponse 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.
  *
- * The [HttpClient] supports persistent connections and caches network
- * connections to reuse then for multiple requests whenever
+ * ## Closing the connection
+ *
+ * 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 one of the many properties

[Søren Gjesse, 2014/03/25 10:27:26]

The headers is not set using 'one of the many properties provided in this class'
but through the headers property.

[mem, 2014/03/25 17:30:49]

Done.

+ * provided in this class and write the data to the body of the request.
+ * HttpClientRequest is an [IOSink]. Use one of the methods from IOSink,

[Søren Gjesse, 2014/03/25 10:27:26]

Remove 'one of' as you can use several in combination.

[mem, 2014/03/25 17:30:49]

Done.

+ * 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().post('localhost', 80, '/file.txt')

[Søren Gjesse, 2014/03/25 10:27:26]

Use get here to avoid data in the request.

[mem, 2014/03/25 17:30:49]

Done.

[mem, 2014/03/25 17:30:49]

Done.

+ *          .then( ... )

[Søren Gjesse, 2014/03/25 10:27:26]

Change

  .then( ... )

to

  .then((HttpClientRequest request) => request.close())

[mem, 2014/03/25 17:30:49]

Done.

+ *          .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;
 }