@pramen/client 0.0.13 → 0.0.15

package/dist/index.d.ts

@@ -19,13 +19,27 @@ export interface ClientOptions {
     /** Override for non-browser environments (defaults to globals). */
     WebSocketImpl?: typeof WebSocket;
     fetchImpl?: typeof fetch;
+    /** Give up reconnecting the live socket after this many consecutive failed
+     * attempts and surface a connection error to every subscriber (default 8). */
+    maxReconnectAttempts?: number;
 }
 export interface SubHandlers<T> {
     onData: (result: T) => void;
+    /** Called when the server rejects THIS subscription (a `{type:"error"}` frame). */
     onError?: (err: {
         error: string;
         code: string;
     }) => void;
+    /** Called when the underlying live connection itself fails — no WebSocket
+     * implementation is available, or the socket has closed and stayed down past
+     * `maxReconnectAttempts`. Distinct from `onError` (a per-subscription server error):
+     * this is a transport-level failure that affects every sub on the connection.
+     * Optional and additive — omitting it preserves the prior (silent) behavior for
+     * existing callers. */
+    onConnectionError?: (err: {
+        error: string;
+        code: string;
+    }) => void;
 }
 /** Result of a file upload (the persisted blob's storage metadata). */
 export interface UploadResult {

package/dist/index.js

@@ -21,32 +21,58 @@ export class PramenError extends Error {
 export function createClient(opts) {
     const doFetch = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
     const WS = opts.WebSocketImpl ?? globalThis.WebSocket;
+    // Normalize the base url: strip any trailing slash so `${base}/rpc/...` can't become
+    // `//rpc/...` (which the Worker serves as a plain-text help page — a 200 that isn't an
+    // envelope, silently resolving `call()` to undefined for every RPC).
+    const baseUrl = opts.url.replace(/\/+$/, "");
+    const maxReconnectAttempts = opts.maxReconnectAttempts ?? 8;
     let token = opts.token;
+    // D1 read-your-writes: when the backend runs on the D1 store it returns an
+    // `x-pramen-d1-bookmark` header marking the latest write this client has observed.
+    // We stash it and echo it on the next request so a fresh D1 session anchors there and
+    // reads our own writes (even off a lagging replica). The DO path never sets the
+    // header, so `d1Bookmark` stays undefined there and nothing changes.
+    let d1Bookmark;
     const subs = new Map();
     let ws = null;
     let counter = 0;
     let reconnectAttempts = 0;
     let reconnectTimer = null;
+    let stableTimer = null;
     let closed = false;
+    // How long a connection must stay open before we trust it and reset the backoff.
+    const STABLE_MS = 3000;
     async function call(name, input) {
         const headers = { "content-type": "application/json" };
         if (token)
             headers.authorization = `Bearer ${token}`;
         if (opts.tenant)
             headers["x-pramen-tenant"] = opts.tenant;
-        const res = await doFetch(`${opts.url}/rpc/${name}`, {
+        if (d1Bookmark)
+            headers["x-pramen-d1-bookmark"] = d1Bookmark;
+        const res = await doFetch(`${baseUrl}/rpc/${name}`, {
             method: "POST",
             headers,
             body: JSON.stringify(input ?? {}),
         });
+        // Capture the D1 read-your-writes bookmark (D1 store only; absent on the DO path).
+        // Keep the MAXIMUM bookmark seen — D1 session bookmarks are lexicographically
+        // ordered, so a slower earlier response arriving after a mutation must not clobber a
+        // newer one and regress read-your-writes.
+        const bookmark = res.headers.get("x-pramen-d1-bookmark");
+        if (bookmark && (!d1Bookmark || bookmark > d1Bookmark))
+            d1Bookmark = bookmark;
         const body = (await res.json().catch(() => ({})));
-        if (!res.ok || body.ok === false) {
+        // Require the success envelope explicitly: only `{ ok: true }` is a success. Any
+        // other 2xx body (e.g. a non-JSON help page parsed to `{}`, or `ok` absent) is an
+        // error, so a call never silently resolves undefined.
+        if (!res.ok || body.ok !== true) {
             throw new PramenError(body.error ?? `request failed (${res.status})`, body.code ?? "error", res.status);
         }
         return body.result;
     }
     function liveUrl() {
-        const u = new URL(opts.url);
+        const u = new URL(baseUrl);
         u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
         u.pathname = "/live";
         if (opts.tenant)
@@ -55,13 +81,34 @@ export function createClient(opts) {
             u.searchParams.set("token", token);
         return u.toString();
     }
+    /** Surface a transport-level failure (no WS impl, or reconnects exhausted) to every
+     * subscriber so a `useLiveQuery` can leave its loading state instead of hanging. */
+    function reportConnectionError(error, code) {
+        for (const sub of subs.values())
+            sub.onConnectionError?.({ error, code });
+    }
     function ensureSocket() {
-        if (closed || ws || !WS || subs.size === 0)
+        if (closed || ws || subs.size === 0)
+            return;
+        if (!WS) {
+            // No WebSocket implementation in this environment — the subscription can never
+            // fire. Surface it instead of returning silently (the old hang-forever behavior).
+            reportConnectionError("no WebSocket implementation available", "no_websocket");
             return;
+        }
         const socket = new WS(liveUrl());
         ws = socket;
         socket.addEventListener("open", () => {
-            reconnectAttempts = 0;
+            // Don't reset the backoff on open alone: an accept-then-immediately-close server
+            // would otherwise hot-loop with no backoff growth. Only clear it once the
+            // connection has stayed up (stableTimer below).
+            if (stableTimer)
+                clearTimeout(stableTimer);
+            stableTimer = setTimeout(() => {
+                stableTimer = null;
+                if (ws === socket)
+                    reconnectAttempts = 0;
+            }, STABLE_MS);
             for (const sub of subs.values()) {
                 socket.send(JSON.stringify({ type: "subscribe", id: sub.id, name: sub.name, input: sub.input }));
             }
@@ -85,6 +132,10 @@ export function createClient(opts) {
         socket.addEventListener("close", () => {
             if (ws === socket)
                 ws = null;
+            if (stableTimer) {
+                clearTimeout(stableTimer);
+                stableTimer = null;
+            }
             scheduleReconnect();
         });
         socket.addEventListener("error", () => {
@@ -99,7 +150,15 @@ export function createClient(opts) {
     function scheduleReconnect() {
         if (closed || reconnectTimer || subs.size === 0)
             return;
-        const delay = Math.min(500 * 2 ** reconnectAttempts, 10_000);
+        if (reconnectAttempts >= maxReconnectAttempts) {
+            // Give up rather than reconnect forever at the 10s cap — a rejected upgrade (e.g.
+            // auth 403) would otherwise spin silently behind a permanent spinner.
+            reportConnectionError(`live connection failed after ${reconnectAttempts} attempts`, "connection_failed");
+            return;
+        }
+        // Exponential backoff with jitter (so a fleet of clients doesn't reconnect in lockstep).
+        const base = Math.min(500 * 2 ** reconnectAttempts, 10_000);
+        const delay = base / 2 + Math.random() * (base / 2);
         reconnectAttempts++;
         reconnectTimer = setTimeout(() => {
             reconnectTimer = null;
@@ -120,17 +179,21 @@ export function createClient(opts) {
             clearTimeout(reconnectTimer);
             reconnectTimer = null;
         }
+        if (stableTimer) {
+            clearTimeout(stableTimer);
+            stableTimer = null;
+        }
         reconnectAttempts = 0;
         ensureSocket();
     }
-    const fileUrl = (path) => new URL(path, opts.url).toString();
+    const fileUrl = (path) => new URL(path, baseUrl).toString();
     async function upload(uploadUrl, body, o) {
         const headers = {};
         if (o?.contentType)
             headers["content-type"] = o.contentType;
         const res = await doFetch(fileUrl(uploadUrl), { method: "PUT", headers, body });
         const j = (await res.json().catch(() => ({})));
-        if (!res.ok || j.ok === false) {
+        if (!res.ok || j.ok !== true) {
             throw new PramenError(j.error ?? `upload failed (${res.status})`, j.code ?? "error", res.status);
         }
         return j.result;
@@ -147,6 +210,7 @@ export function createClient(opts) {
                 input,
                 onData: handlers.onData,
                 onError: handlers.onError,
+                onConnectionError: handlers.onConnectionError,
             };
             subs.set(id, sub);
             if (ws && ws.readyState === 1) {
@@ -170,6 +234,8 @@ export function createClient(opts) {
             subs.clear();
             if (reconnectTimer)
                 clearTimeout(reconnectTimer);
+            if (stableTimer)
+                clearTimeout(stableTimer);
             if (ws) {
                 try {
                     ws.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/client",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Typed client for a pramen backend — RPC over HTTP + live queries over WebSocket.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -34,11 +34,22 @@ export interface ClientOptions {
   /** Override for non-browser environments (defaults to globals). */
   WebSocketImpl?: typeof WebSocket;
   fetchImpl?: typeof fetch;
+  /** Give up reconnecting the live socket after this many consecutive failed
+   * attempts and surface a connection error to every subscriber (default 8). */
+  maxReconnectAttempts?: number;
 }
 
 export interface SubHandlers<T> {
   onData: (result: T) => void;
+  /** Called when the server rejects THIS subscription (a `{type:"error"}` frame). */
   onError?: (err: { error: string; code: string }) => void;
+  /** Called when the underlying live connection itself fails — no WebSocket
+   * implementation is available, or the socket has closed and stayed down past
+   * `maxReconnectAttempts`. Distinct from `onError` (a per-subscription server error):
+   * this is a transport-level failure that affects every sub on the connection.
+   * Optional and additive — omitting it preserves the prior (silent) behavior for
+   * existing callers. */
+  onConnectionError?: (err: { error: string; code: string }) => void;
 }
 
 /** Result of a file upload (the persisted blob's storage metadata). */
@@ -72,38 +83,64 @@ interface Sub {
   input: unknown;
   onData: (result: unknown) => void;
   onError?: (err: { error: string; code: string }) => void;
+  onConnectionError?: (err: { error: string; code: string }) => void;
 }
 
 export function createClient<Api = Record<string, never>>(opts: ClientOptions): PramenClient<Api> {
   const doFetch = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
   const WS = opts.WebSocketImpl ?? (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
+  // Normalize the base url: strip any trailing slash so `${base}/rpc/...` can't become
+  // `//rpc/...` (which the Worker serves as a plain-text help page — a 200 that isn't an
+  // envelope, silently resolving `call()` to undefined for every RPC).
+  const baseUrl = opts.url.replace(/\/+$/, "");
+  const maxReconnectAttempts = opts.maxReconnectAttempts ?? 8;
   let token = opts.token;
 
+  // D1 read-your-writes: when the backend runs on the D1 store it returns an
+  // `x-pramen-d1-bookmark` header marking the latest write this client has observed.
+  // We stash it and echo it on the next request so a fresh D1 session anchors there and
+  // reads our own writes (even off a lagging replica). The DO path never sets the
+  // header, so `d1Bookmark` stays undefined there and nothing changes.
+  let d1Bookmark: string | undefined;
+
   const subs = new Map<string, Sub>();
   let ws: WebSocket | null = null;
   let counter = 0;
   let reconnectAttempts = 0;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stableTimer: ReturnType<typeof setTimeout> | null = null;
   let closed = false;
+  // How long a connection must stay open before we trust it and reset the backoff.
+  const STABLE_MS = 3000;
 
   async function call(name: string, input?: unknown): Promise<unknown> {
     const headers: Record<string, string> = { "content-type": "application/json" };
     if (token) headers.authorization = `Bearer ${token}`;
     if (opts.tenant) headers["x-pramen-tenant"] = opts.tenant;
-    const res = await doFetch(`${opts.url}/rpc/${name}`, {
+    if (d1Bookmark) headers["x-pramen-d1-bookmark"] = d1Bookmark;
+    const res = await doFetch(`${baseUrl}/rpc/${name}`, {
       method: "POST",
       headers,
       body: JSON.stringify(input ?? {}),
     });
+    // Capture the D1 read-your-writes bookmark (D1 store only; absent on the DO path).
+    // Keep the MAXIMUM bookmark seen — D1 session bookmarks are lexicographically
+    // ordered, so a slower earlier response arriving after a mutation must not clobber a
+    // newer one and regress read-your-writes.
+    const bookmark = res.headers.get("x-pramen-d1-bookmark");
+    if (bookmark && (!d1Bookmark || bookmark > d1Bookmark)) d1Bookmark = bookmark;
     const body = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: unknown; error?: string; code?: string };
-    if (!res.ok || body.ok === false) {
+    // Require the success envelope explicitly: only `{ ok: true }` is a success. Any
+    // other 2xx body (e.g. a non-JSON help page parsed to `{}`, or `ok` absent) is an
+    // error, so a call never silently resolves undefined.
+    if (!res.ok || body.ok !== true) {
       throw new PramenError(body.error ?? `request failed (${res.status})`, body.code ?? "error", res.status);
     }
     return body.result;
   }
 
   function liveUrl(): string {
-    const u = new URL(opts.url);
+    const u = new URL(baseUrl);
     u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
     u.pathname = "/live";
     if (opts.tenant) u.searchParams.set("tenant", opts.tenant);
@@ -111,12 +148,31 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
     return u.toString();
   }
 
+  /** Surface a transport-level failure (no WS impl, or reconnects exhausted) to every
+   * subscriber so a `useLiveQuery` can leave its loading state instead of hanging. */
+  function reportConnectionError(error: string, code: string): void {
+    for (const sub of subs.values()) sub.onConnectionError?.({ error, code });
+  }
+
   function ensureSocket(): void {
-    if (closed || ws || !WS || subs.size === 0) return;
+    if (closed || ws || subs.size === 0) return;
+    if (!WS) {
+      // No WebSocket implementation in this environment — the subscription can never
+      // fire. Surface it instead of returning silently (the old hang-forever behavior).
+      reportConnectionError("no WebSocket implementation available", "no_websocket");
+      return;
+    }
     const socket = new WS(liveUrl());
     ws = socket;
     socket.addEventListener("open", () => {
-      reconnectAttempts = 0;
+      // Don't reset the backoff on open alone: an accept-then-immediately-close server
+      // would otherwise hot-loop with no backoff growth. Only clear it once the
+      // connection has stayed up (stableTimer below).
+      if (stableTimer) clearTimeout(stableTimer);
+      stableTimer = setTimeout(() => {
+        stableTimer = null;
+        if (ws === socket) reconnectAttempts = 0;
+      }, STABLE_MS);
       for (const sub of subs.values()) {
         socket.send(JSON.stringify({ type: "subscribe", id: sub.id, name: sub.name, input: sub.input }));
       }
@@ -135,6 +191,10 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
     });
     socket.addEventListener("close", () => {
       if (ws === socket) ws = null;
+      if (stableTimer) {
+        clearTimeout(stableTimer);
+        stableTimer = null;
+      }
       scheduleReconnect();
     });
     socket.addEventListener("error", () => {
@@ -148,7 +208,15 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
 
   function scheduleReconnect(): void {
     if (closed || reconnectTimer || subs.size === 0) return;
-    const delay = Math.min(500 * 2 ** reconnectAttempts, 10_000);
+    if (reconnectAttempts >= maxReconnectAttempts) {
+      // Give up rather than reconnect forever at the 10s cap — a rejected upgrade (e.g.
+      // auth 403) would otherwise spin silently behind a permanent spinner.
+      reportConnectionError(`live connection failed after ${reconnectAttempts} attempts`, "connection_failed");
+      return;
+    }
+    // Exponential backoff with jitter (so a fleet of clients doesn't reconnect in lockstep).
+    const base = Math.min(500 * 2 ** reconnectAttempts, 10_000);
+    const delay = base / 2 + Math.random() * (base / 2);
     reconnectAttempts++;
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
@@ -169,18 +237,22 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
       clearTimeout(reconnectTimer);
       reconnectTimer = null;
     }
+    if (stableTimer) {
+      clearTimeout(stableTimer);
+      stableTimer = null;
+    }
     reconnectAttempts = 0;
     ensureSocket();
   }
 
-  const fileUrl = (path: string): string => new URL(path, opts.url).toString();
+  const fileUrl = (path: string): string => new URL(path, baseUrl).toString();
 
   async function upload(uploadUrl: string, body: BodyInit, o?: { contentType?: string }): Promise<UploadResult> {
     const headers: Record<string, string> = {};
     if (o?.contentType) headers["content-type"] = o.contentType;
     const res = await doFetch(fileUrl(uploadUrl), { method: "PUT", headers, body });
     const j = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: UploadResult; error?: string; code?: string };
-    if (!res.ok || j.ok === false) {
+    if (!res.ok || j.ok !== true) {
       throw new PramenError(j.error ?? `upload failed (${res.status})`, j.code ?? "error", res.status);
     }
     return j.result as UploadResult;
@@ -198,6 +270,7 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
         input,
         onData: handlers.onData as (r: unknown) => void,
         onError: handlers.onError,
+        onConnectionError: handlers.onConnectionError,
       };
       subs.set(id, sub);
       if (ws && ws.readyState === 1) {
@@ -218,6 +291,7 @@ export function createClient<Api = Record<string, never>>(opts: ClientOptions):
       closed = true;
       subs.clear();
       if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (stableTimer) clearTimeout(stableTimer);
       if (ws) {
         try {
           ws.close();