@pikku/core 0.12.106 → 0.12.111

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

@@ -1,212 +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 { runWorkflowGraph } from './graph/graph-runner.js'
-import { assertWorkflowRunOwner } from './workflow-run-ownership.js'
-import { WorkflowStepFunctionMismatchError } from './workflow-errors.js'
-import { ForbiddenError } from '../../errors/errors.js'
-
-const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
-
-const seedSingletons = () =>
-  pikkuState(null, 'package', 'singletonServices', {
-    logger: silentLogger,
-    // `resumeWorkflow` hands the run back to the orchestrator queue; the tests
-    // here assert on what happened before that hand-off.
-    queueService: { add: async () => 'job-1' },
-  } as any)
-
-describe('a graph run starts at an entry node the graph declared', () => {
-  const meta = {
-    name: 'payout',
-    pikkuFuncId: 'payout',
-    source: 'graph' as const,
-    entryNodeIds: ['validate'],
-    graphHash: 'payout-hash',
-    nodes: {
-      validate: { nodeId: 'validate', rpcName: 'validatePayout' },
-      // Reachable only after validation, but its input is a literal — so
-      // `areDependenciesSatisfied` alone would happily start the run here.
-      transfer: {
-        nodeId: 'transfer',
-        rpcName: 'transferFunds',
-        input: { amount: 1000 },
-      },
-    },
-  }
-
-  test('a startNode outside entryNodeIds is rejected', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-
-    await assert.rejects(
-      runWorkflowGraph(
-        ws,
-        'payout',
-        {},
-        { rpcWithWire: async () => ({}) },
-        true,
-        'transfer',
-        undefined,
-        meta
-      ),
-      /'transfer' is not an entry node/
-    )
-  })
-
-  test('a declared entry node still starts the run', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-
-    const { runId } = await runWorkflowGraph(
-      ws,
-      'payout',
-      {},
-      { rpcWithWire: async () => ({}) },
-      true,
-      'validate',
-      undefined,
-      meta
-    )
-
-    assert.ok(runId, 'the graph ran from the entry node it declared')
-  })
-})
-
-describe('a step runs the function the workflow dispatched it with', () => {
-  test('a queue message naming another function is rejected', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'queue',
-    })
-    await ws.insertStepState(runId, 'notify', 'sendReceipt', {})
-
-    const invoked: string[] = []
-    await assert.rejects(
-      ws.executeWorkflowStep(runId, 'notify', 'deleteAllUsers', {}, {
-        rpcWithWire: async (rpcName: string) => {
-          invoked.push(rpcName)
-          return {}
-        },
-      } as any),
-      WorkflowStepFunctionMismatchError
-    )
-    assert.deepEqual(invoked, [], 'nothing was invoked')
-
-    const stepState = await ws.getStepState(runId, 'notify')
-    assert.equal(
-      stepState.status,
-      'pending',
-      'the forged message left the step untouched'
-    )
-  })
-
-  test('the dispatched function still runs', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'queue',
-    })
-    await ws.insertStepState(runId, 'notify', 'sendReceipt', {})
-
-    const invoked: string[] = []
-    await ws.executeWorkflowStep(runId, 'notify', 'sendReceipt', {}, {
-      rpcWithWire: async (rpcName: string) => {
-        invoked.push(rpcName)
-        return {}
-      },
-    } as any)
-
-    assert.deepEqual(invoked, ['sendReceipt'])
-  })
-})
-
-describe('workflow run ownership', () => {
-  test('a run started by a session is readable only by that session', () => {
-    assert.throws(
-      () =>
-        assertWorkflowRunOwner(
-          { type: 'http', pikkuUserId: 'user-a' },
-          {
-            userId: 'user-b',
-          }
-        ),
-      ForbiddenError
-    )
-    assert.throws(
-      () =>
-        assertWorkflowRunOwner(
-          { type: 'http', pikkuUserId: 'user-a' },
-          undefined
-        ),
-      ForbiddenError
-    )
-    assert.doesNotThrow(() =>
-      assertWorkflowRunOwner(
-        { type: 'http', pikkuUserId: 'user-a' },
-        {
-          userId: 'user-a',
-        }
-      )
-    )
-  })
-
-  test('a run with no recorded owner has no ownership to enforce', () => {
-    assert.doesNotThrow(() =>
-      assertWorkflowRunOwner({ type: 'trigger' }, { userId: 'user-b' })
-    )
-  })
-
-  test('approveStep does not impose ownership on a gate that did not ask for it', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'http',
-      pikkuUserId: 'owner',
-    })
-
-    await ws.approveStep(
-      runId,
-      'release-funds',
-      { ok: true },
-      {
-        userId: 'not-the-owner',
-      }
-    )
-
-    const state = await ws.getRunState(runId)
-    assert.equal(
-      Object.keys(state).length,
-      1,
-      'the decision was recorded, to be judged against the gate on replay'
-    )
-  })
-
-  test('approveStep accepts the run owner', async () => {
-    seedSingletons()
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'http',
-      pikkuUserId: 'owner',
-    })
-
-    await ws.approveStep(
-      runId,
-      'release-funds',
-      { ok: true },
-      {
-        userId: 'owner',
-      }
-    )
-
-    const state = await ws.getRunState(runId)
-    assert.equal(
-      Object.keys(state).length,
-      1,
-      'the owner’s decision was recorded'
-    )
-  })
-})

