@pikku/core 0.12.78 → 0.12.80

package/src/wirings/workflow/scenario-hooks.test.ts

@@ -184,6 +184,57 @@ describe('scenario before/after hooks', () => {
     ])
   })
 
+  test('after reads what the body wrote to the scenario context', async () => {
+    // The reason the context exists: teardown needs the ids the body minted,
+    // and a hook only ever receives the run's *input*.
+    let seen: any
+    await runScenario('contextHandover', {
+      after: async (_services, _data, wire) => {
+        seen = { ...wire.scenario.context }
+      },
+      func: async (_services, _data, wire) => {
+        wire.scenario.context.projectId = 'p_1'
+        return { projectId: 'p_1' }
+      },
+    })
+    assert.deepEqual(seen, { projectId: 'p_1' })
+  })
+
+  test('after sees the context of a body that threw after writing it', async () => {
+    // The failing path is the one that matters — a passing run could have
+    // returned the ids instead.
+    let seen: any
+    const { error } = await runScenario('contextOnFailure', {
+      after: async (_services, _data, wire) => {
+        seen = { ...wire.scenario.context }
+      },
+      func: async (_services, _data, wire) => {
+        wire.scenario.context.projectId = 'p_2'
+        throw new Error('body blew up')
+      },
+    })
+    assert.equal(error?.message, 'body blew up')
+    assert.deepEqual(seen, { projectId: 'p_2' })
+  })
+
+  test('before, the body and after all share one context object', async () => {
+    let seen: any
+    await runScenario('contextShared', {
+      before: async (_services, _data, wire) => {
+        wire.scenario.context.seededBy = 'before'
+      },
+      after: async (_services, _data, wire) => {
+        seen = { ...wire.scenario.context }
+      },
+      func: async (_services, _data, wire) => {
+        assert.equal(wire.scenario.context.seededBy, 'before')
+        wire.scenario.context.addedBy = 'func'
+        return { ok: true }
+      },
+    })
+    assert.deepEqual(seen, { seededBy: 'before', addedBy: 'func' })
+  })
+
   test('hooks are scenario-only — a plain DSL workflow never runs them', async () => {
     const order: string[] = []
     await runScenario(

package/src/wirings/workflow/workflow-approval.ts

@@ -0,0 +1,185 @@
+import { getDurationInMilliseconds } from '../../time-utils.js'
+import {
+  WorkflowApprovalResolvedError,
+  WorkflowSuspendedException,
+} from './workflow-errors.js'
+import type {
+  ApprovalOutcome,
+  StepState,
+  WorkflowApprovalOptions,
+} from './workflow.types.js'
+
+/** The durable step name an approval point is recorded under. */
+export const approvalStepNameFor = (reason: string): string =>
+  `__workflow_approval:${reason}`
+
+/**
+ * The run-state key holding an approval's decision.
+ *
+ * Hex-encoded because the key is composed from a caller-supplied reason, and
+ * run state is a flat record — an unescaped reason could collide with, or
+ * shadow, another key.
+ */
+export const approvalStateKey = (stepName: string): string => {
+  let hex = ''
+  for (const byte of new TextEncoder().encode(stepName)) {
+    hex += byte.toString(16).padStart(2, '0')
+  }
+  return `__approval_${hex}`
+}
+
+/** What the approval gate needs from the workflow service. */
+export type ApprovalStore = {
+  getStepState: (runId: string, stepName: string) => Promise<StepState>
+  insertStepState: (
+    runId: string,
+    stepName: string,
+    rpcName: string,
+    input: unknown,
+    output: undefined,
+    fromStepName?: string
+  ) => Promise<StepState>
+  setStepRunning: (stepId: string) => Promise<void>
+  setStepResult: (stepId: string, result: unknown) => Promise<void>
+  getRunState: (runId: string) => Promise<Record<string, unknown>>
+  updateRunState: (runId: string, key: string, value: unknown) => Promise<void>
+  resumeWorkflow: (runId: string) => Promise<void>
+  scheduleRunWake: (runId: string, delay: number) => Promise<void>
+}
+
+/**
+ * Record a decision against an approval point and wake the run.
+ *
+ * A decision arriving for an already-settled approval is refused rather than
+ * overwriting it: the run has moved on, and a second answer would be recorded
+ * against a gate nobody is waiting at.
+ */
+export const recordApprovalDecision = async (
+  store: ApprovalStore,
+  runId: string,
+  reason: string,
+  decision: unknown
+): Promise<void> => {
+  const stepName = approvalStepNameFor(reason)
+  const stateKey = approvalStateKey(stepName)
+
+  let resolved: StepState | undefined
+  try {
+    resolved = await store.getStepState(runId, stepName)
+  } catch {
+    // knowledge: decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md
+  }
+  if (resolved?.stepId && resolved.status === 'succeeded') {
+    const outcome = resolved.result as ApprovalOutcome<unknown> | undefined
+    throw new WorkflowApprovalResolvedError(
+      reason,
+      outcome?.status ?? 'decided'
+    )
+  }
+
+  const state = await store.getRunState(runId)
+  const record = (state[stateKey] ?? {}) as Record<string, unknown>
+  await store.updateRunState(runId, stateKey, {
+    ...record,
+    decision,
+    decidedAt: new Date().toISOString(),
+    error: undefined,
+  })
+  await store.resumeWorkflow(runId)
+}
+
+/**
+ * Evaluate an approval gate on replay.
+ *
+ * The payload is validated here rather than where it was submitted, because the
+ * schema is a value on the workflow and only the workflow has it. A payload
+ * that fails validation is cleared and the run suspends again, so a bad
+ * submission cannot settle the gate.
+ */
+export const evaluateApprovalStep = async (
+  store: ApprovalStore,
+  runId: string,
+  reason: string,
+  approvalStepName: string,
+  fromStepName: string | undefined,
+  options: WorkflowApprovalOptions
+): Promise<ApprovalOutcome<unknown>> => {
+  const insert = () =>
+    store.insertStepState(
+      runId,
+      approvalStepName,
+      'pikkuWorkflowApproval',
+      { reason, expiry: options.expiry },
+      undefined,
+      fromStepName
+    )
+
+  let stepState: StepState
+  try {
+    stepState = await store.getStepState(runId, approvalStepName)
+  } catch {
+    stepState = await insert()
+  }
+  if (!stepState.stepId) {
+    stepState = await insert()
+  }
+
+  if (stepState.status === 'succeeded') {
+    return stepState.result as ApprovalOutcome<unknown>
+  }
+
+  const stateKey = approvalStateKey(approvalStepName)
+  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as {
+    decision?: unknown
+    decidedAt?: string
+    expiresAt?: string
+    error?: unknown
+  }
+
+  if (stepState.status === 'pending') {
+    await store.setStepRunning(stepState.stepId)
+    if (options.expiry !== undefined && !record.expiresAt) {
+      const expiry = getDurationInMilliseconds(options.expiry)
+      record = {
+        ...record,
+        expiresAt: new Date(Date.now() + expiry).toISOString(),
+      }
+      await store.updateRunState(runId, stateKey, record)
+      await store.scheduleRunWake(runId, expiry)
+    }
+  }
+
+  if (record.decision !== undefined) {
+    const validation = await options.schema['~standard'].validate(
+      record.decision
+    )
+    if (validation.issues) {
+      await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision: undefined,
+        decidedAt: undefined,
+        error: validation.issues.map((issue) => ({
+          message: issue.message,
+          path: issue.path?.map((segment) =>
+            typeof segment === 'object' ? segment.key : segment
+          ),
+        })),
+      })
+      throw new WorkflowSuspendedException(runId, reason)
+    }
+    const outcome: ApprovalOutcome<unknown> = {
+      status: 'decided',
+      data: validation.value,
+    }
+    await store.setStepResult(stepState.stepId, outcome)
+    return outcome
+  }
+
+  if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
+    const outcome: ApprovalOutcome<unknown> = { status: 'expired' }
+    await store.setStepResult(stepState.stepId, outcome)
+    return outcome
+  }
+
+  throw new WorkflowSuspendedException(runId, reason)
+}

