@lossless.org/client 1.23.0 → 1.23.2

package/ts/nosqldb/classes.writerevisions.ts

@@ -4,7 +4,6 @@ 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';
-import { logger } from './logging.js';
 
 /**
  * Write revisions let a read set tell writes of other processes apart from
@@ -12,10 +11,12 @@ import { logger } from './logging.js';
  * partition in the same transaction, and a read set compares the counters it
  * read before its reads with the current ones.
  *
- * A bump inserts an entry of its own instead of incrementing a shared
- * document, so concurrent transactions of one partition never conflict on its
- * counter. A counter's value is its base document plus its entries; a
- * background compaction folds entries into the base, which keeps the sum.
+ * A counter is its base document, which a writer bumps alone, and up to
+ * `counterShards - 1` shard documents that overlapping transactions bump
+ * instead, so they do not conflict on the base. A list document beside the
+ * base holds how many slots are in use, and the transaction that first bumps
+ * a slot raises it, so a snapshot reads the bases and lists in one query and
+ * only the listed shards of the counters that have any.
  */
 export interface ISmartdataWriteRevisionsOptions {
   /**
@@ -34,21 +35,21 @@ interface IWriteRevisionDocument {
   _id: string;
   n: number;
   generation?: string;
+  /** On a counter's list: the slots in use, the base included. */
+  slots?: number;
 }
 
 /** The counter every write revision belongs to; a new generation restarts all counters. */
 const epochId = '$epoch';
+/** Joins a counter's id and the slot of one of its shards, or ends the id of its list. No counter id contains it. */
+const shardSeparator = '\u0000';
 /**
- * Joins a counter's id and the suffix of one of its entries. No counter id
- * contains it, so a counter's base and entries are exactly the ids from the
- * counter's own up to, not including, the id followed by `entryRangeEnd`.
+ * Slots per counter, the base included: as many transactions that overlap in
+ * time can bump one counter without conflicting on it.
  */
-const entrySeparator = '\u0000';
-const entryRangeEnd = '\u0001';
-/** Entries one process adds to a counter before it folds the counter's entries into its base. */
-const compactionEntries = 64;
-const maximumCompactedEntries = 1024;
-const compactionTimeoutMs = 5_000;
+const counterShards = 16;
+/** Counters whose slots a database instance remembers, beyond those an open transaction holds. */
+const maximumRememberedCounters = 4096;
 const maximumPartitionLength = 512;
 const maximumPinnedPartitions = 64;
 /** Beyond this many documents, a write by selector bumps the shared counter instead. */
@@ -88,7 +89,7 @@ const partitionOf = (valueArg: unknown): string | undefined =>
   typeof valueArg === 'string'
   && valueArg.length <= maximumPartitionLength
   && valueArg.isWellFormed()
-  && !valueArg.includes(entrySeparator)
+  && !valueArg.includes(shardSeparator)
     ? valueArg
     : undefined;
 
@@ -99,6 +100,13 @@ export const partitionRevisionId = (collectionArg: string, partitionArg: string)
 /** @internal The counter of a collection's writes that no partition can place. */
 export const sharedRevisionId = (collectionArg: string): string => `${collectionArg}$*`;
 
