cry-synced-db-client 0.1.180 → 0.1.182

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Versions
 
+## 0.1.182 (2026-05-14)
+
+### `networkError` utility — quiet log noise during sustained offline
+
+New `src/utils/networkError.ts`:
+
+```ts
+export function networkError(message: string, ...rest: unknown[]): void {
+  const isOnline =
+    typeof navigator === "undefined" || navigator.onLine !== false;
+  if (isOnline) {
+    console.error(message, ...rest);
+  } else {
+    console.info(message, ...rest);
+  }
+}
+```
+
+Applied to 15 sites where the failure mode reduces to "REST/WS
+unreachable because the network is down":
+
+| Module | Site |
+|---|---|
+| `ConnectionManager` | Failed to go online after forceOffline release |
+| `ConnectionManager` | Auto-sync failed |
+| `ConnectionManager` | Reconnect tryGoOnline failed |
+| `PendingChangesManager` | REST upload failed |
+| `WakeSyncManager` | Wake sync (`<trigger>`) failed |
+| `SyncEngine` | uploadDirtyItems failed (download succeeded) |
+| `SyncEngine` | Sync failed |
+| `SyncedDb` | tryGoOnline on becameLeader failed |
+| `SyncedDb` | referToServer failed for `<collection>` |
+| `SyncedDb` | refreshInBackground failed for `<collection>` |
+| `SyncedDb` | Failed to hard delete `<id>` |
+| `SyncedDb` | `[evict]` server-assisted pass failed |
+| `SyncedDb` | `[evict]` server-assisted batch failed |
+| `Ebus2ProxyNotifier` | WebSocket error: `<event.type>` |
+| `Ebus2ProxyNotifier` | Reconnection failed |
+
+Effect: a 5-minute offline period that previously produced ~25–30
+`console.error` lines (auto-sync ticks every 60s, reconnect probes
+every 60s, WS reconnect backoff, dirty-flush retries) now produces 0.
+The events are still logged at `console.info` so an operator inspecting
+them sees the full timeline — they just don't surface as "errors" in
+sentry/log dashboards.
+
+What's NOT routed through `networkError` (intentional — these are real
+bugs regardless of network state):
+- Caller bugs (falsy `_id`, missing `_id`, id mismatch, no id provided)
+- Dexie failures (`bulkPut failed`, `Failed to write to Dexie`, etc.)
+- Consumer-supplied callback throws (`onSyncEnd callback failed`, etc.)
+- WS protocol errors (malformed msgpack, server-side error frames)
+- Server-side per-item rejection (`Sync upload error [coll] _id=...`)
+- `DB-WARNING` per-item warnings
+- BroadcastChannel failures (cross-tab, local, not network)
+
+Caveat: `navigator.onLine` only reports the OS network interface, not
+server reachability. WiFi-on-but-server-unreachable still logs at error
+severity, which is the correct behavior — that failure is unexpected
+from the browser's point of view.
+
+Bundle: 356.0 KB → 356.2 KB. Tests: 736 bun + 18 vitest still pass.
+
+## 0.1.181 (2026-05-14)
+
+### `measureEndToEndRtt` now rides `callWorker` over the WebSocket
+
+The old HTTP echo path was a workaround for the missing WS
+request/response correlation in ebus-proxy 1.x. Now that
+`callWorker` (0.1.180) provides it, `measureEndToEndRtt` becomes a
+5-line wrapper:
+
+```ts
+async measureEndToEndRtt(timeoutMs = 5000): Promise<number> {
+  const sentAt = Date.now();
+  const t0 = performance.now();
+  const echoed = await this.callWorker<number>("echo", sentAt, { timeoutMs });
+  if (echoed !== sentAt) throw payload-mismatch error;
+  return performance.now() - t0;
+}
+```
+
+Dropped HTTP-specific code: base URL derivation (`ws://`→`http://`),
+base64 encoding (Buffer + btoa fallback), URL query-string assembly,
+`AbortSignal.timeout` shim, `fetch` + `arrayBuffer` + `unpack` pipeline,
+HTTP status error branch. Bundle: 356.9 KB → 356.0 KB.
+
+**Semantic shift**: now measures the WebSocket round-trip rather than
+the HTTP round-trip. For this codebase that's more representative —
+real notifications arrive on the WS, not via HTTP. The old HTTP path
+was characterizing a transport the app barely uses (sync uploads go to
+cry-db directly, not through ebus-proxy).
+
+Public signature is unchanged; existing callers keep working. The
+diagnostic interpretation table in CLAUDE.md still applies — the
+labels just refer to the WS chain instead of the HTTP chain.
+
+Tests: 736 bun + 18 vitest, all green.
+
 ## 0.1.180 (2026-05-14)
 
 ### `SyncedDb.callWorker` — invoke ebus2 worker services over the WS