package/src/wirings/workflow/workflow-child-run-session.test.ts

@@ -0,0 +1,89 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+const registerChildWorkflow = (name: string) => {
+  pikkuState(null, 'workflows', 'meta', {
+    [name]: { name, pikkuFuncId: name, source: 'dsl', graphHash: 'h' },
+  } as any)
+  pikkuState(null, 'workflows', 'registrations').set(name, {
+    name,
+    func: async () => undefined,
+  } as any)
+  pikkuState(null, 'function', 'meta', {
+    [name]: {
+      pikkuFuncId: name,
+      inputSchemaName: null,
+      outputSchemaName: null,
+      sessionless: true,
+    },
+  } as any)
+  pikkuState(null, 'function', 'functions').set(name, {
+    func: async () => undefined,
+  } as any)
+}
+
+/**
+ * A step whose rpcName names a workflow starts that workflow as a child. The
+ * child's wire is built by the parent, so whatever identifies the caller has to
+ * be copied across explicitly — nothing else carries it.
+ */
+describe('a child workflow inherits the parent run wire pikkuUserId', () => {
+  const startParentWithChildStep = async (pikkuUserId?: string) => {
+    resetPikkuState()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: silentLogger,
+    } as any)
+    registerChildWorkflow('childFlow')
+
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('parentFlow', {}, true, '', {
+      type: 'test',
+      ...(pikkuUserId ? { pikkuUserId } : {}),
+    })
+    ws.registerInlineRun(runId)
+    await ws.insertStepState(runId, 'callChild', 'childFlow', {})
+
+    await (ws as any).rpcStep(runId, 'callChild', 'childFlow', {}, {})
+    return ws
+  }
+
+  const childRunWire = async (ws: InMemoryWorkflowService) => {
+    const runs: any[] = []
+    for (const id of (ws as any).runs?.keys?.() ?? []) {
+      const run = await ws.getRun(id)
+      if (run?.workflow === 'childFlow') runs.push(run)
+    }
+    assert.equal(runs.length, 1, 'exactly one child run should have started')
+    return runs[0]!.wire
+  }
+
+  test('the child run wire carries the parent pikkuUserId', async () => {
+    const ws = await startParentWithChildStep('user-abc')
+
+    assert.equal(
+      (await childRunWire(ws)).pikkuUserId,
+      'user-abc',
+      'a child started from a step must inherit who the parent was running as'
+    )
+  })
+
+  test('no pikkuUserId is invented when the parent has none', async () => {
+    const ws = await startParentWithChildStep()
+
+    assert.equal((await childRunWire(ws)).pikkuUserId, undefined)
+  })
+
+  test('the child records its parent', async () => {
+    const ws = await startParentWithChildStep('user-abc')
+    const wire = await childRunWire(ws)
+
+    assert.equal(wire.type, 'workflow')
+    assert.equal(wire.id, 'childFlow')
+    assert.ok(wire.parentRunId, 'the child must name the run that started it')
+  })
+})

