akanjs 3.0.2 → 3.1.0-rc.1

package/fetch/client/fetchClient.ts

@@ -4,6 +4,7 @@ import {
   type FetchPolicy,
   fileUploadContract,
   Logger,
+  type RetryPolicy,
   readAuthToken,
   resolveFileUploadCapability,
 } from "akanjs/common";
@@ -28,10 +29,10 @@ import {
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types";
 import { FetchHandle } from "./fetchHandle";
 import { HttpClient } from "./httpClient";
-import type { ErrorConstructor } from "./remoteError";
+import type { ErrorConstructor, RestoredError } from "./remoteError";
 import { SliceInitHandle } from "./sliceInitHandle";
 import { expandQueryArgs, normalizeQueryArgs } from "./sliceQueryArgs";
-import { WsClient } from "./wsClient";
+import { WsClient, type WsClientOptions } from "./wsClient";
 
 type FetchHandler = (...args: unknown[]) => PromiseOrObject<unknown>;
 type FetchHandlerFactory = () => FetchHandler;
@@ -67,6 +68,21 @@ const sharedSignalRegistry: SharedSignalRegistry = globalWithSharedSignal[SHARED
 };
 globalWithSharedSignal[SHARED_SIGNAL_KEY] = sharedSignalRegistry;
 
+export interface FetchBridgeCall {
+  key: string;
+  type: "query" | "mutation";
+  args: UnknownRecord;
+  returns: SerializedReturns;
+}
+
+/** A transport that is not HTTP: a view inside an MCP host has no network, and reaches the server through the host. */
+export interface FetchBridge {
+  call(request: FetchBridgeCall): Promise<unknown>;
+}
+
+const FETCH_BRIDGE_KEY = Symbol.for("akanjs.fetch.bridge");
+const globalWithFetchBridge = globalThis as typeof globalThis & { [FETCH_BRIDGE_KEY]?: FetchBridge | null };
+
 type ClientSignalMap<SigType extends { fetch: any }> = {
   [K in keyof SigType as SigType[K] extends DatabaseSignal<any, any, any, any>
     ? K
@@ -89,13 +105,17 @@ export class FetchClient {
   readonly sortValueMap = new Map<string, { [key: string]: { [path: string]: 1 | -1 } }>();
   readonly filterQueryMap = new Map<string, { [queryKey: string]: SerializedArg[] }>();
   readonly #originWs = new Map<string, WsClient>();
+  #wsOptions: WsClientOptions = {};
   readonly #handlerStore: Record<string, FetchHandler> = {};
   readonly #handlerFactory = new Map<string, FetchHandlerFactory>();
   #sharedRegistryAppliedVersion = 0;
   #clientIp: string | null = null;
+  /** Cloned toward another server: the request being served is this server's visitor, not that server's caller. */
+  #foreign = false;
   static #testClientIps = false;
   static #testClientIpSeq = 0;
   serializedSignal: { [key: string]: SerializedSignal } = {};
+  #ownSignal: { [key: string]: SerializedSignal } = {};
   jwt: string | null = null;
 
   constructor(
@@ -119,6 +139,13 @@ export class FetchClient {
     sharedSignalRegistry.signal = {};
     sharedSignalRegistry.version++;
   }
+  /** Every client in this tab sends its queries and mutations through `bridge`, and opens no socket; `null` restores HTTP. */
+  static setBridge(bridge: FetchBridge | null) {
+    globalWithFetchBridge[FETCH_BRIDGE_KEY] = bridge;
+  }
+  static get bridged() {
+    return !!globalWithFetchBridge[FETCH_BRIDGE_KEY];
+  }
   static resetSharedClient() {
     sharedClientState.proxy = null;
     sharedClientState.origin = null;
@@ -151,27 +178,43 @@ export class FetchClient {
     signal: SerializedSignal,
   ) {
     const current = serializedSignal[refName];
-    serializedSignal[refName] = current
-      ? {
-          ...current,
-          ...signal,
-          endpoint: { ...current.endpoint, ...signal.endpoint },
-          slice: current.slice || signal.slice ? { ...current.slice, ...signal.slice } : undefined,
-          filter:
-            current.filter || signal.filter
-              ? {
-                  filter: { ...current.filter?.filter, ...signal.filter?.filter },
-                  sortKeys: [...new Set([...(current.filter?.sortKeys ?? []), ...(signal.filter?.sortKeys ?? [])])],
-                  sorts: { ...current.filter?.sorts, ...signal.filter?.sorts },
-                }
-              : undefined,
-          getGuards: signal.getGuards ?? current.getGuards,
-          cruGuards: signal.cruGuards ?? current.cruGuards,
-          createGuards: signal.createGuards ?? current.createGuards,
-          updateGuards: signal.updateGuards ?? current.updateGuards,
-          removeGuards: signal.removeGuards ?? current.removeGuards,
-        }
-      : signal;
+    serializedSignal[refName] = current ? FetchClient.#definedOnly(FetchClient.#merged(current, signal)) : signal;
+  }
+  
+  static #definedOnly(signal: SerializedSignal): SerializedSignal {
+    return Object.fromEntries(Object.entries(signal).filter(([, value]) => value !== undefined)) as SerializedSignal;
+  }
+  static #merged(current: SerializedSignal, signal: SerializedSignal): SerializedSignal {
+    return {
+      ...current,
+      ...signal,
+      endpoint: { ...current.endpoint, ...signal.endpoint },
+      slice: current.slice || signal.slice ? { ...current.slice, ...signal.slice } : undefined,
+      filter:
+        current.filter || signal.filter
+          ? {
+              filter: { ...current.filter?.filter, ...signal.filter?.filter },
+              sortKeys: [...new Set([...(current.filter?.sortKeys ?? []), ...(signal.filter?.sortKeys ?? [])])],
+              sorts: { ...current.filter?.sorts, ...signal.filter?.sorts },
+            }
+          : undefined,
+      getGuards: signal.getGuards ?? current.getGuards,
+      cruGuards: signal.cruGuards ?? current.cruGuards,
+      createGuards: signal.createGuards ?? current.createGuards,
+      updateGuards: signal.updateGuards ?? current.updateGuards,
+      removeGuards: signal.removeGuards ?? current.removeGuards,
+      origin:
+        current.origin || signal.origin
+          ? [...new Set([...(current.origin ?? []), ...(signal.origin ?? [])])]
+          : undefined,
+    };
+  }
+  /**
+   * What this client was built with and applied itself, never what it synced from another client in the process:
+   * a `getSerializedSignal` macro reads this, so a lib's bundle cannot depend on which app's signals loaded first.
+   */
+  get ownSerializedSignal(): { [key: string]: SerializedSignal } {
+    return this.#ownSignal;
   }
   /** For calls neither the caller nor the endpoint budgets; `false` waits as long as the runtime will (minutes). */
   setTimeout(timeout?: number | false) {
@@ -185,8 +228,10 @@ export class FetchClient {
   }
   applySignal(serializedSignal: { [key: string]: SerializedSignal }, { share = true }: { share?: boolean } = {}) {
     if (share && Object.keys(serializedSignal).length > 0) {
-      for (const [refName, signal] of Object.entries(serializedSignal))
+      for (const [refName, signal] of Object.entries(serializedSignal)) {
         FetchClient.#mergeSerializedSignalInto(sharedSignalRegistry.signal, refName, signal);
+        FetchClient.#mergeSerializedSignalInto(this.#ownSignal, refName, signal);
+      }
       sharedSignalRegistry.version++;
       this.#sharedRegistryAppliedVersion = sharedSignalRegistry.version;
     }
@@ -246,7 +291,9 @@ export class FetchClient {
     this.#handlerFactory.set(key, factory);
     delete this.#handlerStore[key];
   }
+  
   connect() {
+    if (FetchClient.bridged) return;
     this.ws.connect();
   }
   disconnect() {
@@ -260,14 +307,23 @@ export class FetchClient {
     connect = !(origin && typeof window === "undefined"),
     jwt,
     clientIp,
+    ws,
+    retry,
   }: {
     origin?: string;
     connect?: boolean;
     jwt?: string;
     /** Sent as `x-real-ip`, which a server believes only from a trusted proxy — a test's loopback is one. */
     clientIp?: string | null;
+    /** The clone's sockets: reconnect backoff, upgrade headers and TLS, and state, revocation and error hooks. */
+    ws?: WsClientOptions;
+    /** Every call's `retry` unless it names its own: transient failures, a mutation under one Idempotency-Key. */
+    retry?: RetryPolicy | false;
   } = {}) {
     const instance = new FetchClient(origin ?? this.origin, {}, this.serializedSignal, this.ErrorCls);
+    if (ws) instance.configureWs(ws);
+    if (retry !== undefined) instance.http.setRetry(retry);
+    instance.#foreign = this.#foreign || (!!origin && !FetchClient.#sameOrigin(origin, this.origin));
     instance.#clientIp =
       clientIp !== undefined ? clientIp : FetchClient.#testClientIps ? FetchClient.#nextTestClientIp() : this.#clientIp;
     Object.entries(this.handler).forEach(([key, handler]) => {
@@ -277,6 +333,12 @@ export class FetchClient {
     if (connect) instance.connect();
     return FetchClient.#makeProxy(instance);
   }
+  /** Every socket this client holds or opens later: its own and one per `FetchPolicy.origin`. */
+  configureWs(options: WsClientOptions) {
+    this.#wsOptions = { ...this.#wsOptions, ...options };
+    this.ws.configure(options);
+    for (const ws of this.#originWs.values()) ws.configure(options);
+  }
   setJwt(jwt: string | null) {
     this.jwt = jwt;
     this.ws.setJwt(jwt);
@@ -289,19 +351,19 @@ export class FetchClient {
     if (target === this.origin.replace(/\/+$/, "")) return this.ws;
     const cached = this.#originWs.get(target);
     if (cached) return cached;
-    const ws = new WsClient(FetchClient.#makeWsUri(target), this.ErrorCls);
+    const ws = new WsClient(FetchClient.#makeWsUri(target), this.ErrorCls).configure(this.#wsOptions);
     this.#originWs.set(target, ws);
     ws.setJwt(this.jwt);
     ws.connect();
     return ws;
   }
   #makeRequestHeaders(option?: FetchPolicy): Record<string, string> {
-    const clientIp = this.#clientIp ? { "x-real-ip": this.#clientIp } : FetchClient.#forwardedClientIp(option);
+    const clientIp = this.#clientIp ? { "x-real-ip": this.#clientIp } : this.#forwardedClientIp(option);
     return { ...this.#makeAuthHeaders(option), ...clientIp };
   }
 
-  static #forwardedClientIp(option?: FetchPolicy): Record<string, string> {
-    if (option?.origin) return {};
+  #forwardedClientIp(option?: FetchPolicy): Record<string, string> {
+    if (!this.#forwardsVisitor(option)) return {};
     try {
       if (getEnv().side !== "server") return {};
       const clientIp = requestHeaders().get("x-real-ip");
@@ -310,10 +372,17 @@ export class FetchClient {
       return {};
     }
   }
+  static #sameOrigin(a: string, b: string) {
+    return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+  }
+
+  #forwardsVisitor(option?: FetchPolicy) {
+    return !this.#foreign && (!option?.origin || FetchClient.#sameOrigin(option.origin, this.origin));
+  }
   #makeAuthHeaders(option?: FetchPolicy): Record<string, string> {
     if (option?.token) return { Authorization: `Bearer ${option.token}` };
     try {
-      if (getEnv().side === "server") {
+      if (getEnv().side === "server" && this.#forwardsVisitor(option)) {
         const authorization = requestHeaders().get("authorization");
         if (authorization) return { Authorization: authorization };
         const token = readAuthToken((key) => requestCookies().get(key)?.value);
@@ -344,11 +413,21 @@ export class FetchClient {
       case "query":
         return async (...argData: unknown[]) => {
           const { option, argMap, url } = requestOf(argData);
+          const bridge = option?.origin ? null : globalWithFetchBridge[FETCH_BRIDGE_KEY];
+          if (bridge) {
+            const value = await this.#bridged(bridge, {
+              key,
+              type: "query",
+              args: Object.fromEntries(argMap),
+              returns: endpoint.returns,
+            });
+            return parseReturn(value, { crystalize: option?.crystalize ?? true });
+          }
           const headers = this.#makeRequestHeaders(option);
           const baseUrl = this.#baseUrlOf(endpoint, option?.origin);
           const timeout = option?.timeout ?? endpoint.timeout;
           
-          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout, retry: option?.retry });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -361,11 +440,23 @@ export class FetchClient {
       case "mutation":
         return async (...argData: unknown[]) => {
           const { option, argMap, url } = requestOf(argData);
+          const bridge = option?.origin ? null : globalWithFetchBridge[FETCH_BRIDGE_KEY];
+          if (bridge) {
+            const value = await this.#bridged(bridge, {
+              key,
+              type: "mutation",
+              args: Object.fromEntries(argMap),
+              returns: endpoint.returns,
+            });
+            return parseReturn(value, { crystalize: option?.crystalize ?? true });
+          }
           const body = HttpClient.makeBody(bodyArgs, uploadArgs, argMap);
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeRequestHeaders(option),
             baseUrl: this.#baseUrlOf(endpoint, option?.origin),
             timeout: option?.timeout ?? endpoint.timeout,
+            retry: option?.retry,
+            idempotencyKey: option?.idempotencyKey,
           });
           return parseReturn(response, { crystalize: option?.crystalize ?? true });
         };
@@ -387,6 +478,8 @@ export class FetchClient {
           const parseReturn = this.#makeReturnParser(endpoint.returns);
           const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return (...argData: unknown[]) => {
+            
+            if (FetchClient.bridged) return () => undefined;
             const args = argData.slice(0, roomArgLength);
             const handleEvent = argData[roomArgLength] as (data: unknown) => void;
             const fetchPolicy = argData[roomArgLength + 1] as FetchPolicy | undefined;
@@ -416,6 +509,7 @@ export class FetchClient {
           const msgArgLength = msgArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
           return (...argData: unknown[]) => {
+            if (FetchClient.bridged) return;
             const args = argData.slice(0, msgArgLength);
             const fetchPolicy = argData[msgArgLength] as FetchPolicy | undefined;
             const data = msgArgs.map((arg, idx) => serializerMap.get(arg.name)?.(args[idx]) ?? null);
@@ -443,6 +537,15 @@ export class FetchClient {
         break;
     }
   }
+  
+  async #bridged(bridge: FetchBridge, request: FetchBridgeCall) {
+    try {
+      return await bridge.call(request);
+    } catch (error) {
+      const payload = (error as RestoredError | null)?.toJSON?.();
+      throw payload && this.ErrorCls ? this.ErrorCls.fromJSON(payload) : error;
+    }
+  }
   static #makeWsUri(origin: string) {
     return `${origin.replace("http://", "ws://").replace("https://", "wss://")}${getWsPrefix()}`;
   }
@@ -817,7 +920,7 @@ export class FetchClient {
         );
       } else {
         Object.assign(handler, signal.handler);
-        Object.entries(signal.serializedSignal).forEach(([refName, signal]) => {
+        Object.entries(signal.ownSerializedSignal ?? signal.serializedSignal).forEach(([refName, signal]) => {
           FetchClient.#mergeSerializedSignalInto(serializedSignal, refName, signal);
         });
       }
@@ -882,6 +985,7 @@ export class FetchClient {
       get(target, prop) {
         if (prop in target) return (target as any)[prop];
         else if (prop === "instance") return instance;
+        else if (prop === "ownSerializedSignal") return instance.ownSerializedSignal;
         else if (typeof prop === "string") {
           const handler = instance.#getOrCreateHandler(prop);
           if (handler) return handler;

package/fetch/client/httpClient.ts

@@ -1,3 +1,4 @@
+import { Backoff, type RetryPolicy } from "akanjs/common";
 import type { HttpMutationMethod, SerializedArg } from "akanjs/signal";
 import { type ErrorConstructor, type RestoredError, restoreRemoteError } from "./remoteError";
 
@@ -10,6 +11,9 @@ export interface HttpClientOptions {
 
 interface FetchOptions extends Pick<HttpClientOptions, "headers" | "timeout"> {
   baseUrl?: string;
+  /** Over the client's default; `false` sends once. */
+  retry?: RetryPolicy | false;
+  idempotencyKey?: string;
 }
 
 const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
@@ -23,6 +27,14 @@ const transportErrorKeyMap = {
 } as const;
 
 const serverUnreachableKey = "base.error.serverUnreachable";
+
+const retryableKeys = new Set([
+  serverUnreachableKey,
+  "base.error.serverUnavailable",
+  "base.error.gatewayTimeout",
+  "base.error.tooManyRequests",
+  "base.error.idempotencyInFlight",
+]);
 const unexpectedResponseKey = "base.error.unexpectedResponse";
 const transportDetailLimit = 200;
 
@@ -32,6 +44,7 @@ export class HttpClient {
   readonly baseUrl: string;
   #headers: Record<string, string>;
   #timeout?: number | false;
+  #retry: RetryPolicy | false = false;
   private ErrorCls?: ErrorConstructor;
   constructor(baseUrl: string, options: HttpClientOptions = {}) {
     this.baseUrl = baseUrl;
@@ -47,6 +60,10 @@ export class HttpClient {
   setTimeout(timeout?: number | false) {
     this.#timeout = timeout;
   }
+  /** What every call that names no `retry` of its own does; `false`, the default, sends once. */
+  setRetry(retry: RetryPolicy | false) {
+    this.#retry = retry;
+  }
   #resolveUrl(url: string, options: FetchOptions) {
     return `${(options.baseUrl ?? this.baseUrl).replace(/\/$/, "")}${url}`;
   }
@@ -102,6 +119,34 @@ export class HttpClient {
   }
 
   async #request<Returns>(url: string, init: RequestInit, options: FetchOptions = {}): Promise<Returns> {
+    const retry = options.retry ?? this.#retry;
+    const mutation = !!init.method && init.method !== "GET";
+    const idempotencyKey = options.idempotencyKey ?? (retry && mutation ? crypto.randomUUID() : undefined);
+    const sent: RequestInit = idempotencyKey
+      ? { ...init, headers: { ...(init.headers as Record<string, string>), "Idempotency-Key": idempotencyKey } }
+      : init;
+    const policy = retry && !(init.body instanceof FormData) ? retry : null;
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.#requestOnce<Returns>(url, sent, options);
+      } catch (error) {
+        const wait = policy ? HttpClient.retryWait(error, attempt, policy) : null;
+        if (wait === null) throw error;
+        await new Promise((resolve) => setTimeout(resolve, wait));
+      }
+    }
+  }
+
+  /** The wait before the next try, or `null` when this error is final or the tries are spent. */
+  static retryWait(error: unknown, attempt: number, { attempts = 4, ...backoff }: RetryPolicy): number | null {
+    const restored = error as RestoredError | undefined;
+    if (attempt >= attempts || !retryableKeys.has(restored?.error ?? "")) return null;
+    const wait = Backoff.delay(attempt, { min: 500, ...backoff });
+    const seconds = (restored?.data as { seconds?: unknown } | undefined)?.seconds;
+    return typeof seconds === "number" && seconds > 0 ? Math.max(wait, seconds * 1000) : wait;
+  }
+
+  async #requestOnce<Returns>(url: string, init: RequestInit, options: FetchOptions): Promise<Returns> {
     const res = await this.#fetch(url, this.#withTimeout(init, options));
     const body = await this.#readBody(res);
     if (res.ok) return body as Returns;

package/fetch/client/wsClient.ts

@@ -1,4 +1,5 @@
 import {
+  Backoff,
   Logger,
   type WebsocketHeartbeatAckData,
   websocketAuthContract,
@@ -17,17 +18,40 @@ import { websocketRoomContract } from "../../common/websocketContract";
 import { type ErrorConstructor, restoreRemoteError } from "./remoteError";
 
 export interface WsClientReconnectOptions {
-  enabled?: boolean;
-  interval?: number;
+  /** The first wait in ms; each attempt in a row doubles it. */
+  min?: number;
+  max?: number;
+  /** The share of each wait drawn at random, 0 to 1, so clients one deploy dropped together come back apart. */
+  jitter?: number;
+  /** Attempts in a row before the client gives up; unset, it never does. */
   maxAttempts?: number;
 }
 
+export type WsClientState = "connecting" | "open" | "closed" | "gaveUp";
+
+export interface WsClientOptions {
+  /** `false` stays closed after a drop. */
+  reconnect?: WsClientReconnectOptions | false;
+  /** Sent with the upgrade by a server-side client, the token among them as `authorization`; a browser sends none. */
+  headers?: Record<string, string>;
+  tls?: { rejectUnauthorized?: boolean; ca?: string | string[] };
+  onStateChange?: (state: WsClientState) => void;
+  /** A room the server took back when the credential changed. */
+  onRevoked?: (roomId: string) => void;
+  /** A frame the server answered with an error, and the subscribe or message key it answered. */
+  onError?: (error: unknown, key?: string) => void;
+}
+
 interface SubscribeOption {
   key: string;
   data: unknown[];
   listener: Set<(data: unknown) => void>;
-  /** After a resubscribe following a drop: what was published meanwhile is gone, so a room can only say so. */
+  /** After a resubscribe following a drop, or a hole in the frames: what was published meanwhile is gone. */
   resync: Set<() => void>;
+  /** The numbering of the frames the room delivered, while the server numbers them. */
+  cursor: { epoch: string | null; seq: number | null };
+  /** Resubscribed after a drop: the ack says whether what was missed came back. */
+  recovering: boolean;
 }
 interface Listener {
   callback: (data: unknown) => void;
@@ -68,6 +92,8 @@ export class WsClient {
   #jwt: string | null = null;
   #heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   #lastInboundAt = 0;
+  #options: WsClientOptions = {};
+  #state: WsClientState = "closed";
   connected = false;
 
   constructor(
@@ -81,6 +107,26 @@ export class WsClient {
     this.ErrorCls = ErrorCls;
   }
 
+  /** Merged over what was set before; read at the next connect and the next drop. */
+  configure(options: WsClientOptions) {
+    this.#options = { ...this.#options, ...options };
+    return this;
+  }
+
+  get state(): WsClientState {
+    return this.#state;
+  }
+
+  #setState(state: WsClientState) {
+    if (this.#state === state) return;
+    this.#state = state;
+    this.#options.onStateChange?.(state);
+  }
+
+  static reconnectDelay(attempt: number, policy: WsClientReconnectOptions = {}) {
+    return Backoff.delay(attempt, policy);
+  }
+
   /**
    * For clients holding the token in memory (native, cross-origin): the handshake carries only a same-origin cookie.
    * `null` drops that cookie server-side and revokes the rooms it authorized.
@@ -107,8 +153,9 @@ export class WsClient {
   #connect() {
     if (this.#destroyed) return;
 
+    this.#setState("connecting");
     try {
-      this.#ws = new WebSocket(this.url);
+      this.#ws = this.#open();
     } catch (error) {
       this.logger.error(`Cannot open a WebSocket to ${this.url}: ${error instanceof Error ? error.message : error}`);
       return;
@@ -118,16 +165,25 @@ export class WsClient {
       this.#reconnectAttempts = 0;
       this.connected = true;
       this.logger.debug(`WebSocket connected`);
+      this.#setState("open");
       this.#startHeartbeat();
       
       if (this.#jwt) this.#sendAuth();
       const reconnected = this.#hadConnection;
       this.#hadConnection = true;
       this.#roomSubscribeMap.forEach((option) => {
-        const data: WebsocketReqData = { key: option.key, data: option.data, subscribe: true };
+        const { epoch, seq } = option.cursor;
+        const since = reconnected && epoch !== null && seq !== null ? { epoch, seq } : undefined;
+        const data: WebsocketReqData = {
+          key: option.key,
+          data: option.data,
+          subscribe: true,
+          ...(since ? { since } : {}),
+        };
         this.#ws?.send(JSON.stringify(data));
-        if (!reconnected) return;
-        for (const handler of option.resync) handler();
+        
+        option.cursor = { epoch: null, seq: null };
+        option.recovering = reconnected;
       });
       const queued = this.#outbox;
       this.#outbox = [];
@@ -142,8 +198,12 @@ export class WsClient {
           else this.logger.warn("Unknown binary WebSocket frame");
           return;
         }
-        const parsed = JSON.parse(e.data) as { error?: unknown } & WebsocketResData;
-        if (parsed?.error) throw restoreRemoteError(parsed, 500, this.ErrorCls);
+        const parsed = JSON.parse(e.data) as { error?: unknown; key?: string } & WebsocketResData;
+        if (parsed?.error) {
+          const error = restoreRemoteError(parsed, 500, this.ErrorCls);
+          this.#options.onError?.(error, parsed.key);
+          throw error;
+        }
         const type = (parsed as WebsocketResData | WebsocketHeartbeatAckData).type;
         switch (type) {
           case "msg": {
@@ -158,11 +218,12 @@ export class WsClient {
               else this.#roomAliasMap.delete(sub.roomId);
             }
             this.logger.verbose(`Websocket ${sub.subscribe ? "subscribe" : "unsubscribe"} accepted: ${sub.roomId}`);
+            if (sub.subscribe) this.#acknowledge(sub);
             break;
           }
           case "pub": {
             const publishData = parsed as WebsocketPublishData;
-            this.#handlePubsub(publishData.roomId, publishData.data);
+            this.#handlePubsub(publishData.roomId, publishData.data, publishData.seq);
             break;
           }
           case "pong":
@@ -170,9 +231,11 @@ export class WsClient {
           case "auth": {
             const ack = parsed as WebsocketAuthAck;
             for (const roomId of ack.revokedRooms) {
-              this.#roomSubscribeMap.delete(this.#roomAliasMap.get(roomId) ?? roomId);
+              const requestRoomId = this.#roomAliasMap.get(roomId) ?? roomId;
+              this.#roomSubscribeMap.delete(requestRoomId);
               this.#roomAliasMap.delete(roomId);
               this.logger.warn(`Websocket room ${roomId} is no longer authorized`);
+              this.#options.onRevoked?.(requestRoomId);
             }
             break;
           }
@@ -193,6 +256,7 @@ export class WsClient {
       this.logger.debug(`WebSocket closed: ${event.code} ${event.reason}`);
       this.connected = false;
       this.#stopHeartbeat();
+      if (!this.#destroyed) this.#setState("closed");
       this.#scheduleReconnect();
     };
   }
@@ -225,15 +289,46 @@ export class WsClient {
 
   #scheduleReconnect() {
     if (this.#destroyed || !this.#ws) return;
-    const interval = 3000;
+    this.#ws = null;
+    const { reconnect } = this.#options;
     this.#reconnectAttempts += 1;
+    if (reconnect === false || this.#reconnectAttempts > (reconnect?.maxAttempts ?? Number.POSITIVE_INFINITY)) {
+      this.logger.warn(`WebSocket to ${this.url} gave up after ${this.#reconnectAttempts - 1} attempt(s)`);
+      this.#setState("gaveUp");
+      return;
+    }
+    const interval = WsClient.reconnectDelay(this.#reconnectAttempts, reconnect || undefined);
     this.logger.debug(`WebSocket reconnecting in ${interval}ms (attempt ${this.#reconnectAttempts})`);
-
-    this.#ws = null;
     this.#reconnectTimer = setTimeout(() => {
       this.#reconnectTimer = null;
       this.#connect();
     }, interval);
+    
+    this.#reconnectTimer.unref?.();
+  }
+
+  #open(): WebSocket {
+    if (typeof window !== "undefined") return new WebSocket(this.url);
+    const { headers, tls } = this.#options;
+    const authorization: Record<string, string> = this.#jwt ? { authorization: `Bearer ${this.#jwt}` } : {};
+    const BunWebSocket = WebSocket as unknown as new (
+      url: string,
+      options: { headers?: Record<string, string>; tls?: WsClientOptions["tls"] },
+    ) => WebSocket;
+    return new BunWebSocket(this.url, { headers: { ...headers, ...authorization }, ...(tls ? { tls } : {}) });
+  }
+
+  #acknowledge(ack: WebsocketSubscribeAck) {
+    const option = this.#roomSubscribeMap.get(ack.requestRoomId);
+    if (!option) return;
+    if (ack.cursor) {
+      option.cursor.epoch = ack.cursor.epoch;
+      if (option.cursor.seq === null || ack.cursor.seq > option.cursor.seq) option.cursor.seq = ack.cursor.seq;
+    }
+    if (!option.recovering) return;
+    option.recovering = false;
+    if (ack.replayed === true) return;
+    for (const handler of option.resync) handler();
   }
   #handleMessage(key: string, data: unknown) {
     const listenerSet = this.#listenerMap.get(key);
@@ -246,10 +341,16 @@ export class WsClient {
       }
     }
   }
-  #handlePubsub(roomId: string, data: unknown) {
+  #handlePubsub(roomId: string, data: unknown, seq?: number) {
     const roomSubscribe = this.#roomSubscribeMap.get(this.#roomAliasMap.get(roomId) ?? roomId);
     if (!roomSubscribe) return;
+    const last = roomSubscribe.cursor.seq;
+    
+    if (seq !== undefined && last !== null && seq <= last) return;
+    if (seq !== undefined) roomSubscribe.cursor.seq = seq;
     for (const listener of roomSubscribe.listener) listener(data);
+    
+    if (seq !== undefined && last !== null && seq > last + 1) for (const handler of roomSubscribe.resync) handler();
   }
 
   destroy() {
@@ -267,6 +368,7 @@ export class WsClient {
     this.#roomAliasMap.clear();
     this.#ws?.close();
     this.#ws = null;
+    this.#setState("closed");
   }
 
   on<Data = unknown>(key: string, callback: (data: Data) => void) {
@@ -329,7 +431,14 @@ export class WsClient {
     if (!this.#ws) this.#warnUnconnected("subscribe", option.key);
     let roomSubscribe = this.#roomSubscribeMap.get(roomId);
     if (!roomSubscribe) {
-      roomSubscribe = { key: option.key, data: option.data, listener: new Set(), resync: new Set() };
+      roomSubscribe = {
+        key: option.key,
+        data: option.data,
+        listener: new Set(),
+        resync: new Set(),
+        cursor: { epoch: null, seq: null },
+        recovering: false,
+      };
       this.#roomSubscribeMap.set(roomId, roomSubscribe);
       if (this.#ws?.readyState === WebSocket.OPEN) this.#sendSubscribe(option.key, option.data, true);
       this.logger.verbose(`Websocket subscribe pubsub for ${roomId}`);