Document the HttpClient uses KeepAlive, keeping sockets open for up to 60 seconds after a connectio…

runtime/bin/http.dart

 // Copyright (c) 2012, 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.
 
 /**
  * HTTP status codes.
  */
 interface HttpStatus {
   static final int CONTINUE = 100;
   static final int SWITCHING_PROTOCOLS = 101;
@@ skipping 605 matching lines @@
    * operations on it.
    *
    * This is normally used when a HTTP upgrade request is received
    * and the communication should continue with a different protocol.
    */
   DetachedSocket detachSocket();
 }
 
 
 /**
- * HTTP client factory.
+ * HTTP client factory. The [HttpClient] handles all the sockets associated
+ * with the [HttpClientConnection]s and when the endpoint supports it, it'll

[Bill Hesse, 2012/06/22 08:33:44]

Isn't the real need for documentation on the HttpServer: "When the server
receives an HTTP client request with the keep-alive header, it will keep the
socket open until it has been idle for 60 seconds.  This may keep the server
program running.

[Søren Gjesse, 2012/06/22 08:50:24]

The HttpServer will keep running independently of persistent connections as it
has its listen socket open. HttpServer.close (maybe that should be renamed to
shutdown as well) will close all persistent connections and the listen socket.

[Anders Johnsen, 2012/06/22 09:13:23]

Done.

+ * use keep-alive. This means that sockets may be open up to 60 seconds after

[Søren Gjesse, 2012/06/22 08:12:02]

"it'll use keep-alive" -> it will try to reuse opened sockets for several
requests.

[Søren Gjesse, 2012/06/22 08:12:02]

"may be open up to 60 seconds after a requests have completed" -> "will be kept
open for some time after a requests have completed unless HTTP procedures
indicate that it must be closed as part of completing the request"

[Søren Gjesse, 2012/06/22 08:16:01]

Adding a bit more info.

"it'll use keep-alive" -> "it will try to reuse opened sockets for several
requests to support HTTP 1.1 persistent connections"

[Anders Johnsen, 2012/06/22 09:13:23]

Done.

[Anders Johnsen, 2012/06/22 09:13:23]

Done.

[Anders Johnsen, 2012/06/22 09:13:23]

Done.

+ * a requests have completed. Use [:HttpClient.shutdown:] to force close the
+ * idle sockets.
  */
 interface HttpClient default _HttpClient {
   static final int DEFAULT_HTTP_PORT = 80;
 
   HttpClient();
 
   /**
    * Opens a HTTP connection. The returned [HttpClientConnection] is
    * used to register callbacks for asynchronous events on the HTTP
    * connection. The "Host" header for the request will be set to the
@@ skipping 258 matching lines @@
 class RedirectLimitExceededException extends RedirectException {
   const RedirectLimitExceededException(List<RedirectInfo> redirects)
       : super("Redirect limit exceeded", redirects);
 }
 
 
 class RedirectLoopException extends RedirectException {
   const RedirectLoopException(List<RedirectInfo> redirects)
       : super("Redirect loop detected", redirects);
 }