Initial web socket server implementation

runtime/bin/websocket.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.
+
+/**
+ * The web socket protocol is implemented by a HTTP server handler
+ * which can be instantiated like this:
+ *
+ * WebSocketHandler wsHandler = new WebSocketHandler();
+ *
+ * and then its onRequest method can be assigned to the HTTP server, e.g.
+ *
+ * server.defaultHandler = wsHandler.onRequest;
+ *
+ * or
+ *
+ * server.addRequestHandler((req) => reg.path == "/ws", wsHandler.onRequest);
+ *
+ */
+interface WebSocketHandler default _WebSocketHandler {
+  WebSocketHandler();
+
+  /**
+   * Request handler to be registered with the HTTP server.
+   */
+  void onRequest(HttpRequest request, HttpResponse response);
+
+  /**
+   * Sets the callback to be called when a new web socket connection
+   * has been established.
+   */
+  void set onConnection(callback(WebSocketConnection connection));
+}
+
+
+/**
+ * Web socket connection.
+ */
+interface WebSocketConnection {
+  /**
+   * Sets the callback to be called when a message have been
+   * received. The type on [message] is either [:String:] or
+   * [:List<int>:] depending on whether it is a text or binary
+   * message. If the message is empty [message] will be [:null:].
+   */
+  void set onMessage(void callback(Object message));

[vsm, 2012/04/25 16:45:18]

Consider making this consistent with onError below and omitting "Object".

FWIW, we've been consistently using a "Dynamic" type / no type in the
dom/html/ui APIs in this sort of case instead of Object.  The rationale is the
Object should indicate that any type is valid while Dynamic indicates that the
precise type cannot be specified.

[Søren Gjesse, 2012/04/26 09:37:44]

Done. I agree with the distinction between Object and Dynamic - we have tried to
do the same in dart:io.

+
+  /**
+   * Sets the callback to be called when the web socket connection is
+   * closed.
+   */
+  void set onClosed(void callback(int status, String reason));

[vsm, 2012/04/25 16:45:18]

onClose to be consistent with w3c?

[Søren Gjesse, 2012/04/26 09:37:44]

This is problematic. All over dart:io we are using onClosed (with the d), and
for that reason I will leave it with the d for now.

+
+  /**
+   * Sets the callback to be called when the web socket connection
+   * encountered an error.
+   */
+  void set onError(void callback(e));
+
+  /**

[vsm, 2012/04/25 16:45:18]

Does onOpen (from the spec) make sense here?

[Søren Gjesse, 2012/04/26 09:37:44]

As this is the server side the onOpen corresponds to the onConnection on the
WebSocketHandler interface above. On the server you get the connection when it
is already established, so it cannot be part of the WebSocketConnection object.
I have renamed onConnection to onOpen on the WebSocketHandler interface to be
somewhat consistent with w3c.

+   * Sends a message. The [message] must be a [:String:] a
+   * [:List<int>:] or [:null:].
+   */
+  send(Object message);
+
+  /**
+   * Close the web socket connection. The default value for [status]
+   * and [reason] are [:null:].
+   */
+  close([int status, String reason]);
+}
+
+
+class WebSocketException implements Exception {
+  const WebSocketException([String this.message = ""]);
+  String toString() => "WebSocketException: $message";
+  final String message;
+}