@pikku/core 0.12.69 → 0.12.71

package/src/wirings/workflow/scenario-cookie-jar.test.ts

@@ -0,0 +1,108 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createCookieJar } from './scenario-cookie-jar.js'
+
+// Minimal target: hands out cookies, and reports back what it was sent.
+const startTarget = async () => {
+  let issued = 0
+  const server: Server = createServer((req, res) => {
+    if (req.url === '/set') {
+      issued++
+      res.setHeader('set-cookie', [
+        `session=s${issued}; Path=/; HttpOnly`,
+        `csrf=c${issued}; Path=/`,
+      ])
+      res.writeHead(200, { 'content-type': 'application/json' }).end('{}')
+      return
+    }
+    res.writeHead(200, { 'content-type': 'application/json' }).end(
+      JSON.stringify({
+        cookie: req.headers.cookie ?? '',
+        origin: req.headers.origin ?? '',
+      })
+    )
+  })
+  await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
+  const { port } = server.address() as { port: number }
+  return { server, apiUrl: `http://127.0.0.1:${port}` }
+}
+
+describe('createCookieJar', () => {
+  test('sends back the cookies the target set, on the next request', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const { fetch: call } = createCookieJar(apiUrl)
+    await call(`${apiUrl}/set`)
+    const seen = await (await call(`${apiUrl}/echo`)).json()
+
+    assert.match(seen.cookie, /session=s1/)
+    assert.match(seen.cookie, /csrf=c1/)
+  })
+
+  test('stamps the origin Better Auth checks on state-changing calls', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const seen = await (
+      await createCookieJar(apiUrl).fetch(`${apiUrl}/echo`)
+    ).json()
+
+    assert.equal(seen.origin, apiUrl)
+  })
+
+  test('replaces a cookie the target reissues rather than sending both', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const { fetch: call } = createCookieJar(apiUrl)
+    await call(`${apiUrl}/set`)
+    await call(`${apiUrl}/set`)
+    const seen = await (await call(`${apiUrl}/echo`)).json()
+
+    assert.match(seen.cookie, /session=s2/)
+    assert.doesNotMatch(seen.cookie, /session=s1/)
+  })
+
+  test('keeps each jar to itself, so one actor never inherits another session', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const first = createCookieJar(apiUrl)
+    await first.fetch(`${apiUrl}/set`)
+    const other = await (
+      await createCookieJar(apiUrl).fetch(`${apiUrl}/echo`)
+    ).json()
+
+    assert.equal(other.cookie, '')
+  })
+
+  test('forgets the session when cleared, so a re-login starts fresh', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const jar = createCookieJar(apiUrl)
+    await jar.fetch(`${apiUrl}/set`)
+    assert.equal(jar.empty, false)
+    jar.clear()
+    assert.equal(jar.empty, true)
+
+    const seen = await (await jar.fetch(`${apiUrl}/echo`)).json()
+    assert.equal(seen.cookie, '')
+  })
+
+  test('leaves the caller headers alone', async () => {
+    const { server, apiUrl } = await startTarget()
+    after(() => server.close())
+
+    const headers = new Headers({ 'x-test': 'kept' })
+    const { fetch: call } = createCookieJar(apiUrl)
+    await call(`${apiUrl}/set`)
+    await call(`${apiUrl}/echo`, { headers })
+
+    assert.equal(headers.get('cookie'), null)
+    assert.equal(headers.get('x-test'), 'kept')
+  })
+})

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -0,0 +1,65 @@
+/** A session held the way a browser holds one, for code driving a real target. */
+export interface ScenarioCookieJar {
+  /** `fetch`, but it sends what the target has set and keeps what it sets. */
+  fetch: typeof fetch
+  /** Forgets the session — what an actor does before signing in again. */
+  clear(): void
+  /**
+   * Whether the target has set anything yet. This is a fact about the jar, not
+   * about the session: a target that sets a CSRF or locale cookie before anyone
+   * signs in fills the jar without establishing one. Whoever needs to know
+   * whether a sign-in happened has to track the sign-in.
+   */
+  readonly empty: boolean
+}
+
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
+  const jar = new Map<string, string>()
+  const origin = new URL(apiUrl).origin
+  return {
+    fetch: async (input, init) => {
+      const headers = new Headers(init?.headers)
+      headers.set('origin', origin)
+      const held = [...jar].map(([name, value]) => `${name}=${value}`)
+      const caller = headers.get('cookie')
+      if (held.length > 0 || caller) {
+        headers.set('cookie', [caller, ...held].filter(Boolean).join('; '))
+      }
+      const response = await fetch(input, { ...init, headers })
+      for (const raw of response.headers.getSetCookie()) {
+        const [pair] = raw.split(';')
+        const separator = pair!.indexOf('=')
+        if (separator > 0) {
+          const name = pair!.slice(0, separator)
+          const value = pair!.slice(separator + 1)
+          // An empty value is how a target deletes a cookie — drop the name
+          // rather than holding a cookie whose value says it is gone.
+          if (value) {
+            jar.set(name, value)
+          } else {
+            jar.delete(name)
+          }
+        }
+      }
+      return response
+    },
+    clear: () => jar.clear(),
+    get empty() {
+      return jar.size === 0
+    },
+  }
+}

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-hooks.test.ts