+/** @internal The document of a counter's slot: the base for slot 0, a shard otherwise. */
+export const revisionSlotId = (idArg: string, slotArg: number): string =>
+  slotArg === 0 ? idArg : `${idArg}${shardSeparator}${slotArg}`;
+
+/** @internal The document that lists how many slots of a counter are in use; none means only the base. */
+export const revisionSlotListId = (idArg: string): string => `${idArg}${shardSeparator}`;
+
 /**
  * @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.
@@ -197,17 +205,120 @@ export const writeRevisionBumpsOfKey = (keyArg: string, idsArg: ReadonlySet<stri
   return bumps;
 };
 
-export const beginSmartdataWriteRevisionCommit = (
-  dbArg: SmartdataDb,
-  idsArg: ReadonlySet<string>,
-): (() => void) => {
-  const commits = revisionCommitsOfDb(dbArg);
-  const ids = new Set(idsArg);
-  commits.pending.add(ids);
-  for (const snapshot of commits.snapshots) {
-    if (snapshot.keys.some((keyArg) => writeRevisionBumpsOfKey(keyArg, ids) > 0)) snapshot.lost = true;
+interface IRevisionSlot {
+  /** Attempts of this instance that bump the slot and have not ended yet. */
+  holders: number;
+  /** When the last such attempt ended, on the `performance.now()` clock. */
+  endedAt: number;
+}
+
+interface IRevisionCounterSlots {
+  /** The slot this instance's last committed bump took; a search for a free slot starts there. */
+  preferred: number;
+  slots: IRevisionSlot[];
+}
+
+/** Per database instance, in least recently bumped order. */
+const revisionSlotsOfDbs = new WeakMap<SmartdataDb, Map<string, IRevisionCounterSlots>>();
+
+/**
+ * The slot of a counter an attempt that started at `attemptStartedAtArg`
+ * bumps: from the preferred one on, the first that no attempt of this instance
+ * holds or ended since then, whose commit the attempt's snapshot might not
+ * see. Without one, the first that none holds, and the preferred one last.
+ * Transactions of other instances may still take the same slot; a conflict
+ * then fails the attempt, and its retry starts after the slot's end, so it
+ * moves on to another.
+ */
+const chooseRevisionSlot = (counterArg: IRevisionCounterSlots, attemptStartedAtArg: number): number => {
+  let unheld: number | undefined;
+  for (let offset = 0; offset < counterShards; offset++) {
+    const slot = (counterArg.preferred + offset) % counterShards;
+    const state = counterArg.slots[slot];
+    if (state.holders > 0) continue;
+    if (state.endedAt < attemptStartedAtArg) return slot;
+    unheld ??= slot;
   }
-  return () => { commits.pending.delete(ids); };
+  return unheld ?? counterArg.preferred;
+};
+
+/**
+ * @internal The slots one attempt of a transaction bumps. A counter takes its
+ * slot at its first bump in the attempt and holds it until the attempt ends,
+ * so no other attempt of this instance commits to it in between.
+ */
+export interface ISmartdataWriteRevisionAttempt {
+  /** The slot of each counter the attempt bumps. */
+  readonly slots: ReadonlyMap<string, number>;
+  /** Takes a slot of a counter the attempt has not bumped yet; once the attempt ended, none. */
+  bump(idArg: string): void;
+  /**
+   * Right before the commit: until the attempt ends, a snapshot of this
+   * instance that depends on its counters cannot tell its bumps from those of
+   * other processes.
+   */
+  commit(): void;
+  /**
+   * Ends the attempt: releases its slots and, after a commit, makes them the
+   * counters' preferred ones. Later calls do nothing.
+   */
+  finish(committedArg: boolean): void;
+}
+
+export const beginSmartdataWriteRevisionAttempt = (
+  dbArg: SmartdataDb,
+  attemptStartedAtArg: number,
+): ISmartdataWriteRevisionAttempt => {
+  const taken: [IRevisionCounterSlots, number][] = [];
+  const slots = new Map<string, number>();
+  let pending: ReadonlySet<string> | undefined;
+  let finished = false;
+  return {
+    slots,
+    bump: (idArg) => {
+      if (finished || slots.has(idArg)) return;
+      let counters = revisionSlotsOfDbs.get(dbArg);
+      if (!counters) {
+        counters = new Map();
+        revisionSlotsOfDbs.set(dbArg, counters);
+      }
+      const counter = counters.get(idArg) ?? {
+        preferred: 0,
+        slots: Array.from({ length: counterShards }, () => ({ holders: 0, endedAt: -Infinity })),
+      };
+      counters.delete(idArg);
+      counters.set(idArg, counter);
+      const slot = chooseRevisionSlot(counter, attemptStartedAtArg);
+      counter.slots[slot].holders++;
+      taken.push([counter, slot]);
+      slots.set(idArg, slot);
+      for (const [id, remembered] of counters) {
+        if (counters.size <= maximumRememberedCounters) break;
+        if (remembered.slots.every((slotArg) => slotArg.holders === 0)) counters.delete(id);
+      }
+    },
+    commit: () => {
+      if (finished || pending) return;
+      const commits = revisionCommitsOfDb(dbArg);
+      const ids = new Set(slots.keys());
+      pending = ids;
+      commits.pending.add(ids);
+      for (const snapshot of commits.snapshots) {
+        if (snapshot.keys.some((keyArg) => writeRevisionBumpsOfKey(keyArg, ids) > 0)) snapshot.lost = true;
+      }
+    },
+    finish: (committedArg) => {
+      if (finished) return;
+      finished = true;
+      if (pending) revisionCommitsOfDb(dbArg).pending.delete(pending);
+      const endedAt = performance.now();
+      for (const [counter, slot] of taken) {
+        counter.slots[slot].holders--;
+        counter.slots[slot].endedAt = endedAt;
+        if (committedArg) counter.preferred = slot;
+      }
+    },
+  };
 };
 
 /**
@@ -247,9 +358,12 @@ const connectedDb = (dbArg: SmartdataDb): plugins.mongodb.Db => {
 
 /**
  * @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.
- * Every counter and collection sum is one read, so a compaction that moves
- * entries into a base never shows half done. Bounded by its own deadline.
+ * whose value cannot be known: a missing epoch means the counters restarted,
+ * and a counter with a value or slot count no writer stores stays unknown. One
+ * query reads the epoch, the bases and their lists, a second the listed
+ * shards. Every part only grows, and a slot is listed by the transaction that
+ * first bumps it, so a write that commits between the two queries shows in
+ * this snapshot or in the next, never in neither. Bounded by its own deadline.
  */
 const readStoredWriteRevisionSnapshot = async (
   dbArg: SmartdataDb,
@@ -263,10 +377,14 @@ const readStoredWriteRevisionSnapshot = async (
     timeoutMode: 'cursorLifetime' as const,
     signal,
   });
