add more type information to the 'webSocketHandler' method (#463)

* [shelf_web_socket] add more type information to the 'webSocketHandler' method * update docs * use a dependency_override * require dart 3.5.0
dart-lang · Dec 9, 2024 · e3975a8 · e3975a8
1 parent 2b5b683
commit e3975a8
Show file tree

Hide file tree

Showing 9 changed files with 212 additions and 81 deletions.
diff --git a/.github/workflows/dart.yml b/.github/workflows/dart.yml
@@ -40,16 +40,16 @@ jobs:
       - name: mono_repo self validate
         run: dart pub global run mono_repo generate --validate
   job_002:
-    name: "analyze_and_format; linux; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart analyze --fatal-infos .`"
+    name: "analyze_and_format; linux; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler; `dart analyze --fatal-infos .`"
     runs-on: ubuntu-latest
     steps:
       - name: Cache Pub hosted dependencies
         uses: actions/cache@6849a6489940f00c2f30c0fb92c6274307ccb58a
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler-pkgs/shelf_web_socket;commands:analyze"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler;commands:analyze"
           restore-keys: |
-            os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler-pkgs/shelf_web_socket
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler
             os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0
             os:ubuntu-latest;pub-cache-hosted
             os:ubuntu-latest
@@ -114,15 +114,6 @@ jobs:
         run: dart analyze --fatal-infos .
         if: "always() && steps.pkgs_shelf_test_handler_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf_test_handler
-      - id: pkgs_shelf_web_socket_pub_upgrade
-        name: pkgs/shelf_web_socket; dart pub upgrade
-        run: dart pub upgrade
-        if: "always() && steps.checkout.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
-      - name: "pkgs/shelf_web_socket; dart analyze --fatal-infos ."
-        run: dart analyze --fatal-infos .
-        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
   job_003:
     name: "analyze_and_format; linux; Dart 3.4.0; PKG: pkgs/shelf; `dart analyze --fatal-infos .`"
     runs-on: ubuntu-latest
@@ -154,6 +145,36 @@ jobs:
         if: "always() && steps.pkgs_shelf_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf
   job_004:
+    name: "analyze_and_format; linux; Dart 3.5.0; PKG: pkgs/shelf_web_socket; `dart analyze --fatal-infos .`"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cache Pub hosted dependencies
+        uses: actions/cache@6849a6489940f00c2f30c0fb92c6274307ccb58a
+        with:
+          path: "~/.pub-cache/hosted"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/shelf_web_socket;commands:analyze"
+          restore-keys: |
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/shelf_web_socket
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0
+            os:ubuntu-latest;pub-cache-hosted
+            os:ubuntu-latest
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: "3.5.0"
+      - id: checkout
+        name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - id: pkgs_shelf_web_socket_pub_upgrade
+        name: pkgs/shelf_web_socket; dart pub upgrade
+        run: dart pub upgrade
+        if: "always() && steps.checkout.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+      - name: "pkgs/shelf_web_socket; dart analyze --fatal-infos ."
+        run: dart analyze --fatal-infos .
+        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+  job_005:
     name: "analyze_and_format; linux; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart analyze --fatal-infos .`"
     runs-on: ubuntu-latest
     steps:
@@ -246,7 +267,7 @@ jobs:
         run: dart analyze --fatal-infos .
         if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf_web_socket
-  job_005:
+  job_006:
     name: "analyze_and_format; linux; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart format --output=none --set-exit-if-changed .`"
     runs-on: ubuntu-latest
     steps:
@@ -339,17 +360,17 @@ jobs:
         run: "dart format --output=none --set-exit-if-changed ."
         if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf_web_socket
-  job_006:
-    name: "unit_test; linux; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
+  job_007:
+    name: "unit_test; linux; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random`"
     runs-on: ubuntu-latest
     steps:
       - name: Cache Pub hosted dependencies
         uses: actions/cache@6849a6489940f00c2f30c0fb92c6274307ccb58a
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler-pkgs/shelf_web_socket;commands:test_0"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler;commands:test_0"
           restore-keys: |
-            os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler-pkgs/shelf_web_socket
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0;packages:pkgs/shelf_packages_handler-pkgs/shelf_proxy-pkgs/shelf_router-pkgs/shelf_router_generator-pkgs/shelf_static-pkgs/shelf_test_handler
             os:ubuntu-latest;pub-cache-hosted;sdk:3.3.0
             os:ubuntu-latest;pub-cache-hosted
             os:ubuntu-latest
@@ -414,22 +435,14 @@ jobs:
         run: "dart test --test-randomize-ordering-seed=random"
         if: "always() && steps.pkgs_shelf_test_handler_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf_test_handler
-      - id: pkgs_shelf_web_socket_pub_upgrade
-        name: pkgs/shelf_web_socket; dart pub upgrade
-        run: dart pub upgrade
-        if: "always() && steps.checkout.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
-      - name: "pkgs/shelf_web_socket; dart test --test-randomize-ordering-seed=random"
-        run: "dart test --test-randomize-ordering-seed=random"
-        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
     needs:
       - job_001
       - job_002
       - job_003
       - job_004
       - job_005
-  job_007:
+      - job_006
+  job_008:
     name: "unit_test; linux; Dart 3.3.0; PKG: pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: ubuntu-latest
     steps:
@@ -465,7 +478,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_008:
+      - job_006
+  job_009:
     name: "unit_test; linux; Dart 3.4.0; PKG: pkgs/shelf; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: ubuntu-latest
     steps:
@@ -501,7 +515,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_009:
+      - job_006
+  job_010:
     name: "unit_test; linux; Dart 3.4.0; PKG: pkgs/shelf; `dart test --test-randomize-ordering-seed=random`"
     runs-on: ubuntu-latest
     steps:
@@ -537,7 +552,45 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_010:
+      - job_006
+  job_011:
+    name: "unit_test; linux; Dart 3.5.0; PKG: pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cache Pub hosted dependencies
+        uses: actions/cache@6849a6489940f00c2f30c0fb92c6274307ccb58a
+        with:
+          path: "~/.pub-cache/hosted"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/shelf_web_socket;commands:test_0"
+          restore-keys: |
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0;packages:pkgs/shelf_web_socket
+            os:ubuntu-latest;pub-cache-hosted;sdk:3.5.0
+            os:ubuntu-latest;pub-cache-hosted
+            os:ubuntu-latest
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: "3.5.0"
+      - id: checkout
+        name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - id: pkgs_shelf_web_socket_pub_upgrade
+        name: pkgs/shelf_web_socket; dart pub upgrade
+        run: dart pub upgrade
+        if: "always() && steps.checkout.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+      - name: "pkgs/shelf_web_socket; dart test --test-randomize-ordering-seed=random"
+        run: "dart test --test-randomize-ordering-seed=random"
+        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+    needs:
+      - job_001
+      - job_002
+      - job_003
+      - job_004
+      - job_005
+      - job_006
+  job_012:
     name: "unit_test; linux; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random -p chrome -c dart2wasm`"
     runs-on: ubuntu-latest
     steps:
@@ -582,7 +635,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_011:
+      - job_006
+  job_013:
     name: "unit_test; linux; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: ubuntu-latest
     steps:
@@ -627,7 +681,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_012:
+      - job_006
+  job_014:
     name: "unit_test; linux; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_packages_handler, pkgs/shelf_proxy, pkgs/shelf_router, pkgs/shelf_router_generator, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
     runs-on: ubuntu-latest
     steps:
@@ -726,7 +781,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_013:
+      - job_006
+  job_015:
     name: "unit_test; linux; Dart dev; PKG: pkgs/shelf_router_generator; `dart test --run-skipped -t presubmit-only`"
     runs-on: ubuntu-latest
     steps:
@@ -762,8 +818,9 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_014:
-    name: "unit_test; windows; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
+      - job_006
+  job_016:
+    name: "unit_test; windows; Dart 3.3.0; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_static, pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random`"
     runs-on: windows-latest
     steps:
       - name: Setup Dart SDK
@@ -800,22 +857,14 @@ jobs:
         run: "dart test --test-randomize-ordering-seed=random"
         if: "always() && steps.pkgs_shelf_test_handler_pub_upgrade.conclusion == 'success'"
         working-directory: pkgs/shelf_test_handler
-      - id: pkgs_shelf_web_socket_pub_upgrade
-        name: pkgs/shelf_web_socket; dart pub upgrade
-        run: dart pub upgrade
-        if: "always() && steps.checkout.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
-      - name: "pkgs/shelf_web_socket; dart test --test-randomize-ordering-seed=random"
-        run: "dart test --test-randomize-ordering-seed=random"
-        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
-        working-directory: pkgs/shelf_web_socket
     needs:
       - job_001
       - job_002
       - job_003
       - job_004
       - job_005
-  job_015:
+      - job_006
+  job_017:
     name: "unit_test; windows; Dart 3.3.0; PKG: pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: windows-latest
     steps:
@@ -841,7 +890,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_016:
+      - job_006
+  job_018:
     name: "unit_test; windows; Dart 3.4.0; PKG: pkgs/shelf; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: windows-latest
     steps:
@@ -867,7 +917,35 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_017:
+      - job_006
+  job_019:
+    name: "unit_test; windows; Dart 3.5.0; PKG: pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
+    runs-on: windows-latest
+    steps:
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: "3.5.0"
+      - id: checkout
+        name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - id: pkgs_shelf_web_socket_pub_upgrade
+        name: pkgs/shelf_web_socket; dart pub upgrade
+        run: dart pub upgrade
+        if: "always() && steps.checkout.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+      - name: "pkgs/shelf_web_socket; dart test --test-randomize-ordering-seed=random"
+        run: "dart test --test-randomize-ordering-seed=random"
+        if: "always() && steps.pkgs_shelf_web_socket_pub_upgrade.conclusion == 'success'"
+        working-directory: pkgs/shelf_web_socket
+    needs:
+      - job_001
+      - job_002
+      - job_003
+      - job_004
+      - job_005
+      - job_006
+  job_020:
     name: "unit_test; windows; Dart dev; PKGS: pkgs/shelf, pkgs/shelf_test_handler; `dart test --test-randomize-ordering-seed=random -p chrome`"
     runs-on: windows-latest
     steps:
@@ -902,7 +980,8 @@ jobs:
       - job_003
       - job_004
       - job_005
-  job_018:
+      - job_006
+  job_021:
     name: "unit_test; windows; Dart dev; PKGS: pkgs/shelf_packages_handler, pkgs/shelf_static, pkgs/shelf_test_handler, pkgs/shelf_web_socket; `dart test --test-randomize-ordering-seed=random`"
     runs-on: windows-latest
     steps:
@@ -955,3 +1034,4 @@ jobs:
       - job_003
       - job_004
       - job_005
+      - job_006
diff --git a/pkgs/shelf_test_handler/test/server_test.dart b/pkgs/shelf_test_handler/test/server_test.dart
@@ -29,7 +29,7 @@ void main() {
     addTearDown(server.close);
 
     server.handler.expect('GET', '/',
-        webSocketHandler((WebSocketChannel webSocket) {
+        webSocketHandler((WebSocketChannel webSocket, _) {
       webSocket.sink.add('hello!');
       webSocket.sink.close();
     }));

diff --git a/pkgs/shelf_web_socket/CHANGELOG.md b/pkgs/shelf_web_socket/CHANGELOG.md
@@ -1,12 +1,43 @@
+## 3.0.0-wip
+
+* **BREAKING:**: Change the signature of the `webSocketHandler` method's
+  `onConnection` callback. Previously this took an untyped function with either
+  one or two parameters. This now requires a `ConnectionCallback`; a typedef
+  taking two parameters. See also https://github.com/dart-lang/shelf/issues/457.
+* Add a API usage example.
+* Require Dart `^3.5.0`.
+
+Note that most clients seeing analysis issues from the above breaking change can
+fix it by adding a second parameter to their callback. So, they would change
+this:
+
+```dart
+webSocketHandler((webSocket) {
+  webSocket.stream.listen((message) {
+    webSocket.sink.add('echo $message');
+  });
+});
+```
+
+to this:
+
+```
+webSocketHandler((webSocket, _) {
+  webSocket.stream.listen((message) {
+    webSocket.sink.add('echo $message');
+  });
+});
+```
+
 ## 2.0.1
 
 * Require Dart `^3.3.0`.
 
 ## 2.0.0
 
-* Require Dart `^3.0.0`.
 * **BREAKING:**: Remove support for hijacking WebSocket requests that are not
   being transported using `dart:io` `Socket`s.
+* Require Dart `^3.0.0`.
 
 ## 1.0.4
 

diff --git a/pkgs/shelf_web_socket/README.md b/pkgs/shelf_web_socket/README.md
@@ -19,12 +19,11 @@ connection that's established.
 ```dart
 import 'package:shelf/shelf_io.dart' as shelf_io;
 import 'package:shelf_web_socket/shelf_web_socket.dart';
-import 'package:web_socket_channel/web_socket_channel.dart';
 
 void main() {
-  var handler = webSocketHandler((webSocket) {
+  var handler = webSocketHandler((webSocket, _) {
     webSocket.stream.listen((message) {
-      webSocket.sink.add("echo $message");
+      webSocket.sink.add('echo $message');
     });
   });