@photon-grove/evt 0.1.2 → 0.2.0

package/dist/transaction.d.ts.map

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

package/dist/transaction.js

@@ -0,0 +1,207 @@
+// The Store's multi-stream transaction (ADR 0004 C1, C2): a read set of any aggregate types, the
+// events decided for some of them, and one atomic commit that fences every stream it read but
+// didn't write.
+import { EvtError } from './errors.js';
+import { emptyMetadata } from './metadata.js';
+import { checkNotReserved, } from './repository.js';
+import { commitSnapshot, copyMetadata, projectCommit, serializeEvents } from './staging.js';
+import { compareUtf8 } from './utf8.js';
+const MAX_INT64 = 2n ** 63n - 1n;
+/**
+ * A stream read into a {@link Transaction}, typed by its aggregate. Pass it to
+ * {@link Transaction.append} to stage events for it; a read never appended to is fenced at the
+ * head it was read at.
+ */
+export class StreamRead {
+    #stream;
+    /** @internal Built by {@link Transaction.read}. */
+    constructor(stream) {
+        this.#stream = stream;
+    }
+    get entityId() {
+        return this.#stream.loaded.entityId;
+    }
+    /** The state, with the events appended through this handle. */
+    get state() {
+        return this.#stream.state;
+    }
+    /** The sequence of the last event, with the events appended through this handle. */
+    get sequence() {
+        return this.#stream.loaded.sequence + BigInt(this.#stream.events.length);
+    }
+    /** The stream as it was read. */
+    get loaded() {
+        return this.#stream.loaded;
+    }
+}
+/**
+ * One atomic commit across several streams. {@link read} loads streams of any aggregate types,
+ * {@link append} stages the events decided for them, {@link fence} adds a fence the caller stamped
+ * on a stream it didn't read, and {@link commit} writes everything in one repository transaction,
+ * or nothing. A stream read but never appended to adds a fence the engine filled at the head it
+ * was read at, so the commit fails with a retryable `FenceConflictError` once another writer
+ * moves it. Begin one with {@link Store.transaction}.
+ *
+ * Every staging call checks its input before it changes anything, so one that throws leaves the
+ * transaction as it was. A transaction commits once: after {@link commit}, whatever it returned
+ * or threw, every call throws `invalidCommit`. Begin a new transaction to try again.
+ */
+export class Transaction {
+    #context;
+    #streams = new Map();
+    // Every stream read or being read, by ID, with the position of its read call.
+    #ids = new Map();
+    #fences = new Map();
+    #reads = 0;
+    #pending = 0;
+    #done = false;
+    /** @internal Begun by {@link Store.transaction}. */
+    constructor(context) {
+        this.#context = context;
+    }
+    /**
+     * Loads a stream into the read set, as {@link Store.load} does, and returns its typed handle.
+     * Reading a stream the transaction already read, or is reading, throws `invalidCommit`.
+     */
+    async read(aggregate, entityId, options = {}) {
+        this.#checkOpen();
+        if (this.#ids.has(entityId)) {
+            throw invalidCommit(`duplicate read of ${entityId}`);
+        }
+        // The ID is held while the load runs, so a concurrent read of the same stream is refused too,
+        // and the read keeps the place it was called in, whenever its load finishes.
+        const order = this.#reads++;
+        this.#ids.set(entityId, order);
+        this.#pending++;
+        let loaded;
+        try {
+            loaded = await this.#context.load(aggregate, entityId, options);
+        }
+        catch (error) {
+            this.#ids.delete(entityId);
+            throw error;
+        }
+        finally {
+            this.#pending--;
+        }
+        const stream = {
+            aggregate,
+            order,
+            loaded,
+            state: loaded.state,
+            events: [],
+        };
+        const read = new StreamRead(stream);
+        this.#streams.set(read, stream);
+        return read;
+    }
+    /**
+     * Stages events for a stream this transaction read. They're applied to the handle's state, and
+     * appending again continues the sequence. The commit stamps their metadata, and runs the
+     * aggregate's projectors over every event appended to the stream, with its final state. A
+     * handle from another transaction throws `invalidCommit`.
+     */
+    append(read, events) {
+        this.#checkOpen();
+        const stream = this.#streams.get(read);
+        if (stream === undefined) {
+            throw invalidCommit(`stream ${read.entityId} was not read by this transaction`);
+        }
+        // Serialized now, so an event the aggregate can't encode fails here, with nothing staged.
+        const after = stream.loaded.sequence + BigInt(stream.events.length);
+        const staged = serializeEvents(stream.aggregate, stream.loaded.entityId, after, stream.state, events, emptyMetadata());
+        stream.events.push(...staged.events);
+        stream.state = staged.state;
+        return this;
+    }
+    /**
+     * Adds a fence the caller stamped, for a stream the transaction doesn't read: the commit fails
+     * with a `FenceConflictError` once another writer moves the stream past `head`, which isn't
+     * retryable, since only the caller knows what it read. A fence on a stream the transaction reads,
+     * before or after the read, is dropped at commit: the read's own fence, or its write, holds the
+     * stream instead. A fence in a reserved namespace, at a head outside [0, 2^63 - 1), or on a
+     * stream already fenced throws, with nothing added.
+     */
+    fence(fence) {
+        this.#checkOpen();
+        checkNotReserved(fence.entityId);
+        if (fence.head < 0n || fence.head >= MAX_INT64 || this.#fences.has(fence.entityId)) {
+            throw invalidCommit(`invalid or duplicate fence ${fence.entityId}`);
+        }
+        this.#fences.set(fence.entityId, { ...fence });
+        return this;
+    }
+    /**
+     * Stamps one commit ID and the command's metadata on every appended event, and commits every
+     * stream with events, a fence on every stream read without any, and the caller's fences, in one
+     * atomic repository transaction. On failure nothing is written. A command ID that an event a
+     * read stream folded in since its latest snapshot already carries is a `duplicate`, and nothing
+     * is written. Projector operations follow the streams in the order they were read. A commit
+     * while a read is still loading throws `invalidCommit`, and leaves the transaction open.
+     */
+    async commit(options = {}) {
+        this.#checkOpen();
+        if (this.#pending > 0) {
+            throw invalidCommit('a read is still loading; await it before the commit');
+        }
+        this.#done = true;
+        const metadata = this.#context.metadata(options.metadata);
+        const commandId = metadata.commandId;
+        const streams = [...this.#streams.values()];
+        streams.sort((a, b) => a.order - b.order);
+        if (commandId !== null &&
+            commandId !== '' &&
+            streams.some((stream) => stream.loaded.seenCommandIds.has(commandId))) {
+            return { kind: 'duplicate', commandId };
+        }
+        const commits = [];
+        const fences = [];
+        for (const stream of streams) {
+            const { aggregate, loaded } = stream;
+            if (stream.events.length === 0) {
+                fences.push({
+                    entityId: loaded.entityId,
+                    entityType: aggregate.type,
+                    head: loaded.sequence,
+                    provenance: 'engine',
+                });
+                continue;
+            }
+            for (const event of stream.events) {
+                event.metadata = copyMetadata(metadata);
+            }
+            const interval = this.#context.snapshotInterval(aggregate);
+            const appended = stream.events.length;
+            const snapshot = commitSnapshot(aggregate, loaded.entityId, interval, loaded, appended, stream.state);
+            commits.push({
+                entityId: loaded.entityId,
+                events: stream.events,
+                snapshot,
+                projections: projectCommit(aggregate, loaded.entityId, stream.state, stream.events, snapshot),
+            });
+        }
+        // A caller's fence on a stream the transaction read is superseded by the read's own.
+        for (const fence of this.#fences.values()) {
+            if (!this.#ids.has(fence.entityId)) {
+                fences.push({ ...fence, provenance: 'caller' });
+            }
+        }
+        await this.#context.repository.commitTransaction({ streams: commits, fences }, options);
+        // Sorted apart from what the repository was given, which stays in read order.
+        const written = [...commits];
+        written.sort((a, b) => compareUtf8(a.entityId, b.entityId));
+        return {
+            kind: 'committed',
+            events: written.flatMap((commit) => commit.events),
+        };
+    }
+    #checkOpen() {
+        if (this.#done) {
+            throw invalidCommit('the transaction has committed; begin a new one');
+        }
+    }
+}
+function invalidCommit(message) {
+    return new EvtError('invalidCommit', `invalid commit: ${message}`);
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-grove/evt",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Event sourcing for TypeScript, wire-compatible with the Go and Rust evt implementations.",
   "keywords": [
     "event-sourcing",

package/src/dynamodb/head.ts

@@ -72,6 +72,21 @@ export function headUpdate(
   }
 }
 
+/** The condition of a fence on a stream with no head: it still has none. */
+export const FENCE_ABSENT_CONDITION = 'attribute_not_exists(head)'
+
+/** The condition of a fence on a stream with a head: it still equals the one observed. */
+export const FENCE_CONDITION = 'head = :head'
+
+/** The `ConditionCheck` a transaction fences a stream it read at `head` with. */
+export function headFence(entityId: string, head: bigint): HeadAction {
+  const check = {entityId, updateExpression: null, names: []}
+
+  return head === 0n
+    ? {...check, conditionExpression: FENCE_ABSENT_CONDITION, values: []}
+    : {...check, conditionExpression: FENCE_CONDITION, values: [[':head', head]]}
+}
+
 /**
  * An action's size in the commit budget, by the rule for any update, delete or condition check:
  * its key attributes plus its expression strings, name placeholders (the placeholder and the

package/src/dynamodb/index.ts

@@ -43,4 +43,5 @@ export {
   type SnapshotTtl,
   commitTransaction,
   snapshotTransaction,
+  transactionItems,
 } from './requests.js'

package/src/dynamodb/repository.ts

@@ -14,6 +14,7 @@ import {
   ConflictError,
   EvtError,
   FeatureManifestChangedError,
+  FenceConflictError,
   HistoryDependentProjectionError,
   RebuildInProgressError,
   SequenceGapError,
@@ -34,12 +35,17 @@ import {int64Argument} from '../fields.js'
 import {
   type CallOptions,
   type Commit,
-  type Repository,
+  type NormalizedTransaction,
   type StoreInitializer,
+  type TransactionCommit,
+  type TransactionalRepository,
   checkBudget,
+  checkFenceRetention,
   checkNotReserved,
-  commitSizes,
   isReserved,
+  normalizeTransaction,
+  rankFailures,
+  transactionSizes,
   validateCommit,
 } from '../repository.js'
 import type {DynamoClient, Page, RequestOptions, TransactItem} from './client.js'
@@ -57,10 +63,12 @@ import {FEATURES_PK, manifestFromItem, markerItem} from './marker.js'
 import {DYNAMODB_BACKEND, transactItemSize} from './views.js'
 import {
   type CommitTtl,
-  commitTransaction,
+  type StreamLayout,
+  type TransactionLayout,
   controlKey,
   headKey,
   projectorItems,
+  buildTransaction,
   snapshotTransaction,
 } from './requests.js'
 
@@ -121,7 +129,7 @@ const MAX_SNAPSHOT_GUARD_RETRIES = 4
  * declares a feature, the next write fails, validates the manifest again, and either refuses an
  * unsupported feature or fails once with a retryable {@link FeatureManifestChangedError}.
  */
-export class DynamoRepository implements Repository, StoreInitializer {
+export class DynamoRepository implements TransactionalRepository, StoreInitializer {
   readonly #client: DynamoClient
   readonly #table: string
   readonly #lazy: boolean
@@ -187,29 +195,64 @@ export class DynamoRepository implements Repository, StoreInitializer {
     options?.signal?.throwIfAborted()
     validateCommit(commit)
     checkNotReserved(commit.entityId)
-    if (commit.events.length === 0) {
-      return
+    if (commit.events.length > 0) {
+      await this.#write(normalizeTransaction({streams: [commit]}), options)
     }
+  }
 
-    // One `ttl` for the whole commit, so its head's is never below one of its own items.
-    const entityType = commit.events[0]!.entityType
-    const ttl = this.#ttlFor(entityType)
+  /**
+   * Commits every stream and checks every fence in one `TransactWriteItems` call: the control
+   * checks, the projector operations, each written stream's actions, then a check on each fenced
+   * stream's head. A fence on a type this repository retains is refused before any request, and
+   * one on a type the store's manifest retains after the marker's validation.
+   */
+  async commitTransaction(transaction: TransactionCommit, options?: CallOptions): Promise<void> {
+    options?.signal?.throwIfAborted()
+    const normalized = normalizeTransaction(transaction)
+    if (normalized.streams.length > 0 || normalized.fences.length > 0) {
+      await this.#write(normalized, options)
+    }
+  }
+
+  async #write(transaction: NormalizedTransaction, options?: CallOptions): Promise<void> {
+    // One `ttl` per entity type for the whole transaction, so a stream's head's is never below one
+    // of its own items.
+    const ttls = new Map<string, number | undefined>()
+    const ttlFor = (entityType: string): number | undefined => {
+      if (!ttls.has(entityType)) {
+        ttls.set(entityType, this.#ttlFor(entityType))
+      }
+
+      return ttls.get(entityType)
+    }
 
     // Every backend budgets a commit the same way, so an oversized one fails before any request.
     // The projector operations are sized from the actions this repository sends, which refuses a
     // group for another backend here too.
-    const sizes = projectorItems(commit).map(transactItemSize)
-    const group = {backend: DYNAMODB_BACKEND, operations: sizes, sizes}
-    const budgeted = {...commit, projections: [group]}
-    checkBudget(commitSizes(budgeted, (type) => (type === entityType ? ttl : undefined)))
+    const sizes = projectorItems(transaction.projections).map(transactItemSize)
+    const projections = [{backend: DYNAMODB_BACKEND, operations: sizes, sizes}]
+    checkBudget(transactionSizes({...transaction, projections}, ttlFor))
+
+    // A fence on a type this repository retains needs no request to refuse.
+    checkFenceRetention(transaction, (entityType) => this.#retention.has(entityType))
 
     const request = requestOptions(options)
     const version = await this.#markerVersion(request)
-    const items = commitTransaction(this.#table, commit, version, this.#commitTtl(commit, ttl))
+    if (transaction.fences.length > 0) {
+      // The store's manifest may retain a type this repository doesn't. The marker check holds it
+      // at the version read here, or fails the transaction.
+      const manifest = await this.#readManifest(request)
+      const retention = manifest?.retention ?? []
+      checkFenceRetention(transaction, (entityType) => retention.includes(entityType))
+    }
+
+    const {items, layout} = buildTransaction(this.#table, transaction, version, (commit) =>
+      this.#commitTtl(commit, ttlFor(commit.events[0]!.entityType)),
+    )
     try {
       await this.#client.transactWriteItems({TransactItems: items}, request)
     } catch (error) {
-      throw await this.#classifyCommit(commit, error, request)
+      throw await this.#classifyCommit(layout, error, request)
     }
   }
 
@@ -297,6 +340,12 @@ export class DynamoRepository implements Repository, StoreInitializer {
           if (codes?.some((code) => THROTTLED.has(code))) {
             throw new TransientError('the snapshot write was throttled', {cause: error})
           }
+          if (codes?.includes('TransactionConflict')) {
+            throw new TransientError(
+              `transaction conflict on ${snapshot.entityId}: another writer was committing at the same time`,
+              {cause: error},
+            )
+          }
 
           throw error
         }
@@ -520,7 +569,14 @@ export class DynamoRepository implements Repository, StoreInitializer {
     return new FeatureManifestChangedError({cause})
   }
 
-  async #classifyCommit(commit: Commit, error: unknown, request: RequestOptions): Promise<unknown> {
+  // Maps a cancelled transaction to the error it reports. The control checks outrank everything.
+  // Then every failed stream and fence is classified, and the ranking reports the first drift, else
+  // the first gap, else the first other failure, in transaction order.
+  async #classifyCommit(
+    layout: TransactionLayout,
+    error: unknown,
+    request: RequestOptions,
+  ): Promise<unknown> {
     const codes = cancellationCodes(error)
     if (codes === null) {
       return error
@@ -528,10 +584,14 @@ export class DynamoRepository implements Repository, StoreInitializer {
 
     const failed = codes.indexOf(CONDITION_FAILED)
     if (failed === -1) {
-      if (codes.includes('TransactionConflict')) {
-        return new ConflictError(
-          commit.entityId,
-          'transaction conflict: another writer was committing at the same time',
+      // Another transaction was writing one of the items, perhaps one this commit never changes
+      // (a control check): nothing was written and nothing is known to be stale, so it is
+      // transient, like throttling, and never a conflict, as in Go and Rust.
+      const colliding = codes.indexOf('TransactionConflict')
+      if (colliding !== -1) {
+        return new TransientError(
+          `transaction conflict on ${entityAt(layout, colliding)}: another writer was committing at the same time`,
+          {cause: error},
         )
       }
       if (codes.some((code) => THROTTLED.has(code))) {
@@ -549,17 +609,57 @@ export class DynamoRepository implements Repository, StoreInitializer {
       return new RebuildInProgressError()
     }
 
-    // The projector operations, then the stream's head update, its event puts and its snapshot
-    // put.
-    const projected = projectorItems(commit).length
-    const head = 2 + projected
-    const eventsEnd = head + 1 + commit.events.length
-    const eventFailed = codes.slice(head + 1, eventsEnd).includes(CONDITION_FAILED)
+    const failures: EvtError[] = []
+    for (const stream of layout.streams) {
+      const failure = await this.#streamFailure(stream, codes, request)
+      if (failure !== null) {
+        failures.push(failure)
+      }
+    }
+    for (const {index, fence} of layout.fences) {
+      if (codes[index] !== CONDITION_FAILED) {
+        continue
+      }
+
+      const verdict = await this.#probe(fence.entityId, false, request)
+      failures.push(
+        verdict.drift ?? new FenceConflictError(fence.entityId, fence.head, fence.provenance),
+      )
+    }
+
+    const ranked = rankFailures(failures)
+    if (ranked !== undefined) {
+      return ranked
+    }
+
+    // Only a projector operation's condition failed: its own error, as Go reports it.
+    if (failed < layout.projectorEnd) {
+      return error
+    }
+
+    return new ConflictError(
+      entityAt(layout, failed),
+      'conditional check failed: the sequence or snapshot changed since it was read',
+    )
+  }
+
+  // What a written stream contributes to a failed transaction, or null when none of its actions
+  // failed. A failed head update is classified by the probe. A head update that passed while an
+  // event put failed is an event above the head, unless retention explains it. A failed snapshot
+  // put alone is an ordinary conflict.
+  async #streamFailure(
+    stream: StreamLayout,
+    codes: string[],
+    request: RequestOptions,
+  ): Promise<EvtError | null> {
+    const {commit} = stream
     const {entityId} = commit
     const first = commit.events[0]!.sequence
     const retained = this.#retention.has(commit.events[0]!.entityType)
+    const eventFailed = codes.slice(stream.head + 1, stream.eventsEnd).includes(CONDITION_FAILED)
+    const snapshotFailed = stream.snapshot !== null && codes[stream.snapshot] === CONDITION_FAILED
 
-    if (codes[head] === CONDITION_FAILED) {
+    if (codes[stream.head] === CONDITION_FAILED) {
       const verdict = await this.#probe(entityId, retained, request)
       if (verdict.drift) {
         return verdict.drift
@@ -567,29 +667,26 @@ export class DynamoRepository implements Repository, StoreInitializer {
       if (verdict.healthy && first > 1n && verdict.stored < first - 1n) {
         return new SequenceGapError(entityId, verdict.stored, first)
       }
-    } else if (codes[head] === 'None' && eventFailed) {
-      // The head update passed and an event put failed: an event sits above the head. With
-      // retention, TTL can delete the head before an expired event, so a create passes its head
-      // condition and fails on the leftover item: a conflict until TTL deletes the rest.
-      // The probe already read the remaining items when it found the head item absent below the
-      // head its log derives; read them only if it didn't.
+
+      return conflict(entityId)
+    }
+
+    if (eventFailed && codes[stream.head] === 'None') {
+      // With retention, TTL can delete the head before an expired event, so a create passes its
+      // head condition and fails on the leftover item: a conflict until TTL deletes the rest. The
+      // probe already read the remaining items when it found the head item absent below the head
+      // its log derives; read them only if it didn't.
       const verdict = await this.#probe(entityId, retained, request)
       const expired =
         retained && (verdict.expired ?? (await this.#remainingItemsExpired(entityId, request)))
       if (!expired) {
         return verdict.drift ?? drift(entityId, verdict.head, verdict.derived)
       }
-    }
 
-    // Only a projector operation's condition failed: its own error, as Go reports it.
-    if (failed < head && !codes.slice(head).includes(CONDITION_FAILED)) {
-      return error
+      return conflict(entityId)
     }
 
-    return new ConflictError(
-      entityId,
-      'conditional check failed: the sequence or snapshot changed since it was read',
-    )
+    return eventFailed || snapshotFailed ? conflict(entityId) : null
   }
 
   // Classifies a stream whose head update failed, as the failure-path probe does: a stored head
@@ -983,6 +1080,30 @@ interface Verdict {
   expired?: boolean
 }
 
+function conflict(entityId: string): ConflictError {
+  return new ConflictError(
+    entityId,
+    'conditional check failed: the sequence or snapshot changed since it was read',
+  )
+}
+
+// The stream an action of a transaction belongs to, for a failure no stream check explains: the
+// written or fenced stream at that index, or else the transaction's first.
+function entityAt(layout: TransactionLayout, index: number): string {
+  for (const stream of layout.streams) {
+    if (index >= stream.head && (index < stream.eventsEnd || index === stream.snapshot)) {
+      return stream.commit.entityId
+    }
+  }
+
+  const fenced = layout.fences.find((each) => each.index === index)
+  if (fenced !== undefined) {
+    return fenced.fence.entityId
+  }
+
+  return layout.streams[0]?.commit.entityId ?? layout.fences[0]?.fence.entityId ?? ''
+}
+
 function drift(entityId: string, head: bigint | null, derived: bigint): StreamHeadDriftError {
   return new StreamHeadDriftError(entityId, head, derived)
 }