package/src/wirings/workflow/workflow-constants.ts

@@ -0,0 +1,47 @@
+export const DEFAULT_STEP_RETRIES = 5
+
+/** Statuses from which a run never advances again on its own. */
+export const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'suspended',
+])
+
+/** Statuses a run cannot leave at all. */
+export const WORKFLOW_TERMINAL_STATES: ReadonlySet<string> = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+])
+
+export const WORKFLOW_POLL_MIN_MS = 10
+
+export const WORKFLOW_POLL_FACTOR = 1.6
+
+export const WORKFLOW_CHILD_POLL_MAX_MS = 500
+
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+export const DEFAULT_STALLED_RUN_MS = 5 * 60_000
+
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+export const DEFAULT_STALLED_RUN_LIMIT = 100
+
+/**
+ * How long a step may sit `pending` before the relay assumes its dispatch was
+ * lost. This is a bet that no healthy queue takes this long to move a job from
+ * `pending` to `running`; set it above the observed p99 of that latency.
+ */
+export const DEFAULT_UNDISPATCHED_STEP_MS = 30_000
+
+/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
+export const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100
+
+/** First wait before a step already re-dispatched once is re-dispatched again. */
+export const REDISPATCH_BACKOFF_MS = 30_000
+
+/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
+export const REDISPATCH_BACKOFF_MAX_MS = 10 * 60_000
+
+/** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
+export const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000

package/src/wirings/workflow/workflow-dispatch-durability.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState } from '../../pikku-state.js'
-import { WorkflowDispatchException } from './pikku-workflow-service.js'
+import { WorkflowDispatchException } from './workflow-errors.js'
 
 function registerDispatchedFn(rpcName: string): void {
   const funcId = `fn:${rpcName}`

package/src/wirings/workflow/workflow-dispatch-relay.test.ts

@@ -0,0 +1,128 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+/**
+ * `relayUndispatchedSteps` re-drives a run by putting it back on the
+ * orchestrator queue, so the queue is the observation point.
+ */
+function trackResumes(): { runIds: string[] } {
+  const seen: string[] = []
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: {
+      add: async (_queue: string, data: { runId: string }) => {
+        seen.push(data.runId)
+      },
+    },
+    logger: silentLogger,
+  } as any)
+  return { runIds: seen }
+}
+
+/** Backdates a step's timestamp so it reads as undispatched. */
+async function backdateSteps(
+  ws: InMemoryWorkflowService,
+  runId: string,
+  ms: number
+): Promise<void> {
+  const past = new Date(Date.now() - ms)
+  for (const step of await ws.getRunHistory(runId)) {
+    ;(step as any).updatedAt = past
+  }
+}
+
+describe('undispatched step relay', () => {
+  test('re-dispatches a step whose arming was lost', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    // The row committed; the process died before the timer was armed.
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+    await backdateSteps(ws, runId, 60_000)
+
+    const { redispatched } = await ws.relayUndispatchedSteps()
+
+    assert.deepEqual(redispatched, [runId], 'the run is re-dispatched')
+    assert.deepEqual(resumes.runIds, [runId], 'it is put back on the queue')
+  })
+
+  test('leaves a freshly written step alone', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    // Written milliseconds ago — its dispatch is almost certainly in flight.
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+
+    const { redispatched } = await ws.relayUndispatchedSteps()
+
+    assert.deepEqual(redispatched, [], 'nothing is re-dispatched')
+    assert.deepEqual(resumes.runIds, [], 'nothing is queued')
+  })
+
+  test('backs off rather than re-dispatching the same step every tick', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'Charge card', 'charge', {})
+    await backdateSteps(ws, runId, 60_000)
+
+    const first = await ws.relayUndispatchedSteps()
+    // The step is still pending — a real queue backlog looks exactly like this.
+    const second = await ws.relayUndispatchedSteps()
+
+    assert.deepEqual(first.redispatched, [runId], 'the first tick relays it')
+    assert.deepEqual(
+      second.redispatched,
+      [],
+      'the next tick is held off by the backoff'
+    )
+    assert.deepEqual(resumes.runIds, [runId], 'only one queue message')
+  })
+
+  test('ignores steps belonging to a settled run', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'Wait 15s', null, { duration: 15000 })
+    await backdateSteps(ws, runId, 60_000)
+    await ws.updateRunStatus(runId, 'completed', {})
+
+    const { redispatched } = await ws.relayUndispatchedSteps()
+
+    assert.deepEqual(redispatched, [], 'a finished run is not re-dispatched')
+    assert.deepEqual(resumes.runIds, [], 'nothing is queued')
+  })
+
+  test('re-dispatches each stuck run once per tick', async () => {
+    const resumes = trackResumes()
+    const ws = new InMemoryWorkflowService()
+    const runIds: string[] = []
+    for (const n of [1, 2]) {
+      const runId = await ws.createRun('flow', {}, false, 'hash', {
+        type: 'test',
+      })
+      // Two orphaned steps in one run must still produce a single resume.
+      await ws.insertStepState(runId, `Wait ${n}a`, null, { duration: 1000 })
+      await ws.insertStepState(runId, `Wait ${n}b`, null, { duration: 1000 })
+      await backdateSteps(ws, runId, 60_000)
+      runIds.push(runId)
+    }
+
+    const { redispatched } = await ws.relayUndispatchedSteps()
+
+    assert.deepEqual(redispatched.sort(), runIds.sort(), 'both runs relayed')
+    assert.equal(resumes.runIds.length, 2, 'one queue message per run')
+  })
+})

