duron 0.2.2 → 0.3.0-beta.1

package/src/step-manager.ts

@@ -5,6 +5,8 @@ import type { z } from 'zod'
 import {
   type Action,
   type ActionHandlerContext,
+  type StepDefinition,
+  type StepDefinitionHandlerContext,
   type StepHandlerContext,
   type StepOptions,
   StepOptionsSchema,
@@ -19,7 +21,9 @@ import {
   StepAlreadyExecutedError,
   StepTimeoutError,
   serializeError,
+  UnhandledChildStepsError,
 } from './errors.js'
+import type { ObserveContext, Span, TelemetryAdapter } from './telemetry/adapter.js'
 import pRetry from './utils/p-retry.js'
 import waitForAbort from './utils/wait-for-abort.js'
 
@@ -28,6 +32,8 @@ export interface TaskStep {
   cb: (ctx: StepHandlerContext) => Promise<any>
   options: StepOptions
   abortSignal: AbortSignal
+  parentStepId: string | null
+  parallel: boolean
 }
 
 /**
@@ -61,16 +67,27 @@ export class StepStore {
    * @param name - The name of the step
    * @param timeoutMs - Timeout in milliseconds for the step
    * @param retriesLimit - Maximum number of retries for the step
+   * @param parentStepId - The ID of the parent step (null for root steps)
+   * @param parallel - Whether this step runs in parallel (independent from siblings during time travel)
    * @returns Promise resolving to the created step ID
    * @throws Error if step creation fails
    */
-  async getOrCreate(jobId: string, name: string, timeoutMs: number, retriesLimit: number) {
+  async getOrCreate(
+    jobId: string,
+    name: string,
+    timeoutMs: number,
+    retriesLimit: number,
+    parentStepId: string | null = null,
+    parallel: boolean = false,
+  ) {
     try {
       return await this.#adapter.createOrRecoverJobStep({
         jobId,
         name,
         timeoutMs,
         retriesLimit,
+        parentStepId,
+        parallel,
       })
     } catch (error) {
       throw new NonRetriableError(`Failed to get or create step "${name}" for job "${jobId}"`, { cause: error })
@@ -115,6 +132,7 @@ export interface StepManagerOptions {
   jobId: string
   actionName: string
   adapter: Adapter
+  telemetry: TelemetryAdapter
   logger: Logger
   concurrencyLimit: number
 }
@@ -127,10 +145,15 @@ export class StepManager {
   #jobId: string
   #actionName: string
   #stepStore: StepStore
+  #telemetry: TelemetryAdapter
   #queue: fastq.queueAsPromised<TaskStep, any>
   #logger: Logger
   // each step name should be executed only once per action job
   #historySteps = new Set<string>()
+  // Store step spans for nested step tracking
+  #stepSpans = new Map<string, Span>()
+  // Store the job span for creating step spans
+  #jobSpan: Span | null = null
 
   // ============================================================================
   // Constructor
@@ -145,16 +168,25 @@ export class StepManager {
     this.#jobId = options.jobId
     this.#actionName = options.actionName
     this.#logger = options.logger
+    this.#telemetry = options.telemetry
     this.#stepStore = new StepStore(options.adapter)
     this.#queue = fastq.promise(async (task: TaskStep) => {
       if (this.#historySteps.has(task.name)) {
         throw new StepAlreadyExecutedError(task.name, this.#jobId, this.#actionName)
       }
       this.#historySteps.add(task.name)
-      return this.#executeStep(task.name, task.cb, task.options, task.abortSignal)
+      return this.#executeStep(task.name, task.cb, task.options, task.abortSignal, task.parentStepId, task.parallel)
     }, options.concurrencyLimit)
   }
 
+  /**
+   * Set the job span for this step manager.
+   * Called from ActionJob after the job span is created.
+   */
+  setJobSpan(span: Span): void {
+    this.#jobSpan = span
+  }
+
   // ============================================================================
   // Public API Methods
   // ============================================================================
@@ -168,6 +200,7 @@ export class StepManager {
    * @param variables - Variables available to the action
    * @param abortSignal - Abort signal for cancelling the action
    * @param logger - Pino child logger for this job
+   * @param observeContext - Observability context for telemetry
    * @returns ActionHandlerContext instance
    */
   createActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVariables = Record<string, unknown>>(
@@ -176,8 +209,35 @@ export class StepManager {
     variables: TVariables,
     abortSignal: AbortSignal,
     logger: Logger,
+    observeContext: ObserveContext,
   ): ActionHandlerContext<TInput, TVariables> {
-    return new ActionContext(this, job, action, variables, abortSignal, logger)
+    return new ActionContext(this, job, action, variables, abortSignal, logger, observeContext)
+  }
+
+  /**
+   * Create an observe context for a step.
+   */
+  createStepObserveContext(stepId: string): ObserveContext {
+    const stepSpan = this.#stepSpans.get(stepId)
+    if (stepSpan) {
+      return this.#telemetry.createObserveContext(this.#jobId, stepId, stepSpan)
+    }
+    // Fallback to job span if step span not found
+    if (this.#jobSpan) {
+      return this.#telemetry.createObserveContext(this.#jobId, stepId, this.#jobSpan)
+    }
+    // No-op observe context
+    return {
+      recordMetric: () => {
+        // No-op
+      },
+      addSpanAttribute: () => {
+        // No-op
+      },
+      addSpanEvent: () => {
+        // No-op
+      },
+    }
   }
 
   /**
@@ -206,9 +266,11 @@ export class StepManager {
    * @param cb - The step handler function
    * @param options - Step options including concurrency, retry, and expire settings
    * @param abortSignal - Abort signal for cancelling the step
+   * @param parentStepId - The ID of the parent step (null for root steps)
    * @returns Promise resolving to the step result
    * @throws StepTimeoutError if the step times out
    * @throws StepCancelError if the step is cancelled
+   * @throws UnhandledChildStepsError if child steps are not awaited
    * @throws Error if the step fails
    */
   async #executeStep<TResult>(
@@ -216,6 +278,8 @@ export class StepManager {
     cb: (ctx: StepHandlerContext) => Promise<TResult>,
     options: StepOptions,
     abortSignal: AbortSignal,
+    parentStepId: string | null,
+    parallel: boolean,
   ): Promise<TResult> {
     const expire = options.expire
     const retryOptions = options.retry
@@ -227,8 +291,15 @@ export class StepManager {
           throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled before create step' })
         }
 
-        // Create step record
-        const newStep = await this.#stepStore.getOrCreate(this.#jobId, name, expire, retryOptions.limit)
+        // Create step record with parentStepId and parallel
+        const newStep = await this.#stepStore.getOrCreate(
+          this.#jobId,
+          name,
+          expire,
+          retryOptions.limit,
+          parentStepId,
+          parallel,
+        )
         if (!newStep) {
           throw new NonRetriableError(
             `Failed to create step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`,
@@ -238,6 +309,17 @@ export class StepManager {
 
         step = newStep
 
+        // Start step telemetry span
+        const parentSpan = parentStepId ? this.#stepSpans.get(parentStepId) : this.#jobSpan
+        const stepSpan = await this.#telemetry.startStepSpan({
+          jobId: this.#jobId,
+          stepId: step.id,
+          stepName: name,
+          parentSpan: parentSpan ?? undefined,
+          parentStepId,
+        })
+        this.#stepSpans.set(step.id, stepSpan)
+
         if (abortSignal.aborted) {
           throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled after create step' })
         }
@@ -245,7 +327,7 @@ export class StepManager {
         if (step.status === STEP_STATUS_COMPLETED) {
           // this is how we recover a completed step
           this.#logger.debug(
-            { jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id },
+            { jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId },
             '[StepManager] Step recovered (already completed)',
           )
           return step.output as TResult
@@ -265,11 +347,12 @@ export class StepManager {
 
         // Log step start
         this.#logger.debug(
-          { jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id },
+          { jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId },
           '[StepManager] Step started executing',
         )
       }
 
+      // Create abort controller for this step's timeout
       const stepAbortController = new AbortController()
       const timeoutId = setTimeout(() => {
         const timeoutError = new StepTimeoutError(name, this.#jobId, expire)
@@ -278,18 +361,85 @@ export class StepManager {
 
       timeoutId?.unref?.()
 
-      // Combine abort signals
-      const signal = AbortSignal.any([abortSignal, stepAbortController.signal])
+      // Combine abort signals: parent chain + this step's timeout
+      const stepSignal = AbortSignal.any([abortSignal, stepAbortController.signal])
+
+      // Track child steps for enforcement
+      interface TrackedChildStep {
+        promise: Promise<any>
+        settled: boolean
+      }
+      const childSteps: TrackedChildStep[] = []
+
+      // Create abort controller for child steps (used when parent returns with pending children)
+      const childAbortController = new AbortController()
+      const childSignal = AbortSignal.any([stepSignal, childAbortController.signal])
+
+      // Create observe context for this step
+      const stepObserveContext = this.createStepObserveContext(step.id)
+
+      // Create StepHandlerContext with nested step support
+      const stepContext: StepHandlerContext = {
+        signal: stepSignal,
+        stepId: step.id,
+        parentStepId,
+        observe: stepObserveContext,
+        step: <TChildResult>(
+          childName: string,
+          childCb: (ctx: StepHandlerContext) => Promise<TChildResult>,
+          childOptions: z.input<typeof StepOptionsSchema> = {},
+        ): Promise<TChildResult> => {
+          // Inherit parent step options EXCEPT parallel (each step's parallel status is independent)
+          const { parallel: _parentParallel, ...inheritableOptions } = options
+          const parsedChildOptions = StepOptionsSchema.parse({
+            ...inheritableOptions,
+            ...childOptions,
+          })
+
+          // Push child step with this step as parent
+          const childPromise = this.push({
+            name: childName,
+            cb: childCb,
+            options: parsedChildOptions,
+            abortSignal: childSignal, // Child uses composed signal
+            parentStepId: step!.id, // This step is the parent
+            parallel: parsedChildOptions.parallel, // Pass parallel option
+          })
+
+          // Track the child promise
+          const trackedChild: TrackedChildStep = {
+            promise: childPromise,
+            settled: false,
+          }
+          childSteps.push(trackedChild)
+
+          // Mark as settled when done (success or failure)
+          // Use .then/.catch instead of .finally to properly handle rejections
+          childPromise
+            .then(() => {
+              trackedChild.settled = true
+            })
+            .catch(() => {
+              trackedChild.settled = true
+              // Swallow the error here - it will be re-thrown to the caller via the returned promise
+            })
+
+          return childPromise
+        },
+      }
 
       try {
         // Race between abort signal and callback execution
-        const abortPromise = waitForAbort(signal)
-        const callbackPromise = cb({ signal })
+        const abortPromise = waitForAbort(stepSignal)
+        const callbackPromise = cb(stepContext)
 
         let result: any = null
+        let aborted = false
 
         await Promise.race([
-          abortPromise.promise,
+          abortPromise.promise.then(() => {
+            aborted = true
+          }),
           callbackPromise
             .then((res) => {
               if (res !== undefined && res !== null) {
@@ -301,12 +451,54 @@ export class StepManager {
             }),
         ])
 
+        // If aborted, wait for child steps to settle before propagating
+        if (aborted) {
+          // Wait for all child steps to settle (they'll be aborted via signal propagation)
+          if (childSteps.length > 0) {
+            await Promise.allSettled(childSteps.map((c) => c.promise))
+          }
+          // Re-throw the abort reason
+          throw stepSignal.reason
+        }
+
+        // After parent callback returns, check for pending children
+        const unsettledChildren = childSteps.filter((c) => !c.settled)
+        if (unsettledChildren.length > 0) {
+          this.#logger.warn(
+            {
+              jobId: this.#jobId,
+              actionName: this.#actionName,
+              stepName: name,
+              stepId: step.id,
+              pendingCount: unsettledChildren.length,
+            },
+            '[StepManager] Parent step completed with unhandled child steps - aborting children',
+          )
+
+          // Abort all pending children
+          const unhandledError = new UnhandledChildStepsError(name, unsettledChildren.length)
+          childAbortController.abort(unhandledError)
+
+          // Wait for all children to settle (they'll reject with cancellation)
+          await Promise.allSettled(unsettledChildren.map((c) => c.promise))
+
+          // Now throw the error
+          throw unhandledError
+        }
+
         // Update step as completed
         const completed = await this.#stepStore.updateStatus(step.id, 'completed', result)
         if (!completed) {
           throw new Error(`Failed to complete step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`)
         }
 
+        // End step telemetry span successfully
+        const stepSpan = this.#stepSpans.get(step.id)
+        if (stepSpan) {
+          await this.#telemetry.endStepSpan(stepSpan, { status: 'ok' })
+          this.#stepSpans.delete(step.id)
+        }
+
         // Log step completion
         this.#logger.debug(
           { jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id },
@@ -347,6 +539,17 @@ export class StepManager {
       },
     }).catch(async (error) => {
       if (step) {
+        // End step telemetry span with error/cancelled status
+        const stepSpan = this.#stepSpans.get(step.id)
+        if (stepSpan) {
+          if (isCancelError(error)) {
+            await this.#telemetry.endStepSpan(stepSpan, { status: 'cancelled' })
+          } else {
+            await this.#telemetry.endStepSpan(stepSpan, { status: 'error', error })
+          }
+          this.#stepSpans.delete(step.id)
+        }
+
         if (isCancelError(error)) {
           await this.#stepStore.updateStatus(step.id, 'cancelled')
         } else {
@@ -377,6 +580,7 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
   #jobId: string
   #groupKey: string = '@default'
   #action: Action<TInput, TOutput, TVariables>
+  #observeContext: ObserveContext
 
   // ============================================================================
   // Constructor
@@ -389,6 +593,7 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
     variables: TVariables,
     abortSignal: AbortSignal,
     logger: Logger,
+    observeContext: ObserveContext,
   ) {
     this.#stepManager = stepManager
     this.#variables = variables
@@ -397,6 +602,7 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
     this.#action = action
     this.#jobId = job.id
     this.#groupKey = job.groupKey ?? '@default'
+    this.#observeContext = observeContext
     if (action.input) {
       this.#input = action.input.parse(job.input, {
         error: () => 'Error parsing action input',
@@ -405,6 +611,7 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
     }
     this.#input = job.input ?? {}
     this.step = this.step.bind(this)
+    this.run = this.run.bind(this)
   }
 
   // ============================================================================
@@ -450,8 +657,16 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
     return this.#logger
   }
 
+  /**
+   * Get the observability context for recording metrics and span data.
+   */
+  get observe(): ObserveContext {
+    return this.#observeContext
+  }
+
   /**
    * Execute a step within the action.
+   * This creates a root step (no parent).
    *
    * @param name - The name of the step
    * @param cb - The step handler function
@@ -467,6 +682,71 @@ class ActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVa
       ...this.#action.steps,
       ...options,
     })
-    return this.#stepManager.push({ name, cb, options: parsedOptions, abortSignal: this.#abortSignal })
+    return this.#stepManager.push({
+      name,
+      cb,
+      options: parsedOptions,
+      abortSignal: this.#abortSignal,
+      parentStepId: null, // Root steps have no parent
+      parallel: parsedOptions.parallel, // Pass parallel option
+    })
+  }
+
+  /**
+   * Execute a reusable step definition created with createStep().
+   *
+   * @param stepDef - The step definition to execute
+   * @param input - The input data for the step (validated against the step's input schema)
+   * @param options - Optional step configuration overrides
+   * @returns Promise resolving to the step result
+   */
+  async run<TStepInput extends z.ZodObject, TResult>(
+    stepDef: StepDefinition<TStepInput, TResult, TVariables>,
+    input: z.input<TStepInput>,
+    options: Partial<z.input<typeof StepOptionsSchema>> = {},
+  ): Promise<TResult> {
+    // Validate input against the step's schema if provided
+    // After parsing, validatedInput is z.output<TStepInput> (same as z.infer<TStepInput>)
+    const validatedInput: z.infer<TStepInput> = stepDef.input
+      ? stepDef.input.parse(input, {
+          error: () => 'Error parsing step input',
+          reportInput: true,
+        })
+      : (input as z.infer<TStepInput>)
+
+    // Resolve step name (static or dynamic)
+    const stepName = typeof stepDef.name === 'function' ? stepDef.name({ input: validatedInput }) : stepDef.name
+
+    // Merge options: action defaults -> step definition -> call-time overrides
+    const mergedOptions: z.input<typeof StepOptionsSchema> = {
+      ...this.#action.steps,
+      ...(stepDef.retry !== undefined && { retry: stepDef.retry }),
+      ...(stepDef.expire !== undefined && { expire: stepDef.expire }),
+      ...(stepDef.parallel !== undefined && { parallel: stepDef.parallel }),
+      ...options,
+    }
+
+    const parsedOptions = StepOptionsSchema.parse(mergedOptions)
+
+    // Create a wrapper callback that provides the extended context
+    const wrappedCb = async (baseCtx: StepHandlerContext): Promise<TResult> => {
+      const extendedCtx: StepDefinitionHandlerContext<TStepInput, TVariables> = {
+        ...baseCtx,
+        input: validatedInput,
+        var: this.#variables,
+        logger: this.#logger,
+        jobId: this.#jobId,
+      }
+      return stepDef.handler(extendedCtx)
+    }
+
+    return this.#stepManager.push({
+      name: stepName,
+      cb: wrappedCb,
+      options: parsedOptions,
+      abortSignal: this.#abortSignal,
+      parentStepId: null, // Root steps have no parent
+      parallel: parsedOptions.parallel,
+    })
   }
 }