Allow additional headers for WebSocket connect

sdk/lib/io/websocket.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;
 
 /**
  * Web socket status codes used when closing a web socket connection.
  */
 abstract class WebSocketStatus {
@@ skipping 50 matching lines @@
    * select what protocol to use, if any were provided by the client.
    * [protocolSelector] is should return either a [String] or a [Future]
    * completing with a [String]. The [String] must exist in the list of
    * protocols.
    */
   factory WebSocketTransformer({protocolSelector(List<String> protocols)})
       => new _WebSocketTransformerImpl(protocolSelector);
 
   /**
    * Upgrades a [HttpRequest] to a [WebSocket] connection. If the
    * request is not a valid web socket upgrade request a HTTP response

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

a HTTP -> an HTTP

    * with status code 500 will be returned. Otherwise the returned
    * future will complete with the [WebSocket] when the upgrade pocess
    * is complete.
    *
    * If [protocolSelector] is provided, [protocolSelector] will be called to
    * select what protocol to use, if any were provided by the client.
    * [protocolSelector] is should return either a [String] or a [Future]
    * completing with a [String]. The [String] must exist in the list of
    * protocols.
    */
@@ skipping 36 matching lines @@
    * There are never two outstanding pings at any given time, and the next ping
    * timer starts when the pong is received.
    *
    * Set the [pingInterval] to `null` to disable sending ping messages.
    *
    * The default value is `null`.
    */
   Duration pingInterval;
 
   /**
    * Create a new web socket connection. The URL supplied in [url]

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

I think "web socket" is usually written "WebSocket". 
Probably change it everywhere.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

-   * must use the scheme [:ws:] or [:wss:]. The [protocols] argument is
-   * specifying the subprotocols the client is willing to speak.
+   * must use the scheme `ws` or `wss`.
+   *
+   * The [protocols] argument is specifying the subprotocols the
+   * client is willing to speak.
+   *
+   * The [headers] argument is specifying additional HTTP headers for
+   * the initial upgrade request. This would typically be the `Origin`
+   * header and potentially cookies. The key of the map are the header

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

The key -> The keys.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * fields and the values are either String or List<String>.

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

What is an "upgrade request"? Either say something about the underlying protocol
or link to an external description.

[Søren Gjesse, 2015/01/14 13:54:26]

Changed

the initial upgrade request

to

setting up the connection

+   *
+   * Even if [headers] is provided, there are a number of headers

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

Drop the "even" part. Just go directly to the facts.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * which are controlled by the web socket connection process. These
+   * headers are: `connection`, `sec-websocket-version`,
+   * `sec-websocket-key`, `upgrade` and `sec-websocket-protocol`. If

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

Put the headers in alphabetical order. It looks random now.
Maybe make it a bullet list?

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+   * any of these are passed in the `headers` they will be ignored.

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

add "map" after `headers`. Just "the headers" doesn't sound right.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

    */
   static Future<WebSocket> connect(String url,
-                                   {List<String> protocols: const []}) =>
-      _WebSocketImpl.connect(url, protocols);
+                                   {Iterable<String> protocols: const [],

[Lasse Reichstein Nielsen, 2015/01/14 10:49:21]

I'd use "null" as default, and then do the dispatch inside the function. No need
to put the "const []" into the API documentation.

[Søren Gjesse, 2015/01/14 13:54:26]

Done.

+                                    Map<String, dynamic> headers}) =>
+      _WebSocketImpl.connect(url, protocols, headers);
 
   @Deprecated('This constructor will be removed in Dart 2.0. Use `implements`'
       ' instead of `extends` if implementing this abstract class.')
   WebSocket();
 
   /**
    * Creates a WebSocket from an already-upgraded socket.
    *
    * The initial WebSocket handshake must have occurred prior to this call. A
    * WebSocket client can automatically perform the handshake using
@@ skipping 69 matching lines @@
    */
   Future addStream(Stream stream);
 }
 
 
 class WebSocketException implements IOException {
   final String message;
   const WebSocketException([this.message = ""]);
   String toString() => "WebSocketException: $message";
 }