@pikku/core 0.12.70 → 0.12.71

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

@@ -0,0 +1,153 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createScenarioRunner } from './pikku-scenario-service.js'
+import type { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+
+const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+const fakeActor = (
+  name: string,
+  handler: (rpcName: string, data: unknown) => Promise<unknown>
+): ScenarioActor => ({
+  name,
+  email: `${name}@actors.local`,
+  invoke: async (rpcName: string, data: unknown) => handler(rpcName, data),
+  invokeRaw: async (rpcName: string, data: unknown) => ({
+    status: 200,
+    ok: true,
+    body: await handler(rpcName, data),
+  }),
+})
+
+const setup = async (ws: InMemoryWorkflowService) => {
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: noopLogger,
+  } as any)
+  const runId = await ws.createRun('scenarioTest', {}, true, 'hash', {
+    type: 'test',
+  } as any)
+  ws.registerInlineRun(runId)
+  return runId
+}
+
+/**
+ * The scenario wire, wrapped rather than returned directly: it carries a
+ * `then` — the Gherkin phase, not a promise — so awaiting one is awaiting a
+ * thenable, and the runtime calls it as a step.
+ */
+const scenarioWire = async (rpcService: any = {}): Promise<{ wire: any }> => {
+  const { workflowService } = createScenarioRunner()
+  const ws = workflowService as InMemoryWorkflowService
+  const runId = await setup(ws)
+  return { wire: ws.createWorkflowWire('scenarioTest', runId, rpcService) }
+}
+
+describe('workflow.expectError', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('returns the message when the call throws as expected', async () => {
+    const intruder = fakeActor('intruder', async () => {
+      throw new Error('Forbidden: not your todo')
+    })
+    const { wire } = await scenarioWire()
+
+    const message = await wire.expectError(
+      'intruder cannot delete',
+      'deleteTodo',
+      { todoId: 't1' },
+      { actor: intruder }
+    )
+
+    assert.equal(message, 'Forbidden: not your todo')
+  })
+
+  test('fails when the call succeeds instead of throwing', async () => {
+    const { wire } = await scenarioWire({
+      rpcWithWire: async () => ({ deleted: true }),
+    })
+
+    await assert.rejects(
+      wire.expectError('should have failed', 'deleteTodo', {}, { retries: 0 }),
+      /expected an error but the call succeeded/
+    )
+  })
+
+  test('fails when the error message does not match', async () => {
+    const { wire } = await scenarioWire({
+      rpcWithWire: async () => {
+        throw new Error('database offline')
+      },
+    })
+
+    await assert.rejects(
+      wire.expectError(
+        'wrong reason',
+        'deleteTodo',
+        {},
+        { matches: /Forbidden/, retries: 0 }
+      ),
+      /did not match .*database offline/
+    )
+  })
+})
+
+describe('workflow.expectService', () => {
+  beforeEach(() => resetPikkuState())
+
+  const stubCalls = (
+    calls: Array<{ service: string; method: string; args: unknown[] }>
+  ) => ({
+    rpcWithWire: async (rpcName: string) => {
+      assert.equal(rpcName, 'pikkuScenarioGetStubCalls')
+      return calls
+    },
+  })
+
+  const oneEmail = () =>
+    stubCalls([{ service: 'email', method: 'send', args: [{ to: 'a@b.c' }] }])
+
+  test('passes when the service method was called', async () => {
+    const { wire } = await scenarioWire(oneEmail())
+
+    await wire.expectService('an email went out', 'email.send')
+  })
+
+  test('a call count that does not match names what was recorded', async () => {
+    const { wire } = await scenarioWire(oneEmail())
+
+    await assert.rejects(
+      wire.expectService('two emails', 'email.send', {
+        times: 2,
+        retries: 0,
+      }),
+      /expected 2 call\(s\).*found 1.*email\.send/s
+    )
+  })
+
+  test('calledWith matches on the first argument', async () => {
+    const { wire } = await scenarioWire(oneEmail())
+
+    await wire.expectService('emailed the customer', 'email.send', {
+      calledWith: { to: 'a@b.c' },
+    })
+    await assert.rejects(
+      wire.expectService('emailed someone else', 'email.send', {
+        calledWith: { to: 'x@y.z' },
+        retries: 0,
+      }),
+      /found 0/
+    )
+  })
+
+  test('a name that is not service.method is rejected outright', async () => {
+    const { wire } = await scenarioWire(stubCalls([]))
+
+    await assert.rejects(
+      wire.expectService('bad name', 'emailsend'),
+      /needs 'service\.method'/
+    )
+  })
+})

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