package/src/wirings/workflow/workflow-run-context.test.ts

@@ -1,172 +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() {} }
-
-function service() {
-  pikkuState(null, 'package', 'singletonServices', {
-    queueService: { add: async () => {} },
-    logger: silentLogger,
-  } as any)
-  return new InMemoryWorkflowService() as any
-}
-
-const newRun = (ws: any, inline = false) =>
-  ws.createRun('flow', {}, inline, 'hash', { type: 'test' })
-
-const trackDetaches = (ws: any): string[] => {
-  const detached: string[] = []
-  ws.setRunExtension(() => ({
-    attachRunContext: async () => {},
-    detachRunContext: (runId: string) => detached.push(runId),
-    decorateRunWire: () => {},
-    decorateWorkflowWire: () => {},
-    onBeforeRunFunc: async () => {},
-    onAfterRunFunc: async () => {},
-  }))
-  return detached
-}
-
-describe('per-run state is released when the run stops executing here', () => {
-  test('a finished replay leaves nothing behind', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    await ws.beginReplay(runId)
-    await ws.inlineStep(runId, 'a', async () => 1)
-    ws.endReplay(runId)
-
-    assert.equal(
-      ws.runContexts.size,
-      0,
-      'the replay held on to its ordinals, lineage or step snapshot'
-    )
-  })
-
-  test('the step the walk last reached does not survive its replay', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    await ws.beginReplay(runId)
-    await ws.inlineStep(runId, 'a', async () => 1)
-    ws.endReplay(runId)
-
-    assert.equal(ws.lastStepName(runId), undefined)
-  })
-
-  test('unregistering an inline run releases it', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    ws.registerInlineRun(runId)
-    assert.equal(await ws.isInline(runId), true)
-
-    ws.unregisterInlineRun(runId)
-    assert.equal(await ws.isInline(runId), false)
-    assert.equal(ws.runContexts.size, 0)
-  })
-
-  test('a replay inside an inline run does not change what the run is', async () => {
-    const ws = service()
-    const runId = await newRun(ws, true)
-
-    ws.registerInlineRun(runId)
-    await ws.beginReplay(runId)
-    ws.endReplay(runId)
-
-    assert.equal(
-      await ws.isInline(runId),
-      true,
-      'ending a replay dropped state the run still needs'
-    )
-  })
-
-  test("a queued run's extension context is released when the run reaches a terminal state", async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-    const detached = trackDetaches(ws)
-
-    await ws.updateRunStatus(runId, 'completed', null)
-
-    assert.deepEqual(
-      detached,
-      [runId],
-      'an extension holds live per-run state; a completed run must not keep it'
-    )
-    assert.equal(ws.runContexts.size, 0)
-  })
-
-  test('a suspended run keeps its extension context, because it can still be resumed', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-    const detached = trackDetaches(ws)
-
-    await ws.updateRunStatus(runId, 'suspended')
-
-    assert.deepEqual(detached, [])
-  })
-})
-
-describe('a replay reads the run once', () => {
-  test('the steps of a replay share one read of the run', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    let reads = 0
-    const getRun = ws.getRun.bind(ws)
-    ws.getRun = async (id: string) => {
-      reads++
-      return getRun(id)
-    }
-
-    await ws.beginReplay(runId)
-    await ws.getRunIdentity(runId)
-    await ws.getRunIdentity(runId)
-    await ws.getRunIdentity(runId)
-    ws.endReplay(runId)
-
-    assert.equal(reads, 1, `the run was read ${reads} times in one replay`)
-  })
-
-  test('the next replay re-reads the run rather than trusting the last one', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    let reads = 0
-    const getRun = ws.getRun.bind(ws)
-    ws.getRun = async (id: string) => {
-      reads++
-      return getRun(id)
-    }
-
-    await ws.beginReplay(runId)
-    await ws.getRunIdentity(runId)
-    ws.endReplay(runId)
-    await ws.beginReplay(runId)
-    await ws.getRunIdentity(runId)
-    ws.endReplay(runId)
-
-    assert.equal(reads, 2)
-  })
-
-  test('outside a replay the run is read every time', async () => {
-    const ws = service()
-    const runId = await newRun(ws)
-
-    let reads = 0
-    const getRun = ws.getRun.bind(ws)
-    ws.getRun = async (id: string) => {
-      reads++
-      return getRun(id)
-    }
-
-    await ws.getRunIdentity(runId)
-    await ws.getRunIdentity(runId)
-
-    assert.equal(reads, 2, 'a cached run outside a replay would go stale')
-    assert.equal(ws.runContexts.size, 0, 'reading a run must not create state')
-  })
-})

