cry-synced-db-client 0.1.174 → 0.1.176

package/CHANGELOG.md

@@ -2,6 +2,180 @@
 
 ## 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)`,
+so an update like `{cepljenja: {}}` against an existing
+`{cepljenja: {<id>: {…}}}` emitted **zero diff entries** — children were
+preserved silently. Empty-object value is now treated as a full replace
+of the field (symmetric with `{field: []}` array replace and
+`{field: undefined}` delete).
+
+```typescript
+// existing.cepljenja = { "<id>": { …data } }
+await syncedDb.save("pacienti", id, { cepljenja: {} });
+// after: pacient.cepljenja === {} — children physically removed in
+// in-mem, Dexie, and the dirty payload
+```
+
+Implementation in `src/utils/computeDiff.ts:computeDiffInto`: when both
+sides are plain objects and `update` has zero keys while `existing` has
+some, emit `diff[basePath] = {}` instead of falling through to the
+"iterate update keys" loop. The earlier `deepEquals(existing, update)`
+guard still short-circuits the `{} → {}` no-op case.
+
+Regression test: `test/saveEmptyObjectClearsChildren.test.ts` (4 cases:
+in-mem clear, Dexie clear, dirty payload emits wipe, sibling fields
+preserved). 721 pass / 0 fail.
+
+### `findById` / `findByIds` auto-register unconfigured collections as temporary
+
+Calling `findById(collection, id)` or `findByIds(collection, ids)` for a
+collection NOT in the runtime sync config (e.g. boot-time `collections: [...]`)
+no longer throws. Instead the collection is auto-registered as
+**temporary** with `syncConfig.query: () => ({_id: {$in: [<ids>]}})`. The
+call then proceeds through the normal flow — `referToServer` (default
+`true`) loads the row from the server on cache miss and returns it.
+
+Behavior on subsequent calls (inspected against the existing config's
+`syncConfig.query` shape, no extra bookkeeping state):
+
+| Existing config | Action |
+|---|---|
+| none | install `{_id: {$in: [<ids>]}}` (static object) |
+| temporary, query matches `{_id: {$in: [...]}}` | append novel ids to the existing `$in` array |
+| temporary, query is a function / different shape / absent | skip — leave alone |
+| permanent | skip — never touch a permanent config |
+
+`replaceSyncCollection` naturally resets accumulation by overwriting the
+spec; the new config (whatever shape) drives future syncs alone.
+
+Constraints:
+- Dexie schema must already declare the table (Dexie does not support
+  adding tables to an open database). The auto-register handles only the
+  runtime SyncedDb-level config.
+- An active `syncOnlyTheseCollections` filter (non-null — set via
+  `setSyncOnlyTheseCollections([…])` with at least one entry) is extended
+  to include the new temp collection so it participates in future sync
+  ticks. When no filter is set (sync-all mode), this step is a no-op.
+
+```typescript
+// No runtime config for "zivali" — boot only registers "racuni".
+new SyncedDb({ collections: [{ name: "racuni" }], dexieDb /* has zivali */, ... });
+
+// Previously: throws "Collection 'zivali' not configured".
+// Now: auto-registers as temporary, fetches via referToServer, returns.
+const zival = await syncedDb.findById("zivali", id);
+
+// Upgrade to permanent when the app wires up real sync:
+await syncedDb.replaceSyncCollection({
+  name: "zivali",
+  syncConfig: { query: () => ({ vrsta: "pes" }) },
+});
+```
+
 ### `preprocessDirtyItem` callback — per-item filter / transform before upload
 
 New optional config callback fired for **every** dirty item just before it

package/dist/index.js

@@ -440,6 +440,10 @@ function computeDiffInto(existing, update, basePath, diff) {
     diff[basePath] = update;
     return;
   }
