@procedures/mongo 0.35.0 → 0.36.0

package/dist/storage/own-writes.js

@@ -0,0 +1,130 @@
+/**
+ * The writes of this process (roadmap CLI-77). Each write of a `MongoDocumentStorage` takes
+ * numbers of the sequence of its collection (`_seq`). While a watcher of the collection
+ * (`watchStorageChanges`) tracks the collection, the storage notes here each number that it takes,
+ * and the stored `_id` of each tombstone that it prunes. The watcher then knows the change events
+ * of the writes of this process.
+ *
+ * - The numbers: the collection procedures of this process publish the events of these writes
+ *   already, so a watcher with `ownWrites: "skip"` skips them.
+ * - The pruned tombstones: the delete of a pruned tombstone deletes no item. Without the image
+ *   before the change, the event of the delete has only the stored `_id`, so the watcher reads it
+ *   here, and skips the event.
+ * - Each watcher has its own tracker. A tracker takes each noted entry once: the event of the
+ *   write takes it. A later event with the same `_seq` (for example a raw `$set` that keeps the
+ *   field) is not of this process, and the watcher reads it as a raw write.
+ * - The storage notes entries only while a tracker of the collection is open, so a process without
+ *   a watcher keeps nothing.
+ * - The trackers of a collection are by the `MongoClient` of the database and the names of the
+ *   database and of the collection: two `Db` objects of one database share them.
+ * - An entry without an event (for example of an aborted transaction) goes after
+ *   `OWN_WRITE_TTL_MS` on the clock of the tracker, and a tracker keeps at most `MAX_OWN_WRITES`
+ *   entries of each kind: the oldest go first. An entry that goes too early makes a second hint at
+ *   most, never a lost hint.
+ * - The numbers of an adoption of a raw write (D39) are never noted: the watcher publishes the
+ *   hint of the adoption.
+ */
+import { BSON } from "mongodb";
+/** The longest time that a noted entry waits for its change event: 5 minutes. */
+const OWN_WRITE_TTL_MS = 5 * 60_000;
+/** The most noted entries of each kind of one tracker. */
+const MAX_OWN_WRITES = 100_000;
+/** The trackers of each collection: by the client (else the `Db` object), then by the names of the database and the collection. */
+const TRACKERS = new WeakMap();
+function ownerOf(db) {
+    const client = db.client;
+    return typeof client === "object" && client !== null ? client : db;
+}
+function nameOf(db, collection) {
+    return `${db.databaseName}\u0000${collection}`;
+}
+function trackersOf(db, collection) {
+    return TRACKERS.get(ownerOf(db))?.get(nameOf(db, collection));
+}
+/** The key of a stored `_id` in a tracker: its extended JSON, so an `ObjectId` and a text never meet. */
+function idKey(storedId) {
+    return BSON.EJSON.stringify({ v: storedId }, { relaxed: false });
+}
+/** This function notes some keys in a map with a time limit, and drops the old ones. */
+function noteAll(map, keys, now) {
+    for (const key of keys) {
+        // A key noted again (an aborted transaction gives its numbers again) moves to the end
+        map.delete(key);
+        map.set(key, now + OWN_WRITE_TTL_MS);
+    }
+    // The map keeps the order of the notes: the oldest keys are first
+    for (const [key, until] of map) {
+        if (until > now && map.size <= MAX_OWN_WRITES)
+            break;
+        map.delete(key);
+    }
+}
+/** This function starts a tracker of the writes of this process in a collection. */
+export function trackOwnNumbers(db, collection, options = {}) {
+    const owner = ownerOf(db);
+    const name = nameOf(db, collection);
+    const clock = options.clock;
+    const tracker = {
+        numbers: options.numbers === false ? undefined : new Map(),
+        pruned: new Map(),
+        now: clock ? () => clock.now() : Date.now,
+    };
+    let byName = TRACKERS.get(owner);
+    if (!byName) {
+        byName = new Map();
+        TRACKERS.set(owner, byName);
+    }
+    let trackers = byName.get(name);
+    if (!trackers) {
+        trackers = new Set();
+        byName.set(name, trackers);
+    }
+    trackers.add(tracker);
+    const live = (map, key) => {
+        const until = map.get(key);
+        if (until === undefined)
+            return false;
+        map.delete(key);
+        return until > tracker.now();
+    };
+    return {
+        take(seq) {
+            return tracker.numbers !== undefined && live(tracker.numbers, seq);
+        },
+        takePruned(storedId) {
+            return live(tracker.pruned, idKey(storedId));
+        },
+        close() {
+            const set = TRACKERS.get(owner)?.get(name);
+            set?.delete(tracker);
+            if (set?.size === 0)
+                TRACKERS.get(owner)?.delete(name);
+            tracker.numbers?.clear();
+            tracker.pruned.clear();
+        },
+    };
+}
+/** This function notes the numbers `first` to `first + count - 1` of a write of this process, for each open tracker of the collection. */
+export function noteOwnNumbers(db, collection, first, count) {
+    const trackers = trackersOf(db, collection);
+    if (!trackers)
+        return;
+    for (const tracker of trackers) {
+        if (!tracker.numbers)
+            continue;
+        const numbers = [];
+        for (let seq = first; seq < first + count; seq++)
+            numbers.push(seq);
+        noteAll(tracker.numbers, numbers, tracker.now());
+    }
+}
+/** This function notes the stored `_id` of each tombstone that this process prunes, for each open tracker of the collection. Call it before the delete. */
+export function notePrunedIds(db, collection, storedIds) {
+    const trackers = trackersOf(db, collection);
+    if (!trackers)
+        return;
+    const keys = storedIds.map(idKey);
+    for (const tracker of trackers)
+        noteAll(tracker.pruned, keys, tracker.now());
+}
+//# sourceMappingURL=own-writes.js.map

