RFC: Sending pre-encoded text over a web socket.

sdk/lib/io/websocket.dart

Index: sdk/lib/io/websocket.dart
diff --git a/sdk/lib/io/websocket.dart b/sdk/lib/io/websocket.dart
index df6c8cf523390d47e14b0986b4cd27ff3815a016..53f1c7b1ca5556d4e75d2a39b5181392c49deec6 100644
--- a/sdk/lib/io/websocket.dart
+++ b/sdk/lib/io/websocket.dart
@@ -23,6 +23,16 @@ abstract class WebSocketStatus {
   static const int RESERVED_1015 = 1015;
 }
 
+
+/**
+ * WebSocket message types used for [WebSocket.sendMessage].
+ */
+enum WebSocketMessageType {
+  TEXT,
+  BINARY
+}
+
+
 /**
  * The [CompressionOptions] class allows you to control
  * the options of WebSocket compression.
@@ -402,6 +412,11 @@ abstract class WebSocket
    * must be either `String`s, or `List<int>`s holding bytes.
    */
   Future addStream(Stream stream);
+
+  /**
+   * Sends a binary message or a pre-encoded text message.
+   */
+  void sendMessage(WebSocketMessageType type, List<int> bytes);

[Lasse Reichstein Nielsen, 2016/08/24 05:10:12]

For consistency, the name should start with "add".
Maybe "addRawMessage"?

Also, what is the difference between 
  add(uint8List)
and
  sendMessage(WebSocketMessageType.binary, uint8List)
?
If there isn't any, there is no need to duplicate the functionality.
Instead just have:
  /**
   * Sends a text message with the text represented by [bytes].
   *
   * The [bytes] should be valid UTF-8 encoded Unicode characters.
   */
  addUtf8String(List<int> bytes);

[Lasse Reichstein Nielsen, 2016/08/24 05:51:04]

Or maybe addUtf8Text - it seems that WebSockets talk about "text", not "string".

It should probably also be specified what happens if the encoding is incorrect. 

Is it parsed with invalid sequences replaced by the replacement character, or is
the message lost?

[Cutch, 2016/08/24 14:01:41]

According to the spec https://tools.ietf.org/html/rfc6455#section-8.1 the
connection must be closed by the receiving end.

[Lasse Reichstein Nielsen, 2016/08/24 14:16:47]

That's a perfectly reasonable response, and it should be documented here as
well. IT's not necessary for `add` where we do the encoding, but here we should
document what the user should do and what happens if they don't.

 }
 
 class WebSocketException implements IOException {