@procedures/store 0.26.1 → 0.27.0

package/src/storage/hybrid.ts

@@ -41,6 +41,8 @@
  * - The syncs of one storage run one at a time, in their order: the deltas and the hints of the
  *   feed, the pulls, the pushes, the reads after an own write, and the mode switches. Thus a
  *   remote delta and a full sync never run at the same time (Graph R18).
+ * - `aroundRemoteApply` runs each apply of the remote changes inside a hook, for example inside a
+ *   span of a trace (graph W8).
  */
 
 import type {
@@ -276,6 +278,27 @@ export interface HybridStorageOptions {
    */
   feed?: RemoteChangeFeed<any>;
 
+  /**
+   * The hook around each apply of the remote changes (graph W8), for example a span of a trace.
+   * `RemoteApplyHook` gives the arguments.
+   *
+   * - The hook wraps the apply of each delta of the feed, each hint of the feed that applies, and
+   *   each pull that the feed or a pull of the storage causes.
+   * - A pull of the storage is the timer of `pullInterval`, `syncFromRemote()`, `sync()` and the
+   *   first sync. The hint of a pull is undefined.
+   * - A pull that many hints asked for runs one time. Its hint is the last hint, and
+   *   `context.hints` has the last 128 of them.
+   * - The hook runs inside the chain of the syncs, so it measures the apply, not the wait.
+   * - The sync of a mode switch, the reads of the remote and the new reads of the values that an
+   *   own write deferred are not in the hook.
+   * - An error of `apply` or of the hook makes the pull fail, and the status keeps it. The next
+   *   pull that succeeds clears it.
+   * - Only the leader of a `TabCoordinator` or of a `TabGroup` makes a `HybridStorage`, so only
+   *   the leader runs the hook.
+   * - Without the hook, the applies run as before, with the same timing and no other allocation.
+   */
+  aroundRemoteApply?: RemoteApplyHook | undefined;
+
   /**
    * The store of the sync state: the cursor and the base versions (roadmap CLI-21). A new storage
    * with the same store asks the remote only for the changes since the cursor, and it finds the
@@ -339,6 +362,72 @@ export interface HybridStorageOptions {
   queryPolicy?: StorageQueryPolicy;
 }
 
+/**
+ * The cause of an apply of the remote changes (graph W8).
+ *
+ * - `"delta"`: a delta of the feed.
+ * - `"hint"`: one or more hints of the feed.
+ * - `"gap"`: a gap of the feed: a lost event, an event of another form, or a new subscription.
+ * - `"pull"`: a pull of the storage: the timer, `syncFromRemote()`, `sync()` or the first sync.
+ */
+export type RemoteApplyCause = "delta" | "hint" | "gap" | "pull";
+
+/** The context of an apply of the remote changes, the third argument of `aroundRemoteApply` (graph W8). */
+export interface RemoteApplyContext {
+  /** The cause of the apply. A pull that hints and gaps asked for has the cause `"hint"`. */
+  readonly cause: RemoteApplyCause;
+  /**
+   * The hints of the apply, in their order of arrival. A delta gives one hint with its ids and no
+   * values. A gap and a pull of the storage give no hint. A pull keeps the last 128 hints.
+   */
+  readonly hints: readonly RemoteChangeHint[];
+}
+
+/**
+ * The hook around an apply of the remote changes (graph W8). The hook calls `apply` one time and
+ * gives its promise back, for example from inside a span of a trace.
+ *
+ * - The storage waits for the hook and for the apply. A hook that does not settle stops the syncs.
+ * - The changes apply one time. A second call of `apply` gets the promise of the first call.
+ * - When the hook does not call `apply`, the storage applies the changes after the hook. Thus a
+ *   hook that fails does not stop the sync.
+ * - The sync fails with the error of `apply` first. A hook cannot hide or change it.
+ * - Then the sync fails with the error of the hook, and then with `RemoteApplyHookError` when the
+ *   hook did not call `apply` one time.
+ * - The status of the storage keeps the error of the sync, with the operation `"pull"`.
+ *
+ * @param hint - The last hint of `context.hints`, or undefined when the apply has no hint
+ * @param apply - The function that reads the changes and applies them to the local copy
+ * @param context - The cause of the apply and its hints
+ *
+ * @example
+ * ```typescript
+ * aroundRemoteApply: (hint, apply) => {
+ *   const traceparent = hint?.extra?.["traceparent"];
+ *   return runInRemoteTrace(typeof traceparent === "string" ? traceparent : undefined, apply, { name: "realtime.echo" });
+ * },
+ * ```
+ */
+export type RemoteApplyHook = (hint: RemoteChangeHint | undefined, apply: () => Promise<void>, context: RemoteApplyContext) => Promise<unknown>;
+
+/** The hints of an apply without hints. */
+const NO_HINTS: readonly RemoteChangeHint[] = Object.freeze([]);
+
+/** The most hints that a pull keeps for the hook. A pull drops the older ones. */
+const MAX_JOINED_HINTS = 128;
+
+/** The hint of a delta of the feed: its versions, its ids, its origin and its other fields, without the values (graph W8). */
+function hintOfDelta<T>(changes: RemoteChanges<T>): RemoteChangeHint {
+  return {
+    ...(changes.since !== undefined && { since: changes.since }),
+    ...(changes.version !== undefined && { version: changes.version }),
+    changed: changes.changed.map(([id]) => id),
+    deleted: [...changes.deleted],
+    ...(changes.origin !== undefined && { origin: changes.origin }),
+    ...(changes.extra !== undefined && { extra: changes.extra }),
+  };
+}
+
 /** The kinds of the timers of a `HybridStorage`. */
 interface TimerOptions {
   readonly clock: Clock;
@@ -522,6 +611,19 @@ export class SyncStateError extends Error {
   }
 }
 
+/**
+ * The hook `aroundRemoteApply` did not call `apply` one time (graph W8). The storage applied the
+ * changes one time all the same, and the apply succeeded. `calls` is the number of calls of
+ * `apply` before the hook settled.
+ */
+export class RemoteApplyHookError extends Error {
+  override readonly name = "RemoteApplyHookError";
+  readonly code = "REMOTE_APPLY_HOOK";
+  constructor(readonly calls: number) {
+    super(`The hook aroundRemoteApply called apply ${calls} times, not 1 time: the storage applied the changes 1 time`);
+  }
+}
+
 const defaultIsUnavailable = (error: unknown): boolean => {
   if (typeof error !== "object" || error === null) return true;
   const { retryable, code } = error as { retryable?: unknown; code?: unknown };
@@ -864,6 +966,10 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   private readonly feed: RemoteChangeFeed<T> | undefined;
   private feedStop: (() => void) | undefined;
   private feedToken = 0;
+  /** The hook around each apply of the remote changes (graph W8) */
+  private readonly aroundRemoteApply: RemoteApplyHook | undefined;
+  /** With the hook: the hints that asked for the pull that waits */
+  private readonly joinedHints: RemoteChangeHint[] = [];
   /** True while a pull that a gap asked for waits to start */
   private gapPull = false;
   /** The stop of the capture of the local copy */
@@ -931,6 +1037,10 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     this.syncOrigin = options.syncOrigin ?? "sync";
     this.observers = new StorageListeners<StorageChangeBatch<T>>(options.onListenerError);
     this.feed = options.feed;
+    if (options.aroundRemoteApply !== undefined && typeof options.aroundRemoteApply !== "function") {
+      throw new TypeError("aroundRemoteApply must be a function");
+    }
+    this.aroundRemoteApply = options.aroundRemoteApply;
     this.stateStore = options.syncState;
     this.bases.tracked = this.stateStore !== undefined;
     this.localGiven = options.local !== undefined;
@@ -1220,7 +1330,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
           if (live()) this.onRemoteHint(hint);
         },
         onGap: () => {
-          if (live()) this.requestPull();
+          if (live()) this.requestPull(undefined);
         },
         onError: (error) => {
           if (live()) this.fail("pull", error);
@@ -1255,11 +1365,16 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     if (this.loadError) throw this.loadError;
     if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back")) return;
     if (changes.version === this.cursor) return;
-    if (changes.since === undefined || changes.since !== this.cursor) {
+    const follows = changes.since !== undefined && changes.since === this.cursor;
+    const hook = this.aroundRemoteApply;
+    if (hook) {
+      const apply = follows ? () => this.applyChanges(changes, (id) => this.changedSince(mark, id)) : () => this.pullRemote(false);
+      await this.hookedApply(hook, "delta", [hintOfDelta(changes)], apply);
+    } else if (follows) {
+      await this.applyChanges(changes, (id) => this.changedSince(mark, id));
+    } else {
       await this.pullRemote(false);
-      return;
     }
-    await this.applyChanges(changes, (id) => this.changedSince(mark, id));
   }
 
   /**
@@ -1285,30 +1400,88 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back")) return;
     if (hint.version !== undefined && hint.version === this.cursor) return;
     if (hint.since !== undefined && hint.since === this.cursor && hint.version !== undefined && hint.changed.length === 0) {
-      await this.applyChanges({ version: hint.version, full: false, changed: [], deleted: [...hint.deleted] }, (id) => this.changedSince(mark, id));
+      const version = hint.version;
+      const hook = this.aroundRemoteApply;
+      if (hook) await this.hookedApply(hook, "hint", [hint], () => this.applyDeletes(version, hint.deleted, mark));
+      else await this.applyDeletes(version, hint.deleted, mark);
       return;
     }
-    this.requestPull();
+    this.requestPull(hint);
   }
 
-  /** This method asks for a pull after the syncs that run. A request while a pull waits joins it. */
-  private requestPull(): void {
+  /** This method applies the deletes of a hint whose `since` is the cursor and that changed no value. */
+  private applyDeletes(version: string, deleted: readonly string[], mark: number): Promise<void> {
+    return this.applyChanges({ version, full: false, changed: [], deleted: [...deleted] }, (id) => this.changedSince(mark, id));
+  }
+
+  /**
+   * This method asks for a pull after the syncs that run. A request while a pull waits joins it.
+   * With `aroundRemoteApply`, the pull keeps the last hints of the requests for the hook.
+   */
+  private requestPull(hint: RemoteChangeHint | undefined): void {
+    if (hint !== undefined && this.aroundRemoteApply) {
+      this.joinedHints.push(hint);
+      if (this.joinedHints.length > MAX_JOINED_HINTS) this.joinedHints.shift();
+    }
     if (this.gapPull) return;
     this.gapPull = true;
     void this.loaded
       .then(() =>
         this.serialize(() => {
           this.gapPull = false;
+          const hints = this.joinedHints.length > 0 ? this.joinedHints.splice(0) : NO_HINTS;
           if (this.closed) return Promise.resolve();
           return this.track("pull", async () => {
             if (this.loadError) throw this.loadError;
-            if (this.mode === "write-through" || this.mode === "write-back") await this.pullRemote(false);
+            if (this.mode === "write-through" || this.mode === "write-back") await this.pullThrough(hints.length > 0 ? "hint" : "gap", hints);
           });
         }),
       )
       .catch(() => undefined);
   }
 
+  /**
+   * This method pulls the changes since the cursor, through the hook `aroundRemoteApply` when the
+   * options give it (graph W8). Without the hook, it is `pullRemote(false)`, with no other step.
+   */
+  private pullThrough(cause: RemoteApplyCause, hints: readonly RemoteChangeHint[]): Promise<void> {
+    const hook = this.aroundRemoteApply;
+    return hook ? this.hookedApply(hook, cause, hints, () => this.pullRemote(false)) : this.pullRemote(false);
+  }
+
+  /**
+   * This method runs an apply of the remote changes through the hook (graph W8).
+   *
+   * - The apply runs one time. A second call of `apply` gets the promise of the first call.
+   * - When the hook does not call `apply`, the apply runs after the hook. Thus no change is lost.
+   * - The error of the apply comes first, then the error of the hook, then the misuse of the hook.
+   */
+  private async hookedApply(hook: RemoteApplyHook, cause: RemoteApplyCause, hints: readonly RemoteChangeHint[], apply: () => Promise<void>): Promise<void> {
+    let run: Promise<void> | undefined;
+    let calls = 0;
+    const once = (): Promise<void> => {
+      calls++;
+      if (run === undefined) {
+        run = apply();
+        // The method reads the result after the hook: this handler only stops a report of an unhandled rejection
+        run.catch(() => undefined);
+      }
+      return run;
+    };
+    let failure: { readonly error: unknown } | undefined;
+    try {
+      await hook(hints.at(-1), once, { cause, hints });
+    } catch (error) {
+      failure = { error };
+    }
+    // The count of the hook. A call of apply after the hook settled gets the promise of the first call.
+    const called = calls;
+    // A hook that did not call apply: the storage applies the changes itself
+    await (run ?? once());
+    if (failure) throw failure.error;
+    if (called !== 1) throw new RemoteApplyHookError(called);
+  }
+
   //
   // ═══ The sync state (roadmap CLI-21) ═══
   //
@@ -2021,7 +2194,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       this.track("pull", async () => {
         await this.loaded;
         if (this.loadError) throw this.loadError;
-        if (this.mode === "write-through" || this.mode === "write-back") await this.pullRemote(false);
+        if (this.mode === "write-through" || this.mode === "write-back") await this.pullThrough("pull", NO_HINTS);
       }),
     );
   }

package/src/storage/index.ts

@@ -46,8 +46,16 @@ export {
   ConflictError,
   ModeSwitchError,
   SyncStateError,
+  RemoteApplyHookError,
+} from "./hybrid.js";
+export type {
+  HybridStorageOptions,
+  HybridMode,
+  LocalCopyStorage,
+  RemoteApplyCause,
+  RemoteApplyContext,
+  RemoteApplyHook,
 } from "./hybrid.js";
-export type { HybridStorageOptions, HybridMode, LocalCopyStorage } from "./hybrid.js";
 // One leader tab runs the sync, and the other tabs copy its changes (roadmap CLI-25)
 export { TabCoordinator, TabGroup } from "./tab-coordinator.js";
 export type {