@photon-grove/evt 0.0.0-stage → 0.1.0

package/src/dynamodb/item.ts

@@ -0,0 +1,332 @@
+// The DynamoDB item layout of the event log. It's pure: it shapes items the way the AWS SDK's
+// low-level client takes them, and imports nothing from the SDK.
+//
+// | Attribute    | Type | Event item     | Snapshot item (sk 0) | Head item (sk -1) |
+// | ------------ | ---- | -------------- | -------------------- | ----------------- |
+// | `pk`         | S    | entity ID      | entity ID            | entity ID         |
+// | `sk`         | N    | event sequence | `0`                  | `-1`              |
+// | `type`       | S    | event type     |                      |                   |
+// | `version`    | N    | event version  |                      |                   |
+// | `entityType` | S    | entity type    | entity type          |                   |
+// | `payload`    | S    | payload JSON   | state JSON           |                   |
+// | `metadata`   | S    | metadata JSON  |                      |                   |
+// | `seq`        | N    |                | snapshot sequence    |                   |
+// | `eventSeq`   | N    |                | last event folded in |                   |
+// | `head`       | N    |                |                      | highest sequence  |
+// | `ttl`        | N    | optional       | optional             | optional          |
+
+import {type SerializedEvent, type SerializedSnapshot, eventId} from '../event.js'
+import {EvtError} from '../errors.js'
+import {
+  DOCUMENT,
+  checkInt64,
+  int64Argument,
+  invalid,
+  safeIntegerArgument,
+} from '../fields.js'
+import {parseJson} from '../json.js'
+import {encodeMetadata, metadataFromJson} from '../metadata.js'
+import {utf8Decode, utf8Encode, utf8Length} from '../utf8.js'
+
+/** A DynamoDB attribute value, shaped like the SDK's `AttributeValue`. */
+export type AttributeValue =
+  | {S: string}
+  | {N: string}
+  | {B: Uint8Array}
+  | {BOOL: boolean}
+  | {NULL: boolean}
+  | {M: Item}
+  | {L: AttributeValue[]}
+  | {SS: string[]}
+  | {NS: string[]}
+  | {BS: Uint8Array[]}
+
+/** A DynamoDB item. */
+export type Item = Record<string, AttributeValue>
+
+/** The sort key of a stream's inline snapshot. */
+export const SNAPSHOT_SORT_KEY = 0n
+
+/** The sort key of a stream's head item. */
+export const HEAD_SORT_KEY = -1n
+
+/** The sort key of a single-item view row. */
+export const DEFAULT_VIEW_SORT_KEY = 'VIEW'
+
+/** Encodes an event as an event-log item. `ttl` (Unix seconds) is written only when positive. */
+export function eventItem(event: SerializedEvent, ttl?: number): Item {
+  return withTtl(
+    {
+      pk: {S: event.entityId},
+      sk: {N: int64Argument(event.sequence, 'event.sequence').toString()},
+      type: {S: event.type},
+      version: {N: safeIntegerArgument(event.version, 'event.version').toString()},
+      entityType: {S: event.entityType},
+      payload: {S: payloadText(event.payload, 'event payload')},
+      metadata: {S: encodeMetadata(event.metadata)},
+    },
+    ttl,
+  )
+}
+
+/** Encodes a stream's inline snapshot item. `ttl` is written only when positive. */
+export function snapshotItem(snapshot: SerializedSnapshot, ttl?: number): Item {
+  return withTtl(
+    {
+      pk: {S: snapshot.entityId},
+      sk: {N: SNAPSHOT_SORT_KEY.toString()},
+      seq: {N: int64Argument(snapshot.sequence, 'snapshot.sequence').toString()},
+      eventSeq: {N: int64Argument(snapshot.eventSequence, 'snapshot.eventSequence').toString()},
+      entityType: {S: snapshot.entityType},
+      payload: {S: payloadText(snapshot.payload, 'snapshot payload')},
+    },
+    ttl,
+  )
+}
+
+/** Encodes a stream's head item. `ttl` is written only when positive. */
+export function headItem(entityId: string, head: bigint, ttl?: number): Item {
+  const item: Item = {
+    pk: {S: entityId},
+    sk: {N: HEAD_SORT_KEY.toString()},
+    head: {N: int64Argument(head, 'head').toString()},
+  }
+
+  return withTtl(item, ttl)
+}
+
+/** Encodes a single-item view row: `pk = {entityType}#{entityId}`, `sk = "VIEW"`. */
+export function viewItem(entityType: string, entityId: string, payload: Uint8Array): Item {
+  return {
+    pk: {S: `${entityType}#${entityId}`},
+    sk: {S: DEFAULT_VIEW_SORT_KEY},
+    entityID: {S: entityId},
+    entityType: {S: entityType},
+    payload: {S: payloadText(payload, 'view payload')},
+  }
+}
+
+/**
+ * Decodes an event-log item. Missing attributes other than the key are empty, and `metadata` must
+ * be present and not blank. A JSON `null` metadata is the zero value, as in Go.
+ */
+export function eventFromItem(item: Item): SerializedEvent {
+  const entityId = requiredString(item, 'pk')
+  const sequence = requiredNumber(item, 'sk')
+  const id = eventId(entityId, sequence)
+  const metadata = optionalString(item, 'metadata') ?? ''
+  if (metadata.trim() === '') {
+    throw invalid(`event ${id} has empty metadata`)
+  }
+
+  let decoded
+  try {
+    decoded = metadataFromJson(parseJson(metadata, DOCUMENT))
+  } catch (error) {
+    throw new EvtError('invalidRecord', `event ${id} metadata: ${message(error)}`, {cause: error})
+  }
+
+  return {
+    id,
+    sequence,
+    type: optionalString(item, 'type') ?? '',
+    version: safeInteger(optionalNumber(item, 'version') ?? 0n, 'version'),
+    entityId,
+    entityType: optionalString(item, 'entityType') ?? '',
+    payload: utf8Encode(optionalString(item, 'payload') ?? ''),
+    metadata: decoded,
+  }
+}
+
+/** Decodes a stream's inline snapshot item. */
+export function snapshotFromItem(item: Item): SerializedSnapshot {
+  return {
+    entityType: optionalString(item, 'entityType') ?? '',
+    entityId: requiredString(item, 'pk'),
+    sequence: optionalNumber(item, 'seq') ?? 0n,
+    eventSequence: optionalNumber(item, 'eventSeq') ?? 0n,
+    payload: utf8Encode(optionalString(item, 'payload') ?? ''),
+  }
+}
+
+/** Decodes a head item into its head and its `ttl`, if it has one. */
+export function headFromItem(item: Item): {head: bigint; ttl: number | undefined} {
+  const ttl = optionalNumber(item, 'ttl')
+
+  return {
+    head: requiredNumber(item, 'head'),
+    ttl: ttl === undefined ? undefined : safeInteger(ttl, 'ttl'),
+  }
+}
+
+/** Whether an item is a stream's inline snapshot (`sk = 0`). */
+export function isSnapshotItem(item: Item): boolean {
+  return sortKey(item) === SNAPSHOT_SORT_KEY
+}
+
+/** An item's numeric sort key, if it has one. */
+export function sortKey(item: Item): bigint | undefined {
+  const sk = item['sk']
+  if (sk === undefined || !('N' in sk)) {
+    return undefined
+  }
+
+  return parseNumber(sk.N)
+}
+
+/**
+ * The `ttl` of an item written at `nowMs` (Unix milliseconds) under a retention of `retentionMs`:
+ * their sum in whole Unix seconds, rounded down after adding, as Go's `Time.Add(...).Unix()` is.
+ * Undefined, so no `ttl` is written, for a zero retention. A retention with a fraction of a
+ * millisecond is refused, because Go would count it.
+ */
+export function expiry(nowMs: number, retentionMs: number): number | undefined {
+  if (!Number.isSafeInteger(nowMs) || !Number.isSafeInteger(retentionMs) || retentionMs < 0) {
+    throw new EvtError(
+      'invalidArgument',
+      'the clock and the retention must be whole, non-negative milliseconds: ' +
+        `${nowMs}, ${retentionMs}`,
+    )
+  }
+  if (retentionMs === 0) {
+    return undefined
+  }
+
+  return Math.floor((nowMs + retentionMs) / 1000)
+}
+
+/**
+ * The size DynamoDB counts for an item: each attribute's name plus its value, in UTF-8 bytes. The
+ * commit budget measures every action with it.
+ */
+export function itemSize(item: Item): number {
+  let size = 0
+  for (const [name, value] of Object.entries(item)) {
+    size += utf8Length(name) + valueSize(value)
+  }
+
+  return size
+}
+
+function valueSize(value: AttributeValue): number {
+  if ('S' in value) {
+    return utf8Length(value.S)
+  }
+  if ('N' in value) {
+    return utf8Length(value.N)
+  }
+  if ('B' in value) {
+    return value.B.length
+  }
+  if ('BOOL' in value || 'NULL' in value) {
+    return 1
+  }
+  if ('M' in value) {
+    return 3 + itemSize(value.M) + Object.keys(value.M).length
+  }
+  if ('L' in value) {
+    return value.L.reduce((size, entry) => size + 1 + valueSize(entry), 3)
+  }
+  if ('SS' in value) {
+    return value.SS.reduce((size, entry) => size + utf8Length(entry), 0)
+  }
+  if ('NS' in value) {
+    return value.NS.reduce((size, entry) => size + utf8Length(entry), 0)
+  }
+
+  return value.BS.reduce((size, entry) => size + entry.length, 0)
+}
+
+function withTtl(item: Item, ttl: number | undefined): Item {
+  if (ttl !== undefined && safeIntegerArgument(ttl, 'ttl') > 0) {
+    item['ttl'] = {N: ttl.toString()}
+  }
+
+  return item
+}
+
+// A payload is stored as a DynamoDB string, so it must be UTF-8. A null payload is stored empty.
+function payloadText(payload: Uint8Array | null, what: string): string {
+  if (payload === null) {
+    return ''
+  }
+
+  try {
+    return utf8Decode(payload, what)
+  } catch (error) {
+    const reason = `${what} is not valid UTF-8 and cannot be stored as a string`
+    throw new EvtError('invalidArgument', reason, {cause: error})
+  }
+}
+
+function requiredString(item: Item, name: string): string {
+  const value = optionalString(item, name)
+  if (value === undefined) {
+    throw invalid(`item has no ${name} attribute`)
+  }
+
+  return value
+}
+
+function requiredNumber(item: Item, name: string): bigint {
+  const value = optionalNumber(item, name)
+  if (value === undefined) {
+    throw invalid(`item has no ${name} attribute`)
+  }
+
+  return value
+}
+
+function optionalString(item: Item, name: string): string | undefined {
+  const value = item[name]
+  if (value === undefined || 'NULL' in value) {
+    return undefined
+  }
+  if (!('S' in value)) {
+    throw invalid(`attribute ${name} is not a string`)
+  }
+
+  return value.S
+}
+
+function optionalNumber(item: Item, name: string): bigint | undefined {
+  const value = item[name]
+  if (value === undefined || 'NULL' in value) {
+    return undefined
+  }
+  if (!('N' in value)) {
+    throw invalid(`attribute ${name} is not a number`)
+  }
+
+  const number = parseNumber(value.N)
+  if (number === undefined) {
+    throw invalid(`attribute ${name} is not an integer: ${value.N}`)
+  }
+
+  return number
+}
+
+// An int64 in decimal, as strconv.ParseInt reads it: an optional sign, then digits.
+function parseNumber(text: string): bigint | undefined {
+  if (!/^[+-]?\d+$/.test(text)) {
+    return undefined
+  }
+
+  try {
+    return checkInt64(BigInt(text), 'number')
+  } catch {
+    return undefined
+  }
+}
+
+function safeInteger(value: bigint, name: string): number {
+  if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw invalid(`attribute ${name} is ${value}, past the integers it holds`)
+  }
+
+  return Number(value)
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/envelope.ts

