@procedures/mongo 0.52.2 → 0.53.1

package/src/storage/storage-hints.ts

@@ -68,6 +68,7 @@
  * - Change streams need a replica set or a sharded cluster. The watcher asks the server (`hello`)
  *   before the first open: on a single server, `ready` rejects (code 40573).
  */
+import { backoffDelay, type Backoff } from "@mark1russell7/service/backoff";
 import { MongoAPIError, MongoParseError, BSON, type ChangeStream, type Db, type Document } from "mongodb";
 import {
   collectionChangeTopic,
@@ -94,6 +95,7 @@ import {
 } from "./document-storage.js";
 import { SAME_TOKEN_LIMIT, SPLIT_LARGE_EVENT_STAGE, UNKNOWN_STAGE_CODE, eventJoiner, sameTokenFaults } from "./split-events.js";
 import { trackOwnNumbers, type OwnNumbers } from "./own-writes.js";
+import { tokenAge } from "./token-age.js";
 
 /** The change of one item of a change event of a `MongoDocumentStorage` collection, from `storageChangeOf()`. */
 export interface StorageChange {
@@ -230,6 +232,11 @@ export interface StorageChangesWatch {
    * opens the stream again after the other errors.
    */
   readonly ready: Promise<void>;
+  /**
+   * The milliseconds of the clock since the resume token of the stream last moved to a later cluster time, or since the start
+   * before the first move. The same cluster time again does not move it. A large value on an open watcher tells a stalled feed (roadmap CLI-110).
+   */
+  readonly tokenAgeMs: number;
   /** This method stops the watcher: it closes the stream and cancels the timer of a backoff. */
   stop(): Promise<void>;
 }
@@ -374,7 +381,10 @@ export function storageChangeOf(change: Document, form: StoredForm = DEFAULT_STO
   return { id, partition, deleted: false, raw: false, version, seq: written };
 }
 
-/** The delay before try `attempt` (0 for the first) of a backoff. */
+/**
+ * The delay before try `attempt` (0 for the first) of a backoff. The `backoffDelay` function of
+ * `@mark1russell7/service` gives it: its first try is 1.
+ */
 export function backoffOf(options: ResubscribeBackoff | undefined): (attempt: number) => number {
   const initial = optionalMs(options?.initialDelay, "backoff.initialDelay") ?? 250;
   const max = optionalMs(options?.maxDelay, "backoff.maxDelay") ?? 30_000;
@@ -383,10 +393,8 @@ export function backoffOf(options: ResubscribeBackoff | undefined): (attempt: nu
   if (!(initial >= 0) || !(max >= initial)) throw new RangeError("backoff: initialDelay must be 0 or more, and maxDelay must be initialDelay or more");
   if (!(factor >= 1)) throw new RangeError("backoff: backoffMultiplier must be 1 or more");
   if (!(jitter >= 0 && jitter <= 1)) throw new RangeError("backoff: jitter must be from 0 to 1");
-  return (attempt) => {
-    const full = Math.min(max, initial * factor ** attempt);
-    return full - full * jitter * Math.random();
-  };
+  const policy: Backoff = { base: initial, factor, cap: max, jitter: { kind: "subtract", fraction: jitter } };
+  return (attempt) => backoffDelay(policy, attempt + 1);
 }
 
 /** The message of an error. */
@@ -491,6 +499,12 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
   let stopped = false;
   let stream: ChangeStream | undefined;
   let token: unknown;
+  const age = tokenAge(clock);
+  /** This function sets the token of the watcher, and notes it for `tokenAgeMs`. */
+  const setToken = (next: unknown): void => {
+    token = next;
+    age.note(next);
+  };
   /** True after a stream was open: a new stream without a token can then miss changes. */
   let opened = false;
   let attempt = 0;
@@ -836,7 +850,7 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
   };
 
   const onChange = (change: Document): void => {
-    token = change["_id"];
+    setToken(change["_id"]);
     attempt = 0;
     faults.reset();
     const type = change["operationType"];
@@ -940,6 +954,8 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
     }
     stream = next;
     const joiner = eventJoiner();
+    /** The token before the document of the last token: the token before the event at fragment 1. */
+    let tokenBefore: unknown = token;
     /** The token at the open: a reopen at the same token is no success, so the backoff does not start again. */
     const openToken = JSON.stringify(token ?? null);
     let ended = false;
@@ -975,7 +991,11 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
     next.on("resumeTokenChanged", (resumeToken: unknown) => {
       if (resumeToken === undefined || resumeToken === null) return;
       // In the middle of a split event, the token stays before the event: a stream that opens again gets all its fragments
-      if (!joiner.partial) token = resumeToken;
+      if (!joiner.partial) {
+        // The driver gives the token of a document before its change: fragment 1 puts the token back (audit 2026-11-08)
+        tokenBefore = token;
+        setToken(resumeToken);
+      }
       opened = true;
       if (JSON.stringify(resumeToken) !== openToken) attempt = 0;
       markReady();
@@ -988,15 +1008,20 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
       live = true;
       afterQueue();
       const result = joiner.push(change);
-      if (result.kind === "part") return;
+      if (result.kind === "part") {
+        // The first fragment of a split event: the token goes back to the token before the event
+        // The token goes back with no note for `tokenAgeMs`: the age keeps the latest token that moved it
+        if ((change["splitEvent"] as { fragment?: unknown } | undefined)?.fragment === 1) token = tokenBefore;
+        return;
+      }
       if (result.kind === "missing") {
         // The stream started after a fragment: the event cannot be read, so the subscribers read the collection in full
-        token = result.change["_id"];
+        setToken(result.change["_id"]);
         return gap(`a split event of ${source.collection} came without its first ${result.missing} fragments`, { missing: result.missing, resumeToken: true });
       }
       if (result.change["operationType"] === "invalidate") {
         // The collection was dropped or renamed: the stream starts after the invalidate event
-        token = result.change["_id"];
+        setToken(result.change["_id"]);
         return end("ended (invalidate)");
       }
       onChange(result.change);
@@ -1010,6 +1035,9 @@ export function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish
 
   return {
     ready,
+    get tokenAgeMs(): number {
+      return age.ageMs();
+    },
     async stop(): Promise<void> {
       if (stopped) return;
       stopped = true;

package/src/storage/token-age.ts

@@ -0,0 +1,63 @@
+/**
+ * The age of the resume token of a change watcher (roadmap CLI-110). A token moves when its cluster time is later
+ * than the cluster time of the token before it. The same token again, or a new token at the same cluster time,
+ * does not move it. A user reads a stalled feed from the age, without a sampler of its own.
+ *
+ * The package does not export this module. `watchDatabaseChanges()` and `watchStorageChanges()` give the age as
+ * `tokenAgeMs` on their handles.
+ */
+
+import type { Clock } from "@procedures/client";
+
+/** The type byte of a timestamp at the start of the key of a resume token of the server. */
+const TIMESTAMP_TYPE = "82";
+
+/**
+ * This function gives the cluster time of a resume token as 16 hex digits, or undefined for a token of another form.
+ * The key of a token of the server starts with the type byte `82` and the 8 bytes of the timestamp, high byte first.
+ * So the order of two of these texts is the order of their cluster times.
+ */
+export function clusterTimeOfToken(token: unknown): string | undefined {
+  const data = typeof token === "object" && token !== null ? (token as { _data?: unknown })._data : undefined;
+  if (typeof data !== "string" || !data.startsWith(TIMESTAMP_TYPE) || !/^[0-9a-f]{16}$/i.test(data.slice(2, 18))) return undefined;
+  return data.slice(2, 18).toLowerCase();
+}
+
+/** This function tells if `next` is later than `before`. A token without a cluster time moves when it is a different token. */
+function moves(next: unknown, before: unknown): boolean {
+  if (next === undefined || next === null) return false;
+  if (before === undefined || before === null) return true;
+  const nextTime = clusterTimeOfToken(next);
+  const beforeTime = clusterTimeOfToken(before);
+  if (nextTime !== undefined && beforeTime !== undefined) return nextTime > beforeTime;
+  return JSON.stringify(next) !== JSON.stringify(before);
+}
+
+/** The age of the token of one watcher. */
+export interface TokenAge {
+  /** This method notes a token of the watcher. It moves the age to 0 when the token is later than the last token that moved it. */
+  note(token: unknown): void;
+  /** This method gives the milliseconds of the clock since the token last moved, or since the start before the first move. */
+  ageMs(): number;
+}
+
+/**
+ * This function starts the age of the token of one watcher at the time of the clock.
+ *
+ * @param clock - The clock of the watcher
+ * @param start - The start token of the watcher, or undefined. A later token moves the age.
+ */
+export function tokenAge(clock: Clock, start?: unknown): TokenAge {
+  let last: unknown = start;
+  let movedAt = clock.now();
+  return {
+    note(token: unknown): void {
+      if (!moves(token, last)) return;
+      last = token;
+      movedAt = clock.now();
+    },
+    ageMs(): number {
+      return clock.now() - movedAt;
+    },
+  };
+}