Version 1.3.0-dev.7.7
svn merge -c 34524 https://dart.googlecode.com/svn/branches/bleeding_edge trunk
svn merge -c 34557 https://dart.googlecode.com/svn/branches/bleeding_edge trunk
git-svn-id: http://dart.googlecode.com/svn/trunk@34591 260f80e4-7a28-3924-810f-c04153c831b5
diff --git a/sdk/lib/io/http.dart b/sdk/lib/io/http.dart
index 366fd8d..dee31ab 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -55,31 +55,101 @@
/**
- * 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 (1024 and above).
*
- * 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.
+ *
+ * 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 the Mozilla certutil
+ * must be used to manipulate the certificate database.
+ *
+ * ## Connect to a server socket
+ *
+ * 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.
+ * Pausing the subscription of the stream, pauses at the OS level.
+ *
+ * * 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> {
/**
@@ -261,12 +331,33 @@
/**
- * 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, headers are immutable:
+ *
+ * * HttpRequest and HttpClientResponse always have immutable headers.
+ *
+ * * HttpResponse and HttpClientRequest have immutable headers
+ * from the moment the body is written to.
+ *
+ * In these situations, 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";
@@ -759,11 +850,11 @@
* 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) {
@@ -778,12 +869,10 @@
* 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;
@@ -893,18 +982,37 @@
/**
- * An [HttpResponse] represents the headers and data to be returned to
- * a client in response to an HTTP request.
+ * An HTTP response, which returns the headers and data
+ * 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
+ * HttpResponse object.
*
- * When writing string data through the [IOSink] the encoding used
- * will be determined from the "charset" parameter of the
+ * ## Writing the response
+ *
+ * This class implements [IOSink].
+ * After 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.
+ *
+ * ## Setting the headers
+ *
+ * The HttpResponse object has a number of properties for setting up
+ * the HTTP headers of the response.
+ * When writing string data through the IOSink, the encoding used
+ * is determined from the "charset" parameter of the
* "Content-Type" header.
*
* HttpResponse response = ...
@@ -919,8 +1027,8 @@
* 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 the `write()` method
+ * while an unsupported content-type is set.
*/
abstract class HttpResponse implements IOSink {
// TODO(ajohnsen): Add documentation of how to pipe a file to the response.
@@ -1011,57 +1119,72 @@
* 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. Either the first write to the request object
+ * or a call to [close] sends the request to the server.
*
- * 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.
+ * // Optionally set up headers...
+ * // Optionally write to the request object...
+ * // Then call close.
+ * ...
* 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.
+ * To turn off gzip compression of the response, clear this header:
*
- * The [HttpClient] supports persistent connections and caches network
- * connections to reuse then for multiple requests whenever
+ * request.headers.removeAll(HttpHeaders.ACCEPT_ENCODING)
+ *
+ * ## Closing the HttpClient
+ *
+ * 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();
@@ -1346,15 +1469,16 @@
/**
* 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 = ...
@@ -1362,15 +1486,15 @@
* = 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 {
/**
@@ -1457,9 +1581,19 @@
/**
- * 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>> {
/**
diff --git a/sdk/lib/io/http_date.dart b/sdk/lib/io/http_date.dart
index 9720426..94a3298 100644
--- a/sdk/lib/io/http_date.dart
+++ b/sdk/lib/io/http_date.dart
@@ -51,11 +51,11 @@
..write(month[d.month - 1])
..write(" ")
..write(d.year.toString())
- ..write(d.hour < 9 ? " 0" : " ")
+ ..write(d.hour <= 9 ? " 0" : " ")
..write(d.hour.toString())
- ..write(d.minute < 9 ? ":0" : ":")
+ ..write(d.minute <= 9 ? ":0" : ":")
..write(d.minute.toString())
- ..write(d.second < 9 ? ":0" : ":")
+ ..write(d.second <= 9 ? ":0" : ":")
..write(d.second.toString())
..write(" GMT");
return sb.toString();
diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index f8d8543..b1e5be7 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -41,10 +41,14 @@
/**
- * The [InternetAddress] is an object reflecting either a remote or a
- * local address. When combined with a port number, this represents a
- * endpoint that a socket can connect to or a listening socket can
- * bind to.
+ * An internet address.
+ *
+ * This object holds an internet address. If this internet address
+ * is the result of a DNS lookup, the address also holds the hostname
+ * used to make the lookup.
+ * An Internet address combined with a port number represents an
+ * endpoint to which a socket can connect or a listening socket can
+ * bind.
*/
abstract class InternetAddress {
/**
diff --git a/tests/corelib/date_time_test.dart b/tests/corelib/date_time_test.dart
index dcd656d..e9fc4783 100644
--- a/tests/corelib/date_time_test.dart
+++ b/tests/corelib/date_time_test.dart
@@ -908,6 +908,7 @@
test("-2000-01-01", "12:00:00.000");
test("1970-01-01", "00:00:00.000");
test("1969-12-31", "23:59:59.999");
+ test("1969-09-09", "00:09:09.009");
}
void main() {
diff --git a/tests/standalone/io/http_date_test.dart b/tests/standalone/io/http_date_test.dart
index 960ff82..6e5cd6b 100644
--- a/tests/standalone/io/http_date_test.dart
+++ b/tests/standalone/io/http_date_test.dart
@@ -44,6 +44,7 @@
test(1999, DateTime.JUNE, 11, 18, 46, 53, "Fri, 11 Jun 1999 18:46:53 GMT");
test(1970, DateTime.JANUARY, 1, 0, 0, 0, "Thu, 1 Jan 1970 00:00:00 GMT");
+ test(1970, DateTime.JANUARY, 1, 9, 9, 9, "Thu, 1 Jan 1970 09:09:09 GMT");
test(2012, DateTime.MARCH, 5, 23, 59, 59, "Mon, 5 Mar 2012 23:59:59 GMT");
}
diff --git a/tools/VERSION b/tools/VERSION
index 3db5927..18299e5 100644
--- a/tools/VERSION
+++ b/tools/VERSION
@@ -28,4 +28,4 @@
MINOR 3
PATCH 0
PRERELEASE 7
-PRERELEASE_PATCH 6
+PRERELEASE_PATCH 7
