Add a top-level status library. R=kevmoo@google.com Review URL: https://codereview.chromium.org//1758053002 .
diff --git a/pkgs/web_socket_channel/README.md b/pkgs/web_socket_channel/README.md index 3e984aa..2ea4408 100644 --- a/pkgs/web_socket_channel/README.md +++ b/pkgs/web_socket_channel/README.md
@@ -11,6 +11,26 @@ [IOWebSocketChannel]: https://www.dartdocs.org/documentation/web_socket_channel/latest/io/IOWebSocketChannel-class.html [HtmlWebSocketChannel]: https://www.dartdocs.org/documentation/web_socket_channel/latest/html/HtmlWebSocketChannel-class.html +It also provides constants for the WebSocket protocol's pre-defined status codes +in the [`status.dart` library][status]. It's strongly recommended that users +import this library should be imported with the prefix `status`. + +[status]: https://www.dartdocs.org/documentation/web_socket_channel/latest/status/status-library.html + +```dart +import 'package:web_socket_channel/io.dart'; +import 'package:web_socket_channel/status.dart' as status; + +main() async { + var channel = await IOWebSocketChannel.connect("ws://localhost:1234"); + + channel.stream.listen((message) { + channel.sink.add("received!"); + channel.close(status.goingAway); + }); +} +``` + ## `WebSocketChannel` The [`WebSocketChannel`][WebSocketChannel] class's most important role is as the
diff --git a/pkgs/web_socket_channel/lib/io.dart b/pkgs/web_socket_channel/lib/io.dart index 355e250..8c225be 100644 --- a/pkgs/web_socket_channel/lib/io.dart +++ b/pkgs/web_socket_channel/lib/io.dart
@@ -39,10 +39,10 @@ /// /// [pingInterval] controls the interval for sending ping signals. If a ping /// message is not answered by a pong message from the peer, the WebSocket is - /// assumed disconnected and the connection is closed with a - /// [WebSocketStatus.GOING_AWAY] close code. When a ping signal is sent, the - /// pong message must be received within [pingInterval]. It defaults to - /// `null`, indicating that ping messages are disabled. + /// assumed disconnected and the connection is closed with a `goingAway` code. + /// When a ping signal is sent, the pong message must be received within + /// [pingInterval]. It defaults to `null`, indicating that ping messages are + /// disabled. /// /// If there's an error connecting, the channel's stream emits a /// [WebSocketChannelException] wrapping that error and then closes.
diff --git a/pkgs/web_socket_channel/lib/src/channel.dart b/pkgs/web_socket_channel/lib/src/channel.dart index 0f640de..446eb69 100644 --- a/pkgs/web_socket_channel/lib/src/channel.dart +++ b/pkgs/web_socket_channel/lib/src/channel.dart
@@ -80,10 +80,10 @@ /// /// [pingInterval] controls the interval for sending ping signals. If a ping /// message is not answered by a pong message from the peer, the WebSocket is - /// assumed disconnected and the connection is closed with a - /// [WebSocketStatus.GOING_AWAY] close code. When a ping signal is sent, the - /// pong message must be received within [pingInterval]. It defaults to - /// `null`, indicating that ping messages are disabled. + /// assumed disconnected and the connection is closed with a `goingAway` close + /// code. When a ping signal is sent, the pong message must be received within + /// [pingInterval]. It defaults to `null`, indicating that ping messages are + /// disabled. /// /// If this is a WebSocket server, [serverSide] should be `true` (the /// default); if it's a client, [serverSide] should be `false`.
diff --git a/pkgs/web_socket_channel/lib/status.dart b/pkgs/web_socket_channel/lib/status.dart new file mode 100644 index 0000000..8bd3f16 --- /dev/null +++ b/pkgs/web_socket_channel/lib/status.dart
@@ -0,0 +1,88 @@ +// Copyright (c) 2016, 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. + +/// Status codes that are defined in the WebSocket spec. +/// +/// This library is intended to be imported with a prefix. +/// +/// ```dart +/// import 'package:web_socket_channel/io.dart'; +/// import 'package:web_socket_channel/status.dart' as status; +/// +/// main() async { +/// var channel = await IOWebSocketChannel.connect("ws://localhost:1234"); +/// // ... +/// channel.close(status.goingAway); +/// } +/// ``` +import 'dart:core'; + +/// The purpose for which the connection was established has been fulfilled. +const normalClosure = 1000; + +/// An endpoint is "going away", such as a server going down or a browser having +/// navigated away from a page. +const goingAway = 1001; + +/// An endpoint is terminating the connection due to a protocol error. +const protocolError = 1002; + +/// An endpoint is terminating the connection because it has received a type of +/// data it cannot accept. +/// +/// For example, an endpoint that understands only text data MAY send this if it +/// receives a binary message). +const unsupportedData = 1003; + +/// No status code was present. +/// +/// This **must not** be set explicitly by an endpoint. +const noStatusReceived = 1005; + +/// The connection was closed abnormally. +/// +/// For example, this is used if the connection was closed without sending or +/// receiving a Close control frame. +/// +/// This **must not** be set explicitly by an endpoint. +const abnormalClosure = 1006; + +/// An endpoint is terminating the connection because it has received data +/// within a message that was not consistent with the type of the message. +/// +/// For example, the endpoint may have receieved non-UTF-8 data within a text +/// message. +const invalidFramePayloadData = 1007; + +/// An endpoint is terminating the connection because it has received a message +/// that violates its policy. +/// +/// This is a generic status code that can be returned when there is no other +/// more suitable status code (such as [unsupportedData] or [messageTooBig]), or +/// if there is a need to hide specific details about the policy. +const policyViolation = 1008; + +/// An endpoint is terminating the connection because it has received a message +/// that is too big for it to process. +const messageTooBig = 1009; + +/// The client is terminating the connection because it expected the server to +/// negotiate one or more extensions, but the server didn't return them in the +/// response message of the WebSocket handshake. +/// +/// The list of extensions that are needed should appear in the close reason. +/// Note that this status code is not used by the server, because it can fail +/// the WebSocket handshake instead. +const missingMandatoryExtension = 1010; + +/// The server is terminating the connection because it encountered an +/// unexpected condition that prevented it from fulfilling the request. +const internalServerError = 1011; + +/// The connection was closed due to a failure to perform a TLS handshake. +/// +/// For example, the server certificate may not have been verified. +/// +/// This **must not** be set explicitly by an endpoint. +const tlsHandshakeFailed = 1015;
diff --git a/pkgs/web_socket_channel/pubspec.yaml b/pkgs/web_socket_channel/pubspec.yaml index c6ad187..2888da6 100644 --- a/pkgs/web_socket_channel/pubspec.yaml +++ b/pkgs/web_socket_channel/pubspec.yaml
@@ -1,5 +1,5 @@ name: web_socket_channel -version: 1.0.0-dev +version: 1.0.0 description: StreamChannel wrappers for WebSockets. author: Dart Team <misc@dartlang.org> homepage: https://github.com/dart-lang/web_socket_channel