@pikku/core 0.10.1 → 0.11.0

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

@@ -0,0 +1,85 @@
+import type { CoreWorkflow } from './workflow.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+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 {
+  constructor(
+    public readonly runId: string,
+    public readonly stepName: string
+  ) {
+    super(`Workflow paused at step: ${stepName}`)
+    this.name = 'WorkflowAsyncException'
+  }
+}
+
+/**
+ * Exception thrown when workflow is cancelled
+ */
+export class WorkflowCancelledException extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly reason?: string
+  ) {
+    super(reason || 'Workflow cancelled')
+    this.name = 'WorkflowCancelledException'
+  }
+}
+
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowNotFoundError extends PikkuError {
+  constructor(name: string) {
+    super(`Workflow not found: ${name}`)
+  }
+}
+
+/**
+ * Error class for workflow not found
+ */
+export class WorkflowRunNotFound extends PikkuError {
+  constructor(runId: string) {
+    super(`Workflow run not found: ${runId}`)
+  }
+}
+
+/**
+ * Register a workflow with the system
+ */
+export const wireWorkflow = <
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    any,
+    any,
+    any
+  > = CorePikkuFunctionConfig<any, any, any>,
+>(
+  workflow: CoreWorkflow<PikkuFunctionConfig>
+) => {
+  // Get workflow metadata from inspector
+  const meta = pikkuState('workflows', 'meta')
+  const workflowMeta = meta[workflow.name]
+  if (!workflowMeta) {
+    throw new Error(
+      `Workflow metadata not found for '${workflow.name}'. Make sure to run the CLI to generate metadata.`
+    )
+  }
+
+  // Register the function with pikku
+  addFunction(workflowMeta.pikkuFuncName, {
+    func: workflow.func.func,
+    auth: workflow.func.auth,
+    permissions: workflow.func.permissions,
+    middleware: workflow.func.middleware as any,
+    tags: workflow.func.tags,
+    docs: workflow.func.docs as any,
+  })
+
+  // Store workflow definition in state
+  const registrations = pikkuState('workflows', 'registrations')
+  registrations.set(workflow.name, workflow)
+}

package/src/wirings/workflow/workflow.types.ts

