Clarify WebSocket.addError behavior

Document that WebSocket.addError does not transmit an error event to the
remote peer and only reports the error locally.

Changes:
* sdk/lib/_http/websocket.dart

Bug: #45733
Change-Id: I8913ac4fb466e9d613b3f0c5f0727640c9d9a913
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/502500
Reviewed-by: Brian Quinlan <bquinlan@google.com>
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Commit-Queue: Brian Quinlan <bquinlan@google.com>

Author: Victowolf

sdk/lib/_http/websocket.dart

@@ -433,6 +433,15 @@ abstract class WebSocket
   /// be either a `String`, or a `List<int>` holding bytes.
   void add(/*String|List<int>*/ data);
 
+  /// Reports an error on this WebSocket.
+  ///
+  /// This does not send an error event to the remote peer.
+  /// WebSocket connections only transmit text and binary data frames.
+  ///
+  /// If unhandled, the error may be reported as an uncaught
+  /// asynchronous error.
+  void addError(Object error, [StackTrace? stackTrace]);
+
   /// 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.

tests/standalone/io/web_socket_test.dart

@@ -252,6 +252,52 @@ class SecurityConfiguration {
     });
   }
 
+  void testAddErrorHandledLocally() {
+    asyncStart();
+
+    bool remoteErrorReceived = false;
+
+    runZonedGuarded(
+      () async {
+        final server = await createServer();
+
+        late StreamSubscription clientSubscription;
+        late WebSocket clientSocket;
+
+        server.listen((request) async {
+          final serverSocket = await WebSocketTransformer.upgrade(request);
+
+          // Errors added with addError are reported locally through
+          // async error handling and are not transmitted to the peer.
+          serverSocket.addError("local error");
+
+          await serverSocket.close();
+        });
+
+        clientSocket = await createClient(server.port);
+
+        clientSubscription = clientSocket.listen(
+          (_) {},
+          onError: (_) {
+            remoteErrorReceived = true;
+          },
+        );
+
+        await Future.delayed(Duration(milliseconds: 100));
+
+        await clientSubscription.cancel();
+        await clientSocket.close();
+        await server.close(force: true);
+      },
+      (Object error, StackTrace stackTrace) async {
+        Expect.equals("local error", error);
+        Expect.isFalse(remoteErrorReceived);
+
+        asyncEnd();
+      },
+    );
+  }
+
   void testDoubleCloseClient() {
     createServer().then((server) {
       server.transform(new WebSocketTransformer()).listen((webSocket) {
@@ -664,6 +710,7 @@ class SecurityConfiguration {
     testCancelThenClose();
     testCloseThenCancel();
     testListenAfterClose();
+    testAddErrorHandledLocally();
     testDoubleCloseClient();
     testDoubleCloseServer();
     testImmediateCloseServer();