@pikku/core 0.12.134 → 0.12.135

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.12.135
+
+### Patch Changes
+
+- ce3e5f5: Saga compensation for workflows. A function declares `compensate` inline; when a workflow step fails, completed steps are undone newest-first as durable `<step>:compensate` steps. New run statuses `compensating`, `compensated` and `compensation_failed`, `workflow.milestone(name)` to bound the unwind, `{ compensate: false }` to opt a call out, nested-workflow unwinding, and `PikkuWorkflowService.cancelRun` which unwinds too. Graph nodes replace `onError` with `recover` (`nodeId`, `nodeId[]` or `'ignore'`), exposing the error as `wire.graph.recoveringFrom`. **Breaking:** the DSL `onError` step option and the graph `onError` node field are removed; `getRunSteps` is now abstract on `PikkuWorkflowService`.
+- fb36c37: Remove `WebhookSigningSecret` from `@pikku/core/hmac`: declare `verify` on `wireTriggerWebhookSource` instead, or use `hmacDigest`, `verifyHmacSignature`, `verifyPublicKeySignature` and `timingSafeStringEqual` directly. The trigger skill and the online-shop snippet now teach declarative `verify`, and the `verify` JSDoc describes bodiless requests correctly.
+
 ## 0.12.134
 
 ### Patch Changes

package/dist/function/compensation-name.d.ts

@@ -0,0 +1,4 @@
+export declare const COMPENSATION_STEP_SUFFIX = ":compensate";
+export declare const compensationStepName: (stepName: string) => string;
+export declare const isCompensationStepName: (stepName: string) => boolean;
+export declare const forwardStepName: (stepName: string) => string;

package/dist/function/compensation-name.js

@@ -0,0 +1,6 @@
+export const COMPENSATION_STEP_SUFFIX = ':compensate';
+export const compensationStepName = (stepName) => `${stepName}${COMPENSATION_STEP_SUFFIX}`;
+export const isCompensationStepName = (stepName) => stepName.endsWith(COMPENSATION_STEP_SUFFIX);
+export const forwardStepName = (stepName) => isCompensationStepName(stepName)
+    ? stepName.slice(0, -COMPENSATION_STEP_SUFFIX.length)
+    : stepName;

package/dist/function/function-meta.types.d.ts