@@ -0,0 +1,212 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { createScenarioRunner } from './pikku-scenario-service.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addWorkflow } from './dsl/workflow-runner.js'
+import type { ScenarioActors } from '../../services/scenario-actors-service.js'
+
+const noopLogger = {
+  error() {},
+  info() {},
+  warn() {},
+  debug() {},
+}
+
+const actors = {
+  admin: {
+    name: 'admin',
+    email: 'admin@actors.local',
+    invoke: async () => ({}),
+    invokeRaw: async () => ({ status: 200, ok: true, body: {} }),
+  },
+} as unknown as ScenarioActors
+
+type ScenarioHooks = {
+  before?: (services: any, data: any, wire: any) => Promise<void> | void
+  after?: (services: any, data: any, wire: any) => Promise<void> | void
+}
+
+/**
+ * Registers a scenario (or, with `source: 'dsl'`, a plain workflow) and runs it
+ * inline, returning the error it threw rather than propagating — every hook
+ * assertion here is about what ran, not about how the caller saw it.
+ */
+const runScenario = async (
+  name: string,
+  config: ScenarioHooks & { func: (...args: any[]) => any },
+  { input = {}, source = 'scenario' as 'scenario' | 'dsl' } = {}
+) => {
+  const { workflowService: ws, scenarioService } = createScenarioRunner()
+
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: noopLogger,
+    marker: 'singleton',
+  } as any)
+
+  const metaState = pikkuState(null, 'workflows', 'meta')
+  metaState[name] = {
+    name,
+    pikkuFuncId: name,
+    source,
+    graphHash: `${name}-hash`,
+  } as any
+
+  const functionMetaState = pikkuState(null, 'function', 'meta')
+  functionMetaState[name] = {
+    name,
+    sessionless: true,
+    permissions: [],
+  } as any
+
+  addWorkflow(name, config as any)
+
+  let error: any
+  try {
+    await ws.startWorkflow(name, input, {} as any, {}, { actors })
+  } catch (e: any) {
+    error = e
+  }
+  const runs = await ws.listRuns({ workflowName: name })
+  const run = runs[0]
+  return { error, run, ws }
+}
+
+describe('scenario before/after hooks', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('before runs, then the scenario, then after', async () => {
+    const order: string[] = []
+    await runScenario('hooksOrder', {
+      before: async () => {
+        order.push('before')
+      },
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        return { ok: true }
+      },
+    })
+    assert.deepEqual(order, ['before', 'func', 'after'])
+  })
+
+  test('after still runs when the scenario throws', async () => {
+    const order: string[] = []
+    const { error, run } = await runScenario('hooksAfterOnFailure', {
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        throw new Error('scenario blew up')
+      },
+    })
+    assert.deepEqual(order, ['func', 'after'])
+    assert.equal(error?.message, 'scenario blew up')
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('before throwing skips the scenario but still runs after', async () => {
+    const order: string[] = []
+    const { error, run } = await runScenario('hooksBeforeThrows', {
+      before: async () => {
+        order.push('before')
+        throw new Error('setup failed')
+      },
+      after: async () => {
+        order.push('after')
+      },
+      func: async () => {
+        order.push('func')
+        return { ok: true }
+      },
+    })
+    assert.deepEqual(order, ['before', 'after'], 'the func must not run')
+    assert.match(String(error?.message), /setup failed/)
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('after throwing fails a run that would otherwise have passed', async () => {
+    const { error, run } = await runScenario('hooksAfterThrows', {
+      after: async () => {
+        throw new Error('teardown failed')
+      },
+      func: async () => ({ ok: true }),
+    })
+    assert.match(String(error?.message), /teardown failed/)
+    assert.equal(run?.status, 'failed')
+  })
+
+  test('after throwing never masks the original failure', async () => {
+    const { error } = await runScenario('hooksAfterMasks', {
+      after: async () => {
+        throw new Error('teardown failed')
+      },
+      func: async () => {
+        throw new Error('the real failure')
+      },
+    })
+    assert.equal(
+      error?.message,
+      'the real failure',
+      'the scenario failure must be what the caller sees'
+    )
+    assert.match(
+      String((error as any)?.cause?.message),
+      /teardown failed/,
+      'the teardown failure must survive as the cause'
+    )
+  })
+
+  test('hooks receive the services, the input and the run actors', async () => {
+    const seen: any[] = []
+    await runScenario(
+      'hooksArgs',
+      {
+        before: async (services, data, wire) => {
+          seen.push({
+            marker: services.marker,
+            data,
+            actor: wire?.actors?.admin?.name,
+          })
+        },
+        after: async (services, data, wire) => {
+          seen.push({
+            marker: services.marker,
+            data,
+            actor: wire?.actors?.admin?.name,
+          })
+        },
+        func: async () => ({ ok: true }),
+      },
+      { input: { seed: 7 } }
+    )
+    assert.deepEqual(seen, [
+      { marker: 'singleton', data: { seed: 7 }, actor: 'admin' },
+      { marker: 'singleton', data: { seed: 7 }, actor: 'admin' },
+    ])
+  })
+
+  test('hooks are scenario-only — a plain DSL workflow never runs them', async () => {
+    const order: string[] = []
+    await runScenario(
+      'hooksNotForWorkflows',
+      {
+        before: async () => {
+          order.push('before')
+        },
+        after: async () => {
+          order.push('after')
+        },
+        func: async () => {
+          order.push('func')
+          return { ok: true }
+        },
+      },
+      { source: 'dsl' }
+    )
+    assert.deepEqual(order, ['func'])
+  })
+})

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

@@ -0,0 +1,66 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pollUntil } from './scenario-poll.js'
+
+describe('pollUntil', () => {
+  test('answers with the first attempt that produced something', async () => {
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return attempts === 3 ? 'ready' : undefined
+      },
+      { intervalMs: 1 }
+    )
+
+    assert.equal(found, 'ready')
+    assert.equal(attempts, 3)
+  })
+
+  test('gives up at the deadline rather than looping forever', async () => {
+    const started = Date.now()
+    const found = await pollUntil(() => undefined, {
+      timeoutMs: 30,
+      intervalMs: 5,
+    })
+
+    assert.equal(found, undefined)
+    assert.ok(Date.now() - started < 1_000, 'returned promptly')
+  })
+
+  test('always attempts at least once, however short the deadline', async () => {
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return 'immediate'
+      },
+      { timeoutMs: 0 }
+    )
+
+    assert.equal(attempts, 1)
+    assert.equal(found, 'immediate')
+  })
+
+  test('awaits an async attempt', async () => {
+    const found = await pollUntil(async () => 'awaited', { intervalMs: 1 })
+    assert.equal(found, 'awaited')
+  })
+
+  test('treats a falsy-but-defined answer as an answer', async () => {
+    // `false` is what a "did it happen?" probe returns, and it is a result —
+    // only `undefined` means "not yet".
+    let attempts = 0
+    const found = await pollUntil(
+      () => {
+        attempts++
+        return false
+      },
+      { timeoutMs: 50, intervalMs: 1 }
+    )
+
+    assert.equal(found, false)
+    assert.equal(attempts, 1)
+  })
+})

package/src/wirings/workflow/scenario-poll.ts

@@ -0,0 +1,36 @@
+/** How long to keep trying, and how long to wait between tries. */
+export interface PollOptions {
+  /** Total time to keep attempting before giving up. Default 15s. */
+  timeoutMs?: number
+  /** Gap between attempts. Default 250ms. */
+  intervalMs?: number
+}
+
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export const pollUntil = async <T>(
+  attempt: () => Promise<T | undefined> | T | undefined,
+  { timeoutMs = 15_000, intervalMs = 250 }: PollOptions = {}
+): Promise<T | undefined> => {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const answer = await attempt()
+    if (answer !== undefined) {
+      return answer
+    }
+    if (Date.now() >= deadline) {
+      return undefined
+    }
+    await new Promise((done) => setTimeout(done, intervalMs))
+  }
+}