@@ -0,0 +1,67 @@
+// The stream envelope: the EventBridge-style message around each committed event, which consumers
+// in every language unwrap. Go decodes it with projectors.StreamRecordFromEnvelope.
+
+import {type SerializedEvent, eventFromJson, encodeEvent} from './event.js'
+import {DOCUMENT, invalid, objectOrNull} from './fields.js'
+import {RawJson, parseJson, stringifyJson} from './json.js'
+
+// Go's zero time.Time, which the publisher left in the time field.
+const ZERO_TIME = '0001-01-01T00:00:00Z'
+
+/** Encodes the envelope for an event, byte for byte as the Go publisher wrote it. */
+export function encodeEnvelope(event: SerializedEvent, source: string): string {
+  return stringifyJson({
+    version: '',
+    id: event.id,
+    'detail-type': event.type,
+    source,
+    account: '',
+    time: ZERO_TIME,
+    region: '',
+    resources: null,
+    detail: new RawJson(encodeEvent(event)),
+  })
+}
+
+/**
+ * Decodes the event from an envelope body: an SNS message, or an SQS body delivered raw. An event
+ * with no entity ID or event ID is refused.
+ */
+export function decodeEnvelope(body: string): SerializedEvent {
+  const envelope = objectOrNull(parseJson(body, DOCUMENT), 'envelope') ?? new Map()
+  const event = eventFromJson(objectOrNull(envelope.get('detail'), 'envelope.detail'))
+  if (event.entityId === '') {
+    throw invalid('event envelope has no entity id')
+  }
+  if (event.id === '') {
+    throw invalid('event envelope has no event id')
+  }
+
+  return event
+}
+
+/**
+ * The message attributes the publisher set, all strings: `entityType` and `eventType`, then
+ * `commandId` and `traceparent` when they aren't empty, and `correlationId`, the command ID or
+ * else the traceparent.
+ */
+export function messageAttributes(event: SerializedEvent): Record<string, string> {
+  const attributes: Record<string, string> = {
+    entityType: event.entityType,
+    eventType: event.type,
+  }
+
+  const commandId = event.metadata.commandId
+  if (commandId !== null && commandId !== '') {
+    attributes['commandId'] = commandId
+    attributes['correlationId'] = commandId
+  }
+
+  const traceparent = event.metadata.trace?.get('traceparent')
+  if (traceparent !== undefined && traceparent !== '') {
+    attributes['traceparent'] = traceparent
+    attributes['correlationId'] ??= traceparent
+  }
+
+  return attributes
+}

