@alexify/migronaut 2.2.0 → 2.4.0

package/src/versioning/occ.js

@@ -0,0 +1,318 @@
+const { ConfigInvalidError, RevisionConflictError } = require('../errors/index.js');
+const {
+  resolveFieldNames,
+  resolveRevisionField,
+  revisionFilter,
+  revisionOf,
+  stampedUpdate,
+} = require('./document.js');
+const { filterTouches, isPlainObject, toCount } = require('./internal.js');
+
+/**
+ * Optimistic concurrency for a repository layer: a write that only lands if
+ * the document is still at the revision the caller read, and bumps it.
+ *
+ *   await updateWithRevision(orders, { _id }, order.__rev, { $set: { status } });
+ *
+ * matches `{ _id, __rev: order.__rev }` and adds `$inc: { __rev: 1 }`. When it
+ * matches nothing, someone else wrote in between (or the document is gone):
+ * a `RevisionConflictError` says which, and the caller re-reads and retries
+ * (`retryOnConflict`) or answers its own caller with a conflict.
+ *
+ * The collection is used structurally — anything with the driver's
+ * `updateOne`/`replaceOne`/`findOneAndUpdate`/`findOne`, a Mongoose model's
+ * collection included. Nothing here imports the driver.
+ */
+
+/** Options of ours, kept away from the driver */
+const OWN_OPTIONS = new Set(['field', 'revisionField', 'version', 'verify']);
+
+/** The write's options its explaining re-read takes along, to match the same way */
+const REREAD_OPTIONS = ['session', 'collation', 'hint', 'let'];
+
+/** `{ names, version, verify, driverOptions }` from the caller's options */
+function splitOptions(options = {}) {
+  if (!isPlainObject(options)) throw new ConfigInvalidError('options must be an object');
+  const driverOptions = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!OWN_OPTIONS.has(key)) driverOptions[key] = value;
+  }
+  if (driverOptions.upsert === true) {
+    throw new ConfigInvalidError(
+      'A revision-guarded write cannot upsert: a miss would insert a second document instead ' +
+        'of reporting the conflict',
+    );
+  }
+  const w = driverOptions.writeConcern?.w ?? driverOptions.w;
+  if (w === 0) {
+    throw new ConfigInvalidError(
+      'A revision-guarded write needs an acknowledged write concern — with w: 0 a conflict ' +
+        'cannot be seen',
+    );
+  }
+  // The version field matters only to a write that sets the version.
+  const names =
+    options.version === undefined && options.field === undefined
+      ? { field: null, revisionField: resolveRevisionField(options.revisionField) }
+      : resolveFieldNames({ field: options.field, revisionField: options.revisionField });
+  if (options.version !== undefined) assertCount(options.version, 'version');
+  return { names, version: options.version, verify: options.verify !== false, driverOptions };
+}
+
+function assertCount(value, what) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new ConfigInvalidError(`${what} must be an integer ≥ 0`, { [what]: value });
+  }
+}
+
+/**
+ * The revision the caller read, as a number: an Int32, a Long or a bigint
+ * (a document read with `promoteValues: false`, or `useBigInt64`) counts too.
+ */
+function expectedOf(expected) {
+  const count = toCount(expected);
+  if (count === null) {
+    throw new ConfigInvalidError('expectedRevision must be an integer ≥ 0', {
+      expectedRevision: typeof expected,
+    });
+  }
+  return count;
+}
+
+/** An `_id` given as an operator — anything but a single `$eq` of a value */
+function operatorId(id) {
+  if (!isPlainObject(id)) return false;
+  const keys = Object.keys(id);
+  if (keys.length === 1 && keys[0] === '$eq') return operatorId(id.$eq);
+  for (const key of keys) if (key.startsWith('$')) return true;
+  return false;
+}
+
+/**
+ * The caller's filter, refused if it already constrains the revision, plus
+ * ours. A revision guards one document: an `_id` given as an operator
+ * (`{ $ne: null }` from a request body, say) would let it land on whichever
+ * document is at that revision — every legacy one is at 0 — so it is refused.
+ */
+function guardedFilter(filter, names, expected) {
+  if (!isPlainObject(filter)) throw new ConfigInvalidError('filter must be an object');
+  if (operatorId(filter._id)) {
+    throw new ConfigInvalidError(
+      'filter._id must be a value, not an operator — a revision guards one document',
+    );
+  }
+  if (filterTouches(filter, names.revisionField)) {
+    throw new ConfigInvalidError(
+      `The filter must not constrain "${names.revisionField}" — pass the revision as ` +
+        'expectedRevision',
+    );
+  }
+  return { ...filter, ...revisionFilter(names, expected) };
+}
+
+/**
+ * A miss, explained: read the document without the revision guard and say
+ * whether it moved on (`conflict`, with `actual`), is gone (`not-found`), or
+ * cannot be told (`unknown` — the read was turned off, or it failed). The
+ * filter itself never goes into the error: it may carry PII.
+ */
+async function conflictError(collection, filter, names, expected, { verify, driverOptions }) {
+  const context = { expected, reason: 'unknown' };
+  if (collection?.collectionName !== undefined) context.collection = collection.collectionName;
+  if (verify) {
+    try {
+      // Matched the way the write matched (its collation, hint, variables),
+      // on the primary: a secondary may not have seen the write that won.
+      const read = { projection: { [names.revisionField]: 1 }, readPreference: 'primary' };
+      for (const key of REREAD_OPTIONS) {
+        if (driverOptions[key] !== undefined) read[key] = driverOptions[key];
+      }
+      const current = await collection.findOne(filter, read);
+      if (current === null || current === undefined) {
+        context.reason = 'not-found';
+      } else {
+        const actual = revisionOf(current, names.revisionField);
+        // The same revision again means the guard missed on something else.
+        if (actual !== expected) {
+          context.reason = 'conflict';
+          context.actual = actual;
+        }
+      }
+    } catch {
+      // `unknown` it stays.
+    }
+  }
+  const what =
+    context.reason === 'conflict'
+      ? `is at revision ${context.actual}, not ${expected}`
+      : context.reason === 'not-found'
+        ? 'does not exist'
+        : `was not at revision ${expected}, or no longer exists`;
+  return new RevisionConflictError(`Revision conflict: the document ${what}`, context);
+}
+
+/**
+ * `updateOne` guarded by the revision the caller read: `expectedRevision` is
+ * `doc.__rev` (0 for a document without one). The update is an operator
+ * document or a pipeline; the revision is bumped, and `version` (when given)
+ * set. Returns the driver's result plus `revision`, the new one.
+ *
+ * @throws {RevisionConflictError} when nothing matched
+ * @throws {ConfigInvalidError} on an upsert, a `w: 0` write, a filter or an
+ *   update that handles the revision itself, or a replacement document
+ */
+async function updateWithRevision(collection, filter, expectedRevision, update, options) {
+  const { names, version, verify, driverOptions } = splitOptions(options);
+  const expected = expectedOf(expectedRevision);
+  const guarded = guardedFilter(filter, names, expected);
+  const stamped = stampedUpdate(names, { to: version, update });
+  const result = await collection.updateOne(guarded, stamped, driverOptions);
+  assertAcknowledged(result);
+  if (result.matchedCount === 0) {
+    throw await conflictError(collection, filter, names, expected, { verify, driverOptions });
+  }
+  return { ...result, revision: expected + 1 };
+}
+
+/**
+ * An unacknowledged write (`w: 0` from the collection's or the client's
+ * defaults, which no option of the call shows) reports no match count — it
+ * cannot be told from a success, so it is refused after the fact.
+ */
+function assertAcknowledged(result) {
+  if (result?.acknowledged === false || typeof result?.matchedCount !== 'number') {
+    throw new ConfigInvalidError(
+      'A revision-guarded write needs an acknowledged write concern — this one was not ' +
+        "acknowledged (w: 0 from the collection's or the client's defaults?)",
+    );
+  }
+}
+
+/** A plain document none of whose top-level keys is an operator */
+function isReplacement(value) {
+  if (!isPlainObject(value)) return false;
+  for (const key of Object.keys(value)) if (key.startsWith('$')) return false;
+  return true;
+}
+
+/**
+ * `replaceOne` guarded by the revision the caller read. The replacement's
+ * own revision field (usually the stale one it was read with) is overwritten
+ * with the next revision; `version`, when given, sets the version field.
+ *
+ * @throws {RevisionConflictError} when nothing matched
+ */
+async function replaceWithRevision(collection, filter, expectedRevision, replacement, options) {
+  const { names, version, verify, driverOptions } = splitOptions(options);
+  const expected = expectedOf(expectedRevision);
+  if (!isReplacement(replacement)) {
+    throw new ConfigInvalidError(
+      'The replacement must be a plain document without update operators',
+    );
+  }
+  const guarded = guardedFilter(filter, names, expected);
+  const document = { ...replacement, [names.revisionField]: expected + 1 };
+  if (version !== undefined) document[names.field] = version;
+  const result = await collection.replaceOne(guarded, document, driverOptions);
+  assertAcknowledged(result);
+  if (result.matchedCount === 0) {
+    throw await conflictError(collection, filter, names, expected, { verify, driverOptions });
+  }
+  return { ...result, revision: expected + 1 };
+}
+
+/**
+ * `findOneAndUpdate` guarded by the revision the caller read. Returns the
+ * document — after the update by default (`returnDocument: 'before'` to get
+ * the old one) — the same way on every driver version: the raw result is
+ * always requested with its metadata and unwrapped here.
+ *
+ * @throws {RevisionConflictError} when nothing matched
+ */
+async function findOneAndUpdateWithRevision(collection, filter, expectedRevision, update, options) {
+  const { names, version, verify, driverOptions } = splitOptions(options);
+  const expected = expectedOf(expectedRevision);
+  const guarded = guardedFilter(filter, names, expected);
+  const stamped = stampedUpdate(names, { to: version, update });
+  const result = await collection.findOneAndUpdate(guarded, stamped, {
+    returnDocument: 'after',
+    ...driverOptions,
+    includeResultMetadata: true,
+  });
+  const value = result?.value ?? null;
+  if (value === null) {
+    throw await conflictError(collection, filter, names, expected, { verify, driverOptions });
+  }
+  return value;
+}
+
+/** Full-jitter exponential backoff: anywhere up to `min(maxMs, baseMs · 2^attempt)` */
+function jitter({ baseMs = 10, maxMs = 1000 } = {}) {
+  return (attempt) => Math.random() * Math.min(maxMs, baseMs * 2 ** attempt);
+}
+
+const sleep = (ms, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+/**
+ * Run `fn(attempt)` — which reads, decides and writes with a revision guard —
+ * again after a conflict, up to `attempts` times in all (default 3), with a
+ * full-jitter backoff between tries. A `not-found` is never retried: the
+ * document is gone, and reading it again will not bring it back. Anything
+ * that is not a `RevisionConflictError` is thrown at once.
+ *
+ * `backoff` is `{ baseMs, maxMs }` (default 10 and 1000) or a function of
+ * the attempt number returning milliseconds; `signal` cuts a wait short.
+ */
+async function retryOnConflict(fn, { attempts = 3, backoff, signal } = {}) {
+  if (typeof fn !== 'function') throw new ConfigInvalidError('retryOnConflict needs a function');
+  if (!Number.isSafeInteger(attempts) || attempts < 1) {
+    throw new ConfigInvalidError('attempts must be an integer ≥ 1', { attempts });
+  }
+  const delay = typeof backoff === 'function' ? backoff : jitter(backoff);
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      const retryable =
+        error instanceof RevisionConflictError && error.context?.reason !== 'not-found';
+      if (!retryable || attempt + 1 >= attempts) throw error;
+      await sleep(delay(attempt), signal);
+    }
+  }
+}
+
+/**
+ * `update` with the revision bumped — for a write that is not guarded by a
+ * revision but must still move it. In a collection with revisions every write
+ * has to: a write that leaves the revision alone is one an optimistic
+ * filter — the application's, or a background migration's — cannot see.
+ */
+function bumpRevision(update, { revisionField } = {}) {
+  return stampedUpdate(
+    { field: null, revisionField: resolveRevisionField(revisionField) },
+    { update },
+  );
+}
+
+module.exports = {
+  bumpRevision,
+  findOneAndUpdateWithRevision,
+  replaceWithRevision,
+  retryOnConflict,
+  updateWithRevision,
+};