+  if (Object.keys(update).length === 0 && Object.keys(existing).length > 0) {
+    diff[basePath] = update;
+    return;
+  }
   for (const key of Object.keys(update)) {
     const childPath = basePath ? `${basePath}.${key}` : key;
     computeDiffInto(existing[key], update[key], childPath, diff);
@@ -3079,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;
@@ -3114,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"
@@ -3126,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,
@@ -3135,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,
@@ -3795,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({
@@ -3804,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);
@@ -4567,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`.
    */
@@ -4871,6 +4938,7 @@ var _SyncedDb = class _SyncedDb {
   // ==================== Read Operations ====================
   async findById(collection, id, opts) {
     var _a;
+    this._autoRegisterTemporaryForFind(collection, [id]);
     this.assertCollection(collection);
     if (!id) {
       const err = new Error(`[SyncedDb] findById ${collection} no id ${id}`);
@@ -4928,6 +4996,7 @@ var _SyncedDb = class _SyncedDb {
   }
   async findByIds(collection, ids, opts) {
     var _a;
+    this._autoRegisterTemporaryForFind(collection, ids);
     this.assertCollection(collection);
     ids = ids.map((id) => this.normalizeId(id, "findByIds", collection));
     opts = this.resolveOpts(opts);
@@ -6331,6 +6400,68 @@ var _SyncedDb = class _SyncedDb {
       throw new Error(`SyncedDb: Collection "${(name == null ? void 0 : name.toString()) || "?"}" not configured`);
     }
   }
+  /**
+   * Auto-register an unconfigured collection as TEMPORARY when `findById` /
+   * `findByIds` is called for it. The collection becomes part of the sync
+   * scope with a `{_id: {$in: <ids>}}` static query so future sync ticks
+   * keep those rows fresh.
+   *
+   * Behavior matrix:
+   *
+   * | Existing config | Action |
+   * |---|---|
+   * | none | install temp with `query: {_id: {$in: [<ids>]}}` |
+   * | temporary, query is `{_id: {$in: [...]}}` | append novel `<ids>` to the existing `$in` array |
+   * | temporary, query is anything else (function, different shape, missing) | skip — leave config untouched |
+   * | permanent | skip — never alter a permanent config |
+   *
+   * No extra state map — accumulation lives in the config's own `$in`
+   * array. `replaceSyncCollection` (or any other path that installs a new
+   * config) naturally resets accumulation by overwriting the config.
+   *
+   * Cheap fast paths: synchronous, no Dexie/server I/O. The regular
+   * `findById` flow (in-mem cache → `referToServer` → `ensureItemsAreLoaded`)
+   * handles the actual data load for THIS call.
+   *
+   * If an `syncOnlyTheseCollections` filter is active (non-null, i.e.
+   * `setSyncOnlyTheseCollections([…])` was called with at least one
+   * entry), a newly-installed temp collection is added to the filter so
+   * it participates in future sync ticks. When no filter is set
+   * (sync-all mode), this step is a no-op.
+   */
+  _autoRegisterTemporaryForFind(name, ids) {
+    var _a;
+    const idStrings = ids.map((id) => String(id));
+    const existing = this.collections.get(name);
+    if (!existing) {
+      this.collections.set(name, {
+        name,
+        temporaryConfig: true,
+        syncConfig: {
+          query: { _id: { $in: idStrings } }
+        }
+      });
+      if (this.syncOnlyCollections) {
+        this.syncOnlyCollections.add(name);
+      }
+      return;
+    }
+    if (!existing.temporaryConfig) return;
+    const query = (_a = existing.syncConfig) == null ? void 0 : _a.query;
+    if (typeof query !== "object" || query === null) return;
+    const idField = query._id;
+    if (typeof idField !== "object" || idField === null) return;
+    const inArr = idField.$in;
+    if (!Array.isArray(inArr)) return;
+    const seen = /* @__PURE__ */ new Set();
+    for (const existingId of inArr) seen.add(String(existingId));
+    for (const id of idStrings) {
+      if (!seen.has(id)) {
+        inArr.push(id);
+        seen.add(id);
+      }
+    }
+  }
   /** Stringify an Id parameter (ObjectId → hex string). */
   normalizeId(id, method, collection) {
     if (!id && id !== void 0) {
@@ -9279,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,
@@ -9297,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(
@@ -9311,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) {
@@ -9322,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) {
@@ -9360,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();
@@ -9368,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;
     };
@@ -9502,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;
@@ -9557,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.
@@ -9707,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`.
      */
@@ -426,6 +438,36 @@ export declare class SyncedDb implements I_SyncedDb {
      */
     private preloadAllSyncMetas;
     private assertCollection;
+    /**
+     * Auto-register an unconfigured collection as TEMPORARY when `findById` /
+     * `findByIds` is called for it. The collection becomes part of the sync
+     * scope with a `{_id: {$in: <ids>}}` static query so future sync ticks
+     * keep those rows fresh.
+     *
+     * Behavior matrix:
+     *
+     * | Existing config | Action |
+     * |---|---|
+     * | none | install temp with `query: {_id: {$in: [<ids>]}}` |
+     * | temporary, query is `{_id: {$in: [...]}}` | append novel `<ids>` to the existing `$in` array |
+     * | temporary, query is anything else (function, different shape, missing) | skip — leave config untouched |
+     * | permanent | skip — never alter a permanent config |
+     *
+     * No extra state map — accumulation lives in the config's own `$in`
+     * array. `replaceSyncCollection` (or any other path that installs a new
+     * config) naturally resets accumulation by overwriting the config.
+     *
+     * Cheap fast paths: synchronous, no Dexie/server I/O. The regular
+     * `findById` flow (in-mem cache → `referToServer` → `ensureItemsAreLoaded`)
+     * handles the actual data load for THIS call.
+     *
+     * If an `syncOnlyTheseCollections` filter is active (non-null, i.e.
+     * `setSyncOnlyTheseCollections([…])` was called with at least one
+     * entry), a newly-installed temp collection is added to the filter so
+     * it participates in future sync ticks. When no filter is set
+     * (sync-all mode), this step is a no-op.
+     */
+    private _autoRegisterTemporaryForFind;
     private static readonly STRINGIFIED_FALSY;
     /** Stringify an Id parameter (ObjectId → hex string). */
     private normalizeId;

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)
@@ -864,6 +885,13 @@ export interface I_SyncedDb {
      *   jih v ozadju revalidira s serverja (Dexie + in-mem skozi konflikt
      *   resolucijo). Ortogonalno do referToServer; ne povzroči duplikata
      *   server klicev za missing ID-je.
+     *
+     * Auto-registracija: če `collection` ni registrirana v runtime sync
+     * configu, se avtomatsko doda kot **temporary** s queryjem
+     * `{_id: {$in: [<id>]}}`. Dexie schema mora že imeti tabelo
+     * (Dexie ne podpira dodajanja tabel ob runtime-u). Klic nato teče
+     * skozi normalen findById flow — `referToServer` (privzeto `true`)
+     * naloži zapis s serverja ob cache miss-u.
      */
     findById<T extends DbEntity>(collection: string, id: Id, opts?: QueryOpts): Promise<T | null>;
     /**
@@ -873,6 +901,11 @@ export interface I_SyncedDb {
      *   jih v ozadju revalidira s serverja (Dexie + in-mem skozi konflikt
      *   resolucijo). Ortogonalno do referToServer; ne povzroči duplikata
      *   server klicev za missing ID-je.
+     *
+     * Auto-registracija: enako kot `findById` — če `collection` ni v
+     * runtime sync configu, se doda kot temporary s queryjem
+     * `{_id: {$in: [<ids>]}}` (vsi ID-ji iz klica). Dexie schema mora že
+     * imeti tabelo.
      */
     findByIds<T extends DbEntity>(collection: string, ids: Id[], opts?: QueryOpts): Promise<T[]>;
     /**
@@ -1058,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.174",
+  "version": "0.1.176",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",