Merge pull request #1420 from dart-lang/merge-web_socket_channel-package

Merge `package:web_socket_channel`

.github/ISSUE_TEMPLATE/web_socket_channel.md

@@ -0,0 +1,5 @@
+---
+name: "package:web_socket_channel"
+about: "Create a bug or file a feature request against package:web_socket_channel."
+labels: "package:web_socket_channel"
+---

.github/labeler.yml

@@ -32,6 +32,10 @@
   - changed-files:
     - any-glob-to-any-file: 'pkgs/http_parser/**'
 
+'package:web_socket_channel':
+  - changed-files:
+    - any-glob-to-any-file: 'pkgs/web_socket_channel/**'
+
 'package:web_socket_conformance_tests':
   - changed-files:
-    - any-glob-to-any-file: 'pkgs/web_socket_conformance_tests/**'
+    - any-glob-to-any-file: 'pkgs/http_client_conformance_tests/**'

.github/workflows/web_socket_channel.yaml

@@ -0,0 +1,80 @@
+name: package:web_socket_channel
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '.github/workflows/web_socket_channel.yaml'
+      - 'pkgs/web_socket_channel/**'
+  pull_request:
+    paths:
+      - '.github/workflows/web_socket_channel.yaml'
+      - 'pkgs/web_socket_channel/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+defaults:  
+  run:  
+    working-directory: pkgs/web_socket_channel/
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+jobs:
+  # Check code formatting and static analysis on a single OS (linux)
+  # against Dart dev.
+  analyze:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - name: Analyze code
+        run: dart analyze
+        if: always() && steps.install.outcome == 'success'
+
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        sdk: [3.3, dev]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Run VM tests
+        run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'
+      - name: Run Chrome tests
+        run: dart test --platform chrome
+        if: always() && steps.install.outcome == 'success'
+      - name: Run Chrome tests - wasm
+        run: dart test --platform chrome --compiler dart2wasm
+        if: always() && steps.install.outcome == 'success' && matrix.sdk == 'dev'
+
+  # Run analysis against the oldest supported pub constraints.
+  downgrade:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+      - run: dart pub downgrade
+      - run: dart analyze

README.md