@@ -0,0 +1,332 @@
+import {
+  PikkuDocs,
+  MiddlewareMetadata,
+  SerializedError,
+  CoreSingletonServices,
+  CreateSessionServices,
+  CoreConfig,
+} from '../../types/core.types.js'
+import { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+
+export interface WorkflowServiceConfig {
+  retries: number
+  retryDelay: number
+  orchestratorQueueName: string
+  stepWorkerQueueName: string
+  sleeperRPCName: string
+}
+
+/**
+ * Workflow run status
+ */
+export type WorkflowStatus = 'running' | 'completed' | 'failed' | 'cancelled'
+
+/**
+ * Workflow step status
+ */
+export type StepStatus =
+  | 'pending'
+  | 'running'
+  | 'scheduled'
+  | 'succeeded'
+  | 'failed'
+
+/**
+ * Workflow run representation
+ */
+export interface WorkflowRun {
+  /** Unique run ID */
+  id: string
+  /** Workflow name */
+  workflow: string
+  /** Current status */
+  status: WorkflowStatus
+  /** Input data */
+  input: any
+  /** Output data (if completed) */
+  output?: any
+  /** Error (if failed) */
+  error?: SerializedError
+  /** Creation timestamp */
+  createdAt: Date
+  /** Last update timestamp */
+  updatedAt: Date
+}
+
+/**
+ * Step state representation
+ */
+export interface StepState {
+  /** Unique step ID */
+  stepId: string
+  /** Step status */
+  status: StepStatus
+  /** Step result (if done) */
+  result?: any
+  /** Step error (if error) */
+  error?: SerializedError
+  /** Number of attempts made (starts at 1) */
+  attemptCount: number
+  /** Maximum retry attempts allowed */
+  retries?: number
+  /** Delay between retries */
+  retryDelay?: string | number
+  /** Creation timestamp */
+  createdAt: Date
+  /** Last update timestamp */
+  updatedAt: Date
+  /** Timestamp when step started running */
+  runningAt?: Date
+  /** Timestamp when step was scheduled */
+  scheduledAt?: Date
+  /** Timestamp when step succeeded */
+  succeededAt?: Date
+  /** Timestamp when step failed */
+  failedAt?: Date
+}
+
+/**
+ * Core workflow definition
+ */
+export type CoreWorkflow<
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    any,
+    any,
+    any
+  > = CorePikkuFunctionConfig<any, any, any>,
+> = {
+  /** Unique workflow name */
+  name: string
+  /** Description of the workflow */
+  description?: string
+  /** The workflow function */
+  func: PikkuFunctionConfig
+  /** Middleware chain for this workflow */
+  middleware?: PikkuFunctionConfig['middleware']
+  /** Permission requirements */
+  permissions?: PikkuFunctionConfig['permissions']
+  /** Tags for organization and filtering */
+  tags?: string[]
+  /** Documentation metadata */
+  docs?: PikkuDocs
+}
+
+/**
+ * Workflow step options
+ */
+export interface WorkflowStepOptions {
+  /** Display name for logs/UI (optional, doesn't affect execution) */
+  description?: string
+  /** Number of retry attempts for failed steps (only applies to local execution) */
+  retries?: number
+  /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
+  retryDelay?: string | number
+  // Future: timeout, failFast, priority
+}
+
+/**
+ * Type signature for workflow.do() RPC form - used by inspector
+ */
+export type WorkflowInteractionDoRPC = <TOutput = any, TInput = any>(
+  stepName: string,
+  rpcName: string,
+  data: TInput,
+  options?: WorkflowStepOptions
+) => Promise<TOutput>
+
+/**
+ * Type signature for workflow.do() inline form - used by inspector
+ */
+export type WorkflowInteractionDoInline = <T>(
+  stepName: string,
+  fn: () => Promise<T> | T,
+  options?: WorkflowStepOptions
+) => Promise<T>
+
+/**
+ * Type signature for workflow.sleep() - used by inspector
+ */
+export type WorkflowInteractionSleep = (
+  stepName: string,
+  duration: string
+) => Promise<void>
+
+/**
+ * Workflow step metadata (extracted by inspector)
+ */
+export type WorkflowStepMeta =
+  | {
+      /** RPC form - generates queue worker */
+      type: 'rpc'
+      /** Cache key (stepName from workflow.do) */
+      stepName: string
+      /** RPC to invoke */
+      rpcName: string
+      /** Display name */
+      description?: string
+      /** Step options */
+      options?: WorkflowStepOptions
+    }
+  | {
+      /** Inline form - local execution */
+      type: 'inline'
+      /** Cache key (stepName from workflow.do) */
+      stepName: string
+      /** Display name */
+      description?: string
+      /** Step options */
+      options?: WorkflowStepOptions
+    }
+  | {
+      /** Sleep step */
+      type: 'sleep'
+      /** Cache key (stepName from workflow.sleep) */
+      stepName: string
+      /** Sleep duration */
+      duration: string | number
+    }
+
+/**
+ * Workflow step interaction context for RPC functions
+ * Provides step-level metadata including retry attempt tracking
+ */
+export interface WorkflowStepInteraction {
+  /** The workflow run ID */
+  runId: string
+  /** The unique step ID */
+  stepId: string
+  /** Current attempt number (1-indexed, increments on retry) */
+  attemptCount: number
+}
+
+/**
+ * Workflow interaction object for middleware
+ * Provides workflow-specific capabilities to function execution
+ */
+export interface PikkuWorkflowInteraction {
+  /** The workflow name */
+  workflowName: string
+  /** The current run ID */
+  runId: string
+  /** Get the current workflow run */
+  getRun: () => Promise<WorkflowRun>
+
+  /** Execute a workflow step (overloaded - RPC or inline form) */
+  do: WorkflowInteractionDoRPC & WorkflowInteractionDoInline
+
+  /** Sleep for a duration */
+  sleep: WorkflowInteractionSleep
+
+  /** Cancel the current workflow run */
+  cancel: (reason?: string) => Promise<void>
+}
+
+/**
+ * Workflow client interface
+ */
+export interface PikkuWorkflow {
+  /** Start a new workflow run */
+  start: <I>(input: I) => Promise<{ runId: string }>
+  /** Get a workflow run by ID */
+  getRun: (runId: string) => Promise<WorkflowRun>
+  /** Cancel a running workflow */
+  cancelRun: (runId: string) => Promise<void>
+}
+
+/**
+ * Workflows metadata for inspector/CLI
+ */
+export type WorkflowsMeta = Record<
+  string,
+  {
+    pikkuFuncName: string
+    workflowName: string
+    description?: string
+    session?: undefined
+    docs?: PikkuDocs
+    tags?: string[]
+    middleware?: MiddlewareMetadata[]
+    steps: WorkflowStepMeta[]
+  }
+>
+
+/**
+ * Interface for workflow orchestration
+ * Handles workflow execution, replay, orchestration logic, and run-level state
+ */
+export interface WorkflowService {
+  // Run-level state operations
+  createRun(workflowName: string, input: any): Promise<string>
+  getRun(id: string): Promise<WorkflowRun | null>
+  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  updateRunStatus(
+    id: string,
+    status: WorkflowStatus,
+    output?: any,
+    error?: SerializedError
+  ): Promise<void>
+  withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>
+  close(): Promise<void>
+
+  // Orchestration operations
+  resumeWorkflow(runId: string): Promise<void>
+  setServices(
+    singletonServices: CoreSingletonServices,
+    createSessionServices: CreateSessionServices,
+    config: CoreConfig
+  ): void
+  startWorkflow<I>(
+    name: string,
+    input: I,
+    rpcService: any
+  ): Promise<{ runId: string }>
+  runWorkflowJob(runId: string, rpcService: any): Promise<void>
+  orchestrateWorkflow(runId: string, rpcService: any): Promise<void>
+  executeWorkflowSleep(runId: string, stepId: string): Promise<void>
+
+  // Step-level state operations
+  insertStepState(
+    runId: string,
+    stepName: string,
+    rpcName: string,
+    data: any,
+    stepOptions?: { retries?: number; retryDelay?: string | number }
+  ): Promise<StepState>
+  getStepState(runId: string, stepName: string): Promise<StepState>
+  setStepRunning(stepId: string): Promise<void>
+  setStepScheduled(stepId: string): Promise<void>
+  setStepResult(stepId: string, result: any): Promise<void>
+  setStepError(stepId: string, error: Error): Promise<void>
+  createRetryAttempt(
+    stepId: string,
+    status: 'pending' | 'running'
+  ): Promise<StepState>
+
+  // Step execution
+  executeWorkflowStep(
+    runId: string,
+    stepName: string,
+    rpcName: string | null,
+    data: any,
+    rpcService: any
+  ): Promise<void>
+}
+
+/**
+ * Worker input types for generated queue workers
+ */
+export type WorkflowStepInput = {
+  runId: string
+  stepName: string
+  rpcName: string
+  data: any
+}
+
+export type WorkflowOrchestratorInput = {
+  runId: string
+}
+
+export type WorkflowSleeperInput = {
+  runId: string
+  stepId: string
+}