+  const readDocuments = async (idsArg: string[]) => new Map((await collection.find(
+    { _id: { $in: idsArg } },
+    { projection: { n: 1, generation: 1, slots: 1 }, ...options() },
+  ).toArray()).map((documentArg) => [documentArg._id, documentArg]));
   // `$sum` skips a value that is not a number, so such values are counted apart.
-  const sumOf = async (fromArg: string, toArg: string): Promise<string | undefined> => {
+  const sumOf = async (collectionArg: string): Promise<string | undefined> => {
     const [sum] = await collection.aggregate<{ n: unknown; invalid: unknown }>([
-      { $match: { _id: { $gte: fromArg, $lt: toArg } } },
+      { $match: { _id: { $gte: `${collectionArg}$`, $lt: `${collectionArg}%` } } },
       { $group: { _id: null, n: { $sum: '$n' }, invalid: { $sum: { $cond: [{ $isNumber: '$n' }, 0, 1] } } } },
     ], options()).toArray();
     if (sum === undefined) return '0';
@@ -274,26 +392,44 @@ const readStoredWriteRevisionSnapshot = async (
       ? String(sum.n)
       : undefined;
   };
-  const sums = keysArg.flatMap((keyArg): [string, Promise<string | undefined>][] => {
-    if (keyArg.startsWith('c')) {
-      const id = keyArg.slice(1);
-      return [[keyArg, sumOf(id, `${id}${entryRangeEnd}`)]];
-    }
-    if (keyArg.startsWith('r')) {
-      const collectionName = keyArg.slice(1);
-      return [[keyArg, sumOf(`${collectionName}$`, `${collectionName}%`)]];
-    }
-    return [];
-  });
-  const [epoch, ...values] = await Promise.all([
-    collection.findOne({ _id: epochId }, { projection: { n: 1, generation: 1 }, ...options() }),
-    ...sums.map(([, sumArg]) => sumArg),
+  const counterIds = keysArg.flatMap((keyArg) => keyArg.startsWith('c') ? [keyArg.slice(1)] : []);
+  const ranges = keysArg.flatMap((keyArg) => keyArg.startsWith('r') ? [keyArg.slice(1)] : []);
+  const [bases, ...sums] = await Promise.all([
+    readDocuments([epochId, ...counterIds.flatMap((idArg) => [idArg, revisionSlotListId(idArg)])]),
+    ...ranges.map(sumOf),
   ]);
+  /** The slots each counter's list holds, or `undefined` for a count no writer stores. */
+  const slotCounts = new Map(counterIds.map((idArg): [string, number | undefined] => {
+    const list = bases.get(revisionSlotListId(idArg));
+    const count: unknown = list === undefined ? 1 : list.slots;
+    return [idArg, Number.isSafeInteger(count) && (count as number) >= 1 && (count as number) <= counterShards
+      ? count as number
+      : undefined];
+  }));
+  const shardIds = counterIds.flatMap((idArg) => Array.from(
+    { length: (slotCounts.get(idArg) ?? 1) - 1 },
+    (_unusedArg, indexArg) => revisionSlotId(idArg, indexArg + 1),
+  ));
+  const shards = shardIds.length === 0 ? new Map<string, IWriteRevisionDocument>() : await readDocuments(shardIds);
   const snapshot = new Map<string, string | undefined>();
+  const epoch = bases.get(epochId);
   snapshot.set(epochKey, typeof epoch?.generation === 'string' && Number.isSafeInteger(epoch.n)
     ? `${epoch.generation}:${epoch.n}`
     : undefined);
-  for (const [index, [key]] of sums.entries()) snapshot.set(key, values[index]);
+  for (const id of counterIds) {
+    const count = slotCounts.get(id);
+    let sum: number | undefined = count === undefined ? undefined : 0;
+    for (let slot = 0; sum !== undefined && slot < count!; slot++) {
+      // A slot is missing until its first bump commits; a later one may commit first.
+      const document = slot === 0 ? bases.get(id) : shards.get(revisionSlotId(id, slot));
+      if (document === undefined) continue;
+      sum = Number.isSafeInteger(document.n) && Number.isSafeInteger(sum + document.n)
+        ? sum + document.n
+        : undefined;
+    }
+    snapshot.set(counterKey(id), sum === undefined ? undefined : String(sum));
+  }
+  for (const [index, collectionName] of ranges.entries()) snapshot.set(rangeKey(collectionName), sums[index]);
   return snapshot;
 };
 
@@ -364,129 +500,51 @@ export const bumpSmartdataWriteRevisionEpoch = async (
 
 /**
  * @internal Bumps the counters a transaction's writes touched, inside that
- * transaction, right before its commit: one new entry per counter, which no
- * concurrent transaction writes.
+ * transaction, right before its commit: each in the slot it took. A shard
+ * bump first makes sure the counter's list exists and holds the slot; once it
+ * does, neither update changes it, so later bumps of listed slots write only
+ * their own document. A slot whose value is no number stays as it is, which
+ * keeps its counter unknown, and the write still commits.
  */
 export const flushSmartdataWriteRevisions = async (
   mongoDbArg: plugins.mongodb.Db,
   rawSessionArg: plugins.mongodb.ClientSession,
-  idsArg: ReadonlySet<string>,
+  slotsArg: ReadonlyMap<string, number>,
   signalArg: AbortSignal | undefined,
 ): Promise<void> => {
-  if (idsArg.size === 0) return;
-  await revisionsCollection(mongoDbArg).insertMany([...idsArg].map((idArg) => ({
-    _id: `${idArg}${entrySeparator}${plugins.nodeCrypto.randomUUID()}`,
-    n: 1,
-  })), {
+  if (slotsArg.size === 0) return;
+  const operations: plugins.mongodb.AnyBulkWriteOperation<IWriteRevisionDocument>[] = [];
+  for (const [id, slot] of [...slotsArg].sort(([aArg], [bArg]) => aArg < bArg ? -1 : aArg > bArg ? 1 : 0)) {
+    if (slot > 0) {
+      const listId = revisionSlotListId(id);
+      operations.push(
+        { updateOne: { filter: { _id: listId }, update: { $setOnInsert: { n: 0 } }, upsert: true } },
+        {
+          updateOne: {
+            filter: { _id: listId, $or: [{ slots: { $exists: false } }, { slots: { $lt: slot + 1 } }] },
+            update: { $set: { slots: slot + 1 } },
+          },
+        },
+      );
+    }
+    const slotId = revisionSlotId(id, slot);
+    operations.push(
+      {
+        updateOne: {
+          filter: { _id: slotId, $or: [{ n: { $type: 'int' } }, { n: { $type: 'long' } }, { n: { $type: 'double' } }] },
+          update: { $inc: { n: 1 } },
+        },
+      },
+      { updateOne: { filter: { _id: slotId }, update: { $setOnInsert: { n: 1 } }, upsert: true } },
+    );
+  }
+  await revisionsCollection(mongoDbArg).bulkWrite(operations, {
     ordered: true,
     session: rawSessionArg,
     ...(signalArg === undefined ? {} : { signal: signalArg }),
   });
 };
 
-interface IWriteRevisionCompactions {
-  /** Committed entries this process added per counter since it last compacted it. */
-  entries: Map<string, number>;
-  running: Map<string, Promise<void>>;
-  controller: AbortController;
-}
-
-const revisionCompactions = new WeakMap<SmartdataDb, IWriteRevisionCompactions>();
-
-/**
- * Folds up to `maximumCompactedEntries` entries of one counter into its base
- * in one transaction, which keeps the counter's value. A concurrent compaction
- * of the same counter conflicts on the base and on the entries, and the driver
- * retries it within the deadline; one that still fails leaves the entries for
- * the next.
- */
-const compactWriteRevisionEntries = async (
-  dbArg: SmartdataDb,
-  idArg: string,
-  signalArg: AbortSignal,
-): Promise<void> => {
-  const collection = revisionsCollection(connectedDb(dbArg));
-  const abortable: plugins.mongodb.Abortable = { signal: signalArg };
-  const session = dbArg.mongoDbClient.startSession();
-  try {
-    await session.withTransaction(async () => {
-      const entries = await collection.find(
-        { _id: { $gt: `${idArg}${entrySeparator}`, $lt: `${idArg}${entryRangeEnd}` } },
-        { projection: { n: 1 }, limit: maximumCompactedEntries, session, ...abortable },
-      ).toArray();
-      if (entries.length === 0) return;
-      let sum = 0;
-      for (const entry of entries) {
-        if (!Number.isSafeInteger(entry.n)) {
-          throw new SmartdataPersistenceError('invalid_document',
-            `Write-revision entry "${entry._id}" holds no safe integer.`);
-        }
-        sum += entry.n;
-        if (!Number.isSafeInteger(sum)) {
-          throw new SmartdataPersistenceError('invalid_document',
-            `Write-revision entries of "${idArg}" do not sum to a safe integer.`);
-        }
-      }
-      await collection.deleteMany(
-        { _id: { $in: entries.map((entryArg) => entryArg._id) } },
-        { session, ...abortable },
-      );
-      await collection.updateOne(
-        { _id: idArg },
-        { $inc: { n: sum } },
-        { upsert: true, session, ...abortable },
-      );
-    }, { timeoutMS: compactionTimeoutMs });
-  } finally {
-    await session.endSession();
-  }
-};
-
-/**
- * @internal Counts the entries a committed transaction of this process added,
- * and starts a compaction of each counter that reached `compactionEntries`.
- * Compactions run in the background; `stopSmartdataWriteRevisionCompactions`
- * ends them.
- */
-export const noteSmartdataWriteRevisionEntries = (
-  dbArg: SmartdataDb,
-  idsArg: ReadonlySet<string>,
-): void => {
-  if (idsArg.size === 0 || dbArg.status !== 'connected' || !isSmartdataWriteRevisionsActive(dbArg)) return;
-  let state = revisionCompactions.get(dbArg);
-  if (!state) {
-    state = { entries: new Map(), running: new Map(), controller: new AbortController() };
-    revisionCompactions.set(dbArg, state);
-  }
-  const compactions = state;
-  for (const id of idsArg) {
-    const entries = (compactions.entries.get(id) ?? 0) + 1;
-    if (entries < compactionEntries || compactions.running.has(id)) {
-      compactions.entries.set(id, entries);
-      continue;
-    }
-    compactions.entries.delete(id);
-    const signal = compactions.controller.signal;
-    const compaction = compactWriteRevisionEntries(dbArg, id, signal)
-      .catch((errorArg) => {
-        if (signal.aborted) return;
-        logger.log('warn', `Compacting the write revisions of "${id}" failed; a later compaction retries: ${
-          errorArg instanceof Error ? errorArg.message : String(errorArg)}`);
-      })
-      .finally(() => { compactions.running.delete(id); });
-    compactions.running.set(id, compaction);
-  }
-};
-
-/** @internal Aborts the database's compactions and waits until they settled; `close()` calls it. */
-export const stopSmartdataWriteRevisionCompactions = async (dbArg: SmartdataDb): Promise<void> => {
-  const state = revisionCompactions.get(dbArg);
-  if (!state) return;
-  revisionCompactions.delete(dbArg);
-  state.controller.abort();
-  await Promise.allSettled(state.running.values());
-};
-
 /**
  * @internal The counters of the documents a write by selector is about to
  * change, read in its transaction before it runs. Snapshot isolation makes