package/dist/index.js

@@ -732,6 +732,16 @@ function childPathForArrayElement(prefix, element, index) {
   return prefix ? `${prefix}.${index}` : String(index);
 }
 
+// src/utils/networkError.ts
+function networkError(message, ...rest) {
+  const isOnline = typeof navigator === "undefined" || navigator.onLine !== false;
+  if (isOnline) {
+    console.error(message, ...rest);
+  } else {
+    console.info(message, ...rest);
+  }
+}
+
 // src/db/managers/InMemManager.ts
 var InMemManager = class {
   constructor(config) {
@@ -1422,7 +1432,7 @@ var ConnectionManager = class {
     } else {
       this.deps.tryBecomeLeader();
       this.tryGoOnline().catch((err) => {
-        console.error(`[Connection] Failed to go online after forceOffline release: ${err}`, err);
+        networkError(`[Connection] Failed to go online after forceOffline release: ${err}`, err);
       });
     }
   }
@@ -1480,7 +1490,7 @@ var ConnectionManager = class {
       this.autoSyncTimer = setInterval(() => {
         if (this.forcedOffline || !this.online) return;
         this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
-          console.error(`[Connection] Auto-sync failed: ${err}`, err);
+          networkError(`[Connection] Auto-sync failed: ${err}`, err);
         });
       }, intervalMs);
     }
@@ -1489,7 +1499,7 @@ var ConnectionManager = class {
       this.reconnectTimer = setInterval(() => {
         if (this.forcedOffline || this.online || this.tryGoOnlineInFlight) return;
         this.tryGoOnline().catch((err) => {
-          console.error(`[Connection] Reconnect tryGoOnline failed: ${err}`, err);
+          networkError(`[Connection] Reconnect tryGoOnline failed: ${err}`, err);
         });
       }, retryMs);
     }