@@ -89,7 +89,7 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
 
     // Simulate replay: reset per-run ordinals so the same logical step name
     // resolves to the same durable step key.
-    ;(ws as any).resetStepOrdinals(runId)
+    await (ws as any).beginReplay(runId)
     const replayWire = ws.createWorkflowWire('scenarioTest', runId, {})
     const replayed = await replayWire.do(
       'step',

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

@@ -58,7 +58,7 @@ describe('dispatch durability: a transient queue failure is recoverable', () =>
     // and the step transitions to `scheduled`. A real replay runs through
     // runWorkflowJob which resets the ordinal counter; simulate that so the
     // second reach resolves to the same step key, not the next ordinal.
-    ;(ws as any).resetStepOrdinals(runId)
+    await (ws as any).beginReplay(runId)
     queueUp = true
     await assert.rejects(
       (ws as any).rpcStep(runId, 'thing', 'doThing', {}, {}),

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

@@ -0,0 +1,59 @@
+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() {} }
+
+/**
+ * Captures what the workflow service hands the queue, so a test can tell
+ * whether core serialised the payload on the way past.
+ */
+function serviceWithCapturingQueue() {
+  const added: Array<{ queueName: string; data: any }> = []
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: {
+      add: async (queueName: string, data: any) => {
+        added.push({ queueName, data })
+        return 'job-1'
+      },
+    },
+    logger: silentLogger,
+  } as any)
+  return { ws: new InMemoryWorkflowService() as any, added }
+}
+
+describe('dispatching a step does not serialise the payload twice', () => {
+  test('the queue receives the payload core was given', async () => {
+    const { ws, added } = serviceWithCapturingQueue()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    const payload = { when: new Date('2020-01-01T00:00:00.000Z'), n: 1 }
+
+    await ws.queueStepWorker(runId, 'step-1', 'rpc.fn', payload)
+
+    assert.equal(added.length, 1)
+    assert.ok(
+      added[0]!.data.data.when instanceof Date,
+      'core round-tripped the payload through JSON before handing it to a queue that serialises it anyway'
+    )
+    assert.equal(added[0]!.data.data.n, 1)
+    assert.equal(added[0]!.data.runId, runId)
+    assert.equal(added[0]!.data.stepName, 'step-1')
+  })
+
+  test('a payload the queue cannot serialise is still the queue’s problem, not a silent drop', async () => {
+    const { ws, added } = serviceWithCapturingQueue()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    const circular: any = { name: 'loop' }
+    circular.self = circular
+
+    await ws.queueStepWorker(runId, 'step-1', 'rpc.fn', circular)
+
+    assert.equal(added[0]!.data.data.self, added[0]!.data.data)
+  })
+})

package/src/wirings/workflow/workflow-mirror.test.ts

