@pikku/core 0.10.2 → 0.11.1

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -0,0 +1,430 @@
+import { runPikkuFunc } from '../../function/function-runner.js';
+import { pikkuState } from '../../pikku-state.js';
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { WorkflowAsyncException, WorkflowCancelledException, WorkflowNotFoundError, WorkflowRunNotFound, } from './workflow-runner.js';
+export class WorkflowServiceNotInitialized extends Error {
+}
+export class WorkflowStepNameNotString extends Error {
+    constructor(stepName) {
+        super(`Workflow step name must be a string. Received: ${typeof stepName}`);
+    }
+}
+/**
+ * Abstract workflow state service
+ * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
+ * Combines orchestration and step execution
+ */
+export class PikkuWorkflowService {
+    config;
+    singletonServices;
+    createWireServices;
+    constructor() { }
+    setServices(singletonServices, createWireServices, { workflow }) {
+        this.singletonServices = singletonServices;
+        this.createWireServices = createWireServices;
+        this.config = {
+            retries: workflow?.retries ?? 0,
+            retryDelay: workflow?.retryDelay ?? 0,
+            orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
+            stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
+            sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowStepSleeper',
+        };
+    }
+    // ============================================================================
+    // Workflow Lifecycle Methods
+    // ============================================================================
+    /**
+     * Resume a paused workflow by triggering the orchestrator
+     * @param runId - Run ID
+     */
+    async resumeWorkflow(runId) {
+        const queueService = this.verifyQueueService();
+        await queueService.add(this.getConfig().orchestratorQueueName, { runId });
+    }
+    /**
+     * Execute a workflow sleep step completion
+     * Sets the step result to null and resumes the workflow
+     * @param data - Sleeper input data
+     */
+    async executeWorkflowSleep(runId, stepId) {
+        await this.setStepResult(stepId, null);
+        await this.resumeWorkflow(runId);
+    }
+    /**
+     * Schedule orchestrator retry with delay
+     * @param runId - Run ID
+     * @param retryDelay - Delay in milliseconds or duration string (optional)
+     */
+    async scheduleOrchestratorRetry(runId, retryDelay) {
+        const queueService = this.verifyQueueService();
+        await queueService.add(this.getConfig().orchestratorQueueName, { runId }, retryDelay ? { delay: getDurationInMilliseconds(retryDelay) } : undefined);
+    }
+    /**
+     * Start a new workflow run
+     */
+    async startWorkflow(name, input, rpcService) {
+        const registrations = pikkuState('workflows', 'registrations');
+        const workflow = registrations.get(name);
+        if (!workflow) {
+            throw new WorkflowNotFoundError(name);
+        }
+        // Create workflow run in state
+        const runId = await this.createRun(name, input);
+        // If queue service is available, use remote execution (queue-based)
+        // Otherwise, execute directly (inline/synchronous)
+        if (this.singletonServices?.queueService) {
+            // Queue orchestrator to start the workflow
+            await this.resumeWorkflow(runId);
+        }
+        else {
+            // No queue service - execute directly via runWorkflowJob
+            await this.runWorkflowJob(runId, rpcService);
+        }
+        return { runId };
+    }
+    async runWorkflowJob(runId, rpcService) {
+        const run = await this.getRun(runId);
+        if (!run) {
+            throw new WorkflowRunNotFound(runId);
+        }
+        const registrations = pikkuState('workflows', 'registrations');
+        const workflow = registrations.get(run.workflow);
+        if (!workflow) {
+            throw new WorkflowNotFoundError(run.workflow);
+        }
+        await this.withRunLock(runId, async () => {
+            const meta = pikkuState('workflows', 'meta');
+            const workflowMeta = meta[run.workflow];
+            const workflowWire = this.createWorkflowWire(run.workflow, runId, rpcService);
+            const wire = { workflow: workflowWire };
+            try {
+                const result = await runPikkuFunc('workflow', workflowMeta.workflowName, workflowMeta.pikkuFuncName, {
+                    singletonServices: this.singletonServices,
+                    wire,
+                    createWireServices: this.createWireServices,
+                    data: () => run.input,
+                });
+                await this.updateRunStatus(runId, 'completed', result);
+            }
+            catch (error) {
+                if (error instanceof WorkflowAsyncException) {
+                    // Normal - workflow paused for step execution
+                    throw error;
+                }
+                // Check if it's a WorkflowCancelledException
+                if (error instanceof WorkflowCancelledException) {
+                    // Workflow was cancelled - status already updated, just rethrow
+                    throw error;
+                }
+                await this.updateRunStatus(runId, 'failed', undefined, {
+                    message: error.message,
+                    stack: error.stack,
+                    code: error.code,
+                });
+                throw error;
+            }
+        });
+    }
+    /**
+     * Execute a single workflow step (called by worker)
+     * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
+     */
+    async executeWorkflowStep(runId, stepName, rpcName, data, rpcService) {
+        // Use step-level lock to prevent concurrent execution of same step
+        await this.withStepLock(runId, stepName, async () => {
+            // Get step state
+            let stepState = await this.getStepState(runId, stepName);
+            // Idempotency - if already succeeded, resume orchestrator and return
+            if (stepState.status === 'succeeded') {
+                await this.resumeWorkflow(runId);
+                return;
+            }
+            // Log warning if already running (race condition)
+            if (stepState.status === 'running') {
+                return;
+            }
+            // If status is 'failed', this is a retry - create new attempt history
+            if (stepState.status === 'failed') {
+                stepState = await this.createRetryAttempt(stepState.stepId, 'running');
+            }
+            if (stepState.status !== 'pending') {
+                // Mark step as running (pending or failed status)
+                await this.setStepRunning(stepState.stepId);
+            }
+            try {
+                // Execute RPC with workflow step context
+                const result = await rpcService.rpcWithWire(rpcName, data, {
+                    workflowStep: {
+                        runId,
+                        stepId: stepState.stepId,
+                        attemptCount: stepState.attemptCount,
+                    },
+                });
+                // Store result and mark succeeded
+                await this.setStepResult(stepState.stepId, result);
+                // Resume orchestrator to continue workflow
+                try {
+                    await this.resumeWorkflow(runId);
+                }
+                catch (resumeError) {
+                    throw resumeError;
+                }
+            }
+            catch (error) {
+                // Store error and mark failed
+                await this.setStepError(stepState.stepId, error);
+                const maxAttempts = (stepState.retries ?? 0) + 1;
+                const retriesExhausted = stepState.attemptCount >= maxAttempts;
+                if (retriesExhausted) {
+                    // No more retries - resume orchestrator to mark workflow as failed
+                    await this.resumeWorkflow(runId);
+                }
+                // Always throw so queue knows the job failed and can retry if needed
+                throw error;
+            }
+        });
+    }
+    /**
+     * Orchestrate workflow execution (called by orchestrator)
+     * Runs workflow job and handles async exceptions
+     */
+    async orchestrateWorkflow(runId, rpcService) {
+        try {
+            // Run workflow job (replays with caching)
+            await this.runWorkflowJob(runId, rpcService);
+        }
+        catch (error) {
+            if (error.name === 'WorkflowAsyncException' ||
+                error.name === 'WorkflowCancelledException') {
+                return;
+            }
+            await this.updateRunStatus(runId, 'failed', undefined, {
+                message: error.message,
+                stack: error.stack,
+                code: error.code,
+            });
+            throw error;
+        }
+    }
+    verifyQueueService() {
+        if (!this.singletonServices?.queueService) {
+            throw new Error('QueueService not configured. Remote workflows require a queue service.');
+        }
+        return this.singletonServices.queueService;
+    }
+    async rpcStep(runId, stepName, rpcName, data, rpcService, stepOptions) {
+        // Check if step already exists
+        let stepState;
+        try {
+            stepState = await this.getStepState(runId, stepName);
+        }
+        catch (error) {
+            // Step doesn't exist - create it
+            stepState = await this.insertStepState(runId, stepName, rpcName, data, stepOptions);
+        }
+        if (stepState.status === 'succeeded') {
+            // Return cached result
+            return stepState.result;
+        }
+        if (stepState.status === 'failed') {
+            // Step failed with retries exhausted - throw error to fail the workflow
+            const error = new Error(stepState.error?.message ||
+                `Step '${stepName}' failed after exhausting all retries`);
+            // Preserve original error properties if available
+            if (stepState.error) {
+                Object.assign(error, stepState.error);
+            }
+            throw error;
+        }
+        if (stepState.status === 'scheduled') {
+            // Step is already scheduled, pause workflow
+            throw new WorkflowAsyncException(runId, stepName);
+        }
+        // Step is pending - schedule it
+        await this.setStepScheduled(stepState.stepId);
+        // Enqueue step worker
+        if (this.singletonServices.queueService) {
+            // Map step retry options to queue job options
+            const retries = stepOptions?.retries ?? 0;
+            const retryDelay = stepOptions?.retryDelay;
+            await this.singletonServices.queueService.add(this.getConfig().stepWorkerQueueName, {
+                runId,
+                stepName,
+                rpcName,
+                data,
+            }, {
+                // attempts includes initial attempt, retries doesn't
+                attempts: retries + 1,
+                // Map retry delay to backoff
+                backoff: typeof retryDelay === 'number'
+                    ? { type: 'fixed', delay: retryDelay }
+                    : retryDelay === 'exponential'
+                        ? 'exponential'
+                        : undefined,
+            });
+        }
+        else {
+            // No queue service - execute locally
+            const retries = stepOptions?.retries ?? 0;
+            const retryDelay = stepOptions?.retryDelay;
+            const attemptCount = stepState.attemptCount;
+            try {
+                const result = await rpcService.rpcWithWire(rpcName, data, {
+                    workflowStep: {
+                        runId,
+                        stepId: stepState.stepId,
+                        attemptCount: stepState.attemptCount,
+                    },
+                });
+                await this.setStepResult(stepState.stepId, result);
+                return result;
+            }
+            catch (error) {
+                // Record the error (marks step as failed)
+                await this.setStepError(stepState.stepId, error);
+                // Check if we should retry
+                if (attemptCount < retries) {
+                    // Create a new pending retry attempt (copies metadata from failed step)
+                    await this.createRetryAttempt(stepState.stepId, 'pending');
+                    // Schedule orchestrator to retry after delay
+                    await this.scheduleOrchestratorRetry(runId, retryDelay);
+                    // Pause workflow - orchestrator will replay and pick up new attempt
+                    throw new WorkflowAsyncException(runId, stepName);
+                }
+                // No more retries, fail the workflow
+                throw error;
+            }
+        }
+        // Pause workflow - step will callback when done
+        throw new WorkflowAsyncException(runId, stepName);
+    }
+    async inlineStep(runId, stepName, fn, stepOptions) {
+        // Check if step already exists
+        let stepState;
+        try {
+            stepState = await this.getStepState(runId, stepName);
+        }
+        catch (error) {
+            // Step doesn't exist - create it (inline, no RPC)
+            stepState = await this.insertStepState(runId, stepName, null, // No RPC for inline steps
+            null, // No data for inline steps
+            stepOptions);
+        }
+        if (stepState.status === 'succeeded') {
+            // Return cached result
+            return stepState.result;
+        }
+        // Execute inline function
+        const retries = stepOptions?.retries ?? this.getConfig().retries;
+        const retryDelay = stepOptions?.retryDelay ?? this.getConfig().retryDelay;
+        const attemptCount = stepState.attemptCount;
+        try {
+            const result = await fn();
+            await this.setStepResult(stepState.stepId, result);
+            return result;
+        }
+        catch (error) {
+            // Record the error (marks step as failed)
+            await this.setStepError(stepState.stepId, error);
+            // Check if we should retry
+            if (attemptCount < retries) {
+                // Create a new pending retry attempt (copies metadata from failed step)
+                await this.createRetryAttempt(stepState.stepId, 'pending');
+                // Schedule orchestrator to retry after delay
+                await this.scheduleOrchestratorRetry(runId, retryDelay);
+                // Pause workflow - orchestrator will replay and pick up new attempt
+                throw new WorkflowAsyncException(runId, stepName);
+            }
+            // No more retries, fail the workflow
+            throw error;
+        }
+    }
+    async sleepStep(runId, stepName, duration) {
+        // Check if step already exists
+        let stepState;
+        try {
+            stepState = await this.getStepState(runId, stepName);
+        }
+        catch (error) {
+            // Step doesn't exist - create it (sleep step, no RPC)
+            stepState = await this.insertStepState(runId, stepName, null, // No RPC for sleep steps
+            { duration }, // Store duration as data
+            undefined // No retry options for sleep
+            );
+        }
+        if (stepState.status === 'succeeded') {
+            // Sleep already completed, return immediately
+            return;
+        }
+        if (stepState.status === 'scheduled') {
+            // Sleep is already scheduled, pause workflow
+            throw new WorkflowAsyncException(runId, stepName);
+        }
+        // Step is pending - schedule it
+        await this.setStepScheduled(stepState.stepId);
+        // Check if we have queue service (remote mode) or inline mode
+        if (this.singletonServices.schedulerService) {
+            // Remote mode - enqueue sleep worker with delay
+            await this.singletonServices.schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, {
+                runId,
+                stepId: stepState.stepId,
+            });
+        }
+        else {
+            // Inline mode - use setTimeout with actual duration
+            await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
+            await this.setStepResult(stepState.stepId, null);
+            return;
+        }
+        // Pause workflow - sleep will callback when done
+        throw new WorkflowAsyncException(runId, stepName);
+    }
+    async cancelWorkflow(runId, reason) {
+        // Update workflow run status to cancelled
+        await this.updateRunStatus(runId, 'cancelled', undefined, {
+            message: reason || 'Workflow cancelled by user',
+            stack: '',
+            code: 'WORKFLOW_CANCELLED',
+        });
+        // Throw cancellation exception to stop workflow execution
+        throw new WorkflowCancelledException(runId, reason);
+    }
+    createWorkflowWire(workflowName, runId, rpcService) {
+        const workflowWire = {
+            workflowName,
+            runId,
+            getRun: async () => (await this.getRun(runId)),
+            // Implement workflow.do() - RPC form
+            do: async (stepName, rpcNameOrFn, dataOrOptions, options) => {
+                this.verifyStepName(stepName);
+                if (typeof rpcNameOrFn === 'string') {
+                    return await this.rpcStep(runId, stepName, rpcNameOrFn, dataOrOptions, rpcService, options);
+                }
+                else {
+                    return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
+                }
+            },
+            // Implement workflow.sleep()
+            sleep: async (stepName, duration) => {
+                this.verifyStepName(stepName);
+                await this.sleepStep(runId, stepName, getDurationInMilliseconds(duration));
+            },
+            // Implement workflow.cancel()
+            cancel: async (reason) => {
+                await this.cancelWorkflow(runId, reason);
+            },
+        };
+        return workflowWire;
+    }
+    verifyStepName(stepName) {
+        if (typeof stepName !== 'string') {
+            throw new WorkflowStepNameNotString(stepName);
+        }
+    }
+    getConfig() {
+        if (!this.singletonServices || !this.config) {
+            throw new WorkflowServiceNotInitialized();
+        }
+        return this.config;
+    }
+}

