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

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;
 
 /**
  * WebSocket status codes used when closing a WebSocket 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;
 }
 
+
+/**
+ * WebSocket message types used for [WebSocket.sendMessage].
+ */
+enum WebSocketMessageType {
+  TEXT,
+  BINARY
+}
+
+
 /**
  * The [CompressionOptions] class allows you to control
  * the options of WebSocket compression.
  */
 class CompressionOptions {
   /**
    * Default WebSocket Compression options.
    * Compression will be enabled with the following options:
    * clientNoContextTakeover: false
    * serverNoContextTakeover: false
@@ skipping 359 matching lines @@
    * be either a `String`, or a `List<int>` holding bytes.
    */
   void add(/*String|List<int>*/ data);
 
   /**
    * Sends data from a stream on WebSocket connection. Each data event from
    * [stream] will be send as a single WebSocket frame. The data from [stream]
    * 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 {
   final String message;
 
   const WebSocketException([this.message = ""]);
 
   String toString() => "WebSocketException: $message";
 }