@@ -0,0 +1,178 @@
+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 { WorkflowRunMirror } from './workflow.types.js'
+
+/**
+ * Every method on `WorkflowRunMirror`. A mirror method that is added to the
+ * interface but never wired into the service writes nothing at runtime, and
+ * nothing else would catch that — so the list is spelled out here.
+ */
+const MIRROR_METHODS = [
+  'createRun',
+  'updateRunStatus',
+  'insertStepState',
+  'setStepRunning',
+  'setStepScheduled',
+  'setStepResult',
+  'setStepChildRunId',
+  'setStepError',
+  'createRetryAttempt',
+  'setBranchTaken',
+  'updateRunState',
+  'upsertWorkflowVersion',
+  'updateWorkflowVersionStatus',
+] as const
+
+type Call = { method: string; args: any[] }
+
+/** A mirror that records every call, and optionally throws on all of them. */
+const recordingMirror = (
+  onCall?: (method: string) => void
+): { mirror: WorkflowRunMirror; calls: Call[] } => {
+  const calls: Call[] = []
+  const mirror = {} as any
+  for (const method of MIRROR_METHODS) {
+    mirror[method] = async (...args: any[]) => {
+      calls.push({ method, args })
+      onCall?.(method)
+    }
+  }
+  return { mirror, calls }
+}
+
+const service = (mirror?: WorkflowRunMirror) => {
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: { error() {}, info() {}, warn() {}, debug() {} },
+  } as any)
+  const ws = new InMemoryWorkflowService() as any
+  ws.mirror = mirror
+  return ws
+}
+
+/** Drive every write the service mirrors, in dependency order. */
+const driveEveryWrite = async (ws: any) => {
+  const runId = await ws.createRun('flow', { a: 1 }, false, 'hash', {
+    type: 'test',
+  })
+  const step = await ws.insertStepState(runId, 'step-1', 'rpc.fn', { x: 1 })
+  await ws.setStepRunning(step.stepId)
+  await ws.setStepScheduled(step.stepId)
+  await ws.setStepResult(step.stepId, 'ok')
+  await ws.setStepChildRunId(step.stepId, 'child-1')
+  await ws.setStepError(step.stepId, new Error('boom'))
+  await ws.createRetryAttempt(step.stepId, 'pending')
+  await ws.setBranchTaken(step.stepId, 'left')
+  await ws.updateRunState(runId, 'total', 42)
+  await ws.upsertWorkflowVersion('flow', 'hash', { nodes: {} }, 'code')
+  await ws.updateWorkflowVersionStatus('flow', 'hash', 'archived')
+  await ws.updateRunStatus(runId, 'completed', 'output')
+  return { runId, step }
+}
+
+describe('mirroring workflow state', () => {
+  test('every mirror method is wired to the write it shadows', async () => {
+    const { mirror, calls } = recordingMirror()
+    await driveEveryWrite(service(mirror))
+
+    assert.deepEqual(
+      [...new Set(calls.map((c) => c.method))].sort(),
+      [...MIRROR_METHODS].sort()
+    )
+  })
+
+  test('a mirror write carries the same identifiers as the write it shadows', async () => {
+    const { mirror, calls } = recordingMirror()
+    const ws = service(mirror)
+    const { runId, step } = await driveEveryWrite(ws)
+
+    const call = (method: string) => calls.find((c) => c.method === method)!
+    assert.equal(call('createRun').args[0], runId)
+    assert.equal(call('createRun').args[1], 'flow')
+    assert.equal(call('insertStepState').args[0], runId)
+    assert.equal(call('insertStepState').args[1].stepId, step.stepId)
+    assert.equal(call('insertStepState').args[1].stepName, 'step-1')
+    assert.equal(call('insertStepState').args[1].rpcName, 'rpc.fn')
+    assert.equal(call('setStepResult').args[1], 'ok')
+    assert.equal(call('setStepChildRunId').args[1], 'child-1')
+    assert.equal(call('setBranchTaken').args[1], 'left')
+    assert.equal(call('updateRunState').args[2], 42)
+    assert.equal(call('updateRunStatus').args[1], 'completed')
+  })
+
+  test('a step error reaches the mirror serialised, not as a live Error', async () => {
+    const { mirror, calls } = recordingMirror()
+    await driveEveryWrite(service(mirror))
+
+    const serialised = calls.find((c) => c.method === 'setStepError')!.args[1]
+    assert.equal(serialised instanceof Error, false)
+    assert.equal(serialised.message, 'boom')
+    assert.equal(typeof serialised.stack, 'string')
+    assert.equal(typeof serialised.expected, 'boolean')
+  })
+
+  test('the mirror only ever sees a write that already landed', async () => {
+    const seen: Array<string | undefined> = []
+    const { mirror } = recordingMirror()
+    const ws = service(mirror)
+    ;(mirror as any).updateRunStatus = async () => {
+      seen.push((await ws.getRun(runIdRef.id))?.status)
+    }
+    const runIdRef = { id: '' }
+
+    runIdRef.id = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.updateRunStatus(runIdRef.id, 'completed', 'output')
+
+    assert.deepEqual(
+      seen,
+      ['completed'],
+      'the mirror ran before the write it was mirroring'
+    )
+  })
+
+  test('a write that fails is not mirrored', async () => {
+    const { mirror, calls } = recordingMirror()
+    const ws = service(mirror)
+    ws.updateRunStatusImpl = async () => {
+      throw new Error('database down')
+    }
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+
+    await assert.rejects(
+      ws.updateRunStatus(runId, 'completed'),
+      /database down/
+    )
+    assert.equal(
+      calls.some((c) => c.method === 'updateRunStatus'),
+      false,
+      'a status the store rejected was reported to the mirror as if it had happened'
+    )
+  })
+})
+
+describe('a mirror that is broken', () => {
+  test('no write fails because the mirror did', async () => {
+    const { mirror } = recordingMirror((method) => {
+      throw new Error(`mirror down on ${method}`)
+    })
+    const ws = service(mirror)
+
+    const { runId } = await driveEveryWrite(ws)
+
+    assert.equal((await ws.getRun(runId))?.status, 'completed')
+    assert.equal((await ws.getRun(runId))?.output, 'output')
+    assert.deepEqual(await ws.getRunState(runId), { total: 42 })
+  })
+
+  test('no mirror configured is not an error path', async () => {
+    const ws = service(undefined)
+    const { runId } = await driveEveryWrite(ws)
+    assert.equal((await ws.getRun(runId))?.status, 'completed')
+  })
+})