package/dist/wirings/workflow/workflow-runner.d.ts

@@ -0,0 +1,34 @@
+import { PikkuError } from '../../errors/error-handler.js';
+/**
+ * Exception thrown when workflow needs to pause for async step
+ */
+export declare class WorkflowAsyncException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+/**
+ * Exception thrown when workflow is cancelled
+ */
+export declare class WorkflowCancelledException extends Error {
+    readonly runId: string;
+    readonly reason?: string | undefined;
+    constructor(runId: string, reason?: string | undefined);
+}
+/**
+ * Error class for workflow not found
+ */
+export declare class WorkflowNotFoundError extends PikkuError {
+    constructor(name: string);
+}
+/**
+ * Error class for workflow not found
+ */
+export declare class WorkflowRunNotFound extends PikkuError {
+    constructor(runId: string);
+}
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export declare const addWorkflow: (workflowName: string, workflowFunc: any) => void;

package/dist/wirings/workflow/workflow-runner.js

@@ -0,0 +1,65 @@
+import { pikkuState } from '../../pikku-state.js';
+import { PikkuError } from '../../errors/error-handler.js';
+import { addFunction } from '../../function/function-runner.js';
+/**
+ * Exception thrown when workflow needs to pause for async step
+ */
+export class WorkflowAsyncException extends Error {
+    runId;
+    stepName;
+    constructor(runId, stepName) {
+        super(`Workflow paused at step: ${stepName}`);
+        this.runId = runId;
+        this.stepName = stepName;
+        this.name = 'WorkflowAsyncException';
+    }
+}
+/**
+ * Exception thrown when workflow is cancelled
+ */
+export class WorkflowCancelledException extends Error {
+    runId;
+    reason;
+    constructor(runId, reason) {
+        super(reason || 'Workflow cancelled');
+        this.runId = runId;
+        this.reason = reason;
+        this.name = 'WorkflowCancelledException';
+    }
+}
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowNotFoundError extends PikkuError {
+    constructor(name) {
+        super(`Workflow not found: ${name}`);
+    }
+}
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowRunNotFound extends PikkuError {
+    constructor(runId) {
+        super(`Workflow run not found: ${runId}`);
+    }
+}
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export const addWorkflow = (workflowName, workflowFunc) => {
+    // Get workflow metadata from inspector
+    const meta = pikkuState('workflows', 'meta');
+    const workflowMeta = meta[workflowName];
+    if (!workflowMeta) {
+        throw new Error(`Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // Store workflow definition in state
+    const registrations = pikkuState('workflows', 'registrations');
+    registrations.set(workflowName, {
+        name: workflowName,
+        func: workflowFunc,
+    });
+    // Register the function with pikku
+    addFunction(workflowMeta.pikkuFuncName, workflowFunc);
+};