cry-synced-db-client 0.1.175 → 0.1.176

package/CHANGELOG.md

@@ -2,6 +2,108 @@
 
 ## Unreleased
 
+### Passive transport metrics on `findNewerManyStream` round-trip (rdb2)
+
+`FindNewerManyResultInfo` (delivered to `onFindNewerManyResult`) now
+carries three optional metrics captured passively during the sync
+round-trip — no extra round-trip needed, no overhead when callbacks
+are absent:
+
+- `requestBytes` — msgpack-encoded request body size (upload payload).
+- `responseBytes` — sum of wire bytes received across all streaming
+  chunks (download payload). Renamed from the short-lived
+  `bytesStreamed`.
+- `ttfbMs` — time-to-first-byte: elapsed from request send until
+  response headers arrive. Conflates `upload travel + server work +
+  first-byte travel` (would need a server-timing header to split
+  further).
+
+Combined with the existing `durationMs`, callers can derive download
+throughput and a server-vs-network breakdown without instrumenting the
+transport themselves:
+
+```typescript
+new SyncedDb({
+  onFindNewerManyResult: (info) => {
+    if (!info.success || info.responseBytes == null) return;
+    const downloadMs = info.durationMs - (info.ttfbMs ?? 0);
+    const kBps = downloadMs > 0 ? (info.responseBytes / downloadMs) : 0;
+    metrics.record({
+      req: info.requestBytes,
+      resp: info.responseBytes,
+      ttfb: info.ttfbMs,
+      total: info.durationMs,
+      kBps,
+    });
+  },
+});
+```
+
+Wired through the transport layer:
+
+- `I_RestInterface.findNewerManyStream` options gain three optional
+  byte/timing callbacks: `onRequestBytes(bytes)`,
+  `onTtfbMs(ms)`, `onResponseChunkBytes(bytes)`. All fire even on
+  failure paths where applicable. Old two-arg `onChunk` callbacks keep
+  working unchanged.
+- `RestProxy` fires `onRequestBytes` just before `fetch`, `onTtfbMs`
+  immediately after `await fetch(...)` resolves (separate `fetchStart`
+  marker, independent of `timeRequests`), and `onResponseChunkBytes`
+  per `reader.read()` chunk in `parseStreamingResponse`.
+- `SyncEngine.syncCore` accumulates bytes / captures TTFB and forwards
+  them into `callOnFindNewerManyResult` on both success and error
+  paths. Mocks and alternative transports that don't fire the
+  callbacks leave the fields `undefined` — graceful degradation.
+
+### RTT measurement: `measureWsRtt` + `measureEndToEndRtt` (ebus-proxy)
+
+Two diagnostic methods on `SyncedDb` (and `I_ServerUpdateNotifier`) to
+measure connection latency. Together they isolate where latency comes
+from:
+
+- **`measureWsRtt(timeoutMs?)`** — client → notifier server → client.
+  Sends a tagged WS ping (`{type: "ping", id: <unique>}`) and resolves
+  with `performance.now()` delta when the matching pong arrives. Pure
+  proxy responsiveness + network. Sub-ms on localhost.
+- **`measureEndToEndRtt(timeoutMs?)`** — client → proxy → broker →
+  `echo` worker → broker → proxy → client. HTTP GET to ebus-proxy's
+  `/?service=echo` endpoint with `Date.now()` msgpack payload; worker
+  returns it unchanged. ~3-15 ms on localhost.
+
+Both return RTT in milliseconds, both Promise-based (don't block thread).
+Multiple concurrent `measureWsRtt()` calls work — each uses a unique
+correlation id.
+
+Diagnostic interpretation:
+
+| WS RTT | E2E RTT | Likely cause |
+|---|---|---|
+| low | low | All good |
+| low | high | Broker / echo worker overloaded |
+| high | high (similar Δ) | Network or proxy slow |
+| spikes | stable | WS frame issue (tab throttle, frozen socket) |
+
+```typescript
+const wsRtt = await syncedDb.measureWsRtt();
+const e2eRtt = await syncedDb.measureEndToEndRtt();
+console.log(`network/proxy=${wsRtt.toFixed(1)}ms, full chain=${e2eRtt.toFixed(1)}ms`);
+```
+
+The notifier-interface methods are **optional** (`measureWsRtt?` /
+`measureEndToEndRtt?`) so custom `I_ServerUpdateNotifier`
+implementations don't need to implement them. `SyncedDb` pass-throughs
+throw a descriptive error if missing.
+
+Implementation in `Ebus2ProxyServerUpdateNotifier`: tagged ping reuses
+the existing WS handler (extends pong dispatch in `handleMessage`
+with a `_pendingRttPings` Map). HTTP echo derives the base URL from
+`wsUrl` (`ws://` → `http://`, `wss://` → `https://`), msgpack-encodes
+the payload, hits `/?service=echo`, validates byte-equal echo.
+
+Live test (localhost, warm, 20 samples): WS p50 0.30 ms, E2E p50
+4.11 ms. Mock-only unit tests in `test/measureRtt.test.ts` (7 cases —
+delegation, propagated rejection, no-notifier error, shape sanity).
+
 ### `save(coll, id, {field: {}})` clears existing nested children
 
 `computeDiffInto` for plain objects iterated only `Object.keys(update)`,

package/dist/index.js

@@ -3083,6 +3083,9 @@ var _SyncEngine = class _SyncEngine {
           source: isInitial ? "initial" : "incremental"
         });
       }