package/src/wirings/workflow/workflow-replay-snapshot.test.ts

@@ -0,0 +1,139 @@
+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 inlineService() {
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: { add: async () => {} },
+    logger: silentLogger,
+  } as any)
+  return new InMemoryWorkflowService()
+}
+
+/**
+ * Every per-step read the service issues. In a real backend each one is its own
+ * round-trip, so a replay that walks N completed steps costs N of them — and
+ * over the life of a run that is O(N^2).
+ */
+function countStepReads(ws: any) {
+  const counter = { reads: 0 }
+  const original = ws.getStepState.bind(ws)
+  ws.getStepState = async (...args: any[]) => {
+    counter.reads++
+    return original(...args)
+  }
+  return counter
+}
+
+async function seedRun(ws: any, steps: number) {
+  const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
+  ws.registerInlineRun(runId)
+  await ws.beginReplay(runId)
+  for (let i = 0; i < steps; i++) {
+    await ws.inlineStep(runId, `step-${i}`, async () => i)
+  }
+  ws.endReplay(runId)
+  return runId
+}
+
+describe('replay reads the run steps once, not once per step', () => {
+  test('a replay over completed steps issues no per-step reads', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 8)
+
+    const counter = countStepReads(ws)
+    await ws.beginReplay(runId)
+    for (let i = 0; i < 8; i++) {
+      await ws.inlineStep(runId, `step-${i}`, async () => {
+        throw new Error(`step-${i} re-ran instead of replaying its cached result`)
+      })
+    }
+    ws.endReplay(runId)
+
+    assert.equal(
+      counter.reads,
+      0,
+      `the replay still read each step individually (${counter.reads} reads for 8 steps)`
+    )
+  })
+
+  test('the snapshot still returns each step its own cached result', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 4)
+
+    await ws.beginReplay(runId)
+    const replayed: unknown[] = []
+    for (let i = 0; i < 4; i++) {
+      replayed.push(
+        await ws.inlineStep(runId, `step-${i}`, async () => 'must not run')
+      )
+    }
+    ws.endReplay(runId)
+
+    assert.deepEqual(replayed, [0, 1, 2, 3])
+  })
+
+  test('a step reached for the first time mid-replay is created, not mistaken for a miss', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 2)
+
+    await ws.beginReplay(runId)
+    await ws.inlineStep(runId, 'step-0', async () => 'cached')
+    await ws.inlineStep(runId, 'step-1', async () => 'cached')
+    const fresh = await ws.inlineStep(runId, 'step-new', async () => 'ran')
+    ws.endReplay(runId)
+
+    assert.equal(fresh, 'ran')
+    assert.equal((await ws.getStepState(runId, 'step-new')).result, 'ran')
+  })
+
+  test('a second replay sees what the previous one wrote', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 1)
+
+    await ws.beginReplay(runId)
+    await ws.inlineStep(runId, 'step-0', async () => 'must not run')
+    await ws.inlineStep(runId, 'late', async () => 'first')
+    ws.endReplay(runId)
+
+    await ws.beginReplay(runId)
+    await ws.inlineStep(runId, 'step-0', async () => 'must not run')
+    const late = await ws.inlineStep(runId, 'late', async () => 'must not run')
+    ws.endReplay(runId)
+
+    assert.equal(late, 'first', 'the second replay re-ran a step the first one completed')
+  })
+
+  test('outside a replay, steps are still read one at a time', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 3)
+
+    const counter = countStepReads(ws)
+    await ws.inlineStep(runId, 'step-0', async () => 'must not run')
+
+    assert.equal(
+      counter.reads,
+      1,
+      'a call outside a replay must read the step directly rather than trust a stale snapshot'
+    )
+  })
+
+  test('a backend with no bulk read falls back to per-step reads', async () => {
+    const ws: any = inlineService()
+    const runId = await seedRun(ws, 3)
+    ws.listStepStates = async () => null
+
+    const counter = countStepReads(ws)
+    await ws.beginReplay(runId)
+    for (let i = 0; i < 3; i++) {
+      await ws.inlineStep(runId, `step-${i}`, async () => 'must not run')
+    }
+    ws.endReplay(runId)
+
+    assert.equal(counter.reads, 3)
+  })
+})