dart:io | Add badCertificateCallback to HttpClient.

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 124 matching lines @@
    *
    * If [port] has the value [:0:] an ephemeral port will be chosen by
    * the system. The actual port used can be retrieved using the
    * [port] getter.
    *
    * The optional argument [backlog] can be used to specify the listen
    * backlog for the underlying OS listen setup. If [backlog] has the
    * value of [:0:] (the default) a reasonable value will be chosen by
    * the system.
    *
-   * The certificate with Distinguished Name [certificateName] is looked
-   * up in the certificate database, and is used as the server certificate.
-   * if [requestClientCertificate] is true, the server will request clients
-   * to authenticate with a client certificate.
+   * The certificate with nickname or distinguished name (DN) [certificateName]
+   * is looked up in the certificate database, and is used as the server
+   * certificate. If [requestClientCertificate] is true, the server will
+   * request clients to authenticate with a client certificate.
    */
 
   static Future<HttpServer> bindSecure(address,
                                        int port,
                                        {int backlog: 0,
                                         String certificateName,
                                         bool requestClientCertificate: false})
       => _HttpServer.bindSecure(address,
                                 port,
                                 backlog,
@@ skipping 1006 matching lines @@
 
   /**
    * Add credentials to be used for authorizing HTTP proxies.
    */
   void addProxyCredentials(String host,
                            int port,
                            String realm,
                            HttpClientCredentials credentials);
 
   /**
+   * Set a callback that will decide whether to accept a secure connection
+   * with a server certificate that cannot be authenticated by any of our
+   * trusted root certificates.
+   *
+   * The callback takes an [X509Certificate] object and the server's hostname
+   * and port, and returns true if the connection should be accepted.
+   * If the callback returns true, the future completes

[Søren Gjesse, 2013/08/13 16:56:08]

"the future" - please be more specific to what future that is (HttpClient.open
and friends I assume).

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   * with an HttpRequest object.  Otherwise, the future completes with an error.

[Søren Gjesse, 2013/08/13 16:56:08]

Maybe mention explicitly that "otherwise" includes the calback throwing.

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   *
+   * Each [open] or [get] call uses the value of badCertificateCallback

[Søren Gjesse, 2013/08/13 16:56:08]

We have all of open, openUrl, get, getUrl, port, postUrl, but I don't think we
are normally mentioning all of them...

[Bill Hesse, 2013/08/14 09:25:48]

Done.

+   * at the time the call is made, to handle a bad certificate that is received
+   * while making the connection with the server asynchronously at a later time.
+   */
+  set badCertificateCallback(bool callback(X509Certificate cert,
+                                           String host,
+                                           int port));
+
+  /**
    * Shutdown the HTTP client. If [force] is [:false:] (the default)
    * the [:HttpClient:] will be kept alive until all active
    * connections are done. If [force] is [:true:] any active
    * connections will be closed to immediately release all
    * resources. These closed connections will receive an [:onError:]
    * callback to indicate that the client was shutdown. In both cases
    * trying to establish a new connection after calling [shutdown]
    * will throw an exception.
    */
   void close({bool force: false});
@@ skipping 122 matching lines @@
    * Returns the status code.
    */
   int get statusCode;
 
   /**
    * Returns the reason phrase associated with the status code.
    */
   String get reasonPhrase;
 
   /**
-   * Returns the content length of the request body. Returns -1 if the size of
-   * the request body is not known in advance.
+   * Returns the content length of the response body. Returns -1 if the size of
+   * the response body is not known in advance.
    */
   int get contentLength;
 
   /**
    * Gets the persistent connection state returned by the server.
    */
   bool get persistentConnection;
 
   /**
    * Returns whether the status code is one of the normal redirect
@@ skipping 154 matching lines @@
 
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(String this.message,
                           List<RedirectInfo> this.redirects);
 
   String toString() => "RedirectException: $message";
 }