@evolu/common 8.10.0 → 8.11.0

package/dist/src/WebSocket.d.ts

@@ -6,7 +6,7 @@
 import type { Result } from "./Result.ts";
 import type { Schedule } from "./Schedule.ts";
 import type { RetryError, Task } from "./Task.ts";
-import type { Millis } from "./Time.ts";
+import type { Duration, Millis } from "./Time.ts";
 import { type Typed } from "./Type.ts";
 /**
  * WebSocket with auto-reconnect.
@@ -84,6 +84,8 @@ import { type Typed } from "./Type.ts";
  *   { url: "wss://example.com", data: "Hello" },
  * );
  * ```
+ *
+ * @group Core
  */
 export interface WebSocket extends AsyncDisposable {
     /**
@@ -94,23 +96,82 @@ export interface WebSocket extends AsyncDisposable {
     readonly getReadyState: () => WebSocketReadyState;
     /** Returns true if the WebSocket is open and ready to send data. */
     readonly isOpen: () => boolean;
+    /**
+     * Abandons the current connection and connects again.
+     *
+     * Use it when the connection is dead although it never closed, for example
+     * when a request stays unanswered. The wrapper cannot detect that by itself:
+     * no close or error event arrives, so its own reconnect never runs.
+     *
+     * The connection is dropped without waiting for a close handshake, and
+     * neither {@link WebSocketOptions.onClose} nor
+     * {@link WebSocketOptions.shouldRetryOnClose} is consulted, because the close
+     * is this call rather than something to learn about or veto. A connection
+     * that was open restarts the {@link WebSocketOptions.schedule}, as a close
+     * after {@link WebSocketOptions.healthyConnectionDuration} does; one that was
+     * still connecting keeps its backoff, having proved nothing.
+     *
+     * A connection already closing or closed is left to settle on its own, and
+     * after disposal this does nothing, so a timer or handler that outlives the
+     * connection is safe to call it from.
+     */
+    readonly reconnect: () => void;
 }
 /**
  * An error that occurs when trying to send data but WebSocket is not available
  * or is in the CONNECTING state.
  *
  * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+ *
+ * @group Errors
  */
 export interface WebSocketSendError extends Typed<"WebSocketSendError"> {
 }
-/** WebSocket connection states. */
+/**
+ * WebSocket connection states.
+ *
+ * @group Core
+ */
 export type WebSocketReadyState = "connecting" | "open" | "closing" | "closed";
-/** {@link Task} that creates a {@link WebSocket}. */
+/**
+ * What a {@link WebSocket} reports when a connection closes.
+ *
+ * These are the fields every platform provides. Evolu does not use the DOM
+ * `CloseEvent` type: React Native delivers its own close event and exposes no
+ * `CloseEvent` global, so promising the DOM type would promise an inheritance
+ * chain and an `instanceof` that do not hold there. A platform's own close
+ * event is structurally assignable to this, and {@link createWebSocket} passes
+ * it through unchanged, so a caller that knows its platform can narrow it.
+ *
+ * @group Core
+ */
+export interface WebSocketCloseEvent {
+    /** https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code */
+    readonly code: number;
+    /** https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/reason */
+    readonly reason: string;
+    /** Whether the connection closed after a completed closing handshake. */
+    readonly wasClean: boolean;
+}
+/**
+ * {@link Task} that creates a {@link WebSocket}.
+ *
+ * @group Core
+ */
 export type CreateWebSocket = (url: string, options?: WebSocketOptions) => Task<WebSocket>;
+/**
+ * Dependency wrapper for {@link CreateWebSocket}.
+ *
+ * @group Core
+ */
 export interface CreateWebSocketDep {
     readonly createWebSocket: CreateWebSocket;
 }