package/src/wirings/workflow/workflow-run-engine.types.ts

@@ -1,92 +0,0 @@
-import type { PikkuRawWire } from '../../types/core.types.js'
-import type { SerializedError } from '../../errors/serialized-error.js'
-import type {
-  CoreWorkflow,
-  PikkuWorkflowWire,
-  StepState,
-  WorkflowRun,
-  WorkflowStatus,
-  WorkflowStepOptions,
-} from './workflow.types.js'
-
-export interface RunLifecycleContext {
-  runId: string
-  run: WorkflowRun
-  workflowMeta: any
-  workflow: CoreWorkflow
-  wire: PikkuRawWire
-  packageName: string | null
-}
-
-/**
- * The subset of the workflow service a step executor is allowed to call back
- * into.
- */
-export interface WorkflowRunEngine {
-  inlineStep(
-    runId: string,
-    logicalStepName: string,
-    fn: Function,
-    stepOptions?: WorkflowStepOptions,
-    data?: any,
-    funcName?: string
-  ): Promise<any>
-  updateRunStatus(
-    runId: string,
-    status: WorkflowStatus,
-    output?: any,
-    error?: SerializedError
-  ): Promise<void>
-  onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>
-  verifyStepName(stepName: unknown): void
-}
-
-/**
- * Hooks a host may install to decorate runs it did not start. Used by the
- * scenario service to attach its own per-run state.
- */
-export interface WorkflowRunExtension {
-  attachRunContext(
-    runId: string,
-    workflowMeta: any,
-    options?: Record<string, any>
-  ): Promise<void>
-  detachRunContext(runId: string): void
-  decorateRunWire(
-    wire: PikkuRawWire,
-    context: {
-      runId: string
-      workflowMeta: any
-      workflowWire: PikkuWorkflowWire
-    }
-  ): void
-  decorateWorkflowWire(
-    workflowWire: PikkuWorkflowWire,
-    context: {
-      name: string
-      runId: string
-      rpcService: any
-      addonNamespace?: string | null
-    }
-  ): void
-  onBeforeRunFunc(context: RunLifecycleContext): Promise<void>
-  onAfterRunFunc(
-    context: RunLifecycleContext,
-    outcome: 'completed' | 'failed' | 'interrupted',
-    failure: unknown
-  ): Promise<void>
-}
-
-/**
- * Per-run bookkeeping held only for the lifetime of an in-process execution.
- */
-export type RunContext = {
-  activeExecutions: number
-  inline?: boolean
-  ordinals: Map<string, number>
-  lastStep?: string
-  replay?: {
-    steps?: Map<string, StepState>
-    run?: WorkflowRun
-  }
-}

package/src/wirings/workflow/workflow-run-ownership.ts

@@ -1,37 +0,0 @@
-import { ForbiddenError } from '../../errors/errors.js'
-import { addError } from '../../errors/error-handler.js'
-import type { CoreUserSession } from '../../types/core.types.js'
-import type { WorkflowRunWire } from './workflow.types.js'
-
-export class WorkflowRunForbiddenError extends ForbiddenError {
-  constructor() {
-    super('Not authorized to access this workflow run')
-  }
-}
-addError(WorkflowRunForbiddenError, {
-  status: 403,
-  message: 'Not authorized to access this workflow run.',
-})
-
-/**
- * A run started through a session records that session's user as its owner, and
- * only that user may read it. Who may *answer* a run's approval gates is the
- * gate's own declaration — see `approvers` on `workflow.approval()`.
- *
- * A run with no recorded owner — started by a trigger, a scheduler, or a route
- * wired without auth — has nobody to compare a caller against, so ownership is
- * not a control that exists for it. Gate those with `auth` or `permissions` on
- * the entrypoint instead.
- */
-export const assertWorkflowRunOwner = (
-  wire: WorkflowRunWire | undefined,
-  session: CoreUserSession | undefined
-): void => {
-  const owner = wire?.pikkuUserId
-  if (!owner) {
-    return
-  }
-  if (!session?.userId || session.userId !== owner) {
-    throw new WorkflowRunForbiddenError()
-  }
-}