package/src/wirings/workflow/workflow-errors.ts

@@ -0,0 +1,128 @@
+import { PikkuError, addError } from '../../errors/error-handler.js'
+import type { ApprovalOutcome } from './workflow.types.js'
+
+/**
+ * Thrown to unwind a run that cannot continue on this tick. Not a failure:
+ * the run resumes from its recorded step state.
+ */
+export class WorkflowAsyncException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly stepName: string
+  ) {
+    super(`Workflow paused at step: ${stepName}`)
+    this.name = 'WorkflowAsyncException'
+  }
+}
+
+export class WorkflowCancelledException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly reason?: string
+  ) {
+    super(reason || 'Workflow cancelled')
+    this.name = 'WorkflowCancelledException'
+  }
+}
+
+export class WorkflowSuspendedException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly reason: string
+  ) {
+    super(reason || 'Workflow suspended')
+    this.name = 'WorkflowSuspendedException'
+  }
+}
+
+export class WorkflowDispatchException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly stepName: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `Failed to dispatch workflow step '${stepName}' (run ${runId})`,
+      options
+    )
+    this.name = 'WorkflowDispatchException'
+  }
+}
+
+export class WorkflowNotFoundError extends PikkuError {
+  constructor(name: string) {
+    super(`Workflow not found: ${name}`)
+  }
+}
+addError(WorkflowNotFoundError, {
+  status: 404,
+  message: 'Workflow not found.',
+})
+
+export class WorkflowRunNotFoundError extends PikkuError {
+  constructor(runId: string) {
+    super(`Workflow run not found: ${runId}`)
+  }
+}
+addError(WorkflowRunNotFoundError, {
+  status: 404,
+  message: 'Workflow run not found.',
+})
+
+export class WorkflowRunFailedError extends PikkuError {
+  public payload: { message?: string }
+  constructor(message?: string) {
+    super(`Workflow run failed: ${message ?? 'unknown'}`)
+    this.payload = { message }
+  }
+}
+addError(WorkflowRunFailedError, {
+  status: 422,
+  message: 'Workflow run failed.',
+})
+
+export class WorkflowRunCancelledError extends PikkuError {
+  constructor() {
+    super('Workflow was cancelled')
+  }
+}
+addError(WorkflowRunCancelledError, {
+  status: 409,
+  message: 'Workflow was cancelled.',
+})
+
+export class WorkflowApprovalResolvedError extends PikkuError {
+  public payload: {
+    reason: string
+    outcome: ApprovalOutcome<unknown>['status']
+  }
+  constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']) {
+    super(`Approval already ${outcome}: ${reason}`)
+    this.payload = { reason, outcome }
+  }
+}
+addError(WorkflowApprovalResolvedError, {
+  status: 409,
+  message: 'Approval has already been resolved.',
+})
+
+export class WorkflowStepFunctionMismatchError extends PikkuError {
+  constructor(
+    public readonly runId: string,
+    public readonly stepName: string
+  ) {
+    super(
+      `Workflow step '${stepName}' (run ${runId}) was dispatched with a different function`
+    )
+  }
+}
+addError(WorkflowStepFunctionMismatchError, {
+  status: 409,
+  message: 'Workflow step was dispatched with a different function.',
+})
+
+export class WorkflowStepNameNotString extends Error {
+  constructor(stepName: unknown) {
+    super(`Workflow step name must be a string. Received: ${typeof stepName}`)
+  }
+}

package/src/wirings/workflow/workflow-inline-authority.test.ts

@@ -153,12 +153,18 @@ describe('a run that stops executing here leaves no per-run state behind', () =>
     })
     await ws.insertStepState(runId, 'a', 'someRpc', {})
 
-    await ws.executeWorkflowStep(runId, 'a', 'someRpc', {}, {
-      rpcWithWire: async () => {
-        await ws.inlineStep(runId, 'nested', async () => 'ok')
-        return 'ok'
-      },
-    })
+    await ws.executeWorkflowStep(
+      runId,
+      'a',
+      'someRpc',
+      {},
+      {
+        rpcWithWire: async () => {
+          await ws.inlineStep(runId, 'nested', async () => 'ok')
+          return 'ok'
+        },
+      }
+    )
 
     assert.equal(
       ws.runContexts.size,