-/** Options for creating {@link WebSocket}. */
+/**
+ * Options for creating {@link WebSocket}.
+ *
+ * @group Core
+ */
 export interface WebSocketOptions {
     /** Protocol(s) to use with the WebSocket connection. */
     readonly protocols?: string | ReadonlyArray<string>;
@@ -121,13 +182,13 @@ export interface WebSocketOptions {
     /** Callback when an error occurs. */
     readonly onError?: (error: WebSocketError) => void;
     /** Callback when the connection is closed. */
-    readonly onClose?: (event: CloseEvent) => void;
+    readonly onClose?: (event: WebSocketCloseEvent) => void;
     /**
      * Determines whether a closed connection should trigger a retry.
      *
      * Return false to stop retrying, for example on auth errors or maintenance.
      */
-    readonly shouldRetryOnClose?: (event: CloseEvent) => boolean;
+    readonly shouldRetryOnClose?: (event: WebSocketCloseEvent) => boolean;
     /** Callback when message data is received. */
     readonly onMessage?: (data: string | ArrayBuffer | Blob) => void;
     /**
@@ -135,6 +196,27 @@ export interface WebSocketOptions {
      * {@link webSocketReconnectSchedule}.
      */
     readonly schedule?: Schedule<Millis, WebSocketRetryError>;
+    /**
+     * How long a connection must stay open for its close to start
+     * {@link WebSocketOptions.schedule} over. Defaults to 30 seconds, the delay
+     * cap of {@link webSocketReconnectSchedule}.
+     *
+     * The schedule is stateful and spans every reconnect, so without this a
+     * client that has disconnected often keeps waiting the longest backoff delay
+     * forever, even after hours of healthy connection. A connection that outlasts
+     * the longest delay the schedule can produce shows the endpoint works, so the
+     * next disconnect starts from the base delay again. Shorter connections reset
+     * nothing, so an endpoint that accepts and immediately drops connections
+     * still backs off.
+     *
+     * Choose it with the schedule rather than on its own: it is the schedule's
+     * delay cap, which only the schedule knows. A schedule cannot be asked for
+     * that cap, which is why this is an option rather than something derived. The
+     * delays a schedule has already produced are no substitute, because a
+     * jittered one produces delays near zero early on, and a threshold that low
+     * would reset the backoff for exactly the endpoint it protects against.
+     */
+    readonly healthyConnectionDuration?: Duration;
     /**
      * For custom WebSocket implementations.
      *
@@ -144,10 +226,18 @@ export interface WebSocketOptions {
      */
     readonly WebSocketConstructor?: typeof globalThis.WebSocket;
 }
+/**
+ * Any error reported by a {@link WebSocket}, including exhausted reconnect
+ * retries.
+ *
+ * @group Errors
+ */
 export type WebSocketError = WebSocketConnectError | WebSocketConnectionError | RetryError<WebSocketRetryError>;
 /**
  * An error that occurs when a connection cannot be established due to a network
  * error. Fires before `onclose`.
+ *
+ * @group Errors
  */
 export interface WebSocketConnectError extends Typed<"WebSocketConnectError"> {
     readonly event: Event;
@@ -160,53 +250,114 @@ export interface WebSocketConnectError extends Typed<"WebSocketConnectError"> {
  * Chromium and Firefox only fire `onclose` without a preceding error event.
  *
  * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event
+ *
+ * @group Errors
  */
 export interface WebSocketConnectionError extends Typed<"WebSocketConnectionError"> {
     readonly event: Event;
 }
-export type WebSocketRetryError = WebSocketConnectError | WebSocketConnectionCloseError;
-/** An error that occurs when the connection is closed by the server. */
+/**
+ * Errors that trigger a reconnect attempt under
+ * {@link webSocketReconnectSchedule}.
+ *
+ * @group Errors
+ */
+export type WebSocketRetryError = WebSocketConnectError | WebSocketConnectionCloseError | WebSocketReconnectError;
+/**
+ * The error {@link WebSocket.reconnect} settles the current connection with.
+ *
+ * Reconnecting is not a close, so it carries no close event: nothing observed
+ * one to report.
+ *
+ * @group Errors
+ */
+export interface WebSocketReconnectError extends Typed<"WebSocketReconnectError"> {
+}
+/**
+ * An error that occurs when the connection is closed by the server.
+ *
+ * @group Errors
+ */
 export interface WebSocketConnectionCloseError extends Typed<"WebSocketConnectionCloseError"> {
-    readonly event: CloseEvent;
+    readonly event: WebSocketCloseEvent;
 }
 /**
  * Default WebSocket reconnect schedule.
  *
  * Uses unlimited exponential backoff with a 100ms base, 30s cap, and full
  * jitter.
+ *
+ * @group Core
  */
 export declare const webSocketReconnectSchedule: Schedule<Millis, WebSocketRetryError>;
-/** Create a new {@link WebSocket}. */
+/**
+ * Create a new {@link WebSocket}.
+ *
+ * @group Core
+ */
 export declare const createWebSocket: CreateWebSocket;
 /**
  * An inspectable in-memory {@link CreateWebSocket} for testing by
  * {@link testCreateWebSocket}.
+ *
+ * Sockets report the states {@link createWebSocket} reports, including the
+ * `connecting` a socket is in before it opens and while the wrapper retries
+ * after a close or a {@link WebSocket.reconnect}. While it retries,
+ * {@link WebSocket.reconnect} does nothing, as the wrapper has no socket until
+ * {@link TestCreateWebSocket.open}. Only disposal ends in `closed`. The
+ * `closing` state is not modeled: no helper starts a close handshake. The event
+ * helpers throw for a disposed socket, which cannot receive events:
+ * {@link createWebSocket} detaches its handlers on disposal.
+ *
+ * @group Testing
  */
 export interface TestCreateWebSocket extends CreateWebSocket {
     readonly createdUrls: Array<string>;
+    /** URLs whose newest socket was reconnected, in call order. */
+    readonly reconnectedUrls: Array<string>;
     readonly sentMessages: Array<{
         readonly url: string;
         readonly data: BufferSource | Blob | string | globalThis.Uint8Array;
     }>;
     readonly message: (url: string, data: string | ArrayBuffer | Blob) => void;
     readonly open: (url: string) => void;
+    /**
+     * Reports the close event, with `code` defaulting to 1006, and leaves the
+     * socket connecting.
+     */
+    readonly close: (url: string, event?: Partial<WebSocketCloseEvent>) => void;
+    readonly error: (url: string, error: WebSocketError) => void;
 }
-/** Creates {@link TestCreateWebSocket}. */
+/**
+ * Creates {@link TestCreateWebSocket}.
+ *
+ * @group Testing
+ */
 export declare const testCreateWebSocket: (options?: {
     /** Throw immediately when a socket is created. */
     readonly throwOnCreate?: boolean;
-    /** Initial open state of created sockets. Defaults to true. */
+    /**
+     * Whether created sockets start open, skipping
+     * {@link TestCreateWebSocket.open}. Defaults to true. A socket that does not
+     * start open is connecting.
+     */
     readonly isOpen?: boolean;
 }) => TestCreateWebSocket;
 /**
  * A native {@link WebSocket} prepared for integration tests by
  * {@link testSetupWebSocket}.
+ *
+ * @group Testing
  */
 export interface TestSetupWebSocket extends AsyncDisposable {
     readonly socket: globalThis.WebSocket;
     readonly send: (data: BufferSource | Blob | string | globalThis.Uint8Array) => void;
     readonly waitForMessage: () => Promise<string | globalThis.Uint8Array>;
 }
-/** Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}. */
+/**
+ * Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}.
+ *
+ * @group Testing
+ */
 export declare const testSetupWebSocket: (url: string) => Promise<TestSetupWebSocket>;
 //# sourceMappingURL=WebSocket.d.ts.map

package/dist/src/WebSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSocket.d.ts","sourceRoot":"","sources":["../../src/WebSocket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WebSocket.d.ts","sourceRoot":"","sources":["../../src/WebSocket.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAmB,MAAM,WAAW,CAAC;AAEnE,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,WAAW,SAAU,SAAQ,eAAe;IAChD;;;OAGG;IACH,IAAI,EAAE,CACJ,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC,UAAU,KACvD,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAEtC,QAAQ,CAAC,aAAa,EAAE,MAAM,mBAAmB,CAAC;IAElD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,KAAK,CAAC,oBAAoB,CAAC;CAAG;AAE1E;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,KACvB,IAAI,CAAC,SAAS,CAAC,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEpD,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAE7C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAEnD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAExD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC;IAEtE,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAEjE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,QAAQ,CAAC;IAE9C;;;;;;OAMG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,UAAU,CAAC,SAAS,CAAC;CAC7D;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,qBAAqB,GACrB,wBAAwB,GACxB,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,uBAAuB,CAAC;IAC3E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAyB,SAAQ,KAAK,CAAC,0BAA0B,CAAC;IACjF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,6BAA6B,GAC7B,uBAAuB,CAAC;AAE5B;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,KAAK,CAAC,yBAAyB,CAAC;CAAG;AAEpF;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,KAAK,CAAC,+BAA+B,CAAC;IAC3F,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAG1E,CAAC;AAKJ;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,eA8L3B,CAAC;AAsBJ;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC;QAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC;KACrE,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,KAAK,IAAI,CAAC;IAC5E,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC9D;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,aACrB;IACP,kDAAkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B,KACA,mBAgHF,CAAC;AAUF;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,CACb,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC,UAAU,KACvD,IAAI,CAAC;IACV,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;CACxE;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QACxB,MAAM,KACV,OAAO,CAAC,kBAAkB,CAwE5B,CAAC"}

package/dist/src/WebSocket.js

@@ -60,22 +60,36 @@ import { constTrue } from "./Function.js";
 import { err, ok } from "./Result.js";
 import { exponential, jitter, maxDelay } from "./Schedule.js";
 import { callback, retry } from "./Task.js";
+import { durationToMillis, performanceDurationBetween } from "./Time.js";
 import { ArrayBuffer, String, Uint8Array } from "./Type.js";
 /**
  * Default WebSocket reconnect schedule.
  *
  * Uses unlimited exponential backoff with a 100ms base, 30s cap, and full
  * jitter.
+ *
+ * @group Core
  */
 export const webSocketReconnectSchedule = 
 /*#__PURE__*/ jitter("100%")(
 /*#__PURE__*/ maxDelay("30s")(/*#__PURE__*/ exponential("100ms")));
-/** Create a new {@link WebSocket}. */
-export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, shouldRetryOnClose = constTrue, onMessage, onError, schedule = webSocketReconnectSchedule, WebSocketConstructor = globalThis.WebSocket, } = {}) => async (run) => {
+/** The delay cap of {@link webSocketReconnectSchedule}. */
+const defaultHealthyConnectionDuration = /*#__PURE__*/ durationToMillis("30s");
+/**
+ * Create a new {@link WebSocket}.
+ *
+ * @group Core
+ */
+export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, shouldRetryOnClose = constTrue, onMessage, onError, schedule = webSocketReconnectSchedule, healthyConnectionDuration = defaultHealthyConnectionDuration, WebSocketConstructor = globalThis.WebSocket, } = {}) => async (run) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
         const disposer = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+        const healthyConnectionMillis = durationToMillis(healthyConnectionDuration);
         let socket = null;