@@ -2827,7 +2837,7 @@ var PendingChangesManager = class {
     try {
       await this.deps.uploadDirtyItems();
     } catch (err) {
-      console.error(`[PendingChanges] REST upload failed: ${err}`, err);
+      networkError(`[PendingChanges] REST upload failed: ${err}`, err);
     } finally {
       this.isUploadingToRest = false;
       resolveUpload();
@@ -3209,7 +3219,7 @@ var _SyncEngine = class _SyncEngine {
           }
         }
       } catch (err) {
-        console.error(
+        networkError(
           "[SyncEngine] uploadDirtyItems failed (download succeeded, staying online):",
           err
         );
@@ -3236,7 +3246,7 @@ var _SyncEngine = class _SyncEngine {
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      console.error(`[SyncEngine] Sync failed: ${err}`, err);
+      networkError(`[SyncEngine] Sync failed: ${err}`, err);
       this.deps.onSyncFailed(`Sync failed: ${reason}`);
       this.callOnSyncEnd({
         durationMs: Date.now() - startTime,
@@ -4291,7 +4301,7 @@ var WakeSyncManager = class {
         }
       }
       this.deps.sync(`wake-sync:${trigger}`).catch((err) => {
-        console.error(`[WakeSync] Wake sync (${trigger}) failed:`, err);
+        networkError(`[WakeSync] Wake sync (${trigger}) failed:`, err);
       });
     }, this.debounceMs);
   }
@@ -4447,7 +4457,7 @@ var _SyncedDb = class _SyncedDb {
         onBecameLeader: () => {
           if (this.initialized && !this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
             this.connectionManager.tryGoOnline().catch((err) => {
-              console.error(`[SyncedDb] tryGoOnline on becameLeader failed: ${err}`, err);
+              networkError(`[SyncedDb] tryGoOnline on becameLeader failed: ${err}`, err);
             });
           }
           if (config.onBecameLeader) {
@@ -5246,7 +5256,7 @@ var _SyncedDb = class _SyncedDb {
         await this.syncEngine.processCollectionServerData(collection, serverData, { source: "refresh" });
       }
     }).catch((err) => {
-      console.error(`[SyncedDb] referToServer failed for ${collection}:`, err);
+      networkError(`[SyncedDb] referToServer failed for ${collection}:`, err);
     });
   }
   /**
@@ -5267,7 +5277,7 @@ var _SyncedDb = class _SyncedDb {
       if (!serverItems || serverItems.length === 0) return;
       await this.syncEngine.processCollectionServerData(collection, serverItems, { source: "incremental" });
     }).catch((err) => {
-      console.error(`[SyncedDb] refreshInBackground failed for ${collection}:`, err);
+      networkError(`[SyncedDb] refreshInBackground failed for ${collection}:`, err);
     });
   }
   async ensureItemsAreLoaded(collection, ids, withDeleted) {
@@ -5532,7 +5542,7 @@ var _SyncedDb = class _SyncedDb {
             this.inMemManager.writeBatch(collection, [{ _id: item.id }], "delete", { source: "incremental" });
             results.push(true);
           } catch (err) {
-            console.error(`[SyncedDb] Failed to hard delete ${String(item.id)}:`, err);
+            networkError(`[SyncedDb] Failed to hard delete ${String(item.id)}:`, err);
             results.push(false);
           }
         }
@@ -5913,7 +5923,7 @@ var _SyncedDb = class _SyncedDb {
         for (const id of serverExits) evictIds.push(id);
         serverEvictedCount = serverExits.length;
       } catch (err) {
-        console.error(
+        networkError(
           `[SyncedDb] [evict] server-assisted pass failed for ${collection} (proceeding with local-only):`,
           err
         );
@@ -6030,7 +6040,7 @@ var _SyncedDb = class _SyncedDb {
         }
       } catch (err) {
         serverFailed = true;
-        console.error(
+        networkError(
           "[SyncedDb] [evict] server-assisted batch failed (proceeding with local-only):",
           err
         );
@@ -9845,41 +9855,22 @@ var Ebus2ProxyServerUpdateNotifier = class {
   }
   /**
    * End-to-end RTT (client → proxy → broker → echo worker → broker →
-   * proxy → client). Sends an HTTP request to ebus-proxy's `echo`
-   * service with `Date.now()` as the msgpack payload; the worker
-   * returns the payload unchanged, and we verify byte-equality before
-   * reporting RTT.
+   * proxy → client). Invokes the `echo` worker via `callWorker` with
+   * `Date.now()` as the payload; the worker returns it unchanged and
+   * we verify byte-equality before reporting RTT.
    *
-   * The HTTP base URL is derived from `wsUrl` (`ws://` → `http://`,
-   * `wss://` → `https://`). Throws on HTTP error, payload mismatch,
-   * or timeout.
+   * Rides the existing WebSocket — same transport real notifications
+   * arrive on, so this is the more representative diagnostic of actual
+   * app-traffic latency. Throws on payload mismatch, timeout, or any
+   * `callWorker` failure path (WS not OPEN, proxy error, etc).
    *
-   * @param timeoutMs Max wait for HTTP response (default: 5000)
+   * @param timeoutMs Max wait for echo reply (default: 5000)
    * @returns RTT in milliseconds (full round-trip)
    */
   async measureEndToEndRtt(timeoutMs = 5e3) {
-    const httpBase = this.wsUrl.replace(/^ws:\/\//, "http://").replace(/^wss:\/\//, "https://").replace(/\/+$/, "");
     const sentAt = Date.now();
-    const packed = packr2.pack(sentAt);
-    let payloadB64;
-    const bufCtor = globalThis.Buffer;
-    if (bufCtor) {
-      payloadB64 = bufCtor.from(packed).toString("base64");
-    } else {
-      let bin = "";
-      for (let i = 0; i < packed.length; i++) bin += String.fromCharCode(packed[i]);
-      payloadB64 = btoa(bin);
-    }
-    const keyParam = this.ebusProxyApiKey ? `&apikey=${encodeURIComponent(this.ebusProxyApiKey)}` : "";
-    const url = `${httpBase}/?service=echo&payload=${encodeURIComponent(payloadB64)}${keyParam}&timeout=${timeoutMs}`;
     const t0 = performance.now();
-    const signal = typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(timeoutMs) : void 0;
-    const res = await fetch(url, signal ? { signal } : void 0);
-    if (!res.ok) {
-      throw new Error(`[Ebus2ProxyNotifier] measureEndToEndRtt: HTTP ${res.status}`);
-    }
-    const buf = new Uint8Array(await res.arrayBuffer());
-    const echoed = unpackr2.unpack(buf);
+    const echoed = await this.callWorker("echo", sentAt, { timeoutMs });
     if (echoed !== sentAt) {
       throw new Error(
         `[Ebus2ProxyNotifier] measureEndToEndRtt: payload mismatch (sent ${sentAt}, got ${JSON.stringify(echoed)})`
@@ -10132,7 +10123,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     }
   }
   handleError(event) {
-    console.error(`[Ebus2ProxyNotifier] WebSocket error: ${event.type}`, event);
+    networkError(`[Ebus2ProxyNotifier] WebSocket error: ${event.type}`, event);
   }
   handleMessage(event) {
     try {
@@ -10253,7 +10244,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
       this.reconnectTimer = void 0;
       if (this.shouldReconnect && !this.forcedOffline) {
         this.createWebSocket().catch((err) => {
-          console.error(`[Ebus2ProxyNotifier] Reconnection failed: ${err}`, err);
+          networkError(`[Ebus2ProxyNotifier] Reconnection failed: ${err}`, err);
           this.currentReconnectDelay = Math.min(
             this.currentReconnectDelay * 2,
             this.maxReconnectDelayMs

package/dist/src/db/Ebus2ProxyServerUpdateNotifier.d.ts

@@ -104,16 +104,16 @@ export declare class Ebus2ProxyServerUpdateNotifier implements I_ServerUpdateNot
     measureWsRtt(timeoutMs?: number): Promise<number>;
     /**
      * End-to-end RTT (client → proxy → broker → echo worker → broker →
-     * proxy → client). Sends an HTTP request to ebus-proxy's `echo`
-     * service with `Date.now()` as the msgpack payload; the worker
-     * returns the payload unchanged, and we verify byte-equality before
-     * reporting RTT.
+     * proxy → client). Invokes the `echo` worker via `callWorker` with
+     * `Date.now()` as the payload; the worker returns it unchanged and
+     * we verify byte-equality before reporting RTT.
      *
-     * The HTTP base URL is derived from `wsUrl` (`ws://` → `http://`,
-     * `wss://` → `https://`). Throws on HTTP error, payload mismatch,
-     * or timeout.
+     * Rides the existing WebSocket — same transport real notifications
+     * arrive on, so this is the more representative diagnostic of actual
+     * app-traffic latency. Throws on payload mismatch, timeout, or any
+     * `callWorker` failure path (WS not OPEN, proxy error, etc).
      *
-     * @param timeoutMs Max wait for HTTP response (default: 5000)
+     * @param timeoutMs Max wait for echo reply (default: 5000)
      * @returns RTT in milliseconds (full round-trip)
      */
     measureEndToEndRtt(timeoutMs?: number): Promise<number>;

package/dist/src/utils/networkError.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Log a failure at appropriate severity depending on perceived network
+ * connectivity.
+ *
+ * - **Online** (`navigator.onLine === true`, or `navigator` unavailable
+ *   like in Node/SSR): routes to `console.error`. Failures while the
+ *   browser thinks it's online are unexpected — operators should see
+ *   them.
+ * - **Offline** (`navigator.onLine === false`): routes to
+ *   `console.info`. Sync/upload/reconnect failures are the expected
+ *   steady-state and shouldn't pollute the error stream.
+ *
+ * Use this ONLY for sites whose failure reduces to "the network is
+ * down" — caller bugs, Dexie failures, parse errors, and consumer
+ * callback throws must keep using `console.error` directly so they're
+ * visible regardless of connectivity.
+ *
+ * Signature mirrors `console.error` — first arg is the tag-line string
+ * (per the console-reporting skill), remaining args are objects /
+ * values for devtools inspection.
+ *
+ * Caveat: `navigator.onLine` only tells you whether the browser has a
+ * network interface; it can't detect "WiFi connected but server
+ * unreachable". In that case this still routes to `console.error`,
+ * which is correct — the failure is unexpected from the browser's
+ * point of view.
+ */
+export declare function networkError(message: string, ...rest: unknown[]): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.180",
+  "version": "0.1.182",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",