Add individual HTTP request to web socket upgrade support

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 {
   static const int NORMAL_CLOSURE = 1000;
   static const int GOING_AWAY = 1001;
   static const int PROTOCOL_ERROR = 1002;
   static const int UNSUPPORTED_DATA = 1003;
   static const int RESERVED_1004  = 1004;
   static const int NO_STATUS_RECEIVED = 1005;
   static const int ABNORMAL_CLOSURE = 1006;
   static const int INVALID_FRAME_PAYLOAD_DATA = 1007;
   static const int POLICY_VIOLATION = 1008;
   static const int MESSAGE_TOO_BIG = 1009;
   static const int MISSING_MANDATORY_EXTENSION = 1010;
   static const int INTERNAL_SERVER_ERROR = 1011;
   static const int RESERVED_1015 = 1015;
 }
 
 /**
- * The [WebSocketTransformer] is implemented as a stream transformer that
- * transforms a stream of HttpRequest into a stream of WebSockets by upgrading
- * each HttpRequest from the HTTP or HTTPS server, to the WebSocket protocol.
+ * The [WebSocketTransformer] provides the ability to upgrade a
+ * [HttpRequest] to a [WebSocket] connection. It supports both
+ * upgrading a single [HttpRequest] and upgrading a stream of
+ * [HttpRequest]s.
  *
- * Example of usage:
+ * To upgrade a single [HttpRequest] use the static [upgrade] method.
+ *
+ *     HttpServer server;
+ *     server.listen((request) {
+ *       if (...) {
+ *         WebSocketTransformer.upgrade(request).then(websocket) {
+ *           ...
+ *         }
+ *       } else {
+ *         // Do normal HTTP request processing.
+ *       }
+ *     });
+ *
+ * To transform a stream of [HttpRequest] events as it implements a
+ * stream transformer that transforms a stream of HttpRequest into a
+ * stream of WebSockets by upgrading each HttpRequest from the HTTP or
+ * HTTPS server, to the WebSocket protocol.
  *
  *     server.transform(new WebSocketTransformer()).listen((webSocket) => ...);
  *
- * or
- *
- *     server
- *         .where((request) => request.uri.scheme == "ws")
- *         .transform(new WebSocketTransformer()).listen((webSocket) => ...);
- *
  * This transformer strives to implement web sockets as specified by RFC6455.
  */
 abstract class WebSocketTransformer
     implements StreamTransformer<HttpRequest, WebSocket> {
   factory WebSocketTransformer() => new _WebSocketTransformerImpl();
+
+  /**
+   * Upgrades a [HttpRequest] to a [WebSocket] connection. If the
+   * request is not a valid web socket upgrade request a HTTP response
+   * with status code 500 will be returned. Otherwise the returned
+   * future will complete with the [WebSocket] when the upgrade pocess
+   * is complete.
+   */
+  static Future<WebSocket> upgrade(HttpRequest request) {
+    return _WebSocketTransformerImpl._upgrade(request);
+  }
+
+  /**
+   * Checks whether the request is a valid WebSocket upgrade request.
+   */
+  static bool isUpgradeRequest(HttpRequest request) {
+    return _WebSocketTransformerImpl._isUpgradeRequest(request);
+  }
 }
 
 
 /**
  * A client or server web socket connection. The stream exposes the
  * messages received. A text message will be of type [:String:] and a
  * binary message will be of type [:List<int>:].
  */
 abstract class WebSocket implements Stream {
   /**
@@ skipping 56 matching lines @@
    */
   void send(data);
 }
 
 
 class WebSocketException implements Exception {
   const WebSocketException([String this.message = ""]);
   String toString() => "WebSocketException: $message";
   final String message;
 }