+        // Set by a close that proves the endpoint works and by `reconnect`, and
+        // consumed by the next schedule step.
+        let shouldResetSchedule = false;
+        let resolveConnect = null;
         const closeSocket = () => {
             if (!socket)
                 return;
@@ -99,17 +113,27 @@ export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, s
          */
         const connect = callback(({ resolve }) => {
             closeSocket();
+            resolveConnect = resolve;
             socket = new WebSocketConstructor(url, String.is(protocols) ? protocols : protocols && [...protocols]);
             if (binaryType)
                 socket.binaryType = binaryType;
             let isOpen = false;
+            // Monotonic: how long the connection lasted must not follow a system
+            // clock adjustment, which would reset the schedule for a connection that
+            // proved nothing, or withhold the reset from one that proved the
+            // endpoint works.
+            let openedAt = null;
             // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
             socket.onopen = () => {
                 isOpen = true;
+                openedAt = run.deps.time.performance.now();
                 onOpen?.();
             };
             // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
             socket.onclose = (event) => {
+                if (openedAt !== null &&
+                    performanceDurationBetween(openedAt, run.deps.time.performance.now()) >= healthyConnectionMillis)
+                    shouldResetSchedule = true;
                 onClose?.(event);
                 if (shouldRetryOnClose(event)) {
                     resolve(err({ type: "WebSocketConnectionCloseError", event }));
@@ -131,9 +155,29 @@ export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, s
                 if (error.type === "WebSocketConnectError")
                     resolve(err(error));
             };
-            return closeSocket;
+            return () => {
+                resolveConnect = null;
+                closeSocket();
+            };
         });
-        const retryFiber = disposer.use(run.daemon(retry(connect, schedule)));
+        /**
+         * Wraps `schedule` so a healthy connection starts its backoff over.
+         *
+         * `retry` builds one schedule step per call and `connect` settles only when
+         * a connection closes, so a single step would otherwise accumulate backoff
+         * across every close for this wrapper's lifetime.
+         */
+        const reconnectSchedule = (deps) => {
+            let step = schedule(deps);
+            return (error) => {
+                if (shouldResetSchedule) {
+                    shouldResetSchedule = false;
+                    step = schedule(deps);
+                }
+                return step(error);
+            };
+        };
+        const retryFiber = disposer.use(run.daemon(retry(connect, reconnectSchedule)));
         // Report RetryError (schedule exhausted) via onError callback
         void retryFiber.then((result) => {
             if (!result.ok && result.error.type === "RetryError") {
@@ -157,6 +201,26 @@ export const createWebSocket = (url, { protocols, binaryType, onOpen, onClose, s
             },
             isOpen: () => !disposables.disposed &&
                 socket?.readyState === globalThis.WebSocket.OPEN,
+            reconnect: () => {
+                const resolve = resolveConnect;
+                if (disposables.disposed || !resolve || !socket)
+                    return;
+                // A closing or closed socket settles the connection on its own.
+                // Reconnecting it would discard `shouldRetryOnClose` and restart the
+                // schedule for a close that proved nothing. `onClose` and `onError`
+                // run before that settlement, so a handler can reach this.
+                if (socket.readyState !== socket.CONNECTING &&
+                    socket.readyState !== socket.OPEN)
+                    return;
+                // Only a connection that was open makes the backoff before it stale.
+                if (socket.readyState === socket.OPEN)
+                    shouldResetSchedule = true;
+                resolveConnect = null;
+                // Handlers are cleared before settling, so the abandoned connection
+                // reports nothing while `retry` waits out its delay.
+                closeSocket();
+                resolve(err({ type: "WebSocketReconnectError" }));
+            },
             [Symbol.asyncDispose]: () => disposables.disposeAsync(),
         });
     }
@@ -184,9 +248,14 @@ const nativeToStringState = {
     [globalThis.WebSocket.CLOSING]: "closing",
     [globalThis.WebSocket.CLOSED]: "closed",
 };
-/** Creates {@link TestCreateWebSocket}. */
+/**
+ * Creates {@link TestCreateWebSocket}.
+ *
+ * @group Testing
+ */
 export const testCreateWebSocket = (options = {}) => {
     const createdUrls = [];
+    const reconnectedUrls = [];
     const sentMessages = [];
     const stateByUrl = new Map();
     const getState = (url) => {
@@ -199,15 +268,18 @@ export const testCreateWebSocket = (options = {}) => {
             throw new Error("testCreateWebSocket is configured to throw on create");
         }
         createdUrls.push(url);
-        stateByUrl.set(url, {
+        // A URL can be created again after its socket was disposed. Each socket
+        // keeps its own state; the helpers address the newest socket for a URL.
+        const state = {
             options: socketOptions,
-            isOpen: options.isOpen ?? true,
+            readyState: (options.isOpen ?? true) ? "open" : "connecting",
             isDisposed: false,
-        });
+            isWaitingToRetry: false,
+        };
+        stateByUrl.set(url, state);
         return ok({
             send: (data) => {
-                const state = getState(url);
-                if (state.isDisposed || !state.isOpen) {
+                if (state.isDisposed || state.readyState !== "open") {
                     return err({ type: "WebSocketSendError" });
                 }
                 sentMessages.push({
@@ -216,38 +288,75 @@ export const testCreateWebSocket = (options = {}) => {
                 });
                 return ok();
             },
-            getReadyState: () => {
-                const state = getState(url);
-                if (state.isDisposed)
-                    return "closed";
-                return state.isOpen ? "open" : "closed";
-            },
-            isOpen: () => {
-                const state = getState(url);
-                return !state.isDisposed && state.isOpen;
+            getReadyState: () => (state.isDisposed ? "closed" : state.readyState),
+            isOpen: () => !state.isDisposed && state.readyState === "open",
+            reconnect: () => {
+                // A closed socket settles on its own, and a retrying wrapper has no
+                // socket, as in `createWebSocket`.
+                if (state.isDisposed ||
+                    state.readyState === "closed" ||
+                    state.isWaitingToRetry)
+                    return;
+                state.readyState = "connecting";
+                state.isWaitingToRetry = true;
+                reconnectedUrls.push(url);
             },
             [Symbol.asyncDispose]: () => {
-                const state = getState(url);
                 state.isDisposed = true;
-                state.isOpen = false;
+                state.readyState = "closed";
                 return Promise.resolve();
             },
         });
     };
     return Object.assign(createWebSocket, {
         createdUrls,
+        reconnectedUrls,
         sentMessages,
         message: (url, data) => {
-            getState(url).options?.onMessage?.(data);
+            const state = getState(url);
+            assert(!state.isDisposed, `Test WebSocket for ${url} is disposed.`);
+            state.options?.onMessage?.(data);
         },
         open: (url) => {
             const state = getState(url);
-            state.isOpen = true;
+            assert(!state.isDisposed, `Test WebSocket for ${url} is disposed.`);
+            state.readyState = "open";
+            state.isWaitingToRetry = false;
             state.options?.onOpen?.();
         },
+        close: (url, event = {}) => {
+            const state = getState(url);
+            assert(!state.isDisposed, `Test WebSocket for ${url} is disposed.`);
+            state.readyState = "closed";
+            state.options?.onClose?.({
+                code: 1006,
+                reason: "",
+                wasClean: false,
+                ...event,
+            });
+            // `createWebSocket` still holds the closed socket while it reports the
+            // close, and drops it to retry once that settles. Anything the handler
+            // schedules therefore still reads `closed`; anything later reads
+            // `connecting`.
+            queueMicrotask(() => {
+                if (state.readyState === "closed" && !state.isDisposed) {
+                    state.readyState = "connecting";
+                    state.isWaitingToRetry = true;
+                }
+            });
+        },
+        error: (url, error) => {
+            const state = getState(url);
+            assert(!state.isDisposed, `Test WebSocket for ${url} is disposed.`);
+            state.options?.onError?.(error);
+        },
     });
 };
-/** Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}. */
+/**
+ * Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}.
+ *
+ * @group Testing
+ */
 export const testSetupWebSocket = async (url) => {
     const socket = new globalThis.WebSocket(url);
     socket.binaryType = "arraybuffer";