@pikku/core 0.12.79 → 0.12.82

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

@@ -0,0 +1,289 @@
+import { getDurationInMilliseconds } from '../../time-utils.js'
+import {
+  WorkflowApprovalResolvedError,
+  WorkflowSuspendedException,
+} from './workflow-errors.js'
+import type {
+  ApprovalOutcome,
+  StepState,
+  WorkflowApprovalOptions,
+} from './workflow.types.js'
+import type {
+  ApprovalDecider,
+  WorkflowApprovalPolicy,
+} from './dsl/workflow-dsl.types.js'
+import {
+  approvalPolicyRefusal,
+  WorkflowApprovalForbiddenError,
+} from './workflow-approval-policy.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}`
+}
+
+/**
+ * An answer to an approval gate, as the audit trail sees it.
+ *
+ * `denied` covers both a submission refused at the door and a decision cleared
+ * on replay — from the trail's point of view they are the same event, someone
+ * tried to answer a gate they could not.
+ */
+export type ApprovalAuditEvent = {
+  runId: string
+  reason: string
+  outcome: 'success' | 'denied'
+  decidedBy?: ApprovalDecider
+  refusal?: string
+}
+
+/** 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>
+  getRunOwner: (runId: string) => Promise<string | undefined>
+  auditApproval: (event: ApprovalAuditEvent) => Promise<void>
+}
+
+/** What run state holds for an approval point between suspension and replay. */
+type ApprovalRecord = {
+  decision?: unknown
+  decidedAt?: string
+  decidedBy?: ApprovalDecider
+  policy?: WorkflowApprovalPolicy
+  expiresAt?: string
+  error?: unknown
+}
+
+/**
+ * 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.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
+ */
+export const recordApprovalDecision = async (
+  store: ApprovalStore,
+  runId: string,
+  reason: string,
+  decision: unknown,
+  decidedBy?: ApprovalDecider
+): 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 ApprovalRecord
+
+  if (record.policy) {
+    const refusal = approvalPolicyRefusal(
+      record.policy,
+      await store.getRunOwner(runId),
+      decidedBy
+    )
+    if (refusal) {
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy,
+        refusal,
+      })
+      throw new WorkflowApprovalForbiddenError(reason, refusal)
+    }
+  }
+
+  await store.updateRunState(runId, stateKey, {
+    ...record,
+    decision,
+    decidedAt: new Date().toISOString(),
+    decidedBy,
+    error: undefined,
+  } satisfies ApprovalRecord)
+  await store.auditApproval({ runId, reason, outcome: 'success', decidedBy })
+  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.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
+ */
+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,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+      },
+      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 ApprovalRecord
+
+  const policy: WorkflowApprovalPolicy = {
+    approvers: options.approvers,
+    approverScope: options.approverScope,
+  }
+
+  if (stepState.status === 'pending') {
+    await store.setStepRunning(stepState.stepId)
+    record = { ...record, policy }
+    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)
+    } else {
+      await store.updateRunState(runId, stateKey, record)
+    }
+  }
+
+  if (record.decision !== undefined) {
+    const refusal = approvalPolicyRefusal(
+      policy,
+      await store.getRunOwner(runId),
+      record.decidedBy
+    )
+    if (refusal) {
+      await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision: undefined,
+        decidedAt: undefined,
+        decidedBy: undefined,
+        error: [{ message: refusal }],
+      } satisfies ApprovalRecord)
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy: record.decidedBy,
+        refusal,
+      })
+      throw new WorkflowSuspendedException(runId, reason)
+    }
+
+    const validation = await options.schema['~standard'].validate(
+      record.decision
+    )
+    if (validation.issues) {
+      await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision: undefined,
+        decidedAt: undefined,
+        decidedBy: 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)
+    }
+    // Spread rather than assigned, so a gate answered without a session keeps
+    // the shape it had before there was anything to record.
+    const outcome: ApprovalOutcome<unknown> = {
+      status: 'decided',
+      data: validation.value,
+      ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
+      ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
+    }
+    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-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,

package/src/wirings/workflow/workflow-meta-resolver.ts

@@ -0,0 +1,45 @@
+import { pikkuState } from '../../pikku-state.js'
+import type { WorkflowRuntimeMeta } from './workflow.types.js'
+
+export type ResolvedWorkflowMeta = {
+  meta: WorkflowRuntimeMeta
+  packageName: string | null
+  resolvedName: string
+}
+
+/**
+ * Resolves a workflow name against the root registry, then — for a
+ * `namespace:name` form — against the addon package that claims the namespace.
+ */
+export const resolveWorkflowMeta = (
+  name: string
+): ResolvedWorkflowMeta | null => {
+  const rootMeta = pikkuState(null, 'workflows', 'meta')
+  if (rootMeta[name]) {
+    return { meta: rootMeta[name], packageName: null, resolvedName: name }
+  }
+
+  const colonIndex = name.indexOf(':')
+  if (colonIndex === -1) {
+    return null
+  }
+
+  const namespace = name.substring(0, colonIndex)
+  const localName = name.substring(colonIndex + 1)
+  const addons = pikkuState(null, 'addons', 'packages')
+  const pkgConfig = addons?.get(namespace)
+  if (!pkgConfig) {
+    return null
+  }
+
+  const addonMeta = pikkuState(pkgConfig.package, 'workflows', 'meta')
+  if (!addonMeta?.[localName]) {
+    return null
+  }
+
+  return {
+    meta: addonMeta[localName],
+    packageName: pkgConfig.package,
+    resolvedName: localName,
+  }
+}