package/dist/storage/own-writes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-writes.js","sourceRoot":"","sources":["../../src/storage/own-writes.ts"],"names":[],"mappings":"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"}

package/dist/storage/storage-hints.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The change hints of a `MongoDocumentStorage` collection (roadmap CLI-77). `watchStorageChanges()`
+ * watches the change stream of the collection, and publishes each change as a
+ * `CollectionChangeEvent` on the topic of the collection procedures. Thus a subscriber also gets
+ * the writes that did not go through the procedures: a raw write, a script, another process, a
+ * view.
+ *
+ * - The topic is `collectionChangeTopic(name, partition)`, as the procedures publish it: the
+ *   partition of a document comes from `storage.form.partitionOf()`.
+ * - The event is a hint, without `since` and without `version` (the version of the change log): the
+ *   subscriber reads the changes with `changes`, as for each event without `since`. The event has
+ *   the id in `changed` or in `deleted`, and the version of the item in `versions` (a field of
+ *   `CollectionChangeEvent`): the version that `storage.versionOf(id)` gives after the write.
+ * - A write through the storage gives the document a new `_seq`. The watcher reads that from the
+ *   event, never from the `fullDocument` of the lookup: an update with `_seq` in
+ *   `updateDescription.updatedFields`, an insert or a replace with `_seq`. With the image before
+ *   the change, a replace whose `_seq` is the `_seq` before is a raw write (a copy). Without the
+ *   image, a replace with `_seq` counts as a write of the storage.
+ * - A raw write (D39), with `rawWrites: "adopt"` (the default): the watcher publishes nothing for
+ *   its event. The storage adopts it: one conditional write through the path of each write gives
+ *   the document a new `_seq` (and the storage fields and partition fields that a raw replace took
+ *   away), so `changes(since)` has it. The event of the adoption is a write of the storage: its
+ *   hint goes out, with the new version. When two watchers adopt the same write, or a write of the
+ *   storage comes first, one write wins and the others do nothing. A raw write never gets the old
+ *   version. With `rawWrites: "ignore"` (for example for a user that can only read), the hint of a
+ *   raw write goes out without a version, and `changes(since)` does not have the write.
+ * - The adoptions wait in one queue for each watcher: one adoption at a time, and the raw writes
+ *   that wait together take one block of numbers for each partition. An adoption that fails with
+ *   an error that can go away tries again after the backoff. When the queue is full, the hint of
+ *   the next raw write goes out without a version. The watcher keeps the ids of the raw writes that
+ *   did not fit or that failed (at most 10,000), and adopts them again when the queue is empty,
+ *   after a sweep. An adoption that fails for good (after its last try, or a second time), or an id
+ *   over that limit, gives its partition a reset hint (`reset: true`): its subscribers read it in full.
+ * - The adoption is exact only with the images before the change (`changeStreamPreAndPostImages`).
+ *   An insert and a replace show their document, but an update shows only its fields: without the
+ *   image, the `_seq` that the update kept comes from the lookup. When a write of the storage comes
+ *   after the raw update, the adoption can then give that write a newer version, and a client that
+ *   holds the version of that write gets a conflict of its precondition.
+ * - The sweep: after each gap (`sweep`, on by default with `rawWrites: "adopt"`), after a full
+ *   queue, and when the stream opens (`sweepAtOpen`, off by default), the watcher sends each
+ *   document without `_seq` to the same queue, in pages. Thus a document without `_seq` gets its
+ *   number. A raw update of a document with `_seq` keeps that `_seq`: no sweep finds it, so a gap
+ *   publishes a reset hint. The scan walks the index of `_id` and reads each document of the
+ *   collection: a partial index cannot express `$exists: false`. A document that the sweep cannot
+ *   place (no id, or another partition) goes to the log once, and the next sweeps leave it.
+ * - A raw hard delete of an item: with the image before the change, the storage adopts it as a
+ *   tombstone. Without the image (no `changeStreamPreAndPostImages` on the collection), the hint
+ *   goes out without a version, and the delete stays out of `changes(since)`.
+ * - A delete of a tombstone (the storage prunes the oldest ones) deletes no item: no hint, no
+ *   adoption. The image before the change tells it. Without the image, the watcher knows the
+ *   prunes of this process only.
+ * - The writes of this process through the storage: with `ownWrites: "skip"` (the default), the
+ *   watcher skips their events, because the collection procedures publish them already, with
+ *   `since`. Thus a subscriber gets one event for each write. With `ownWrites: "publish"`, the
+ *   watcher publishes each change. Use it when the writes of this process do not go through the
+ *   procedures, or when the procedures publish no events (`changeEvents: false`). An adoption is
+ *   never an own write.
+ * - After an error of the stream, the watcher opens the stream again after a backoff, from the
+ *   resume token of the last event: it loses no change. When the server does not have the token
+ *   any more, or the collection was dropped or renamed, the watcher cannot know what it missed: it
+ *   publishes a reset hint (a gap: no ids, `reset: true`) on the plain topic and on the topic of
+ *   each partition that it knows: the partitions of the counters, of `forPartition()`, of the
+ *   hints, of the subscribed topics of the bus, and of `gapPartitions`. The counters have a floor
+ *   document for each partition with a write through a storage. The subscribers read the
+ *   collection in full.
+ * - The pipeline of the stream is `[]`: the storage of a partition (`forPartition()`) watches the
+ *   whole collection and drops the events of other partitions.
+ * - 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 { type Document } from "mongodb";
+import { type Clock, type CollectionChangeEvent, type ResubscribeBackoff } from "@procedures/client";
+import { type MongoDocumentStorage, type StoredForm } from "./document-storage.js";
+/** The change of one item of a change event of a `MongoDocumentStorage` collection, from `storageChangeOf()`. */
+export interface StorageChange {
+    /** The id of the item. */
+    readonly id: string;
+    /** The partition of the document. */
+    readonly partition: string | undefined;
+    /** True for a delete: a tombstone, or a delete of the document. */
+    readonly deleted: boolean;
+    /**
+     * True for a raw write: a write that did not give the document a new `_seq` (see the module
+     * comment), and each delete of a document that is not a tombstone.
+     */
+    readonly raw: boolean;
+    /** The version of the item after a write of the storage (`versionOfStored()`). A delete and a raw write have no version. */
+    readonly version?: string | undefined;
+    /** The new `_seq` of a write of the storage, or the `_seq` that a raw write kept (none for a document without `_seq`). */
+    readonly seq?: number | undefined;
+}
+/**
+ * The change event of `watchStorageChanges()`: a `CollectionChangeEvent` without `since` (a hint),
+ * with the version of each changed item in `versions`. A subscriber of the collection procedures
+ * reads it as each other event. It is an alias of `CollectionChangeEvent`.
+ */
+export type StorageChangeHint = CollectionChangeEvent;
+/**
+ * The function or the bus that gets the events of `watchStorageChanges()`, for example the bus of
+ * the procedures. A bus with `channels()` (the `EventBus` of `@procedures/client`) also tells the
+ * subscribed topics: the hint of a gap goes to their partitions.
+ */
+export type StorageHintPublisher = ((topic: string, event: StorageChangeHint) => void | Promise<void>) | {
+    emit(topic: string, event: StorageChangeHint): void;
+    channels?(): readonly string[];
+};
+/** The options of `watchStorageChanges()`. */
+export interface WatchStorageChangesOptions {
+    /**
+     * The name of the collection in the topic: the name of `createCollectionProcedures()`.
+     * @default the MongoDB collection of the storage
+     */
+    collection?: string | undefined;
+    /**
+     * The topic of the events of a partition, or undefined for no event. Give the same rule as the
+     * option `changeEvents.topic` of the procedures.
+     * @default `collectionChangeTopic(collection, partition)`
+     */
+    topic?: ((collection: string, partition: string | undefined) => string | undefined) | undefined;
+    /**
+     * `skip`: the watcher skips the events of the writes of this process through the storage, because
+     * the collection procedures publish them. `publish`: the watcher publishes each change.
+     * @default "skip"
+     */
+    ownWrites?: "skip" | "publish" | undefined;
+    /**
+     * `adopt`: the storage gives each raw write a new `_seq`, so `changes(since)` has it, and the hint
+     * goes out with the new version (D39). The watcher needs write access. `ignore`: the hint of a raw
+     * write goes out without a version, and the storage writes nothing (for a user that can only read).
+     * @default "adopt"
+     */
+    rawWrites?: "adopt" | "ignore" | undefined;
+    /**
+     * More partitions for the hint of a gap. The host gives the partitions that its subscribers
+     * subscribed to, when the publisher cannot tell them (a function, or a bus without
+     * `channels()`). The watcher adds the plain topic, the partitions of the counters and of
+     * `forPartition()`, the partitions of the hints, and the subscribed topics of the bus. Each
+     * partition with a write through a storage (in any process) has a floor document in the
+     * counters (roadmap O66). So give `gapPartitions` only for the partitions that only raw writes
+     * wrote.
+     */
+    gapPartitions?: (() => Iterable<string | undefined>) | undefined;
+    /**
+     * True: after each gap, the watcher adopts each document without `_seq` (a raw write during the
+     * gap), in pages, through the queue of the adoptions. It needs `rawWrites: "adopt"`. With
+     * `false`, a sweep still runs when the watcher had more raw writes to adopt again than it can
+     * keep.
+     * @default true with `rawWrites: "adopt"`, else false
+     */
+    sweep?: boolean | undefined;
+    /**
+     * True: a sweep also runs when the stream opens first, for the raw writes before the watcher
+     * started. It needs `rawWrites: "adopt"`. The first watcher on a legacy collection adopts every
+     * legacy document, and the next delta of every subscriber is the whole collection.
+     * @default false
+     */
+    sweepAtOpen?: boolean | undefined;
+    /**
+     * The backoff before the stream opens again after an error.
+     * @default { initialDelay: ms(250), maxDelay: seconds(30), backoffMultiplier: 2, jitter: 1 }
+     */
+    backoff?: ResubscribeBackoff | undefined;
+    /** The clock of the timers and of the time limit of the own writes (default the clock of the platform). The timers do not keep a process alive. */
+    clock?: Clock | undefined;
+    /** The log (default `console`, with the prefix `[storage-hints]`). */
+    log?: ((level: "info" | "warn" | "error", message: string) => void) | undefined;
+}
+/** The handle of `watchStorageChanges()`. */
+export interface StorageChangesWatch {
+    /**
+     * It resolves when the first stream is open (each later change reaches the publisher), or when
+     * `stop()` runs. It rejects when the first open fails with an error that does not go away (a
+     * single server, a refused authentication or permission): the watcher then stops. The watcher
+     * opens the stream again after the other errors.
+     */
+    readonly ready: Promise<void>;
+    /** This method stops the watcher: it closes the stream and cancels the timer of a backoff. */
+    stop(): Promise<void>;
+}
+/**
+ * This function reads the change of an item from a change event of a `MongoDocumentStorage`
+ * collection (roadmap CLI-77), for an app that watches the collection itself. It gives `undefined`
+ * for an event of no item: another operation (for example `drop`), an update whose document is
+ * gone (its delete event follows), the delete of a tombstone, or a document whose id neither
+ * `idOf` nor `_key` tells.
+ *
+ * - The partition is `form.partitionOf()` of `fullDocumentBeforeChange`, else of `fullDocument`,
+ *   else of `documentKey`: the first whose partition gives the id with `form.idOf()` of the stored
+ *   `_id`. Else the id is `_key`, in the partition of the first document.
+ * - A tombstone and a delete are deletes.
+ * - `raw` tells a raw write, from the event only (see the module comment). A write of the storage
+ *   has the version of its new `_seq`. A raw write has no version.
+ *
+ * @param change - A change event of the collection, with `fullDocument: "updateLookup"` for the updates
+ * @param form - The stored form of the storage, for example `storage.form` (default `DEFAULT_STORED_FORM`)
+ */
+export declare function storageChangeOf(change: Document, form?: StoredForm): StorageChange | undefined;
+/**
+ * This function watches the change stream of the collection of a `MongoDocumentStorage`, and
+ * publishes a hint of each change of an item on the topic of the collection procedures (roadmap
+ * CLI-77). The writes that do not go through the procedures (a raw write, another process, a
+ * script) then reach the subscribers too, and the storage adopts each raw write (D39). See the
+ * module comment for the rules.
+ *
+ * - The storage of a partition (`forPartition()`) publishes only the documents of its partition.
+ * - The watcher reads only the collection of the items. The documents of the counters
+ *   (`__storage_counters`) are in another collection, and a change there is never a hint.
+ * - An error of the publisher goes to the log. It never stops the watcher.
+ * - The adoption of raw writes needs write access. A refused adoption goes to the log once, and
+ *   the hint of that write goes out without a version: set `rawWrites: "ignore"` for a user that
+ *   can only read.
+ * - The adoption is exact only with `changeStreamPreAndPostImages` on the collection. Without the
+ *   image, a raw update and a later write of the storage can give that write an extra version.
+ *
+ * @param storage - The storage, for its collection, its database and its stored form
+ * @param publish - The function or the bus of the events, for example the bus of the procedures
+ * @param options - The topic, the own writes, the raw writes, the gap, the backoff, the clock and the log
+ * @returns The handle: `ready` and `stop()`
+ *
+ * @example
+ * ```typescript
+ * const notes = new MongoDocumentStorage<Note>({ collection: "notes" });
+ * const watch = watchStorageChanges(notes, bus); // the bus of the procedures
+ * await watch.ready;
+ * // ... a raw write of a note reaches the subscribers of collections.notes.<partition>
+ * await watch.stop();
+ * ```
+ */
+export declare function watchStorageChanges<T>(storage: MongoDocumentStorage<T>, publish: StorageHintPublisher, options?: WatchStorageChangesOptions): StorageChangesWatch;
+//# sourceMappingURL=storage-hints.d.ts.map

package/dist/storage/storage-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-hints.d.ts","sourceRoot":"","sources":["../../src/storage/storage-hints.ts"],"names":[],"mappings":"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"}