onServerDisconnectError callback (#37850)

Stopgap client callback to report unusual server disconnect errors.

This would be an ugly API to be stuck with for the long term because it leaks details that are irrelevant, but customers have requested a way to know on their users' clients that the connection is down so we're getting this out quickly.

The content of these messages, which messages trigger the callback, and the existence of the callback are all subject to change.

GitOrigin-RevId: 86c37e76ee0517f1dee54273ec6ac129021371d2

Author: thomasballinger

src/browser/sync/client.ts

@@ -83,6 +83,20 @@ export interface BaseConvexClientOptions {
    * The default value is `false`.
    */
   reportDebugInfoToConvex?: boolean;
+  /**
+   * This API is experimental: it may change or disappear.
+   *
+   * A function to call on receiving abnormal WebSocket close messages from the
+   * connected Convex deployment. The content of these messages is not stable,
+   * it is an implementation detail that may change.
+   *
+   * Consider this API an observability stopgap until higher level codes with
+   * recommendations on what to do are available, which could be a more stable
+   * interface instead of `string`.
+   *
+   * Check `connectionState` for more quantitative metrics about connection status.
+   */
+  onServerDisconnectError?: (message: string) => void;
   /**
    * Skip validating that the Convex deployment URL looks like
    * `https://happy-animal-123.convex.cloud` or localhost.
@@ -450,6 +464,7 @@ export class BaseConvexClient {
             hasSyncedPastLastReconnect: this.hasSyncedPastLastReconnect(),
           };
         },
+        onServerDisconnectError: options.onServerDisconnectError,
       },
       webSocketConstructor,
       this.logger,

src/browser/sync/web_socket_manager.ts

@@ -167,13 +167,17 @@ export class WebSocketManager {
   private readonly onMessage: (message: ServerMessage) => OnMessageResponse;
   private readonly webSocketConstructor: typeof WebSocket;
   private readonly logger: Logger;
+  private readonly onServerDisconnectError:
+    | ((message: string) => void)
+    | undefined;
 
   constructor(
     uri: string,
     callbacks: {
       onOpen: (reconnectMetadata: ReconnectMetadata) => void;
       onResume: () => void;
       onMessage: (message: ServerMessage) => OnMessageResponse;
+      onServerDisconnectError?: (message: string) => void;
     },
     webSocketConstructor: typeof WebSocket,
     logger: Logger,
@@ -195,6 +199,7 @@ export class WebSocketManager {
     this.onOpen = callbacks.onOpen;
     this.onResume = callbacks.onResume;
     this.onMessage = callbacks.onMessage;
+    this.onServerDisconnectError = callbacks.onServerDisconnectError;
     this.logger = logger;
 
     this.connect();
@@ -293,6 +298,12 @@ export class WebSocketManager {
           msg += `: ${event.reason}`;
         }
         this.logger.log(msg);
+        if (this.onServerDisconnectError) {
+          // This callback is a unstable API, InternalServerErrors may be removed in the future
+          // since they reflect a expected temporary outage. But until a quantitative measure
+          // of uptime is reported this unstable API errs on the inclusive side.
+          this.onServerDisconnectError(msg);
+        }
       }
       const reason = classifyDisconnectError(event.reason);
       this.scheduleReconnect(reason);