@owlmeans/server-planning 0.1.18-rc.0

package/src/store/fold.ts

@@ -0,0 +1,257 @@
+import {
+  applyRelationship, applyTransition, CommitState, isProject, PlanningUnsupported, TransitionAction,
+} from '@owlmeans/planning'
+import type {
+  CommitEvent, PlanningStore, Relationship, SpecificationRevision, Transition, Workcard,
+} from '@owlmeans/planning'
+import type { FoldOptions, FoldResult } from './types.js'
+
+const isoNow = (): string => new Date().toISOString()
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+const errorText = (error: unknown): string =>
+  error instanceof Error ? error.message : `${error}`
+
+const safely = async (label: string, run: () => Promise<void> | void | undefined): Promise<void> => {
+  try {
+    await run()
+  } catch (error) {
+    console.error(`planning: ${label} failed:`, error)
+  }
+}
+
+/** The event a settled transition publishes. `record` is in-process only — strip it before a bus. */
+export const commitEventOf = (
+  transition: Transition, state: CommitState, at: string, extra?: { error?: string, record?: Workcard | null }
+): CommitEvent => clean({
+  transition: transition.id!,
+  card: transition.card,
+  entityId: transition.entityId,
+  project: transition.project,
+  kind: transition.kind,
+  type: transition.type,
+  seq: transition.seq,
+  action: transition.action,
+  state,
+  at,
+  error: extra?.error,
+  record: extra?.record,
+})
+
+const bearsRelationships = (transition: Transition): boolean =>
+  transition.action === TransitionAction.Link
+  || transition.action === TransitionAction.Unlink
+  || transition.action === TransitionAction.Delete
+  || (transition.action === TransitionAction.Create && (transition.links?.length ?? 0) > 0)
+
+const foldRelationships = async (store: PlanningStore, transition: Transition): Promise<void> => {
+  const links = store.links
+  if (links == null || !bearsRelationships(transition)) {
+    return
+  }
+  const where = { entityId: transition.entityId }
+  const [outgoing, incoming] = await Promise.all([
+    links.list({ ...where, from: transition.card }, { size: 0 }),
+    links.list({ ...where, to: transition.card }, { size: 0 }),
+  ])
+  const before = [...new Map([...outgoing.items, ...incoming.items].map(link => [link.id, link])).values()]
+  const after = applyRelationship(before, transition)
+  const kept = new Set(after.filter(link => link.id != null).map(link => link.id))
+
+  for (const link of before) {
+    if (link.id != null && !kept.has(link.id)) {
+      await links.drop({ entityId: transition.entityId, id: link.id })
+    }
+  }
+  for (const link of after) {
+    if (link.id == null) {
+      await links.put(link as Relationship)
+    }
+  }
+}
+
+const writeFold = async (
+  store: PlanningStore, before: Workcard | null, after: Workcard | null, transition: Transition
+): Promise<void> => {
+  if (transition.action === TransitionAction.Delete) {
+    if (before != null && isProject(before)) {
+      // A project takes everything under it, its own log included — the hub remembers the commit.
+      await store.cards.purge(transition.card, transition.entityId)
+      return
+    }
+    await foldRelationships(store, transition)
+    await store.cards.drop(transition.card, transition.entityId)
+    return
+  }
+  if (after != null) {
+    await store.cards.put(after)
+  }
+  await foldRelationships(store, transition)
+}
+
+/**
+ * Fold every pending transition of one card — the projection body every store reuses.
+ *
+ * Transitions are read in `seq` order past the card's own `seq`, and only `pending` ones are
+ * applied, each with `applyTransition` and nothing else. Per transition: write the record (a
+ * `delete` drops it, a project `delete` purges everything under it), fold its relationships, mark
+ * it `committed`, `publish` the event, then run `onCommitted` — so the `after` chain runs in THIS
+ * process, exactly once per committed transition. A transition that cannot be folded is marked
+ * `failed` with the reason and a failed event is published, and the fold goes PAST it: the card's
+ * `seq` advances to the failed transition with every other value as it was, so the next
+ * transition applies normally. Nothing is removed from the log. A create that fails leaves no card
+ * to advance, so what follows it fails too; a store that refuses the advancing write itself stops
+ * the fold there and reports `followUp`, leaving the rest pending for a retry.
+ *
+ * The caller owns single flight: two folds of one card running at once would both publish.
+ *
+ * @throws {PlanningUnsupported} for a store without a transition log
+ */
+export const foldPending = async (
+  store: PlanningStore, cardId: string, entityId: string, opts: FoldOptions = {}
+): Promise<FoldResult> => {
+  const transitions = store.transitions
+  if (transitions == null) {
+    throw new PlanningUnsupported(`fold:${store.alias ?? 'store'}`)
+  }
+  const now = opts.now ?? isoNow
+
+  let card = await store.cards.get(cardId, entityId)
+  const listed = await transitions.list(
+    { entityId, card: cardId, sinceSeq: card?.seq ?? 0, state: CommitState.Pending },
+    { sort: ['seq'], size: opts.limit ?? 0 }
+  )
+
+  let folded = 0
+  let failed = 0
+  for (const transition of listed.items) {
+    if (transition.commit.state !== CommitState.Pending || transition.id == null) {
+      continue
+    }
+    await opts.touch?.()
+    const at = now()
+
+    let next: Workcard | null
+    try {
+      next = applyTransition(card, transition)
+      if (card != null && next === card) {
+        // Already applied by another folder, which owns its commit and its event.
+        continue
+      }
+      await writeFold(store, card, next, transition)
+    } catch (error) {
+      failed++
+      const message = errorText(error)
+      if (card != null && transition.seq > card.seq) {
+        // Fold PAST it: the record keeps its previous values and only its cursor moves, so the
+        // next transition still applies. The card is re-written whole, which also undoes a write
+        // that got half way before it threw.
+        const skipped: Workcard = { ...card, seq: transition.seq, head: Math.max(card.head ?? card.seq, transition.seq) }
+        try {
+          await store.cards.put(skipped)
+          card = skipped
+        } catch (advance) {
+          // The store itself refuses writes: leave the rest pending for a retry rather than
+          // failing every later transition as out of order.
+          console.error(`planning: cannot advance ${cardId} past failed seq ${transition.seq}:`, advance)
+          await safely('commit failure', () => transitions.commit(transition.id!, { state: CommitState.Failed, at, error: message }))
+          await safely('publish', () => opts.publish?.(commitEventOf(transition, CommitState.Failed, at, { error: message })))
+          return { card, folded, failed, followUp: true }
+        }
+      }
+      await safely('commit failure', () => transitions.commit(transition.id!, { state: CommitState.Failed, at, error: message }))
+      const event = commitEventOf(transition, CommitState.Failed, at, { error: message })
+      await safely('publish', () => opts.publish?.(event))
+      continue
+    }
+
+    card = next
+    folded++
+    await safely('commit', () => transitions.commit(transition.id!, { state: CommitState.Committed, at }))
+    const event = commitEventOf(transition, CommitState.Committed, at, { record: next })
+    await safely('publish', () => opts.publish?.(event))
+    await safely('onCommitted', () => opts.onCommitted?.(event))
+  }
+
+  return { card, folded, failed, followUp: listed.total > listed.items.length }
+}
+
+/**
+ * Mark every pending transition of a card `failed` and publish a failed event for each — what a
+ * queued store does when its projection job is dead, or waiters hang until their timeout.
+ */
+export const failPending = async (
+  store: PlanningStore, cardId: string, entityId: string, reason: string,
+  opts: Pick<FoldOptions, 'publish' | 'now'> = {}
+): Promise<number> => {
+  const transitions = store.transitions
+  if (transitions == null) {
+    return 0
+  }
+  const at = (opts.now ?? isoNow)()
+  const pending = await transitions.list({ entityId, card: cardId, state: CommitState.Pending }, { sort: ['seq'], size: 0 })
+  for (const transition of pending.items) {
+    if (transition.id == null) {
+      continue
+    }
+    await transitions.commit(transition.id, { state: CommitState.Failed, at, error: reason })
+    const event = commitEventOf(transition, CommitState.Failed, at, { error: reason })
+    await safely('publish', () => opts.publish?.(event))
+  }
+
+  return pending.items.length
+}
+
+const CONTENT_KEYS = ['body', 'ref', 'format', 'version'] as const
+
+/**
+ * A specification's history, replayed from its log: one entry per create and per committed
+ * content change, newest first. The fold is `applyTransition` itself, so an entry's `body` is the
+ * body AT that revision even when the transition changed only `ref`.
+ */
+export const revisionsFromLog = (log: Transition[], limit?: number): SpecificationRevision[] => {
+  const ordered = log.filter(transition => transition.commit.state !== CommitState.Pending)
+    .sort((left, right) => left.seq - right.seq)
+
+  const entries: SpecificationRevision[] = []
+  let state: Workcard | null = null
+  for (const transition of ordered) {
+    if (transition.commit.state === CommitState.Failed) {
+      // The fold went past it; so does the replay.
+      if (state != null && transition.seq > state.seq) {
+        state = { ...(state as Workcard), seq: transition.seq }
+      }
+      continue
+    }
+    try {
+      state = applyTransition(state, transition)
+    } catch {
+      break
+    }
+    if (state == null) {
+      break
+    }
+    const changed = transition.action === TransitionAction.Create
+      || CONTENT_KEYS.some(key => (transition.changes as Record<string, unknown>)[key] !== undefined
+        || transition.unset?.includes(key) === true)
+    if (!changed) {
+      continue
+    }
+    const spec = state as Workcard & { body?: string, ref?: string, bodyChars?: number, version?: number, revision?: number }
+    entries.push(clean({
+      revision: spec.revision ?? entries.length + 1,
+      body: spec.body,
+      ref: spec.ref,
+      bodyChars: spec.bodyChars,
+      version: spec.version,
+      at: transition.at,
+      by: transition.actor,
+      transition: transition.id!,
+    }))
+  }
+
+  const newest = entries.reverse()
+  return limit != null && limit > 0 ? newest.slice(0, limit) : newest
+}

