@prestack/thread 0.0.1 → 0.0.3

package/dist/operations/memory.ts

@@ -0,0 +1,470 @@
+import { randomUUID } from 'node:crypto'
+
+import type { Actor } from '../core/actor.ts'
+import type {
+  Store, Row, Seams, Telemetry, Log, Audit, Errors, Search, Cost, Idempotency, EventBus, RateLimiter, PlatformEvent, LogLevel,
+  Queue, Job, EnqueueOpts, Transactional, FeatureGate, Quotas, Outbox, AuditRecord, ErrorRecord, Vault,
+  Files, Views, FieldList } from './seams.ts'
+import { backoffMs, isExhausted } from './queue-policy.ts'
+
+function projectRow(row: Row, fields: FieldList, key: string): Row {
+  const keep = new Set<string>([key, 'version', ...fields])
+  const projected: Row = {}
+  for (const [name, value] of Object.entries(row)) {
+    if (keep.has(name)) projected[name] = value
+  }
+  return projected
+}
+
+export class UnknownColumnError extends Error {
+  constructor(entity: string, key: string) {
+    super(
+      `${entity} does not declare "${key}", so writing it would be silently discarded. ` +
+        'Declare the field or relation on the entity, or stop writing the key.',
+    )
+    this.name = 'UnknownColumnError'
+  }
+}
+
+export class VersionConflictError extends Error {
+  constructor(entity: string, id: string, expectedVersion: number) {
+    super(
+      `${entity} ${id} was not at version ${expectedVersion} — someone else changed it first. ` +
+        're-read the row and retry with its current ETag.',
+    )
+    this.name = 'VersionConflictError'
+  }
+}
+
+export class MemoryStore implements Store, Transactional {
+  private data = new Map<string, Row[]>()
+
+  private readonly declared: ReadonlyMap<string, ReadonlySet<string>>
+
+  private readonly keys: ReadonlyMap<string, string>
+
+  constructor(declared?: ReadonlyMap<string, ReadonlySet<string>>, keys?: ReadonlyMap<string, string>) {
+    this.declared = declared ?? new Map()
+    this.keys = keys ?? new Map()
+  }
+
+  private keyOf(entity: string): string {
+    const held = this.keys.get(entity)
+    if (held === undefined) {
+      throw new Error(
+        `nothing told this store which value identifies a ${entity}, so it cannot find one row rather than all of ` +
+          'them. An entity states that with a `unique` invariant over one of its values, and whatever builds this ' +
+          'store passes those along with the columns each entity declares.',
+      )
+    }
+    return held
+  }
+
+  private static readonly SYSTEM = new Set(['version'])
+
+  private assertDeclared(entity: string, row: Record<string, unknown>): void {
+    const allowed = this.declared.get(entity)
+    if (allowed === undefined) return
+    for (const key of Object.keys(row)) {
+      if (allowed.has(key) || MemoryStore.SYSTEM.has(key)) continue
+      throw new UnknownColumnError(entity, key)
+    }
+  }
+
+  private depth = 0
+
+  async transaction<T>(_actor: Actor, fn: () => Promise<T>): Promise<T> {
+    if (this.depth > 0) return fn()
+    const snapshot = new Map<string, Row[]>()
+    for (const [key, rows] of this.data) snapshot.set(key, rows.map((r) => ({ ...r })))
+
+    this.depth += 1
+    try {
+      return await fn()
+    } catch (err) {
+      this.data = snapshot
+      throw err
+    } finally {
+      this.depth -= 1
+    }
+  }
+
+  async insert(_actor: Actor, entity: string, row: Row): Promise<Row> {
+    this.assertDeclared(entity, row)
+    const rows = this.data.get(entity) ?? []
+
+    const rec = { ...row, version: 1 }
+    rows.push(rec)
+    this.data.set(entity, rows)
+    return { ...rec }
+  }
+
+  async get(_actor: Actor, entity: string, key: string | number, fields: FieldList): Promise<Row | null> {
+    const named = this.keyOf(entity)
+    const row = this.data.get(entity)?.find((r) => r[named] === key) ?? null
+    return row === null ? null : projectRow(row, fields, named)
+  }
+  async list(
+    _actor: Actor,
+    entity: string,
+    opts?: { limit?: number; where?: Readonly<Record<string, string | number | boolean | null>> },
+  ): Promise<Row[]> {
+    const all = this.data.get(entity) ?? []
+
+    const where = Object.entries(opts?.where ?? {})
+    for (const [field] of where) this.assertDeclared(entity, { [field]: null })
+
+    const matched = where.length === 0 ? all : all.filter((row) => where.every(([f, v]) => (row[f] ?? null) === v))
+    return opts?.limit ? matched.slice(0, opts.limit).map((r) => ({ ...r })) : matched.map((r) => ({ ...r }))
+  }
+  async update(
+    _actor: Actor,
+    entity: string,
+    key: string | number,
+    patch: Record<string, unknown>,
+    expectedVersion?: number,
+  ): Promise<Row> {
+    this.assertDeclared(entity, patch)
+    const named = this.keyOf(entity)
+    const rows = this.data.get(entity) ?? []
+    const i = rows.findIndex((r) => r[named] === key)
+    const cur = rows[i]
+    if (i < 0 || !cur) throw new Error(`record ${String(key)} not found`)
+    const currentVersion = typeof cur['version'] === 'number' ? cur['version'] : 1
+    if (expectedVersion !== undefined && expectedVersion !== currentVersion) {
+      throw new VersionConflictError(entity, String(key), expectedVersion)
+    }
+
+    const next = { ...cur, ...patch, [named]: key, version: currentVersion + 1 }
+    rows[i] = next
+    return { ...next }
+  }
+  async remove(_actor: Actor, entity: string, key: string | number): Promise<void> {
+    const named = this.keyOf(entity)
+    this.data.set(entity, (this.data.get(entity) ?? []).filter((r) => r[named] !== key))
+  }
+}
+
+export class MemoryQueue implements Queue {
+  private jobs = new Map<string, Job & { runAt: number; claimed: boolean; dedupeKey?: string }>()
+  private dead: Job[] = []
+  private seq = 0
+
+  async enqueue<T>(actor: Actor, kind: string, payload: T, opts?: EnqueueOpts): Promise<string> {
+
+    if (opts?.dedupeKey) {
+      for (const [id, job] of this.jobs) {
+        if (job.dedupeKey === opts.dedupeKey) return id
+      }
+    }
+    const id = `job_${++this.seq}`
+    this.jobs.set(id, {
+      id,
+      kind,
+      payload,
+      attempts: 0,
+      runAt: opts?.runAt ?? 0,
+      claimed: false,
+      dedupeKey: opts?.dedupeKey,
+      actor,
+    })
+    return id
+  }
+
+  async poll(kinds: string[], limit: number, now: number): Promise<Job[]> {
+    const due: Job[] = []
+    for (const job of this.jobs.values()) {
+      if (due.length >= limit) break
+      if (job.claimed || !kinds.includes(job.kind) || job.runAt > now) continue
+      job.claimed = true
+      due.push({ ...job })
+    }
+    return due
+  }
+
+  async ack(id: string): Promise<void> {
+    this.jobs.delete(id)
+  }
+
+  async fail(id: string, error: string, now: number): Promise<void> {
+    const job = this.jobs.get(id)
+    if (!job) return
+    job.attempts += 1
+    job.claimed = false
+
+    if (isExhausted(job.attempts)) {
+
+      this.dead.push({ ...job })
+      this.jobs.delete(id)
+      return
+    }
+    job.runAt = now + backoffMs(job.attempts)
+    void error
+  }
+
+  async deadLetter(id: string, error: string): Promise<void> {
+    const job = this.jobs.get(id)
+    if (!job) return
+    this.dead.push({ ...job })
+    this.jobs.delete(id)
+    void error
+  }
+
+  async deadLetters(): Promise<Job[]> {
+    return this.dead.map((j) => ({ ...j }))
+  }
+}
+
+export interface Sink {
+  logs: { level: LogLevel; action: string; data: Record<string, unknown> }[]
+  events: PlatformEvent[]
+  audits: AuditRecord[]
+  errors: ErrorRecord[]
+  costs: string[]
+  indexed: { entity: string; row: Row }[]
+  spans: { action: string; status: 'ok' | 'error' }[]
+
+  outbox: PlatformEvent[]
+
+  gateOrder: string[]
+
+  quota: { reserved: number[]; committed: number[]; released: number }
+
+  files: { action: 'put' | 'get' | 'signed' | 'remove'; key: string; bytes: number | null }[]
+
+  queries: { sql: string; params: readonly unknown[]; rows: number }[]
+}
+
+export class MemoryIdempotency implements Idempotency {
+  private readonly records: Map<string, unknown>
+  private readonly onCheck?: () => void
+
+  constructor(opts: {
+    readonly onCheck?: () => void
+
+    readonly records?: Map<string, unknown>
+  }) {
+    this.records = opts.records ?? new Map<string, unknown>()
+    this.onCheck = opts.onCheck
+  }
+
+  private keyFor(key: string, action: string): string {
+    return `${key}:${action}`
+  }
+
+  async check(key: string | undefined, action: string): Promise<unknown | null> {
+    this.onCheck?.()
+    if (!key) return null
+    const k = this.keyFor(key, action)
+    return this.records.has(k) ? (this.records.get(k) ?? null) : null
+  }
+
+  async store(key: string | undefined, action: string, output: unknown): Promise<void> {
+    if (!key) return
+    const k = this.keyFor(key, action)
+
+    if (!this.records.has(k)) this.records.set(k, output)
+  }
+}
+
+export interface MemorySeamOptions {
+  readonly allowRate?: boolean
+
+  readonly features?: readonly string[]
+
+  readonly quota?: Readonly<Record<string, number>>
+  readonly onExceed?: string
+
+  readonly entities?: ReadonlyMap<string, ReadonlySet<string>>
+
+  readonly keys?: ReadonlyMap<string, string>
+
+  readonly secrets?: Readonly<Record<string, string>>
+
+  readonly views?: Readonly<Record<string, readonly unknown[]>>
+}
+
+export function memoryVault(seed: Readonly<Record<string, string>> = {}): Vault {
+  return {
+    async resolve(refs) {
+      const found: Record<string, string> = {}
+      for (const ref of refs) {
+        const value = seed[ref]
+        if (value === undefined) throw new Error(`vault has no value for "${ref}"`)
+        found[ref] = value
+      }
+      return found
+    },
+  }
+}
+
+export const arrived = (): number => Date.now()
+
+export const fresh = (): string => randomUUID()
+
+export function inMemorySeams(opts?: MemorySeamOptions): {
+  seams: Seams
+  sink: Sink
+  store: MemoryStore
+  queue: MemoryQueue
+} {
+  const sink: Sink = {
+    logs: [], events: [], audits: [], errors: [], costs: [], indexed: [], spans: [],
+    outbox: [], gateOrder: [], quota: { reserved: [], committed: [], released: 0 },
+    files: [], queries: [],
+  }
+  const store = new MemoryStore(opts?.entities, opts?.keys)
+  const queue = new MemoryQueue()
+  const searchIdx = new Map<string, Row[]>()
+
+  const telemetry: Telemetry = {
+    start(action) {
+      let status: 'ok' | 'error' = 'ok'
+      return {
+        ok() { status = 'ok' },
+        error() { status = 'error' },
+        end() { sink.spans.push({ action, status }) },
+      }
+    },
+  }
+  const log: Log = { write(level, action, _actor, data) { sink.logs.push({ level, action, data }) } }
+
+  const audit: Audit = { async append(_actor, record) { sink.audits.push(record) } }
+  const errors: Errors = { async record(_actor, record) { sink.errors.push(record) } }
+  const cost: Cost = { meter(action) { sink.costs.push(action) } }
+  const events: EventBus = { async publish(e) { sink.events.push(e) } }
+  const rateLimiter: RateLimiter = {
+    async check() {
+      sink.gateOrder.push('rate')
+      return opts?.allowRate ?? true
+    },
+    async checkPolicy() {
+      sink.gateOrder.push('rate')
+      return opts?.allowRate ?? true
+    },
+  }
+
+  const featureGate: FeatureGate | undefined =
+    opts?.features === undefined
+      ? undefined
+      : {
+          async check(_actor, feature) {
+            sink.gateOrder.push('feature')
+            return (opts.features ?? []).includes(feature)
+          },
+        }
+
+  const used = new Map<string, number>()
+  const quotas: Quotas | undefined =
+    opts?.quota === undefined
+      ? undefined
+      : {
+          async reserve(_actor, meter, estimate) {
+            sink.gateOrder.push('quota')
+            sink.quota.reserved.push(estimate)
+
+            const allowance = opts.quota?.[meter] ?? Number.POSITIVE_INFINITY
+            const before = used.get(meter) ?? 0
+
+            if (before + estimate > allowance) {
+
+              return {
+                ok: false,
+                behavior: opts.onExceed ?? 'block',
+                retryAfterSeconds: 60,
+                async commit() {},
+                async release() {},
+              }
+            }
+
+            used.set(meter, before + estimate)
+            let settled = false
+            return {
+              ok: true,
+              behavior: null,
+              retryAfterSeconds: 0,
+              async commit(actual) {
+                if (settled) return
+                settled = true
+                sink.quota.committed.push(actual)
+                used.set(meter, (used.get(meter) ?? 0) - estimate + actual)
+              },
+              async release() {
+                if (settled) return
+                settled = true
+                sink.quota.released += 1
+                used.set(meter, (used.get(meter) ?? 0) - estimate)
+              },
+            }
+          },
+        }
+
+  const outbox: Outbox = {
+    async emit(_actor, event) {
+      sink.outbox.push(event)
+    },
+  }
+
+  const idempotency: Idempotency = new MemoryIdempotency({
+    onCheck: () => sink.gateOrder.push('idempotency'),
+  })
+  const search: Search = {
+    async index(_actor, entity, row) {
+      sink.indexed.push({ entity, row })
+      searchIdx.set(entity, [...(searchIdx.get(entity) ?? []), row])
+    },
+    async query(_actor, entity, q) {
+
+      const needle = q.toLowerCase()
+      return (searchIdx.get(entity) ?? []).filter((r) => JSON.stringify(r).toLowerCase().includes(needle))
+    },
+  }
+
+  const vault: Vault | undefined = opts?.secrets === undefined ? undefined : memoryVault(opts.secrets)
+
+  const stored = new Map<string, { body: Uint8Array; contentType: string }>()
+  const files: Files = {
+    async put(_actor, key, body, contentType) {
+      stored.set(key, { body, contentType })
+      sink.files.push({ action: 'put', key, bytes: body.byteLength })
+      return { size: body.byteLength }
+    },
+    async get(_actor, key) {
+      const found = stored.get(key)
+      sink.files.push({ action: 'get', key, bytes: found === undefined ? null : found.body.byteLength })
+      return found === undefined ? null : { body: found.body, contentType: found.contentType }
+    },
+    async signedUrl(_actor, key, expiresInSeconds) {
+      sink.files.push({ action: 'signed', key, bytes: null })
+      return `https://files.invalid/unsigned-in-memory/${encodeURIComponent(key)}?expires_in=${String(expiresInSeconds)}`
+    },
+    async remove(_actor, key) {
+      stored.delete(key)
+      sink.files.push({ action: 'remove', key, bytes: null })
+    },
+  }
+
+  const answers = opts?.views
+  const views: Views | undefined =
+    answers === undefined
+      ? undefined
+      : {
+          async query<T>(_actor: Actor, sql: string, params: readonly unknown[]) {
+            const found = (answers[sql] ?? []) as readonly T[]
+            sink.queries.push({ sql, params, rows: found.length })
+            return found
+          },
+        }
+
+  return {
+    seams: {
+      store, telemetry, log, audit, errors, search, cost, idempotency, events, rateLimiter, queue,
+      outbox, files, clock: { now: arrived }, random: { next: Math.random, uuid: fresh },
+      ...(featureGate ? { featureGate } : {}),
+      ...(quotas ? { quotas } : {}),
+      ...(vault ? { vault } : {}),
+      ...(views ? { views } : {}),
+    },
+    sink, store, queue,
+  }
+}