@@ -21,6 +21,7 @@ and the browser.
 | [http_profile](pkgs/http_profile/) | A library used by HTTP client authors to integrate with the DevTools Network View. | [![pub package](https://img.shields.io/pub/v/http_profile.svg)](https://pub.dev/packages/http_profile) |
 | [ok_http](pkgs/ok_http/) | An Android Flutter plugin that provides access to the [OkHttp](https://square.github.io/okhttp/) HTTP client and the OkHttp [WebSocket](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-web-socket/index.html) API. | [![pub package](https://img.shields.io/pub/v/ok_http.svg)](https://pub.dev/packages/ok_http) |
 | [web_socket](pkgs/web_socket/) | Any easy-to-use library for communicating with WebSockets that has multiple implementations. | [![pub package](https://img.shields.io/pub/v/web_socket.svg)](https://pub.dev/packages/web_socket) |
+| [web_socket_channel](pkgs/web_socket_channel/) | StreamChannel wrappers for WebSockets. Provides a cross-platform WebSocketChannel API. | [![package issues](https://img.shields.io/badge/package:web_socket_channel-4774bc)](https://github.com/dart-lang/tools/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Aweb_socket_channel) | [![pub package](https://img.shields.io/pub/v/web_socket_channel.svg)](https://pub.dev/packages/web_socket_channel) |
 | [web_socket_conformance_tests](pkgs/web_socket_conformance_tests/) | A library that tests whether implementations of `package:web_socket`'s `WebSocket` class behave as expected. |  |
 
 ## Contributing

pkgs/web_socket_channel/.gitignore

@@ -0,0 +1,3 @@
+.dart_tool/
+.packages
+pubspec.lock

pkgs/web_socket_channel/CHANGELOG.md

@@ -0,0 +1,160 @@
+## 3.0.2
+
+- Move to `dart-lang/http` monorepo.
+
+## 3.0.1
+
+- Remove unnecessary `dependency_overrides`.
+- Remove obsolete documentation for `WebSocketChannel.new`.
+- Update package `web: '>=0.5.0 <2.0.0'`.
+
+## 3.0.0
+
+- Provide an adapter around `package:web_socket` `WebSocket`s and make it the
+  default implementation for `WebSocketChannel.connect`.
+- **BREAKING**: Remove `WebSocketChannel` constructor.
+- **BREAKING**: Make `WebSocketChannel` an `abstract interface`.
+- **BREAKING**: `IOWebSocketChannel.ready` will throw
+  `WebSocketChannelException` instead of `WebSocketException`.
+
+## 2.4.5
+
+- use secure random number generator for frame masking.
+
+## 2.4.4
+
+- Require Dart `^3.3`
+- Require `package:web` `^0.5.0`.
+
+## 2.4.3
+
+- `HtmlWebSocketChannel`: Relax the type of the websocket parameter to the
+  constructor in order to mitigate a breaking change introduced in `2.4.1`.
+
+## 2.4.2 (retracted)
+
+- Allow `web: '>=0.3.0 <0.5.0'`
+
+## 2.4.1
+
+- Update the examples to use `WebSocketChannel.ready` and clarify that
+  `WebSocketChannel.ready` should be awaited before sending data over the
+  `WebSocketChannel`.
+- Mention `ready` in the docs for `connect`.
+- Bump minimum Dart version to 3.2.0
+- Move to `pkg:web` to support WebAssembly compilation.
+
+## 2.4.0
+
+- Add a `customClient` parameter to the `IOWebSocketChannel.connect` factory,
+  which allows the user to provide a custom `HttpClient` instance to use for the
+  WebSocket connection
+- Bump minimum Dart version to 2.15.0
+
+## 2.3.0
+
+- Added a Future `ready` property to `WebSocketChannel`, which completes when
+  the connection is established
+- Added a `connectTimeout` parameter to the `IOWebSocketChannel.connect` factory,
+  which controls the timeout of the WebSocket Future.
+- Use platform agnostic code in README example.
+
+## 2.2.0
+
+- Add `HtmlWebSocketChannel.innerWebSocket` getter to access features not exposed
+  through the shared `WebSocketChannel` interface.
+
+## 2.1.0
+
+- Add `IOWebSocketChannel.innerWebSocket` getter to access features not exposed
+  through the shared `WebSocketChannel` interface.
+
+## 2.0.0
+
+- Support null safety.
+- Require Dart 2.12.
+
+## 1.2.0
+
+* Add `protocols` argument to `WebSocketChannel.connect`. See the docs for
+  `WebSocket.connet`.
+* Allow the latest crypto release (`3.x`).
+
+## 1.1.0
+
+* Add `WebSocketChannel.connect` factory constructor supporting platform
+  independent creation of WebSockets providing the lowest common denominator
+  of support on dart:io and dart:html.
+
+## 1.0.15
+
+* bug fix don't pass protocols parameter to WebSocket.
+
+## 1.0.14
+
+* Updates to handle `Socket implements Stream<Uint8List>`
+
+## 1.0.13
+
+* Internal changes for consistency with the Dart SDK.
+
+## 1.0.12
+
+* Allow `stream_channel` version 2.x
+
+## 1.0.11
+
+* Fixed description in pubspec.
+
+* Fixed lints in README.md.
+
+## 1.0.10
+
+* Fixed links in README.md.
+
+* Added an example.
+
+* Fixed analysis lints that affected package score.
+
+## 1.0.9
+
+* Set max SDK version to `<3.0.0`.
+
+## 1.0.8
+
+* Remove use of deprecated constant name.
+
+## 1.0.7
+
+* Support the latest dev SDK.
+
+## 1.0.6
+
+* Declare support for `async` 2.0.0.
+
+## 1.0.5
+
+* Increase the SDK version constraint to `<2.0.0-dev.infinity`.
+
+## 1.0.4
+
+* Support `crypto` 2.0.0.
+
+## 1.0.3
+
+* Fix all strong-mode errors and warnings.
+
+* Fix a bug where `HtmlWebSocketChannel.close()` would crash on non-Dartium
+  browsers if the close code and reason weren't provided explicitly.
+
+## 1.0.2
+
+* Properly use `BASE64` from `dart:convert` rather than `crypto`.
+
+## 1.0.1
+
+* Add support for `crypto` 1.0.0.
+
+## 1.0.0
+
+* Initial version

pkgs/web_socket_channel/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2016, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/web_socket_channel/README.md

@@ -0,0 +1,72 @@
+[![pub package](https://img.shields.io/pub/v/web_socket_channel.svg)](https://pub.dev/packages/web_socket_channel)
+[![package publisher](https://img.shields.io/pub/publisher/web_socket_channel.svg)](https://pub.dev/packages/web_socket_channel/publisher)
+
+`package:web_socket_channel` provides cross-platform
+[`StreamChannel`][stream_channel] wrappers for WebSocket connections.
+
+## Docs and Usage
+
+It provides a cross-platform
+[`WebSocketChannel`][WebSocketChannel] API, a cross-platform implementation of
+that API that communicates over an underlying [`StreamChannel`][stream_channel],
+[an implementation][IOWebSocketChannel] that wraps `dart:io`'s `WebSocket`
+class, and [a similar implementation][HtmlWebSocketChannel] that wraps
+`dart:html`'s.
+
+[stream_channel]: https://pub.dev/packages/stream_channel
+[WebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel-class.html
+[IOWebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.io/IOWebSocketChannel-class.html
+[HtmlWebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.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 with the prefix `status`.
+
+[status]: https://pub.dev/documentation/web_socket_channel/latest/status/status-library.html
+
+```dart
+import 'package:web_socket_channel/web_socket_channel.dart';
+import 'package:web_socket_channel/status.dart' as status;
+
+main() async {
+  final wsUrl = Uri.parse('ws://example.com');
+  final channel = WebSocketChannel.connect(wsUrl);
+
+  await channel.ready;
+
+  channel.stream.listen((message) {
+    channel.sink.add('received!');
+    channel.sink.close(status.goingAway);
+  });
+}
+```
+
+## `WebSocketChannel`
+
+The [`WebSocketChannel`][WebSocketChannel] class's most important role is as the
+interface for WebSocket stream channels across all implementations and all
+platforms. In addition to the base `StreamChannel` interface, it adds a
+[`protocol`][protocol] getter that returns the negotiated protocol for the
+socket, as well as [`closeCode`][closeCode] and [`closeReason`][closeReason]
+getters that provide information about why the socket closed.
+
+[protocol]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/protocol.html
+[closeCode]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/closeCode.html
+[closeReason]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/closeReason.html
+
+The channel's [`sink` property][sink] is also special. It returns a
+[`WebSocketSink`][WebSocketSink], which is just like a `StreamSink` except that
+its [`close()`][sink.close] method supports optional `closeCode` and
+`closeReason` parameters. These parameters allow the caller to signal to the
+other socket exactly why they're closing the connection.
+
+[sink]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/sink.html
+[WebSocketSink]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketSink-class.html
+[sink.close]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketSink/close.html
+
+`WebSocketChannel` also works as a cross-platform implementation of the
+WebSocket protocol. The [`WebSocketChannel.connect` constructor][connect]
+connects to a listening server using the appropriate implementation for the
+platform.
+
+[connect]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/WebSocketChannel.connect.html