+      let requestBytes;
+      let responseBytes;
+      let ttfbMs;
       try {
         const completedCollections = /* @__PURE__ */ new Set();
         const allSpecs = extras && extras.specs.length > 0 ? [...syncSpecs, ...extras.specs] : syncSpecs;
@@ -3118,6 +3121,17 @@ var _SyncEngine = class _SyncEngine {
                   items: items.length
                 });
               }
+            },
+            {
+              onRequestBytes: (bytes) => {
+                requestBytes = bytes;
+              },
+              onTtfbMs: (ms) => {
+                ttfbMs = ms;
+              },
+              onResponseChunkBytes: (bytes) => {
+                responseBytes = (responseBytes != null ? responseBytes : 0) + bytes;
+              }
             }
           ),
           "findNewerManyStream"
@@ -3130,7 +3144,15 @@ var _SyncEngine = class _SyncEngine {
             sentCount: 0
           };
         }
-        this.callOnFindNewerManyResult(syncSpecs, {}, findNewerManyStartTime, true, calledFrom);
+        this.callOnFindNewerManyResult(
+          syncSpecs,
+          {},
+          findNewerManyStartTime,
+          true,
+          calledFrom,
+          void 0,
+          { requestBytes, responseBytes, ttfbMs }
+        );
         this.callbackSafe(this.callbacks.onServerSyncEnd, {
           calledFrom,
           collectionCount: syncSpecs.length,
@@ -3139,7 +3161,15 @@ var _SyncEngine = class _SyncEngine {
           success: true
         });
       } catch (err) {
-        this.callOnFindNewerManyResult(syncSpecs, {}, findNewerManyStartTime, false, calledFrom, err);
+        this.callOnFindNewerManyResult(
+          syncSpecs,
+          {},
+          findNewerManyStartTime,
+          false,
+          calledFrom,
+          err,
+          { requestBytes, responseBytes, ttfbMs }
+        );
         this.callbackSafe(this.callbacks.onServerSyncEnd, {
           calledFrom,
           collectionCount: syncSpecs.length,
@@ -3799,7 +3829,7 @@ var _SyncEngine = class _SyncEngine {
       }
     }
   }
-  callOnFindNewerManyResult(specs, results, startTime, success, calledFrom, error) {
+  callOnFindNewerManyResult(specs, results, startTime, success, calledFrom, error, metrics) {
     if (this.callbacks.onFindNewerManyResult) {
       try {
         this.callbacks.onFindNewerManyResult({
@@ -3808,7 +3838,10 @@ var _SyncEngine = class _SyncEngine {
           durationMs: Date.now() - startTime,
           success,
           error: error instanceof Error ? error : error ? new Error(String(error)) : void 0,
-          calledFrom
+          calledFrom,
+          requestBytes: metrics == null ? void 0 : metrics.requestBytes,
+          responseBytes: metrics == null ? void 0 : metrics.responseBytes,
+          ttfbMs: metrics == null ? void 0 : metrics.ttfbMs
         });
       } catch (err) {
         console.error("[SyncEngine] onFindNewerManyResult callback failed:", err);
@@ -4571,6 +4604,36 @@ var _SyncedDb = class _SyncedDb {
   followerSince() {
     return this.leaderElection.followerSince();
   }
+  /**
+   * WS round-trip time (client → notifier server → client). Delegates
+   * to `serverUpdateNotifier.measureWsRtt`. Throws if no notifier is
+   * configured or the notifier implementation doesn't support RTT.
+   */
+  async measureWsRtt(timeoutMs) {
+    var _a;
+    const fn = (_a = this.serverUpdateNotifier) == null ? void 0 : _a.measureWsRtt;
+    if (!fn) {
+      throw new Error(
+        "[SyncedDb] measureWsRtt: no serverUpdateNotifier or notifier does not support RTT"
+      );
+    }
+    return fn.call(this.serverUpdateNotifier, timeoutMs);
+  }
+  /**
+   * End-to-end RTT including downstream broker/worker hop. Delegates
+   * to `serverUpdateNotifier.measureEndToEndRtt`. Throws if no
+   * notifier is configured or the notifier doesn't support it.
+   */
+  async measureEndToEndRtt(timeoutMs) {
+    var _a;
+    const fn = (_a = this.serverUpdateNotifier) == null ? void 0 : _a.measureEndToEndRtt;
+    if (!fn) {
+      throw new Error(
+        "[SyncedDb] measureEndToEndRtt: no serverUpdateNotifier or notifier does not support end-to-end RTT"
+      );
+    }
+    return fn.call(this.serverUpdateNotifier, timeoutMs);
+  }
   /**
    * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
    */
@@ -9347,11 +9410,12 @@ var RestProxy = class {
    *   type=0x01 for data, type=0x00 for end-of-stream.
    */
   async findNewerManyStream(spec, onChunk, options) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const connectTimeout = (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : this.defaultTimeoutMs;
     const activityTimeout = (_b = options == null ? void 0 : options.activityTimeoutMs) != null ? _b : 3e4;
     const externalSignal = (_c = options == null ? void 0 : options.signal) != null ? _c : this.globalSignal;
     const startTime = this.timeRequests ? performance.now() : 0;
+    const fetchStart = performance.now();
     const data = {
       payload: {
         db: this.tenant,
@@ -9365,6 +9429,7 @@ var RestProxy = class {
       }
     };
     const body = pack2(data);
+    (_d = options == null ? void 0 : options.onRequestBytes) == null ? void 0 : _d.call(options, body.byteLength);
     const requestUrl = this.apiKey ? `${this.endpoint}?apikey=${this.apiKey}&stream=1` : `${this.endpoint}?stream=1`;
     const controller = new AbortController();
     let timeoutId = setTimeout(
@@ -9379,6 +9444,7 @@ var RestProxy = class {
         body,
         signal: combinedSignal
       });
+      (_e = options == null ? void 0 : options.onTtfbMs) == null ? void 0 : _e.call(options, performance.now() - fetchStart);
       clearTimeout(timeoutId);
       timeoutId = void 0;
       if (!response.ok) {
@@ -9390,7 +9456,12 @@ var RestProxy = class {
         timeoutId = setTimeout(() => controller.abort(), activityTimeout);
       };
       resetActivity();
-      await this.parseStreamingResponse(response, onChunk, resetActivity);
+      await this.parseStreamingResponse(
+        response,
+        onChunk,
+        resetActivity,
+        options == null ? void 0 : options.onResponseChunkBytes
+      );
       if (timeoutId !== void 0) clearTimeout(timeoutId);
       timeoutId = void 0;
       if (this.timeRequests) {
@@ -9428,7 +9499,7 @@ var RestProxy = class {
    *
    * `onChunk` receives `specId` as the third arg for type-0x02 frames; `undefined` otherwise.
    */
-  async parseStreamingResponse(response, onChunk, onActivity) {
+  async parseStreamingResponse(response, onChunk, onActivity, onChunkBytes) {
     const reader = response.body.getReader();
     const buffer = new StreamBuffer();
     const decoder2 = new TextDecoder();
@@ -9436,6 +9507,7 @@ var RestProxy = class {
       const { done, value } = await reader.read();
       if (done) return false;
       onActivity();
+      if (onChunkBytes) onChunkBytes(value.byteLength);
       buffer.append(value);
       return true;
     };
@@ -9570,6 +9642,13 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.reconnectAttempt = 0;
     this.forcedOffline = false;
     this.subscribedChannels = /* @__PURE__ */ new Set();
+    /**
+     * Pending RTT measurement promises keyed by ping id. Each entry is a
+     * resolver that the pong handler invokes once the matching pong
+     * arrives. Disconnect clears the map (caller's timeout fires soon
+     * after if any are still pending).
+     */
+    this._pendingRttPings = /* @__PURE__ */ new Map();
     var _a, _b, _c, _d, _e;
     this.endpoint = config.wsUrl;
     this.wsUrl = config.wsUrl;
@@ -9625,10 +9704,88 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.onWsConnectCallbacks.length = 0;
     this.onWsDisconnectCallbacks.length = 0;
     this.onWsReconnectCallbacks.length = 0;
+    this._pendingRttPings.clear();
   }
   isConnected() {
     return this.connected && !this.forcedOffline;
   }
+  /**
+   * WS round-trip time (client → proxy → client). Sends a tagged ping
+   * over the existing WebSocket and resolves with `performance.now()`
+   * delta when the matching pong arrives. Does NOT touch the cry-ebus2
+   * broker or any worker — measures pure proxy responsiveness +
+   * network latency.
+   *
+   * Throws if the WebSocket is not OPEN. The keepalive ping/pong
+   * watchdog is unaffected; multiple `measureWsRtt()` calls can be
+   * in flight simultaneously (each uses a unique correlation id).
+   *
+   * @param timeoutMs Max wait for matching pong (default: 5000)
+   * @returns RTT in milliseconds
+   */
+  async measureWsRtt(timeoutMs = 5e3) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("[Ebus2ProxyNotifier] measureWsRtt: WebSocket not OPEN");
+    }
+    const id = `rtt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const t0 = performance.now();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pendingRttPings.delete(id);
+        reject(new Error(`[Ebus2ProxyNotifier] measureWsRtt: timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this._pendingRttPings.set(id, () => {
+        clearTimeout(timer);
+        resolve(performance.now() - t0);
+      });
+      const pingMsg = { type: "ping", id };
+      this.ws.send(packr2.pack(preprocessForPack2(pingMsg)));
+    });
+  }
+  /**
+   * 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.
+   *
+   * The HTTP base URL is derived from `wsUrl` (`ws://` → `http://`,
+   * `wss://` → `https://`). Throws on HTTP error, payload mismatch,
+   * or timeout.
+   *
+   * @param timeoutMs Max wait for HTTP response (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);
+    if (echoed !== sentAt) {
+      throw new Error(
+        `[Ebus2ProxyNotifier] measureEndToEndRtt: payload mismatch (sent ${sentAt}, got ${JSON.stringify(echoed)})`
+      );
+    }
+    return performance.now() - t0;
+  }
   /**
    * Set connection lifecycle callbacks.
    * These are merged with any callbacks provided in the constructor config.
@@ -9775,6 +9932,13 @@ var Ebus2ProxyServerUpdateNotifier = class {
           break;
         case "pong":
           this.handlePong();
+          if (message.id !== void 0) {
+            const resolver = this._pendingRttPings.get(message.id);
+            if (resolver) {
+              this._pendingRttPings.delete(message.id);
+              resolver(message);
+            }
+          }
           break;
         case "error":
           console.error("[Ebus2ProxyNotifier] WebSocket server error:", message.error);

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

@@ -62,6 +62,13 @@ export declare class Ebus2ProxyServerUpdateNotifier implements I_ServerUpdateNot
     private pongTimer?;
     private forcedOffline;
     private subscribedChannels;
+    /**
+     * Pending RTT measurement promises keyed by ping id. Each entry is a
+     * resolver that the pong handler invokes once the matching pong
+     * arrives. Disconnect clears the map (caller's timeout fires soon
+     * after if any are still pending).
+     */
+    private _pendingRttPings;
     constructor(config: Ebus2ProxyServerUpdateNotifierConfig);
     subscribe(callback: ServerUpdateCallback): () => void;
     connect(): Promise<void>;
@@ -73,6 +80,36 @@ export declare class Ebus2ProxyServerUpdateNotifier implements I_ServerUpdateNot
      */
     dispose(): void;
     isConnected(): boolean;
+    /**
+     * WS round-trip time (client → proxy → client). Sends a tagged ping
+     * over the existing WebSocket and resolves with `performance.now()`
+     * delta when the matching pong arrives. Does NOT touch the cry-ebus2
+     * broker or any worker — measures pure proxy responsiveness +
+     * network latency.
+     *
+     * Throws if the WebSocket is not OPEN. The keepalive ping/pong
+     * watchdog is unaffected; multiple `measureWsRtt()` calls can be
+     * in flight simultaneously (each uses a unique correlation id).
+     *
+     * @param timeoutMs Max wait for matching pong (default: 5000)
+     * @returns RTT in milliseconds
+     */
+    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.
+     *
+     * The HTTP base URL is derived from `wsUrl` (`ws://` → `http://`,
+     * `wss://` → `https://`). Throws on HTTP error, payload mismatch,
+     * or timeout.
+     *
+     * @param timeoutMs Max wait for HTTP response (default: 5000)
+     * @returns RTT in milliseconds (full round-trip)
+     */
+    measureEndToEndRtt(timeoutMs?: number): Promise<number>;
     /**
      * Set connection lifecycle callbacks.
      * These are merged with any callbacks provided in the constructor config.

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

@@ -119,6 +119,9 @@ export declare class RestProxy implements I_RestInterface {
         timeoutMs?: number;
         signal?: AbortSignal;
         activityTimeoutMs?: number;
+        onRequestBytes?: (bytes: number) => void;
+        onTtfbMs?: (ms: number) => void;
+        onResponseChunkBytes?: (bytes: number) => void;
     }): Promise<void>;
     /**
      * Parse streaming response. Auto-detects format:

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

@@ -65,6 +65,18 @@ export declare class SyncedDb implements I_SyncedDb {
     isLeaderTab(): boolean;
     leaderSince(): Date | undefined;
     followerSince(): Date | undefined;
+    /**
+     * WS round-trip time (client → notifier server → client). Delegates
+     * to `serverUpdateNotifier.measureWsRtt`. Throws if no notifier is
+     * configured or the notifier implementation doesn't support RTT.
+     */
+    measureWsRtt(timeoutMs?: number): Promise<number>;
+    /**
+     * End-to-end RTT including downstream broker/worker hop. Delegates
+     * to `serverUpdateNotifier.measureEndToEndRtt`. Throws if no
+     * notifier is configured or the notifier doesn't support it.
+     */
+    measureEndToEndRtt(timeoutMs?: number): Promise<number>;
     /**
      * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
      */

package/dist/src/types/I_RestInterface.d.ts

@@ -106,10 +106,26 @@ export interface I_RestInterface {
      * Streaming variant of findNewerMany. Calls onChunk for each batch of items as they arrive.
      * `specId` is forwarded as the third arg when the originating spec set one — `undefined` otherwise.
      * Old two-arg `onChunk` callbacks keep working unchanged (the third arg is ignored).
+     *
+     * Optional metric callbacks (all fire even on failure paths where applicable):
+     * - `onRequestBytes(bytes)` — fires once just before fetch with the
+     *   msgpack-encoded request body's byte length.
+     * - `onTtfbMs(ms)` — fires once when response headers are received,
+     *   with elapsed time since the fetch started. TTFB conflates
+     *   upload + server processing + first-byte travel — server-side
+     *   timing header (if available) is required to split further.
+     * - `onResponseChunkBytes(bytes)` — fires per response chunk read
+     *   with that chunk's byte length (summed = total response bytes).
+     *
+     * Combined, callers can compute upload/download throughput AND
+     * server-vs-network breakdown without extra round-trips.
      */
     findNewerManyStream<T>(spec: GetNewerSpec<T>[], onChunk: (collection: string, items: T[], specId?: string) => Promise<void>, options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
+        onRequestBytes?: (bytes: number) => void;
+        onTtfbMs?: (ms: number) => void;
+        onResponseChunkBytes?: (bytes: number) => void;
     }): Promise<void>;
     deleteOne<T>(collection: string, query: QuerySpec<T>): Promise<T>;
     /** Izvede agregacijo na serverju */

package/dist/src/types/I_ServerUpdateNotifier.d.ts

@@ -54,4 +54,33 @@ export interface I_ServerUpdateNotifier {
      * Optional method.
      */
     dispose?(): void;
+    /**
+     * Measure round-trip time over the existing transport (e.g. WebSocket
+     * ping/pong). Returns RTT in milliseconds. Does NOT involve any
+     * downstream broker or worker — measures the client ↔ notifier
+     * server hop only.
+     *
+     * Useful for diagnosing connection quality. Compare with
+     * `measureEndToEndRtt` to isolate broker/worker overhead.
+     *
+     * Optional. Throws if transport is not connected or doesn't support
+     * RTT measurement.
+     *
+     * @param timeoutMs Max wait for response (default: 5000)
+     */
+    measureWsRtt?(timeoutMs?: number): Promise<number>;
+    /**
+     * Measure full round-trip time including any downstream broker /
+     * worker hop (e.g. ebus-proxy → cry-ebus2 broker → echo worker →
+     * back). Returns RTT in milliseconds.
+     *
+     * Implementation typically invokes a server-side `echo` service that
+     * returns the payload unchanged, so the measurement is end-to-end.
+     *
+     * Optional. Throws if not supported or if the round-trip fails
+     * (e.g. timeout, payload mismatch, transport error).
+     *
+     * @param timeoutMs Max wait for response (default: 5000)
+     */
+    measureEndToEndRtt?(timeoutMs?: number): Promise<number>;
 }

package/dist/src/types/I_SyncedDb.d.ts

@@ -189,6 +189,27 @@ export interface FindNewerManyResultInfo {
     error?: Error;
     /** Where sync was called from (for debugging) */
     calledFrom?: string;
+    /**
+     * Msgpack-encoded request body size in bytes (upload payload).
+     * Undefined when the transport implementation didn't report it.
+     */
+    requestBytes?: number;
+    /**
+     * Sum of wire bytes received across all streaming chunks (download
+     * payload). For passive download-speed measurement compute
+     * `responseBytes / (durationMs - ttfbMs) * 1000` for bytes/sec
+     * (excludes server processing time).
+     * Undefined when the transport didn't report per-chunk byte counts.
+     */
+    responseBytes?: number;
+    /**
+     * Time-to-first-byte in ms — elapsed from request send until response
+     * headers are received. Conflates upload travel + server processing +
+     * first-byte travel. Together with `responseBytes` and `durationMs`
+     * enables passive throughput + server-vs-network breakdown estimates.
+     * Undefined when the transport didn't report it.
+     */
+    ttfbMs?: number;
 }
 /**
  * Callback payload for Dexie write requests (before writing)
@@ -1070,6 +1091,33 @@ export interface I_SyncedDb {
      * @returns Date of follower transition, or undefined if currently the leader
      */
     followerSince(): Date | undefined;
+    /**
+     * Measure WS round-trip time: client → notifier server → client.
+     * Pure proxy / network latency, without any downstream broker or
+     * worker hop. Pairs with `measureEndToEndRtt` for diagnostics:
+     * a low WS RTT + high end-to-end RTT points at the broker/worker
+     * as the bottleneck; a high WS RTT points at the network or proxy.
+     *
+     * Throws when no `serverUpdateNotifier` is configured or the
+     * notifier implementation does not support RTT measurement.
+     *
+     * @param timeoutMs Max wait for response (default: 5000)
+     * @returns RTT in milliseconds
+     */
+    measureWsRtt(timeoutMs?: number): Promise<number>;
+    /**
+     * Measure end-to-end RTT including the downstream broker/worker
+     * hop (e.g. ebus-proxy → cry-ebus2 broker → echo worker → back).
+     * The implementation typically calls a server-side `echo` service
+     * that returns the payload unchanged.
+     *
+     * Throws when no `serverUpdateNotifier` is configured or the
+     * notifier implementation does not support end-to-end RTT.
+     *
+     * @param timeoutMs Max wait for response (default: 5000)
+     * @returns RTT in milliseconds (full round-trip)
+     */
+    measureEndToEndRtt(timeoutMs?: number): Promise<number>;
     /**
      * Get metadata for a single object.
      * @param collection Collection name

package/package.json

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