@@ -58,6 +58,8 @@ export type FunctionRuntimeMeta = {
     readonly?: boolean;
     deploy?: 'serverless' | 'server' | 'auto';
     sessionless?: boolean;
+    /** The function declares a `compensate`, run as the sibling `<id>:compensate` when a workflow unwinds. */
+    compensate?: boolean;
     /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
     workflowQueued?: boolean;
     /** Retry count when this function is used as a workflow step. */

package/dist/function/function-runner.js

@@ -1,4 +1,5 @@
 import { beginChanges } from './abort-scope.js';
+import { forwardStepName, isCompensationStepName } from './compensation-name.js';
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../wirings/channel/channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
@@ -71,6 +72,22 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     let funcConfig = funcMap.get(funcName);
     const allMeta = pikkuState(packageName, 'function', 'meta');
     let funcMeta = allMeta[funcName];
+    if ((!funcConfig || !funcMeta) && isCompensationStepName(funcName)) {
+        const forwardName = forwardStepName(funcName);
+        const forward = funcMap.get(forwardName);
+        const forwardMeta = allMeta[forwardName];
+        if (forward?.compensate && forwardMeta) {
+            const { compensate, ...rest } = forward;
+            funcConfig = { ...rest, func: compensate };
+            funcMeta = {
+                ...forwardMeta,
+                pikkuFuncId: funcName,
+                outputs: null,
+                expose: false,
+                compensate: undefined,
+            };
+        }
+    }
     if (!funcConfig || !funcMeta) {
         const { baseName, version } = parseVersionedId(funcName);
         if (version !== null) {

package/dist/function/functions.types.d.ts

@@ -83,6 +83,13 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     approvalRequired?: boolean;
     /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
     workflowQueued?: boolean;
+    /**
+     * Undoes this function's effect when a workflow that called it unwinds. It
+     * receives the function's own input, and `wire.workflow.compensatingFor`
+     * carries the forward output (or the error, when the forward step failed).
+     * It is never callable on its own — only the workflow engine runs it.
+     */
+    compensate?: (services: any, data: any, wire: any) => Promise<any> | any;
     /** Number of retry attempts when this function is used as a workflow step. */
     workflowRetries?: number;
     /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */

package/dist/testing/service-tests/queued-workflow-harness.d.ts

@@ -0,0 +1,61 @@
+import type { PikkuWorkflowService } from '../../wirings/workflow/pikku-workflow-service.js';
+import type { CompensatingFor } from '../../wirings/workflow/dsl/workflow-dsl.types.js';
+export type Handler = {
+    forward: (data: any, wire: any) => Promise<any> | any;
+    compensate?: (data: any, context: CompensatingFor) => Promise<void> | void;
+    queued?: boolean;
+};
+interface Job {
+    queue: string;
+    data: any;
+    attempts?: number;
+    attempt?: number;
+}
+/**
+ * Drives a workflow the way a deployment does: every orchestration and every
+ * `workflowQueued` step goes through a queue, and a pump plays the workers.
+ * Delays are ignored, so a retry runs on the next pass.
+ */
+export declare class QueuedWorkflowHarness {
+    handlers: Record<string, Handler>;
+    log: string[];
+    contexts: Array<{
+        rpc: string;
+        context: CompensatingFor | undefined;
+    }>;
+    recovering: Array<{
+        rpc: string;
+        from: any;
+    }>;
+    queue: Job[];
+    jobsRun: Array<{
+        queue: string;
+        step?: string;
+    }>;
+    ws: PikkuWorkflowService;
+    /** Return true to drop the job instead of running it, simulating a worker that never ran. */
+    dropWhen?: (job: Job) => boolean;
+    /** Make `queue.add` throw for a job, simulating the broker being unreachable. */
+    rejectAddWhen?: (queue: string, data: any) => boolean;
+    constructor(service: PikkuWorkflowService);
+    readonly rpc: {
+        rpcWithWire: (rpcName: string, data: any, wire: any) => Promise<any>;
+    };
+    register(name: string, handler: Handler): void;
+    defineDsl(name: string, body: (workflow: any, input: any) => Promise<any>): void;
+    defineGraph(name: string, entry: string, nodes: Record<string, any>): void;
+    start(name: string, input?: any): Promise<string>;
+    /** Run jobs until the queue is empty. */
+    pump(limit?: number): Promise<void>;
+    run(runId: string): Promise<import("../../wirings/workflow/workflow.types.js").WorkflowRun>;
+    steps(runId: string): Promise<(import("../../wirings/workflow/workflow.types.js").StepState & {
+        stepName: string;
+        rpcName?: string;
+        data?: any;
+    })[]>;
+    get undone(): string[];
+    ok(output?: any): Handler;
+    boom(message?: string): Handler;
+    undoable(output?: any): Handler;
+}
+export {};

package/dist/testing/service-tests/queued-workflow-harness.js

@@ -0,0 +1,151 @@
+import { pikkuState, resetPikkuState } from '../../pikku-state.js';
+import { addWorkflow } from '../../wirings/workflow/dsl/workflow-runner.js';
+/**
+ * Drives a workflow the way a deployment does: every orchestration and every
+ * `workflowQueued` step goes through a queue, and a pump plays the workers.
+ * Delays are ignored, so a retry runs on the next pass.
+ */
+export class QueuedWorkflowHarness {
+    handlers = {};
+    log = [];
+    contexts = [];
+    recovering = [];
+    queue = [];
+    jobsRun = [];
+    ws;
+    /** Return true to drop the job instead of running it, simulating a worker that never ran. */
+    dropWhen;
+    /** Make `queue.add` throw for a job, simulating the broker being unreachable. */
+    rejectAddWhen;
+    constructor(service) {
+        resetPikkuState();
+        this.ws = service;
+        const queueService = {
+            add: async (queue, data, options) => {
+                if (this.rejectAddWhen?.(queue, data)) {
+                    throw new Error('broker unreachable');
+                }
+                this.queue.push({ queue, data, attempts: options?.attempts ?? 1 });
+            },
+        };
+        pikkuState(null, 'package', 'singletonServices', {
+            logger: { error() { }, info() { }, warn() { }, debug() { } },
+            queueService,
+            workflowService: this.ws,
+        });
+    }
+    rpc = {
+        rpcWithWire: async (rpcName, data, wire) => {
+            const isCompensation = rpcName.endsWith(':compensate');
+            const base = isCompensation
+                ? rpcName.slice(0, -':compensate'.length)
+                : rpcName;
+            const handler = this.handlers[base];
+            this.contexts.push({
+                rpc: rpcName,
+                context: wire.workflow?.compensatingFor,
+            });
+            if (isCompensation) {
+                this.log.push(`undo:${base}`);
+                return handler.compensate(data, wire.workflow.compensatingFor);
+            }
+            this.log.push(`do:${base}`);
+            if (wire.graph?.recoveringFrom) {
+                this.recovering.push({ rpc: base, from: wire.graph.recoveringFrom });
+            }
+            return handler.forward(data, wire);
+        },
+    };
+    register(name, handler) {
+        this.handlers[name] = handler;
+        pikkuState(null, 'rpc', 'meta')[name] = name;
+        pikkuState(null, 'function', 'meta')[name] = {
+            name,
+            pikkuFuncId: name,
+            sessionless: true,
+            permissions: [],
+            workflowQueued: handler.queued !== false,
+            ...(handler.compensate ? { compensate: true } : {}),
+        };
+    }
+    defineDsl(name, body) {
+        pikkuState(null, 'workflows', 'meta')[name] = {
+            name,
+            pikkuFuncId: name,
+            source: 'dsl',
+            graphHash: `${name}-hash`,
+        };
+        pikkuState(null, 'function', 'meta')[name] = {
+            name,
+            sessionless: true,
+            permissions: [],
+        };
+        addWorkflow(name, {
+            func: async (_services, input, wire) => body(wire.workflow, input),
+        });
+    }
+    defineGraph(name, entry, nodes) {
+        pikkuState(null, 'workflows', 'meta')[name] = {
+            name,
+            pikkuFuncId: name,
+            source: 'graph',
+            entryNodeIds: [entry],
+            graphHash: `${name}-hash`,
+            nodes: Object.fromEntries(Object.entries(nodes).map(([id, node]) => [
+                id,
+                { nodeId: id, rpcName: id, retries: 0, ...node },
+            ])),
+        };
+    }
+    async start(name, input = {}) {
+        const { runId } = await this.ws.startWorkflow(name, input, { type: 'test' }, this.rpc);
+        await this.pump();
+        return runId;
+    }
+    /** Run jobs until the queue is empty. */
+    async pump(limit = 500) {
+        for (let i = 0; i < limit && this.queue.length > 0; i++) {
+            const job = this.queue.shift();
+            if (this.dropWhen?.(job))
+                continue;
+            this.jobsRun.push({ queue: job.queue, step: job.data.stepName });
+            try {
+                if (job.data.stepName !== undefined) {
+                    await this.ws.executeWorkflowStep(job.data.runId, job.data.stepName, job.data.rpcName, job.data.data, this.rpc);
+                }
+                else {
+                    await this.ws.orchestrateWorkflow(job.data.runId, this.rpc);
+                }
+            }
+            catch {
+                job.attempt = (job.attempt ?? 1) + 1;
+                if (job.attempt <= (job.attempts ?? 1))
+                    this.queue.push(job);
+            }
+        }
+        if (this.queue.length > 0)
+            throw new Error('queue did not drain');
+    }
+    async run(runId) {
+        return (await this.ws.getRun(runId));
+    }
+    async steps(runId) {
+        return this.ws.getRunSteps(runId);
+    }
+    get undone() {
+        return this.log.filter((l) => l.startsWith('undo'));
+    }
+    ok(output = {}) {
+        return { forward: async () => output };
+    }
+    boom(message = 'boom') {
+        return {
+            forward: async () => {
+                throw new Error(message);
+            },
+        };
+    }
+    undoable(output = {}) {
+        return { ...this.ok(output), compensate: async () => { } };
+    }
+}

package/dist/testing/service-tests/workflow-compensation-queued-tests.d.ts

@@ -0,0 +1,11 @@
+import type { PikkuWorkflowService } from '../../wirings/workflow/pikku-workflow-service.js';
+/**
+ * Conformance suite for saga compensation and graph `recover` on the queued
+ * path: every orchestration and step goes through a queue and is played back by
+ * a pump, as in a deployment. Each test gets a fresh service.
+ */
+export interface QueuedCompensationOptions {
+    /** False for a runtime where one run owns its storage and cannot start a child run. */
+    childWorkflows?: boolean;
+}
+export declare const defineWorkflowCompensationQueuedTests: (name: string, create: () => Promise<PikkuWorkflowService>, options?: QueuedCompensationOptions) => void;