package/src/wirings/workflow/workflow-run-polling.test.ts

@@ -1,127 +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 { WorkflowRun } from './workflow.types.js'
-
-class PollProbe extends InMemoryWorkflowService {
-  readonly reads: number[] = []
-  readonly waits: number[] = []
-  endAfter = 1
-
-  override async waitBeforeNextRead(ms: number): Promise<void> {
-    this.waits.push(ms)
-  }
-
-  override async startWorkflow(): Promise<{ runId: string }> {
-    return { runId: 'run-1' }
-  }
-
-  override async getRun(_runId: string): Promise<WorkflowRun | null> {
-    this.reads.push(Date.now())
-    const done = this.reads.length >= this.endAfter
-    return {
-      id: 'run-1',
-      status: done ? 'completed' : 'running',
-      output: 'result',
-    } as WorkflowRun
-  }
-}
-
-const probe = () => {
-  pikkuState(null, 'package', 'singletonServices', {
-    logger: { error() {}, info() {}, warn() {}, debug() {} },
-  } as any)
-  return new PollProbe()
-}
-
-describe('waiting for a run to finish', () => {
-  test('a run that finishes quickly is not held for a whole poll interval', async () => {
-    const ws = probe()
-    ws.endAfter = 2
-
-    const output = await ws.runToCompletion('flow', {}, {} as any)
-
-    assert.equal(output, 'result')
-    assert.equal(ws.waits.length, 1)
-    assert.ok(
-      ws.waits[0]! < 1000,
-      `a run done after one poll waited the full ${ws.waits[0]}ms default — a fixed interval makes every fast workflow pay for it`
-    )
-  })
-
-  test('reads spread out as a run keeps running', async () => {
-    const ws = probe()
-    ws.endAfter = 8
-
-    await ws.runToCompletion('flow', {}, {} as any)
-
-    assert.ok(ws.waits.length >= 6)
-    assert.ok(
-      ws.waits.at(-1)! > ws.waits[0]! * 2,
-      `waits stayed flat (${ws.waits.join('ms, ')}ms) — a run that drags on keeps costing the same read rate forever`
-    )
-    for (let i = 1; i < ws.waits.length; i++) {
-      assert.ok(
-        ws.waits[i]! >= ws.waits[i - 1]!,
-        `wait ${i} shrank (${ws.waits.join('ms, ')}ms)`
-      )
-    }
-  })
-
-  test('the wait never grows past the configured interval', async () => {
-    const ws = probe()
-    ws.endAfter = 12
-
-    await ws.runToCompletion('flow', {}, {} as any, { pollIntervalMs: 40 })
-
-    for (const wait of ws.waits) {
-      assert.ok(wait <= 40, `a wait of ${wait}ms overshot the 40ms ceiling`)
-    }
-    assert.equal(
-      ws.waits.at(-1),
-      40,
-      `the ceiling was never reached (${ws.waits.join('ms, ')}ms)`
-    )
-  })
-
-  test('a run that is already finished is returned without any wait', async () => {
-    const ws = probe()
-    ws.endAfter = 1
-
-    await ws.runToCompletion('flow', {}, {} as any)
-
-    assert.equal(ws.reads.length, 1)
-    assert.deepEqual(ws.waits, [])
-  })
-})
-
-describe('a run that ends badly', () => {
-  test('a failed run surfaces its error message', async () => {
-    const ws = probe()
-    ws.getRun = async () =>
-      ({
-        id: 'run-1',
-        status: 'failed',
-        error: { message: 'step blew up' },
-      }) as WorkflowRun
-
-    await assert.rejects(ws.runToCompletion('flow', {}, {} as any), /blew up/)
-  })
-
-  test('a cancelled run rejects', async () => {
-    const ws = probe()
-    ws.getRun = async () =>
-      ({ id: 'run-1', status: 'cancelled' }) as WorkflowRun
-
-    await assert.rejects(ws.runToCompletion('flow', {}, {} as any))
-  })
-
-  test('a run that disappears rejects rather than polling forever', async () => {
-    const ws = probe()
-    ws.getRun = async () => null
-
-    await assert.rejects(ws.runToCompletion('flow', {}, {} as any), /run-1/)
-  })
-})