diff --git a/CHANGELOG.md b/CHANGELOG.md index 5026c83..455784c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ - **BREAKING**: Make `WebSocketChannel` an `abstract interface`. - **BREAKING**: `IOWebSocketChannel.ready` will throw `WebSocketChannelException` instead of `WebSocketException`. +- `HtmlWebSocketChannel.connect` is deprecated. +- The `HtmlWebSocketChannel` constructor is deprecated. +- `IOWebSocketChannel.connect` is deprecated. +- The `IOWebSocketChannel` constructor is deprecated. ## 2.4.5 diff --git a/README.md b/README.md index 35f16c8..c43520f 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ It provides a cross-platform 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. +`package:web`'s. [stream_channel]: https://pub.dev/packages/stream_channel [WebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel-class.html @@ -27,7 +27,6 @@ import this library with the prefix `status`. ```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'); @@ -37,7 +36,7 @@ main() async { channel.stream.listen((message) { channel.sink.add('received!'); - channel.sink.close(status.goingAway); + channel.sink.close(); }); } ``` diff --git a/example/example.dart b/example/example.dart index b09b798..8647df0 100644 --- a/example/example.dart +++ b/example/example.dart @@ -2,7 +2,6 @@ // 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. -import 'package:web_socket_channel/status.dart' as status; import 'package:web_socket_channel/web_socket_channel.dart'; void main() async { @@ -13,6 +12,6 @@ void main() async { channel.stream.listen((message) { channel.sink.add('received!'); - channel.sink.close(status.goingAway); + channel.sink.close(); }); } diff --git a/lib/html.dart b/lib/html.dart index a96076f..3fdad4f 100644 --- a/lib/html.dart +++ b/lib/html.dart @@ -72,6 +72,7 @@ class HtmlWebSocketChannel extends StreamChannelMixin /// received by this socket. It defaults to [BinaryType.list], which causes /// binary messages to be delivered as [Uint8List]s. If it's /// [BinaryType.blob], they're delivered as [Blob]s instead. + @Deprecated('Use WebSocketChannel.connect() instead') HtmlWebSocketChannel.connect(Object url, {Iterable? protocols, BinaryType? binaryType}) : this( @@ -85,6 +86,7 @@ class HtmlWebSocketChannel extends StreamChannelMixin /// /// The parameter [webSocket] should be either a dart:html `WebSocket` /// instance or a package:web [WebSocket] instance. + @Deprecated('Use WebSocketChannel.connect() instead') HtmlWebSocketChannel(Object /*WebSocket*/ webSocket) : innerWebSocket = webSocket as WebSocket { _readyCompleter = Completer(); diff --git a/lib/io.dart b/lib/io.dart index ff10d1a..d0a35a6 100644 --- a/lib/io.dart +++ b/lib/io.dart @@ -33,6 +33,35 @@ class IOWebSocketChannel extends AdapterWebSocketChannel { /// /// If there's an error connecting, the channel's stream emits a /// [WebSocketChannelException] wrapping that error and then closes. + /// + /// **DEPRECATED**: Instead of using this method, use [IOWebSocket] with + /// [AdapterWebSocketChannel]. For example: + /// + /// ```dart + /// import 'dart:io' show WebSocket; + /// + /// import 'package:web_socket/io_web_socket.dart' show IOWebSocket; + /// import 'package:web_socket_channel/adapter_web_socket_channel.dart'; + /// + /// void main() async { + /// final ioWebSocket = await WebSocket.connect('', protocols: [ + /// 'chatV1', + /// 'chatV2', + /// ], headers: { + /// 'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV', + /// }).timeout(const Duration(milliseconds: 500)); + /// + /// ioWebSocket.pingInterval = const Duration(seconds: 10); + /// + /// final channel = + /// AdapterWebSocketChannel(IOWebSocket.fromWebSocket(ioWebSocket)); + /// + /// await channel.ready; + /// + /// // Use the `WebSocketChannel`. + /// } + /// ``` + @Deprecated('Use IOWebSocket with AdapterWebSocketChannel') factory IOWebSocketChannel.connect( Object url, { Iterable? protocols, @@ -56,6 +85,36 @@ class IOWebSocketChannel extends AdapterWebSocketChannel { } /// Creates a channel wrapping [webSocket]. + /// + /// **DEPRECATED**: Instead, use [IOWebSocket] with [AdapterWebSocketChannel]. + /// + /// For example: + /// + /// ```dart + /// import 'dart:io' show WebSocket; + /// + /// import 'package:web_socket/io_web_socket.dart' show IOWebSocket; + /// import 'package:web_socket_channel/adapter_web_socket_channel.dart'; + /// + /// void main() async { + /// final ioWebSocket = await WebSocket.connect('', protocols: [ + /// 'chatV1', + /// 'chatV2', + /// ], headers: { + /// 'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV', + /// }).timeout(const Duration(milliseconds: 500)); + /// + /// ioWebSocket.pingInterval = const Duration(seconds: 10); + /// + /// final channel = + /// AdapterWebSocketChannel(IOWebSocket.fromWebSocket(ioWebSocket)); + /// + /// await channel.ready; + /// + /// // Use the `WebSocketChannel`. + /// } + /// ``` + @Deprecated('Use IOWebSocket with AdapterWebSocketChannel') IOWebSocketChannel(FutureOr webSocket) : super(webSocket is Future ? webSocket.then(IOWebSocket.fromWebSocket) as FutureOr diff --git a/lib/status.dart b/lib/status.dart index 121c2cc..68efee2 100644 --- a/lib/status.dart +++ b/lib/status.dart @@ -16,6 +16,8 @@ /// channel.close(status.goingAway); /// } /// ``` +@Deprecated('RFC-6455 reserves codes 1000-4999 for applications. ' + 'Some WebSocket implementations only allow those codes to be set.') library web_socket_channel.status; import 'dart:core'; diff --git a/test/html_test.dart b/test/html_test.dart index 98fe43f..29309fa 100644 --- a/test/html_test.dart +++ b/test/html_test.dart @@ -2,6 +2,8 @@ // 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. +// ignore_for_file: deprecated_member_use_from_same_package + @TestOn('browser') library; diff --git a/test/io_test.dart b/test/io_test.dart index 1b7ae35..31368ed 100644 --- a/test/io_test.dart +++ b/test/io_test.dart @@ -2,6 +2,8 @@ // 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. +// ignore_for_file: deprecated_member_use_from_same_package + @TestOn('vm') library;