package/src/errors.ts

@@ -0,0 +1,214 @@
+// Every failure evt throws is an EvtError with a code, as the Rust crate returns its Error enum.
+// Domain outcomes (a rejected command, a duplicate) are values, never errors. A failure with
+// details has its own subclass, so `instanceof` narrows to its fields.
+
+/**
+ * What went wrong:
+ *
+ * - `invalidJson`: text that isn't JSON.
+ * - `invalidRecord`: a stored record (an event, a snapshot, an item) with the wrong shape.
+ * - `invalidArgument`: a value evt can't write, such as a float that isn't finite or an object
+ *   whose key order the engine has already changed, or a read with a bad argument, such as
+ *   `latest(0)`.
+ * - `invalidCommit`: a commit built wrong, such as one with another entity's event. Nothing was
+ *   written.
+ * - `conflict`: optimistic concurrency failed. Another writer committed since the stream was
+ *   read. Reload and run the command again.
+ * - `sequenceGap`: a commit or a load skips a sequence. A conflict.
+ * - `streamHeadDrift`: a stream's head disagrees with its events or snapshot. Never retried.
+ * - `commitTooLarge`: the commit is over the transaction budget. Nothing was written.
+ * - `compactionUncovered`: no snapshot covers the events compaction was asked to delete.
+ * - `reservedEntityId`: a write to an entity ID in a namespace only the engine writes.
+ * - `replay`: a stored event failed to upcast or decode while an aggregate loaded.
+ * - `snapshot`: a stored snapshot failed to decode while an aggregate loaded.
+ */
+export type EvtErrorCode =
+  | 'invalidJson'
+  | 'invalidRecord'
+  | 'invalidArgument'
+  | 'invalidCommit'
+  | 'conflict'
+  | 'sequenceGap'
+  | 'streamHeadDrift'
+  | 'commitTooLarge'
+  | 'compactionUncovered'
+  | 'reservedEntityId'
+  | 'replay'
+  | 'snapshot'
+
+export class EvtError extends Error {
+  override readonly name: string = 'EvtError'
+  readonly code: EvtErrorCode
+
+  constructor(code: EvtErrorCode, message: string, options?: {cause?: unknown}) {
+    super(message, options)
+    this.code = code
+  }
+}
+
+/** Optimistic concurrency failed on a written stream: its sequence or snapshot moved. */
+export class ConflictError extends EvtError {
+  override readonly name = 'ConflictError'
+  override readonly code = 'conflict'
+  readonly entityId: string
+
+  constructor(entityId: string, detail: string) {
+    super('conflict', `conflict on entity ${entityId}: ${detail}`)
+    this.entityId = entityId
+  }
+}
+
+/** A commit's first event skips past the stream's head, or a load found a hole. A conflict. */
+export class SequenceGapError extends EvtError {
+  override readonly name = 'SequenceGapError'
+  override readonly code = 'sequenceGap'
+  readonly entityId: string
+  /** The last sequence before the gap. */
+  readonly after: bigint
+  /** The sequence found next, which isn't `after + 1`. */
+  readonly found: bigint
+
+  constructor(entityId: string, after: bigint, found: bigint) {
+    super(
+      'sequenceGap',
+      `conflict on entity ${entityId}: the stream skips from sequence ${after} to ${found}: it ` +
+        'was compacted during the load, or events expired',
+    )
+    this.entityId = entityId
+    this.after = after
+    this.found = found
+  }
+}
+
+/**
+ * A stream's head disagrees with its events or snapshot (ADR 0007): a writer appended without
+ * raising the head, events were deleted, a snapshot is ahead of the head, or a stream has data and
+ * no head. It isn't retryable: running the command again fails the same way. Repair is offline.
+ */
+export class StreamHeadDriftError extends EvtError {
+  override readonly name = 'StreamHeadDriftError'
+  override readonly code = 'streamHeadDrift'
+  readonly entityId: string
+  /** The stored head, or null when the stream has no head. */
+  readonly stored: bigint | null
+  /** The head its events and snapshot imply: the higher of the two. */
+  readonly derived: bigint
+
+  constructor(entityId: string, stored: bigint | null, derived: bigint) {
+    super(
+      'streamHeadDrift',
+      `stream head drift on entity ${entityId}: stored head ${stored ?? 'absent'}, ` +
+        `derived head ${derived}`,
+    )
+    this.entityId = entityId
+    this.stored = stored
+    this.derived = derived
+  }
+}
+
+/** The commit is over the transaction budget: too many actions, bytes, or bytes in one item. */
+export class CommitTooLargeError extends EvtError {
+  override readonly name = 'CommitTooLargeError'
+  override readonly code = 'commitTooLarge'
+  readonly actions: number
+  readonly bytes: number
+  readonly largestItem: number
+
+  constructor(actions: number, bytes: number, largestItem: number) {
+    super(
+      'commitTooLarge',
+      `commit exceeds transaction budget: ${actions} actions, ${bytes} bytes, ` +
+        `largest item ${largestItem}`,
+    )
+    this.actions = actions
+    this.bytes = bytes
+    this.largestItem = largestItem
+  }
+}
+
+/** Compaction was refused because no snapshot covers the events it would delete. */
+export class CompactionUncoveredError extends EvtError {
+  override readonly name = 'CompactionUncoveredError'
+  override readonly code = 'compactionUncovered'
+  readonly entityId: string
+  readonly through: bigint
+  /** The event sequence the stored snapshot covers, or null with no snapshot. */
+  readonly covered: bigint | null
+
+  constructor(entityId: string, through: bigint, covered: bigint | null) {
+    super(
+      'compactionUncovered',
+      'compaction refused: no durable snapshot covers the requested range ' +
+        `(entity ${entityId}, through ${through}, snapshot covers ${covered ?? 'nothing'})`,
+    )
+    this.entityId = entityId
+    this.through = through
+    this.covered = covered
+  }
+}
+
+/** A write to an entity ID in a reserved namespace (`SYSTEM#`, `command-outcome#`). */
+export class ReservedEntityIdError extends EvtError {
+  override readonly name = 'ReservedEntityIdError'
+  override readonly code = 'reservedEntityId'
+  readonly entityId: string
+
+  constructor(entityId: string) {
+    super(
+      'reservedEntityId',
+      `entity ID ${entityId} is in a reserved namespace (SYSTEM#, command-outcome#)`,
+    )
+    this.entityId = entityId
+  }
+}
+
+/** A load failed closed on a stored event: an upcaster threw, or the payload didn't decode. */
+export class ReplayError extends EvtError {
+  override readonly name = 'ReplayError'
+  override readonly code = 'replay'
+  readonly eventType: string
+  /** The stored version, or the version an earlier upcaster produced. */
+  readonly version: number
+  readonly phase: 'upcast' | 'decode'
+
+  constructor(
+    eventType: string,
+    version: number,
+    phase: 'upcast' | 'decode',
+    detail: string,
+    cause?: unknown,
+  ) {
+    const doing = phase === 'upcast' ? 'upcasting' : 'decoding'
+    super('replay', `replay failed while ${doing} ${eventType} v${version}: ${detail}`, {cause})
+    this.eventType = eventType
+    this.version = version
+    this.phase = phase
+  }
+}
+
+/** A load found a stored snapshot whose payload the aggregate's state codec doesn't decode. */
+export class SnapshotError extends EvtError {
+  override readonly name = 'SnapshotError'
+  override readonly code = 'snapshot'
+  readonly entityId: string
+
+  constructor(entityId: string, cause: unknown) {
+    super('snapshot', `decoding snapshot for entity ${entityId}: ${messageOf(cause)}`, {cause})
+    this.entityId = entityId
+  }
+}
+
+/** Whether an error is an optimistic-concurrency conflict: a `conflict` or a `sequenceGap`. */
+export function isConflict(error: unknown): boolean {
+  return error instanceof EvtError && (error.code === 'conflict' || error.code === 'sequenceGap')
+}
+
+/** Whether reloading and running the command again may succeed. So far, only after a conflict. */
+export function isRetryable(error: unknown): boolean {
+  return isConflict(error)
+}
+
+/** An error's message, or the value itself as text. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}