package/src/store/index.ts

@@ -0,0 +1,6 @@
+export type * from './types.js'
+
+export * from './commits.js'
+export * from './composite.js'
+export * from './fold.js'
+export * from './memory.js'

package/src/store/types.ts

@@ -0,0 +1,94 @@
+import type {
+  CommitEvent, CommitSource, CommitStatus, PlanningStore, ProjectionStore, Relationship,
+  RelationshipStore, SpecificationStore, Transition, TransitionStore, Workcard,
+} from '@owlmeans/planning'
+
+/** What a folding store calls for every committed transition — the service's `committed`. */
+export interface CommitListener {
+  (event: CommitEvent): Promise<void>
+}
+
+/**
+ * A store the planning service can hand its `committed` to.
+ *
+ * `appendPlanningService` calls `bind` on the default store and on every plugin store it resolves,
+ * so the process that FOLDS is the process that runs the `after` chain. A store without `bind`
+ * reaches the service some other way (a durable store's projection processor looks it up on the
+ * context).
+ */
+export interface BindablePlanningStore extends PlanningStore {
+  bind?: (committed: CommitListener) => void
+}
+
+export interface CommitHubOptions {
+  /** The authoritative answer for one transition, or `null` when the store has no such row. */
+  status: (transition: string) => Promise<CommitStatus | null>
+  /** Settled events remembered for `status` after their row is gone. */
+  remember?: number
+  /** The poll ladder `wait` climbs, in milliseconds; the last step repeats. */
+  ladder?: readonly number[]
+}
+
+/** An in-process commit fan-out: the `CommitSource` a store answers with, plus the publishing half. */
+export interface CommitHub extends CommitSource {
+  /** Deliver an event to every matching subscriber. A listener that throws is logged, never rethrown. */
+  publish: (event: CommitEvent) => Promise<void>
+  /** A settled event remembered by transition id, whether or not its row still exists. */
+  recall: (transition: string) => CommitEvent | undefined
+  /** How many subscribers are attached. */
+  listeners: () => number
+}
+
+export interface FoldOptions {
+  /** The service's `committed` — run once per committed transition, after `publish`. */
+  onCommitted?: CommitListener
+  /** Where commit events go. Strip `record` before a cross-process bus. */
+  publish?: (event: CommitEvent) => Promise<void>
+  now?: () => string
+  /** The most transitions one call folds; the rest is reported as `followUp`. Unlimited when omitted. */
+  limit?: number
+  /** Called between transitions — a queue processor renews its lock here. */
+  touch?: () => Promise<void>
+}
+
+export interface FoldResult {
+  card: Workcard | null
+  folded: number
+  failed: number
+  /** More pending transitions than `limit` allowed in one call. */
+  followUp: boolean
+}
+
+export interface MemoryPlanningStoreSeed {
+  cards?: Workcard[]
+  links?: Relationship[]
+  transitions?: Transition[]
+}
+
+export interface MemoryPlanningStoreOptions {
+  /** Fold and publish inside `project()`. Default `true`; `false` folds only on `flush()`. */
+  sync?: boolean
+  ids?: () => string
+  now?: () => string
+  seed?: MemoryPlanningStoreSeed
+  /** The commit listener used until a service binds its own. */
+  onCommitted?: CommitListener
+  alias?: string
+}
+
+export interface MemoryPlanningStore extends BindablePlanningStore {
+  transitions: TransitionStore
+  cards: ProjectionStore
+  specs: SpecificationStore
+  links: RelationshipStore
+  commits: CommitHub
+  bind: (committed: CommitListener) => void
+  /** Fold what is pending — for one card, or for every card with a pending transition. */
+  flush: (card?: string) => Promise<void>
+}
+
+/** One owning route of a composite store. */
+export interface StoreRoute {
+  owns: (type: string) => boolean
+  store: PlanningStore
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+import type { BasicConfig, BasicContext, LazyService } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type {
+  AnyTypeSchema, PlanningPlugin, PlanningScope, PlanningService, PlanningStore, StatusFlowSchema,
+  WithPlanningService,
+} from '@owlmeans/planning'
+import type { ApiServerAppend } from '@owlmeans/server-api'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export interface Config extends ServerConfig { }
+
+export interface Context<C extends Config = Config> extends ServerContext<C>, ApiServerAppend, WithPlanningService { }
+
+export interface PlanningServiceOptions {
+  /** The default store — every type no plugin owns. An in-memory store when omitted. */
+  store?: PlanningStore
+  plugins?: PlanningPlugin[]
+  /** Schemas registered before any plugin's. */
+  schemas?: { types?: AnyTypeSchema[], flows?: StatusFlowSchema[] }
+  /** Run the `after` chain in this process. Default `true`. */
+  hooks?: boolean
+  /** Card ids when the store mints none. */
+  ids?: () => string
+  /** ISO-8601 timestamps. */
+  now?: () => string
+}
+
+/**
+ * The registered host. Lazy on purpose: a plugin package reaches it with `ensurePlanningService`
+ * from an application's `makeContext`, before the context initializes, and `context.service()`
+ * refuses an uninitialized non-lazy service.
+ */
+export interface PlanningHostService extends PlanningService, LazyService { }
+
+/** Extra scope a deployment derives from the request — typically the write `channel`. */
+export interface PlanningScopeExtractor {
+  (req: AbstractRequest, ctx: BasicContext<BasicConfig>): Partial<PlanningScope> | Promise<Partial<PlanningScope>>
+}
+
+export interface PlanningHandlerOptions {
+  /** The planning service alias. `PLANNING_SERVICE` when omitted. */
+  service?: string
+  /** The socket frame name commit events are pushed under. `PLANNING_COMMIT_EVENT` when omitted. */
+  event?: string
+  /** The longest single long poll, in seconds — clamps `commit.get`'s `wait` and `execute`'s `timeout`. */
+  maxPoll?: number
+  scope?: PlanningScopeExtractor
+}

package/src/utils/guard.ts

@@ -0,0 +1,40 @@
+import { PlanningScopeMismatch, WorkcardNotFound } from '@owlmeans/planning'
+import type { Workcard } from '@owlmeans/planning'
+
+export const notFoundOf = (id: string): WorkcardNotFound => new WorkcardNotFound(id)
+
+/**
+ * A record of another entity is absent, not forbidden.
+ *
+ * @throws {WorkcardNotFound}
+ */
+export const assertScope = <T extends Pick<Workcard, 'entityId'>>(
+  record: T | null | undefined, scope: { entityId: string }, id: string
+): T => {
+  if (record == null || record.entityId !== scope.entityId) {
+    throw notFoundOf(id)
+  }
+  return record
+}
+
+/**
+ * Run a handler body so that a scope mismatch leaves as `WorkcardNotFound` — telling "not yours"
+ * apart from "does not exist" is what turns an id space into an enumeration oracle.
+ */
+export const concealed = async <T>(run: () => Promise<T>): Promise<T> => {
+  try {
+    return await run()
+  } catch (error) {
+    if (error instanceof PlanningScopeMismatch
+      || (error as { type?: string } | null)?.type === PlanningScopeMismatch.typeName) {
+      throw new WorkcardNotFound()
+    }
+    throw error
+  }
+}
+
+/** Seconds as the wire sends them, clamped to `[0, max]`. */
+export const clampSeconds = (value: unknown, max: number): number => {
+  const number = typeof value === 'number' ? value : Number(value ?? 0)
+  return Number.isFinite(number) ? Math.min(Math.max(number, 0), max) : 0
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './guard.js'
+export * from './scope.js'

package/src/utils/scope.ts

@@ -0,0 +1,51 @@
+import { requireEntityKey } from '@owlmeans/auth-common'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import { PLANNING_SERVICE } from '@owlmeans/planning'
+import type { PlanningFacade, PlanningScope, PlanningService, TransitionActor } from '@owlmeans/planning'
+import type { PlanningHandlerOptions, PlanningHostService } from '../types.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== '')) as T
+
+/** The authenticated subject of a request, as a transition names it. */
+export const actorOf = (req: AbstractRequest): TransitionActor => clean({
+  profileId: req.auth?.profileId,
+  userId: req.auth?.userId,
+})
+
+/**
+ * The scope a request reads and writes as.
+ *
+ * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
+ * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
+ * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
+ *
+ * @throws {AuthorizationError} when the request carries no organization
+ */
+export const scopeOf = (req: AbstractRequest, extra?: Partial<PlanningScope>): PlanningScope => {
+  const entityId = requireEntityKey(req)
+  const subject = actorOf(req)
+  const channel = extra?.channel ?? extra?.actor?.channel
+
+  return clean({
+    ...extra,
+    ...subject,
+    entityId,
+    channel,
+    actor: clean({ ...extra?.actor, ...subject, channel }),
+  }) as PlanningScope
+}
+
+export const planningServiceOf = (
+  ctx: BasicContext<BasicConfig>, opts?: Pick<PlanningHandlerOptions, 'service'>
+): PlanningService => ctx.service<PlanningHostService>(opts?.service ?? PLANNING_SERVICE)
+
+/** The facade a handler works through: the request's scope plus what `opts.scope` derives. */
+export const handlerFacade = async (
+  ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions
+): Promise<PlanningFacade> => {
+  const extra = await opts?.scope?.(req, ctx)
+
+  return planningServiceOf(ctx, opts).for(scopeOf(req, extra ?? undefined))
+}

package/tests/commits.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitFailed, CommitState, CommitTimeout, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { CommitEvent, Transition } from '@owlmeans/planning'
+import { createProject, ENTITY, makeTestPlanning, PROJECT } from './context.js'
+
+const createPending = (planning: ReturnType<Awaited<ReturnType<typeof makeTestPlanning>>['facade']>, title: string) =>
+  planning.execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title }, action: TransitionAction.Create })
+
+describe('@owlmeans/server-planning — commits', () => {
+  test('waiting on a commit that already landed resolves with the card', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const receipt = await createPending(planning, 'Landed')
+
+    expect(receipt.card!.title).toBe('Landed')
+    expect((await receipt.committed())!.id).toBe(receipt.transition.card)
+    expect((await planning.commits.wait(receipt.transition.id!, { timeout: 50 }))!.title).toBe('Landed')
+  })
+
+  test('a wait that times out is CommitTimeout and leaves the transition pending', async () => {
+    const { facade, store } = await makeTestPlanning({}, { sync: false })
+    const planning = facade()
+    const receipt = await createPending(planning, 'Queued')
+
+    expect(receipt.transition.commit.state).toBe(CommitState.Pending)
+    await expect(receipt.committed({ timeout: 30 })).rejects.toBeInstanceOf(CommitTimeout)
+    expect((await planning.commits.status(receipt.transition.id!)).state).toBe(CommitState.Pending)
+    expect(await planning.cards.load(receipt.transition.card)).toBeNull()
+
+    const waiting = planning.commits.wait(receipt.transition.id!, { timeout: 1000 })
+    await store.flush()
+    expect((await waiting)!.title).toBe('Queued')
+  })
+
+  test('a fold that fails marks the transition failed, and a waiter gets CommitFailed with the reason', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning, 'Stable')
+    const rogue = await store.transitions.append({
+      entityId: ENTITY, card: project.id!, kind: WorkcardKind.Project, type: PROJECT, seq: 3,
+      action: TransitionAction.Update, changes: { title: 'Skipped a seq' }, actor: {},
+      at: new Date().toISOString(), commit: { state: CommitState.Pending },
+    })
+
+    await store.cards.project(project.id!)
+
+    const refusal = await planning.commits.wait(rogue.id!, { timeout: 100 }).catch(error => error)
+    expect(refusal).toBeInstanceOf(CommitFailed)
+    expect(refusal.message).toContain('out-of-order')
+    expect((await planning.commits.status(rogue.id!)).state).toBe(CommitState.Failed)
+    expect((await planning.cards.get(project.id!)).title).toBe('Stable')
+  })
+
+  test('a failing middle transition does not block the next one — the fold goes past it', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning, 'Before')
+    const events: CommitEvent[] = []
+    store.commits.subscribe(event => { events.push(event) })
+    const logRow = (seq: number, patch: Partial<Transition>): Transition => ({
+      entityId: ENTITY, card: project.id!, kind: WorkcardKind.Project, type: PROJECT, seq,
+      action: TransitionAction.Update, changes: {}, actor: {}, at: new Date().toISOString(),
+      commit: { state: CommitState.Pending }, ...patch,
+    })
+    // A corrupted row: `unset` is not a list, so the fold of seq 2 throws.
+    const broken = await store.transitions.append(logRow(2, { changes: { title: 'Broken' }, unset: 5 as never }))
+    const next = await store.transitions.append(logRow(3, { changes: { title: 'After' } }))
+
+    await store.cards.project(project.id!)
+
+    expect(events.map(event => [event.seq, event.state])).toEqual([[2, CommitState.Failed], [3, CommitState.Committed]])
+    expect((await planning.commits.status(broken.id!)).state).toBe(CommitState.Failed)
+    expect((await planning.commits.wait(next.id!, { timeout: 100 }))!.title).toBe('After')
+    const card = await planning.cards.get(project.id!)
+    expect(card.seq).toBe(3)
+    expect(card.title).toBe('After')
+  })
+})