@pikku/core 0.12.107 → 0.12.112

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

@@ -1,128 +0,0 @@
-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

@@ -1,132 +0,0 @@
-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'
-  }
-}
-
-/**
- * Thrown inside a workflow step when the run has been cancelled, so the step
- * stops rather than finishing work nobody wants.
- */
-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

@@ -1,175 +0,0 @@
-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'
-import type {
-  WorkflowPlannedStep,
-  WorkflowRun,
-  WorkflowRunWire,
-} from './workflow.types.js'
-
-const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
-
-const installSingletons = () =>
-  pikkuState(null, 'package', 'singletonServices', {
-    queueService: { add: async () => {} },
-    logger: silentLogger,
-  } as any)
-
-class SharedStoreWorkflowService extends InMemoryWorkflowService {
-  constructor(private readonly runStore: Map<string, WorkflowRun>) {
-    super()
-  }
-
-  protected override async createRunImpl(
-    workflowName: string,
-    input: any,
-    inline: boolean,
-    graphHash: string,
-    wire: WorkflowRunWire,
-    options?: {
-      deterministic?: boolean
-      plannedSteps?: WorkflowPlannedStep[]
-    }
-  ): Promise<string> {
-    const runId = await super.createRunImpl(
-      workflowName,
-      input,
-      inline,
-      graphHash,
-      wire,
-      options
-    )
-    this.runStore.set(runId, (await super.getRun(runId))!)
-    return runId
-  }
-
-  override async getRun(id: string): Promise<WorkflowRun | null> {
-    return this.runStore.get(id) ?? null
-  }
-}
-
-describe('whether a run is inline is decided by the run record, not by the process', () => {
-  test('an instance that did not start the run still knows it is inline', async () => {
-    installSingletons()
-    const store = new Map<string, WorkflowRun>()
-    const starter = new SharedStoreWorkflowService(store) as any
-    const observer = new SharedStoreWorkflowService(store) as any
-
-    const runId = await starter.createRun('flow', {}, true, 'hash', {
-      type: 'test',
-    })
-
-    assert.equal(await starter.isInline(runId), true)
-    assert.equal(
-      await observer.isInline(runId),
-      true,
-      'a second instance dispatched a queued job for a run that is already executing in-process'
-    )
-  })
-
-  test('an instance that did not start the run still knows it is queued', async () => {
-    installSingletons()
-    const store = new Map<string, WorkflowRun>()
-    const starter = new SharedStoreWorkflowService(store) as any
-    const observer = new SharedStoreWorkflowService(store) as any
-
-    const runId = await starter.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-
-    assert.equal(await starter.isInline(runId), false)
-    assert.equal(await observer.isInline(runId), false)
-  })
-
-  test('asking whether an unknown run is inline creates no state', async () => {
-    installSingletons()
-    const store = new Map<string, WorkflowRun>()
-    const ws = new SharedStoreWorkflowService(store) as any
-
-    assert.equal(await ws.isInline('no-such-run'), false)
-    assert.equal(ws.runContexts.size, 0)
-  })
-})
-
-describe('a run that stops executing here leaves no per-run state behind', () => {
-  const service = () => {
-    installSingletons()
-    return new InMemoryWorkflowService() as any
-  }
-
-  test('an inline run releases its ordinals when it unregisters', async () => {
-    const ws = service()
-    const before = ws.runContexts.size
-    const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
-
-    await ws.inlineStep(runId, 'a', async () => 1)
-    await ws.inlineStep(runId, 'a', async () => 2)
-    ws.unregisterInlineRun(runId)
-
-    assert.equal(
-      ws.runContexts.size,
-      before,
-      'the ordinals map outlived the run that owned it'
-    )
-  })
-
-  test('a completed run releases the ordinals a step left behind', async () => {
-    const ws = service()
-    const before = ws.runContexts.size
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-
-    await ws.inlineStep(runId, 'a', async () => 1)
-    await ws.updateRunStatus(runId, 'completed', 1)
-
-    assert.equal(
-      ws.runContexts.size,
-      before,
-      'a terminal run still held its replay state'
-    )
-  })
-
-  test('a failed run releases the ordinals a step left behind', async () => {
-    const ws = service()
-    const before = ws.runContexts.size
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-
-    await ws.inlineStep(runId, 'a', async () => 1)
-    await ws.updateRunStatus(runId, 'failed', undefined, { message: 'boom' })
-
-    assert.equal(ws.runContexts.size, before)
-  })
-
-  test('running a queued step releases its context when the step returns', async () => {
-    const ws = service()
-    const before = ws.runContexts.size
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-    await ws.insertStepState(runId, 'a', 'someRpc', {})
-
-    await ws.executeWorkflowStep(
-      runId,
-      'a',
-      'someRpc',
-      {},
-      {
-        rpcWithWire: async () => {
-          await ws.inlineStep(runId, 'nested', async () => 'ok')
-          return 'ok'
-        },
-      }
-    )
-
-    assert.equal(
-      ws.runContexts.size,
-      before,
-      'the step worker kept per-run state for a run it no longer executes'
-    )
-  })
-})

