@pikku/core 0.12.78 → 0.12.79

package/src/wirings/gateway/gateway-authorization.test.ts

@@ -8,6 +8,7 @@ import {
   addGlobalPermission,
   clearPermissionsCache,
 } from '../../permissions.js'
+import { addTagMiddleware } from '../../middleware-runner.js'
 import type {
   GatewayAdapter,
   GatewayInboundMessage,
@@ -84,6 +85,31 @@ const seedCompiledMeta = () => {
   }
 }
 
+/**
+ * What the inspector records for a gateway and the function it was wired with.
+ * These tests wire gateways by hand, so nothing populates it otherwise — and it
+ * has to be in place before `wireGateway`, exactly as the generated bootstrap
+ * loads every meta file before any wiring file.
+ */
+const seedDeclaredHandler = (
+  gatewayName: string,
+  funcId: string,
+  funcMeta: Record<string, any>,
+  gatewayMeta: Record<string, any> = {}
+) => {
+  ;(pikkuState(null, 'function', 'meta') as any)[funcId] = {
+    pikkuFuncId: funcId,
+    inputSchemaName: null,
+    outputSchemaName: null,
+    ...funcMeta,
+  }
+  ;(pikkuState(null, 'gateway', 'meta') as any)[gatewayName] = {
+    pikkuFuncId: funcId,
+    name: gatewayName,
+    ...gatewayMeta,
+  }
+}
+
 const postMessage = async (route: string) => {
   const request = new Request(`http://localhost${route}`, {
     method: 'POST',
@@ -229,6 +255,68 @@ describe('gateway handler authorization', () => {
       assert.deepEqual(calls, ['ran'])
     })
 
+    test('a handler declared with pikkuFunc keeps its session requirement', async () => {
+      const calls: string[] = []
+
+      seedDeclaredHandler('declared-session', 'myHandler', {
+        sessionless: false,
+      })
+
+      wireGateway({
+        name: 'declared-session',
+        type: 'webhook',
+        route: '/webhooks/declared-session',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/declared-session')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(
+        calls,
+        [],
+        'a session-required pikkuFunc must not be silently made sessionless'
+      )
+    })
+
+    test('a handler declared sessionless keeps running without a session', async () => {
+      const calls: string[] = []
+
+      seedDeclaredHandler('declared-sessionless', 'mySessionlessHandler', {
+        sessionless: true,
+      })
+
+      wireGateway({
+        name: 'declared-sessionless',
+        type: 'webhook',
+        route: '/webhooks/declared-sessionless',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/declared-sessionless')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(calls, ['ran'])
+    })
+
     test('gateway-level auth: true requires a session', async () => {
       const calls: string[] = []
 
@@ -281,6 +369,49 @@ describe('gateway handler authorization', () => {
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 
+    test('tag middleware declared for the gateway actually runs', async () => {
+      const order: string[] = []
+
+      addTagMiddleware('audited', [
+        async (_s: any, _wire: any, next: any) => {
+          order.push('middleware')
+          await next()
+        },
+      ] as any)
+
+      seedDeclaredHandler(
+        'tagged',
+        'myTaggedHandler',
+        { sessionless: true },
+        { tags: ['audited'], middleware: [{ type: 'tag', tag: 'audited' }] }
+      )
+
+      wireGateway({
+        name: 'tagged',
+        type: 'webhook',
+        route: '/webhooks/tagged',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            order.push('handler')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/tagged')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(
+        order,
+        ['middleware', 'handler'],
+        'addTagMiddleware must gate a gateway carrying the tag'
+      )
+    })
+
     test('the adapter still auto-sends the handler reply', async () => {
       const adapter = createMockAdapter()
 

package/src/wirings/gateway/gateway-runner.ts

@@ -23,20 +23,46 @@ const bridgeMiddlewareSession = async (wire: PikkuRawWire): Promise<void> => {
   }
 }
 
+/**
+ * Metadata the inspector recorded for the function the gateway was wired with.
+ * The bootstrap loads every meta file before any wiring file, so this is
+ * already populated by the time a gateway wires itself. A gateway wired by
+ * hand rather than through codegen has no entry, and falls back to the
+ * sessionless default below.
+ */
+const declaredHandlerMeta = (config: CoreGateway) => {
+  const declaredFuncId = pikkuState(null, 'gateway', 'meta')[config.name]
+    ?.pikkuFuncId
+  return declaredFuncId
+    ? pikkuState(null, 'function', 'meta')[declaredFuncId]
+    : undefined
+}
+
 // knowledge: decisions/security/gateway-handlers-run-through-the-function-runner-gate.md
 const registerGatewayHandler = (config: CoreGateway): string => {
   const funcId = gatewayHandlerFuncId(config.name)
   const funcMeta = pikkuState(null, 'function', 'meta')
+  const declared = declaredHandlerMeta(config)
   funcMeta[funcId] = {
+    ...declared,
     pikkuFuncId: funcId,
-    inputSchemaName: null,
-    outputSchemaName: null,
-    sessionless: true,
+    inputSchemaName: declared?.inputSchemaName ?? null,
+    outputSchemaName: declared?.outputSchemaName ?? null,
+    sessionless: declared?.sessionless ?? true,
   }
   addFunction(funcId, config.func as any)
   return funcId
 }
 
+/**
+ * Tag middleware the inspector resolved for this gateway. It is keyed by
+ * gateway name rather than reachable from `config`, because `tags` is a
+ * compile-time input everywhere — nothing at runtime maps a tag to its
+ * middleware group.
+ */
+const gatewayInheritedMiddleware = (config: CoreGateway) =>
+  pikkuState(null, 'gateway', 'meta')[config.name]?.middleware
+
 export const resolveGatewayAdapter = (
   config: CoreGateway,
   services: CoreSingletonServices
@@ -134,6 +160,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
 const createWebhookPostHandler = (config: CoreGateway) => {
   const { name, middleware: userMiddleware } = config
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   return async (
     services: CoreSingletonServices,
@@ -169,6 +196,7 @@ const createWebhookPostHandler = (config: CoreGateway) => {
         singletonServices: services,
         data: () => parsed,
         auth: config.auth,
+        inheritedMiddleware,
         wire: wire as any,
       })
     }
@@ -253,6 +281,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
 
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   addFunction(connectFuncId, {
     auth: false,
@@ -292,6 +321,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
           singletonServices: services,
           data: () => parsed,
           auth: config.auth,
+          inheritedMiddleware,
           wire: wire as any,
         })
       }
@@ -333,6 +363,7 @@ export const createListenerMessageHandler = (
 ): ((rawData: unknown) => Promise<void>) => {
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
   const handlerFuncId = registerGatewayHandler(config)
+  const inheritedMiddleware = gatewayInheritedMiddleware(config)
 
   return async (rawData: unknown): Promise<void> => {
     const adapter = await resolveGatewayAdapter(config, singletonServices)
@@ -354,6 +385,7 @@ export const createListenerMessageHandler = (
         singletonServices,
         data: () => parsed,
         auth: config.auth,
+        inheritedMiddleware,
         wire,
       })
     }

package/src/wirings/secret/validate-secret-definitions.test.ts

@@ -108,6 +108,53 @@ describe('validateAndBuildSecretDefinitionsMeta', () => {
     )
   })
 
+  test('should carry allowedHosts into the meta', () => {
+    const definitions = [
+      {
+        name: 'example-api',
+        displayName: 'Example API',
+        secretId: 'EXAMPLE_API_CREDENTIALS',
+        allowedHosts: ['api.example.com', '*.example.com'],
+        sourceFile: 'a.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.deepStrictEqual(result['example-api']!.allowedHosts, [
+      'api.example.com',
+      '*.example.com',
+    ])
+  })
+
+  test('should carry allowedHosts into the meta for a shared secretId', () => {
+    const definitions = [
+      {
+        name: 'cred1',
+        displayName: 'Cred 1',
+        secretId: 'SHARED',
+        allowedHosts: ['first.example.com'],
+        sourceFile: 'a.ts',
+      },
+      {
+        name: 'cred2',
+        displayName: 'Cred 2',
+        secretId: 'SHARED',
+        allowedHosts: ['second.example.com'],
+        sourceFile: 'b.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    assert.deepStrictEqual(result['cred1']!.allowedHosts, ['first.example.com'])
+    assert.deepStrictEqual(result['cred2']!.allowedHosts, [
+      'second.example.com',
+    ])
+  })
+
   test('should handle empty definitions', () => {
     const result = validateAndBuildSecretDefinitionsMeta([], new Map())
     assert.deepStrictEqual(result, {})

package/src/wirings/secret/validate-secret-definitions.ts

@@ -57,6 +57,7 @@ export function validateAndBuildSecretDefinitionsMeta(
           oauth2: def.oauth2,
           rotationPeriod: def.rotationPeriod,
           docsUrl: def.docsUrl,
+          allowedHosts: def.allowedHosts,
           sourceFile: def.sourceFile,
         }
       }
@@ -75,6 +76,7 @@ export function validateAndBuildSecretDefinitionsMeta(
         oauth2: def.oauth2,
         rotationPeriod: def.rotationPeriod,
         docsUrl: def.docsUrl,
+        allowedHosts: def.allowedHosts,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -281,6 +281,25 @@ const DEFAULT_STALLED_RUN_MS = 5 * 60_000
 /** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
 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.
+ */
+const DEFAULT_UNDISPATCHED_STEP_MS = 30_000
+
+/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
+const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100
+
+/** First wait before a step already re-dispatched once is re-dispatched again. */
+const REDISPATCH_BACKOFF_MS = 30_000
+
+/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
+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. */
+const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000
+
 const WORKFLOW_POLL_MIN_MS = 10
 
 const WORKFLOW_POLL_FACTOR = 1.6
@@ -975,6 +994,118 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     return { resumed }
   }
 
+  /**
+   * Runs holding a step that has sat `pending` since before `before`, paired
+   * with the step that flagged them.
+   *
+   * Returns nothing by default so a store that cannot express the query keeps
+   * working unchanged — and, because it does not opt in, gains no re-dispatches
+   * either. A store must have an atomic `withStepLock` before overriding this,
+   * or no concurrency for one to exclude: the relay makes duplicate dispatch
+   * routine, and the claim in `executeWorkflowStepInner` is what keeps a
+   * duplicate from becoming a second execution. `kysely-postgres` and
+   * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
+   * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+   */
+  protected async findUndispatchedSteps(
+    _before: Date,
+    _limit: number
+  ): Promise<Array<{ runId: string; stepId: string }>> {
+    return []
+  }
+
+  /**
+   * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+   *
+   * Arming a step is two writes to two systems: the step row lands `pending`,
+   * then a queue or scheduler job is published. Nothing spans both, so a crash
+   * in between leaves a durable row that nothing will ever pick up — the run
+   * neither finishes nor fails. (Seen on a `workflow.sleep()`: a deploy restart
+   * landed between the sleep step's insert and its timer.)
+   *
+   * The row is the outbox record and this is the relay. Age is the only signal
+   * available — a step `pending` because its dispatch was lost is
+   * indistinguishable from one whose job is merely still queued — so a step
+   * past `undispatchedAfterMs` is re-dispatched regardless, and correctness
+   * rests on the claim rather than on the guess being right. A redundant
+   * dispatch costs one queue message: the loser reads `running` and returns
+   * without invoking anything.
+   *
+   * Re-dispatches back off per step (doubling from 30s, capped at 10m) so a
+   * genuine queue backlog is not amplified by a tick that keeps firing at the
+   * steps the backlog is already delaying. The backoff is per process and
+   * advisory — losing it on restart costs extra dispatches, never correctness.
+   *
+   * This is not self-starting. Call it from a scheduled task; ~30s suits a
+   * queue whose `pending`→`running` latency is well under that.
+   */
+  public async relayUndispatchedSteps(options?: {
+    undispatchedAfterMs?: number
+    limit?: number
+  }): Promise<{ redispatched: string[] }> {
+    const before = new Date(
+      Date.now() -
+        (options?.undispatchedAfterMs ?? DEFAULT_UNDISPATCHED_STEP_MS)
+    )
+    const steps = await this.findUndispatchedSteps(
+      before,
+      options?.limit ?? DEFAULT_UNDISPATCHED_STEP_LIMIT
+    )
+
+    // Backoff is keyed by run, not step, because the run is the unit of
+    // re-drive: `resumeWorkflow` replays the whole run and re-dispatches every
+    // step still owed a job. Holding off a single step while resuming its run
+    // would not suppress anything.
+    const now = Date.now()
+    const runIds = new Set<string>()
+    for (const { runId } of steps) {
+      const eligibleAt = this.redispatchBackoff.get(runId)
+      if (eligibleAt !== undefined && eligibleAt > now) {
+        continue
+      }
+      this.noteRedispatch(runId, now)
+      runIds.add(runId)
+    }
+
+    const redispatched: string[] = []
+    for (const runId of runIds) {
+      try {
+        await this.resumeWorkflow(runId)
+        redispatched.push(runId)
+      } catch (err) {
+        // One unresumable run must not stop the tick from relaying the rest.
+        getSingletonServices()?.logger?.error(
+          `Failed to re-dispatch workflow run ${runId}: ${err instanceof Error ? err.message : String(err)}`
+        )
+      }
+    }
+    return { redispatched }
+  }
+
+  /** Advisory, per-process record of when a run may next be re-dispatched. */
+  private readonly redispatchBackoff = new Map<string, number>()
+
+  private readonly redispatchDelays = new Map<string, number>()
+
+  private noteRedispatch(runId: string, now: number): void {
+    const previous = this.redispatchDelays.get(runId)
+    const delay = Math.min(
+      previous === undefined ? REDISPATCH_BACKOFF_MS : previous * 2,
+      REDISPATCH_BACKOFF_MAX_MS
+    )
+    // A run that settles is never returned again, so entries are only evicted by
+    // this bound — oldest first, which is also least recently re-dispatched.
+    if (this.redispatchBackoff.size >= REDISPATCH_BACKOFF_MAX_ENTRIES) {
+      const oldest = this.redispatchBackoff.keys().next()
+      if (!oldest.done) {
+        this.redispatchBackoff.delete(oldest.value)
+        this.redispatchDelays.delete(oldest.value)
+      }
+    }
+    this.redispatchDelays.set(runId, delay)
+    this.redispatchBackoff.set(runId, now + delay)
+  }
+
   protected resolveStepJobOptions(
     stepOptions?: WorkflowStepOptions
   ): JobOptions {

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

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