@lossless.org/client 1.21.0 → 1.22.0

package/ts/nosqldb/classes.writerevisions.ts

@@ -0,0 +1,328 @@
+import * as plugins from './plugins.js';
+
+import type { SmartdataDb } from './classes.db.js';
+import { assertDataOptions } from './classes.operationbudget.js';
+import type { SmartdataOperationDeadline } from './classes.operationdeadline.js';
+import { SmartdataPersistenceError, isMongoDuplicateKeyError } from './classes.persistence.js';
+
+/**
+ * Write revisions let a read set tell writes of other processes apart from
+ * no writes at all. Every model write bumps a counter per collection and
+ * partition in the same transaction, and a read set compares the counters it
+ * read before its reads with the current ones.
+ */
+export interface ISmartdataWriteRevisionsOptions {
+  /**
+   * The top-level field whose string value splits a collection's counters, so
+   * writes of one partition never invalidate reads pinned to another. A
+   * document whose field holds anything but such a string shares one counter
+   * per collection with every write the partitions cannot place.
+   */
+  partitionField: string;
+}
+
+/** The collection that holds the counters. */
+export const writeRevisionsCollectionName = '__smartdata_write_revisions';
+
+interface IWriteRevisionDocument {
+  _id: string;
+  n: number;
+  generation?: string;
+}
+
+/** The counter every write revision belongs to; a new generation restarts all counters. */
+const epochId = '$epoch';
+const maximumPartitionLength = 512;
+const maximumPinnedPartitions = 64;
+/** Beyond this many documents, a write by selector bumps the shared counter instead. */
+export const maximumPreReadDocuments = 1024;
+const snapshotTimeoutMs = 5_000;
+
+const partitionFields = new WeakMap<SmartdataDb, string>();
+
+/** @internal Validates and records the option; called once by the database's constructor. */
+export const configureSmartdataWriteRevisions = (dbArg: SmartdataDb, optionsArg: unknown): void => {
+  if (optionsArg === undefined) return;
+  const { partitionField } = assertDataOptions(optionsArg, ['partitionField']);
+  if (
+    typeof partitionField !== 'string'
+    || partitionField.length === 0
+    || !partitionField.isWellFormed()
+    || partitionField.includes('.')
+    || partitionField.startsWith('$')
+    || partitionField === '_id'
+  ) {
+    throw new SmartdataPersistenceError('invalid_argument',
+      'Write revisions require a top-level partition field other than _id: no "." and no leading "$".');
+  }
+  partitionFields.set(dbArg, partitionField);
+};
+
+/** @internal The configured partition field, whether or not the engine can carry revisions. */
+export const writeRevisionsPartitionField = (dbArg: SmartdataDb): string | undefined =>
+  partitionFields.get(dbArg);
+
+/** @internal Write revisions are configured and the engine runs transactions. */
+export const isSmartdataWriteRevisionsActive = (dbArg: SmartdataDb): boolean =>
+  partitionFields.has(dbArg) && dbArg.capabilities?.transactions === 'available';
+
+/** A string the counters can name, or `undefined`. */
+const partitionOf = (valueArg: unknown): string | undefined =>
+  typeof valueArg === 'string' && valueArg.length <= maximumPartitionLength && valueArg.isWellFormed()
+    ? valueArg
+    : undefined;
+
+/** @internal The counter of one partition of a collection. */
+export const partitionRevisionId = (collectionArg: string, partitionArg: string): string =>
+  `${collectionArg}$s${partitionArg}`;
+
+/** @internal The counter of a collection's writes that no partition can place. */
+export const sharedRevisionId = (collectionArg: string): string => `${collectionArg}$*`;
+
+/**
+ * @internal The counter a stored value of the partition field belongs to:
+ * its partition's for a string the counters can name, the shared one otherwise.
+ */
+export const revisionIdOfValue = (collectionArg: string, valueArg: unknown): string => {
+  const partition = partitionOf(valueArg);
+  return partition === undefined
+    ? sharedRevisionId(collectionArg)
+    : partitionRevisionId(collectionArg, partition);
+};
+
+const isPlainRecord = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  if (typeof valueArg !== 'object' || valueArg === null || Array.isArray(valueArg)) return false;
+  const prototype = Object.getPrototypeOf(valueArg);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * The partitions a filter pins the field to: a string, `{ $eq: string }` or
+ * `{ $in: [...strings] }` beside other operators, at the top level or inside
+ * `$and`. The first pin found wins.
+ */
+const pinnedPartitions = (filterArg: unknown, fieldArg: string): string[] | undefined => {
+  if (!isPlainRecord(filterArg)) return undefined;
+  if (Object.hasOwn(filterArg, fieldArg)) {
+    const condition = filterArg[fieldArg];
+    if (typeof condition === 'string') {
+      const partition = partitionOf(condition);
+      if (partition !== undefined) return [partition];
+    } else if (
+      isPlainRecord(condition)
+      && Object.keys(condition).length > 0
+      && Object.keys(condition).every((keyArg) => keyArg.startsWith('$'))
+    ) {
+      if (Object.hasOwn(condition, '$eq')) {
+        const partition = partitionOf(condition.$eq);
+        if (partition !== undefined) return [partition];
+      }
+      const values = condition.$in;
+      if (
+        Array.isArray(values)
+        && values.length > 0
+        && values.length <= maximumPinnedPartitions
+        && values.every((valueArg) => partitionOf(valueArg) !== undefined)
+      ) {
+        return [...new Set(values as string[])];
+      }
+    }
+  }
+  if (Array.isArray(filterArg.$and)) {
+    for (const conjunct of filterArg.$and) {
+      const partitions = pinnedPartitions(conjunct, fieldArg);
+      if (partitions) return partitions;
+    }
+  }
+  return undefined;
+};
+
+/*
+ * Snapshot keys: `e` for the epoch, `c<id>` for one counter and `r<collection>`
+ * for the sum of every counter of a collection.
+ */
+const epochKey = 'e';
+const counterKey = (idArg: string): string => `c${idArg}`;
+const rangeKey = (collectionArg: string): string => `r${collectionArg}`;
+
+/**
+ * @internal The snapshot keys one read depends on. A read the field pins
+ * depends on its partitions and the shared counter, which holds every
+ * document whose field holds no single string; any other read depends on the
+ * whole collection.
+ */
+export const writeRevisionKeysOfRead = (
+  dbArg: SmartdataDb,
+  collectionArg: string,
+  kindArg: 'documents' | 'count' | 'collection',
+  filterArg: unknown,
+): string[] => {
+  const field = partitionFields.get(dbArg);
+  const partitions = field === undefined || kindArg === 'collection'
+    ? undefined
+    : pinnedPartitions(filterArg, field);
+  if (!partitions) return [epochKey, rangeKey(collectionArg)];
+  return [
+    epochKey,
+    counterKey(sharedRevisionId(collectionArg)),
+    ...partitions.map((partitionArg) => counterKey(partitionRevisionId(collectionArg, partitionArg))),
+  ];
+};
+
+const revisionsCollection = (mongoDbArg: plugins.mongodb.Db) =>
+  mongoDbArg.collection<IWriteRevisionDocument>(writeRevisionsCollectionName);
+
+const connectedDb = (dbArg: SmartdataDb): plugins.mongodb.Db => {
+  if (dbArg.status !== 'connected' || !dbArg.mongoDb) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'Write revisions require a connected SmartdataDb.');
+  }
+  return dbArg.mongoDb;
+};
+
+/**
+ * @internal The current value of each snapshot key, or `undefined` for a key
+ * whose value cannot be known: a missing epoch means the counters restarted.
+ * Bounded by its own deadline.
+ */
+export const readWriteRevisionSnapshot = async (
+  dbArg: SmartdataDb,
+  keysArg: readonly string[],
+): Promise<Map<string, string | undefined>> => {
+  const collection = revisionsCollection(connectedDb(dbArg));
+  const signal = AbortSignal.timeout(snapshotTimeoutMs);
+  const expiresAt = performance.now() + snapshotTimeoutMs;
+  const options = () => ({
+    timeoutMS: Math.max(1, Math.ceil(expiresAt - performance.now())),
+    timeoutMode: 'cursorLifetime' as const,
+    signal,
+  });
+  const counterIds = keysArg.flatMap((keyArg) => keyArg.startsWith('c') ? [keyArg.slice(1)] : []);
+  const ranges = keysArg.flatMap((keyArg) => keyArg.startsWith('r') ? [keyArg.slice(1)] : []);
+  const [counters, ...sums] = await Promise.all([
+    collection.find(
+      { _id: { $in: [epochId, ...counterIds] } },
+      { projection: { n: 1, generation: 1 }, ...options() },
+    ).toArray(),
+    ...ranges.map((collectionArg) => collection.aggregate<{ n: unknown }>([
+      { $match: { _id: { $gte: `${collectionArg}$`, $lt: `${collectionArg}%` } } },
+      { $group: { _id: null, n: { $sum: '$n' } } },
+    ], options()).toArray()),
+  ]);
+  const byId = new Map(counters.map((documentArg) => [documentArg._id, documentArg]));
+  const snapshot = new Map<string, string | undefined>();
+  const epoch = byId.get(epochId);
+  snapshot.set(epochKey, typeof epoch?.generation === 'string' && Number.isSafeInteger(epoch.n)
+    ? `${epoch.generation}:${epoch.n}`
+    : undefined);
+  for (const id of counterIds) {
+    const counter = byId.get(id);
+    snapshot.set(counterKey(id), counter === undefined
+      ? '0'
+      : Number.isSafeInteger(counter.n) ? String(counter.n) : undefined);
+  }
+  for (const [index, collectionArg] of ranges.entries()) {
+    const sum = sums[index].length === 0 ? 0 : sums[index][0].n;
+    snapshot.set(rangeKey(collectionArg), typeof sum === 'number' && Number.isSafeInteger(sum)
+      ? String(sum)
+      : undefined);
+  }
+  return snapshot;
+};
+
+/**
+ * @internal Creates the epoch of a database that has none, before `init()`
+ * publishes the connection. Another process creating it at the same time is
+ * fine.
+ */
+export const ensureSmartdataWriteRevisions = async (
+  mongoDbArg: plugins.mongodb.Db,
+  optionsArg: { timeoutMS?: number; signal?: AbortSignal } = {},
+): Promise<void> => {
+  try {
+    await revisionsCollection(mongoDbArg).updateOne(
+      { _id: epochId },
+      { $setOnInsert: { n: 0, generation: plugins.nodeCrypto.randomUUID() } },
+      { upsert: true, ...optionsArg },
+    );
+  } catch (errorArg) {
+    if (!isMongoDuplicateKeyError(errorArg)) throw errorArg;
+  }
+};
+
+/**
+ * @internal Bumps the epoch, which every read set depends on, so every read
+ * set of every process stops being current. An epoch that went missing is
+ * recreated with a new generation.
+ */
+export const bumpSmartdataWriteRevisionEpoch = async (
+  dbArg: SmartdataDb,
+  optionsArg: { timeoutMS?: number; signal?: AbortSignal },
+): Promise<void> => {
+  const collection = revisionsCollection(connectedDb(dbArg));
+  const bump = () => collection.updateOne(
+    { _id: epochId },
+    { $inc: { n: 1 }, $setOnInsert: { generation: plugins.nodeCrypto.randomUUID() } },
+    { upsert: true, ...optionsArg },
+  );
+  try {
+    await bump();
+  } catch (errorArg) {
+    // A concurrent upsert created the epoch first; the update now matches it.
+    if (!isMongoDuplicateKeyError(errorArg)) throw errorArg;
+    await bump();
+  }
+};
+
+/**
+ * @internal Bumps the counters a transaction's writes touched, inside that
+ * transaction, right before its commit. Sorted, so concurrent transactions
+ * take the counters in one order.
+ */
+export const flushSmartdataWriteRevisions = async (
+  mongoDbArg: plugins.mongodb.Db,
+  rawSessionArg: plugins.mongodb.ClientSession,
+  idsArg: ReadonlySet<string>,
+  signalArg: AbortSignal | undefined,
+): Promise<void> => {
+  if (idsArg.size === 0) return;
+  await revisionsCollection(mongoDbArg).bulkWrite([...idsArg].sort().map((idArg) => ({
+    updateOne: { filter: { _id: idArg }, update: { $inc: { n: 1 } }, upsert: true },
+  })), {
+    ordered: true,
+    session: rawSessionArg,
+    ...(signalArg === undefined ? {} : { signal: signalArg }),
+  });
+};
+
+/**
+ * @internal The counters of the documents a write by selector is about to
+ * change, read in its transaction before it runs. Snapshot isolation makes
+ * them exactly the documents the write sees. More documents than the bound,
+ * or a value the counters cannot name, bump the shared counter.
+ */
+export const readPreviousRevisionIds = async (
+  dbArg: SmartdataDb,
+  collectionArg: plugins.mongodb.Collection<any>,
+  rawSessionArg: plugins.mongodb.ClientSession,
+  selectorArg: unknown,
+  deadlineArg: SmartdataOperationDeadline,
+): Promise<Set<string>> => {
+  const field = partitionFields.get(dbArg)!;
+  const documents = await collectionArg.find(selectorArg as plugins.mongodb.Filter<any>, {
+    projection: { [field]: 1, _id: 0 },
+    limit: maximumPreReadDocuments + 1,
+    session: rawSessionArg,
+    ...deadlineArg.cursorOptions(),
+  }).toArray();
+  const ids = new Set<string>();
+  if (documents.length > maximumPreReadDocuments) {
+    ids.add(sharedRevisionId(collectionArg.collectionName));
+    return ids;
+  }
+  for (const document of documents) {
+    ids.add(revisionIdOfValue(collectionArg.collectionName,
+      Object.hasOwn(document, field) ? document[field] : undefined));
+  }
+  return ids;
+};