package/src/wirings/workflow/workflow-invocation-id.test.ts

@@ -1,51 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { uuidv5, deriveInvocationId } from './workflow-invocation-id.js'
-
-const UUID_RE =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
-
-describe('uuidv5', () => {
-  test('matches the canonical RFC 4122 v5 vector', () => {
-    const DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
-    assert.equal(
-      uuidv5('www.example.com', DNS),
-      '2ed6657d-e927-568b-95e1-2665a8aea6a2'
-    )
-  })
-
-  test('is deterministic and sets version 5 + RFC variant bits', () => {
-    const a = uuidv5('hello')
-    const b = uuidv5('hello')
-    assert.equal(a, b, 'same input → same UUID')
-    assert.match(a, UUID_RE, 'version nibble is 5 and variant is 8/9/a/b')
-  })
-
-  test('different names produce different UUIDs', () => {
-    assert.notEqual(uuidv5('a'), uuidv5('b'))
-  })
-})
-
-describe('deriveInvocationId', () => {
-  test('is stable across calls for the same run + step (the dedupe key)', () => {
-    const id1 = deriveInvocationId('run-1', 'updateUser')
-    const id2 = deriveInvocationId('run-1', 'updateUser')
-    assert.equal(id1, id2)
-    assert.match(id1, UUID_RE)
-  })
-
-  test('differs per step name within a run', () => {
-    assert.notEqual(
-      deriveInvocationId('run-1', 'updateUser'),
-      deriveInvocationId('run-1', 'chargeCard')
-    )
-  })
-
-  test('differs per run for the same step name', () => {
-    assert.notEqual(
-      deriveInvocationId('run-1', 'updateUser'),
-      deriveInvocationId('run-2', 'updateUser')
-    )
-  })
-})

package/src/wirings/workflow/workflow-invocation-id.ts

@@ -1,28 +0,0 @@
-import { createHash } from 'node:crypto'
-
-const PIKKU_WORKFLOW_NAMESPACE = '70696b6b-7500-5770-9f6c-6f77000a0001'
-
-const parseUuid = (uuid: string): Buffer =>
-  Buffer.from(uuid.replace(/-/g, ''), 'hex')
-
-const formatUuid = (bytes: Buffer): string => {
-  const hex = bytes.toString('hex')
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
-}
-
-export const uuidv5 = (
-  name: string,
-  namespace: string = PIKKU_WORKFLOW_NAMESPACE
-): string => {
-  const hash = createHash('sha1')
-    .update(parseUuid(namespace))
-    .update(name, 'utf8')
-    .digest()
-  const bytes = hash.subarray(0, 16)
-  bytes[6] = (bytes[6]! & 0x0f) | 0x50
-  bytes[8] = (bytes[8]! & 0x3f) | 0x80
-  return formatUuid(bytes)
-}
-
-export const deriveInvocationId = (runId: string, stepName: string): string =>
-  uuidv5(`${runId}:${stepName}`)

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

@@ -1,45 +0,0 @@
-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,
-  }
-}