package/src/versioning/registry.js

@@ -0,0 +1,187 @@
+const { ConfigInvalidError, ShapeVersionError } = require('../errors/index.js');
+const { resolveVersioning } = require('./config.js');
+const { refuseTouch, stampDocument, versionOf } = require('./document.js');
+const { isPlainObject, touchedFields, unwrapDefinition } = require('./internal.js');
+const { applyVersioningPlugin } = require('./mongoose.js');
+const {
+  bumpRevision,
+  findOneAndUpdateWithRevision,
+  replaceWithRevision,
+  updateWithRevision,
+} = require('./occ.js');
+const { createUpcaster } = require('./upcaster.js');
+
+/**
+ * `defineShapes` — the application's view of its versioned collections, read
+ * from the very definition files converge declares them with:
+ *
+ *   const shapes = defineShapes({ orders: require('./collections/orders') });
+ *   await orders.insertOne(shapes.stamp('orders', doc)); // __v: current, __rev: 0
+ *
+ * so the version a repository writes and the version the validator demands
+ * can never drift apart.
+ */
+
+/** `[name, definition]` pairs from a `{ name: definition }` map or a definition list */
+function entriesOf(definitions) {
+  if (Array.isArray(definitions)) {
+    const entries = [];
+    for (const [position, item] of definitions.entries()) {
+      const definition = unwrapDefinition(item);
+      if (!isPlainObject(definition) || typeof definition.name !== 'string') {
+        throw new ConfigInvalidError(
+          `defineShapes: definitions[${position}] needs a name — or pass { name: definition }`,
+        );
+      }
+      // A collections list may hold unversioned collections too.
+      if (definition.versioning !== undefined) entries.push([definition.name, definition]);
+    }
+    return entries;
+  }
+  if (!isPlainObject(definitions)) {
+    throw new ConfigInvalidError(
+      'defineShapes takes { name: definition } or an array of definitions with a name',
+    );
+  }
+  const entries = [];
+  for (const [name, definition] of Object.entries(definitions)) {
+    const resolved = unwrapDefinition(definition);
+    if (!isPlainObject(resolved) || resolved.versioning === undefined) {
+      throw new ConfigInvalidError(`defineShapes: "${name}" declares no versioning`);
+    }
+    entries.push([name, resolved]);
+  }
+  return entries;
+}
+
+/**
+ * Called without arguments — `defineShapes<Shapes>()(definitions)` — it
+ * returns itself: TypeScript then takes the shape map from the first call
+ * and infers the definitions from the second. Nothing changes at run time.
+ */
+function defineShapes(definitions) {
+  if (arguments.length === 0) return (defs) => defineShapes(defs);
+  const registry = new Map();
+  for (const [name, definition] of entriesOf(definitions)) {
+    if (registry.has(name)) {
+      throw new ConfigInvalidError(`defineShapes: "${name}" is declared twice`);
+    }
+    registry.set(name, resolveVersioning(definition.versioning, { path: `${name}.versioning` }));
+  }
+  const names = Object.freeze([...registry.keys()]);
+
+  const get = (name) => {
+    const versioning = registry.get(name);
+    if (versioning === undefined) {
+      throw new ConfigInvalidError(
+        `"${name}" is not a versioned collection (known: ${names.join(', ') || 'none'})`,
+        { collection: name },
+      );
+    }
+    return versioning;
+  };
+
+  const docVersion = (name, doc) => {
+    const versioning = get(name);
+    const version = versionOf(doc, versioning.field);
+    if (version === null) {
+      throw new ShapeVersionError(
+        `${name}: the document's ${versioning.field} is not a non-negative integer`,
+        { collection: name, reason: 'invalid', current: versioning.current },
+      );
+    }
+    return version;
+  };
+
+  const stamp = (name, doc) => {
+    const versioning = get(name);
+    return stampDocument(doc, versioning, versioning.current);
+  };
+
+  return Object.freeze({
+    names,
+    has: (name) => registry.has(name),
+    get,
+    current: (name) => get(name).current,
+    versionOf: docVersion,
+    isCurrent: (name, doc) => docVersion(name, doc) === get(name).current,
+    isVersion: (name, doc, version) => docVersion(name, doc) === version,
+    stamp,
+    /** The Mongoose plugin for this collection: `schema.plugin(shapes.plugin('orders'))` */
+    plugin: (name) => {
+      const versioning = get(name);
+      return (schema) => applyVersioningPlugin(schema, versioning);
+    },
+    /** An upcaster over this collection's versioning — see upcaster.js */
+    upcaster: (name, steps, options) =>
+      createUpcaster(get(name), steps, { ...options, collection: name }),
+    /**
+     * The revision guards bound to this collection's field names, so no call
+     * can forget them — a custom `revisionField` left out of one write would
+     * guard nothing (no document has `__rev`, so the filter matches them all).
+     */
+    occ: (name) => {
+      const { field, revisionField } = get(name);
+      if (revisionField === null) {
+        throw new ConfigInvalidError(
+          `"${name}" declares revision: false — it has no revision to guard`,
+          { collection: name },
+        );
+      }
+      const bound = (options = {}) => {
+        if (!isPlainObject(options)) throw new ConfigInvalidError('options must be an object');
+        for (const [key, value] of [
+          ['field', field],
+          ['revisionField', revisionField],
+        ]) {
+          if (options[key] !== undefined && options[key] !== value) {
+            throw new ConfigInvalidError(
+              `${name}: ${key} is "${value}" — the guards bound to it take no other`,
+              { collection: name, [key]: options[key] },
+            );
+          }
+        }
+        return { ...options, field, revisionField };
+      };
+      return Object.freeze({
+        // Async, like the helpers: a refused option rejects, it does not throw.
+        updateWithRevision: async (collection, filter, expected, update, options) =>
+          updateWithRevision(collection, filter, expected, update, bound(options)),
+        replaceWithRevision: async (collection, filter, expected, replacement, options) =>
+          replaceWithRevision(collection, filter, expected, replacement, bound(options)),
+        findOneAndUpdateWithRevision: async (collection, filter, expected, update, options) =>
+          findOneAndUpdateWithRevision(collection, filter, expected, update, bound(options)),
+        bumpRevision: (update) => bumpRevision(update, { revisionField }),
+      });
+    },
+    /** `stamp` for one document or every document of an array — for `insertMany` */
+    onInsert: (name, docs) =>
+      Array.isArray(docs) ? docs.map((doc) => stamp(name, doc)) : stamp(name, docs),
+    /**
+     * An upsert's update with the stamp of a document it may insert: the
+     * version on `$setOnInsert` (unless the update sets it itself) and the
+     * revision bumped — an inserted document starts at revision 1. A
+     * replacement or a pipeline is refused: `$setOnInsert` has no place there.
+     */
+    stampUpsert: (name, update) => {
+      const versioning = get(name);
+      if (Array.isArray(update) || !isPlainObject(update)) {
+        throw new ConfigInvalidError('stampUpsert takes an operator update, not a pipeline');
+      }
+      const { fields, whole } = touchedFields(update);
+      if (whole) {
+        throw new ConfigInvalidError('stampUpsert takes an operator update, not a replacement');
+      }
+      const { field, revisionField } = versioning;
+      refuseTouch(fields, revisionField, 'revision');
+      const out = { ...update };
+      if (!fields.has(field)) {
+        out.$setOnInsert = { ...update.$setOnInsert, [field]: versioning.current };
+      }
+      if (revisionField !== null) out.$inc = { ...update.$inc, [revisionField]: 1 };
+      return out;
+    },
+  });
+}
+
+module.exports = { defineShapes };