duron 0.2.2 → 0.3.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duron",
-  "version": "0.2.2",
+  "version": "0.3.0-beta.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -67,17 +67,19 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "@opentelemetry/api": "^1.9.0",
     "@types/bun": "latest",
     "@types/node": "^24.0.15",
-    "drizzle-kit": "^1.0.0-beta.2-b782ae1",
-    "drizzle-orm": "^1.0.0-beta.2-b782ae1",
+    "drizzle-kit": "^1.0.0-beta.11-05230d9",
+    "drizzle-orm": "^1.0.0-beta.11-05230d9",
     "postgres": "^3.4.7",
     "typescript": "^5.6.3"
   },
   "dependencies": {
-    "elysia": "^1.4.16",
+    "elysia": "^1.4.22",
     "fastq": "^1.19.1",
     "jose": "^6.1.2",
+    "p-all": "^5.0.1",
     "p-retry": "^7.1.0",
     "p-timeout": "^7.0.1",
     "pino": "^10.1.0",

package/src/action-job.ts

@@ -4,12 +4,14 @@ import type { Action } from './action.js'
 import type { Adapter } from './adapters/adapter.js'
 import { ActionCancelError, ActionTimeoutError, isCancelError, StepTimeoutError, serializeError } from './errors.js'
 import { StepManager } from './step-manager.js'
+import type { Span, TelemetryAdapter } from './telemetry/adapter.js'
 import waitForAbort from './utils/wait-for-abort.js'
 
 export interface ActionJobOptions<TAction extends Action<any, any, any>> {
   job: { id: string; input: any; groupKey: string; timeoutMs: number; actionName: string }
   action: TAction
   database: Adapter
+  telemetry: TelemetryAdapter
   variables: Record<string, unknown>
   logger: Logger
 }
@@ -24,6 +26,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
   #job: { id: string; input: any; groupKey: string; timeoutMs: number; actionName: string }
   #action: TAction
   #database: Adapter
+  #telemetry: TelemetryAdapter
   #variables: Record<string, unknown>
   #logger: Logger
   #stepManager: StepManager
@@ -31,6 +34,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
   #timeoutId: NodeJS.Timeout | null = null
   #done: Promise<void>
   #resolve: (() => void) | null = null
+  #jobSpan: Span | null = null
 
   // ============================================================================
   // Constructor
@@ -45,6 +49,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
     this.#job = options.job
     this.#action = options.action
     this.#database = options.database
+    this.#telemetry = options.telemetry
     this.#variables = options.variables
     this.#logger = options.logger
     this.#abortController = new AbortController()
@@ -54,6 +59,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
       jobId: options.job.id,
       actionName: options.job.actionName,
       adapter: options.database,
+      telemetry: options.telemetry,
       logger: options.logger,
       concurrencyLimit: options.action.concurrency,
     })
@@ -78,6 +84,17 @@ export class ActionJob<TAction extends Action<any, any, any>> {
    * @throws Error if the job fails or output validation fails
    */
   async execute() {
+    // Start job telemetry span
+    this.#jobSpan = await this.#telemetry.startJobSpan({
+      jobId: this.#job.id,
+      actionName: this.#action.name,
+      groupKey: this.#job.groupKey,
+      input: this.#job.input,
+    })
+
+    // Set the job span on the step manager
+    this.#stepManager.setJobSpan(this.#jobSpan)
+
     try {
       // Create a child logger for this job
       const jobLogger = this.#logger.child({
@@ -85,6 +102,9 @@ export class ActionJob<TAction extends Action<any, any, any>> {
         actionName: this.#action.name,
       })
 
+      // Create observe context for the action handler
+      const observeContext = this.#telemetry.createObserveContext(this.#job.id, null, this.#jobSpan)
+
       // Create action context with step manager
       const ctx = this.#stepManager.createActionContext(
         this.#job,
@@ -92,6 +112,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
         this.#variables as any,
         this.#abortController.signal,
         jobLogger,
+        observeContext,
       )
 
       this.#timeoutId = setTimeout(() => {
@@ -138,6 +159,9 @@ export class ActionJob<TAction extends Action<any, any, any>> {
         '[ActionJob] Action finished executing',
       )
 
+      // End job span successfully
+      await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'ok' })
+
       return result
     } catch (error) {
       if (
@@ -146,6 +170,11 @@ export class ActionJob<TAction extends Action<any, any, any>> {
       ) {
         this.#logger.warn({ jobId: this.#job.id, actionName: this.#action.name }, '[ActionJob] Job cancelled')
         await this.#database.cancelJob({ jobId: this.#job.id })
+
+        // End job span as cancelled
+        if (this.#jobSpan) {
+          await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'cancelled' })
+        }
         return
       }
 
@@ -158,6 +187,12 @@ export class ActionJob<TAction extends Action<any, any, any>> {
 
       this.#logger.error({ jobId: this.#job.id, actionName: this.#action.name }, message)
       await this.#database.failJob({ jobId: this.#job.id, error: serializeError(error) })
+
+      // End job span with error
+      if (this.#jobSpan) {
+        await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'error', error })
+      }
+
       throw error
     } finally {
       this.#clear()

package/src/action-manager.ts

@@ -4,10 +4,12 @@ import type { Logger } from 'pino'
 import type { Action } from './action.js'
 import { ActionJob } from './action-job.js'
 import type { Adapter, Job } from './adapters/adapter.js'
+import type { TelemetryAdapter } from './telemetry/adapter.js'
 
 export interface ActionManagerOptions<TAction extends Action<any, any, any>> {
   action: TAction
   database: Adapter
+  telemetry: TelemetryAdapter
   variables: Record<string, unknown>
   logger: Logger
   concurrencyLimit: number
@@ -22,6 +24,7 @@ export interface ActionManagerOptions<TAction extends Action<any, any, any>> {
 export class ActionManager<TAction extends Action<any, any, any>> {
   #action: TAction
   #database: Adapter
+  #telemetry: TelemetryAdapter
   #variables: Record<string, unknown>
   #logger: Logger
   #queue: fastq.queueAsPromised<Job, void>
@@ -41,6 +44,7 @@ export class ActionManager<TAction extends Action<any, any, any>> {
   constructor(options: ActionManagerOptions<TAction>) {
     this.#action = options.action
     this.#database = options.database
+    this.#telemetry = options.telemetry
     this.#variables = options.variables
     this.#logger = options.logger
     this.#concurrencyLimit = options.concurrencyLimit
@@ -149,6 +153,7 @@ export class ActionManager<TAction extends Action<any, any, any>> {
       },
       action: this.#action,
       database: this.#database,
+      telemetry: this.#telemetry,
       variables: this.#variables,
       logger: this.#logger,
     })

package/src/action.ts

@@ -1,6 +1,7 @@
 import type { Logger } from 'pino'
 import * as z from 'zod'
 
+import type { ObserveContext } from './telemetry/adapter.js'
 import generateChecksum from './utils/checksum.js'
 
 export type RetryOptions = z.infer<typeof RetryOptionsSchema>
@@ -13,15 +14,157 @@ export interface ActionHandlerContext<TInput extends z.ZodObject, TVariables = R
   groupKey: string
   var: TVariables
   logger: Logger
+
+  /**
+   * Observability context for recording metrics and span data.
+   * Allows recording custom metrics, span attributes, and events.
+   */
+  observe: ObserveContext
+
+  /**
+   * Execute an inline step within the action.
+   *
+   * @param name - The name of the step (must be unique within the job)
+   * @param cb - The step handler callback
+   * @param options - Optional step configuration
+   * @returns Promise resolving to the step result
+   */
   step: <TResult>(
     name: string,
     cb: (ctx: StepHandlerContext) => Promise<TResult>,
     options?: z.input<typeof StepOptionsSchema>,
   ) => Promise<TResult>
+
+  /**
+   * 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
+   */
+  run: <TStepInput extends z.ZodObject, TResult>(
+    stepDef: StepDefinition<TStepInput, TResult, TVariables>,
+    input: z.input<TStepInput>,
+    options?: Partial<z.input<typeof StepOptionsSchema>>,
+  ) => Promise<TResult>
 }
 
 export interface StepHandlerContext {
+  /**
+   * The abort signal for this step.
+   * This signal will be aborted when:
+   * - The action is cancelled
+   * - The parent step times out
+   * - This step times out
+   */
   signal: AbortSignal
+
+  /**
+   * The unique ID of this step.
+   */
+  stepId: string
+
+  /**
+   * The ID of the parent step, or null if this is a root step.
+   */
+  parentStepId: string | null
+
+  /**
+   * Observability context for recording metrics and span data.
+   * Allows recording custom metrics, span attributes, and events.
+   */
+  observe: ObserveContext
+
+  /**
+   * Create a nested child step.
+   * Child steps inherit the abort signal chain from their parent.
+   * All child steps MUST be awaited before the parent step returns.
+   *
+   * @param name - The name of the child step (must be unique within the job)
+   * @param cb - The step handler callback
+   * @param options - Optional step configuration
+   * @returns Promise resolving to the step result
+   */
+  step: <TResult>(
+    name: string,
+    cb: (ctx: StepHandlerContext) => Promise<TResult>,
+    options?: z.input<typeof StepOptionsSchema>,
+  ) => Promise<TResult>
+}
+
+/**
+ * Extended context for step definition handlers.
+ * Includes all StepHandlerContext properties plus action-level context.
+ */
+export interface StepDefinitionHandlerContext<TInput extends z.ZodObject, TVariables = Record<string, unknown>>
+  extends StepHandlerContext {
+  /**
+   * The validated input for this step.
+   */
+  input: z.infer<TInput>
+
+  /**
+   * Variables shared across the action.
+   */
+  var: TVariables
+
+  /**
+   * Logger instance for this step.
+   */
+  logger: Logger
+
+  /**
+   * The job ID this step belongs to.
+   */
+  jobId: string
+}
+
+/**
+ * A reusable step definition created with createStep().
+ * Can be executed within an action handler using ctx.run().
+ */
+export interface StepDefinition<
+  TInput extends z.ZodObject,
+  TResult,
+  TVariables = Record<string, unknown>,
+> {
+  /**
+   * The name of the step.
+   * Can be a static string or a function that generates the name from the input.
+   */
+  name: string | ((ctx: { input: z.infer<TInput> }) => string)
+
+  /**
+   * Zod schema for validating the step input.
+   */
+  input?: TInput
+
+  /**
+   * Retry configuration for this step.
+   */
+  retry?: z.input<typeof RetryOptionsSchema>
+
+  /**
+   * Timeout in milliseconds for this step.
+   */
+  expire?: number
+
+  /**
+   * Whether this step runs in parallel with siblings.
+   */
+  parallel?: boolean
+
+  /**
+   * The handler function that executes the step logic.
+   */
+  handler: (ctx: StepDefinitionHandlerContext<TInput, TVariables>) => Promise<TResult>
+
+  /**
+   * Internal marker to identify this as a step definition.
+   * @internal
+   */
+  __stepDefinition: true
 }
 
 export interface ConcurrencyHandlerContext<TInput extends z.ZodObject, TVariables = Record<string, unknown>> {
@@ -99,6 +242,15 @@ export const StepOptionsSchema = z.object({
     .number()
     .default(5 * 60 * 1000)
     .describe('The expire time for the step (milliseconds)'),
+
+  /**
+   * Whether this step runs in parallel with siblings.
+   * Parallel steps are independent from siblings during time travel.
+   * When time traveling to a step, completed parallel siblings are preserved.
+   *
+   * @default false
+   */
+  parallel: z.boolean().default(false).describe('Whether this step runs in parallel (independent from siblings)'),
 })
 
 /**
@@ -245,3 +397,50 @@ export const defineAction = <TVariables = Record<string, unknown>>() => {
     })
   }
 }
+
+/**
+ * Input type for createStep() - the definition object before transformation.
+ */
+export type StepDefinitionInput<
+  TInput extends z.ZodObject,
+  TResult,
+  TVariables = Record<string, unknown>,
+> = Omit<StepDefinition<TInput, TResult, TVariables>, '__stepDefinition'>
+
+/**
+ * Creates a reusable step definition that can be executed within action handlers.
+ *
+ * @template TVariables - Type of variables available to the step handler
+ * @returns A curried function that accepts the step definition and returns a StepDefinition
+ *
+ * @example
+ * ```typescript
+ * const sendEmailStep = createStep<typeof variables>()({
+ *   name: 'send-email',
+ *   input: z.object({
+ *     email: z.string().email(),
+ *     body: z.string(),
+ *   }),
+ *   retry: { limit: 3 },
+ *   expire: 60000,
+ *   handler: async (ctx) => {
+ *     // ctx.input is typed as { email: string, body: string }
+ *     // ctx.var, ctx.logger, ctx.jobId are also available
+ *     return { success: true }
+ *   },
+ * })
+ *
+ * // In an action handler:
+ * const result = await ctx.run(sendEmailStep, { email: 'test@example.com', body: 'Hello' })
+ * ```
+ */
+export const createStep = <TVariables = Record<string, unknown>>() => {
+  return <TInput extends z.ZodObject, TResult>(
+    def: StepDefinitionInput<TInput, TResult, TVariables>,
+  ): StepDefinition<TInput, TResult, TVariables> => {
+    return {
+      ...def,
+      __stepDefinition: true as const,
+    }
+  }
+}

package/src/adapters/adapter.ts

@@ -24,6 +24,7 @@ import type {
   DelayJobStepOptions,
   DeleteJobOptions,
   DeleteJobsOptions,
+  DeleteMetricsOptions,
   FailJobOptions,
   FailJobStepOptions,
   FetchOptions,
@@ -32,12 +33,16 @@ import type {
   GetJobStepsResult,
   GetJobsOptions,
   GetJobsResult,
+  GetMetricsOptions,
+  GetMetricsResult,
+  InsertMetricOptions,
   Job,
   JobStatusResult,
   JobStep,
   JobStepStatusResult,
   RecoverJobsOptions,
   RetryJobOptions,
+  TimeTravelJobOptions,
 } from './schemas.js'
 import {
   BooleanResultSchema,
@@ -51,6 +56,7 @@ import {
   DelayJobStepOptionsSchema,
   DeleteJobOptionsSchema,
   DeleteJobsOptionsSchema,
+  DeleteMetricsOptionsSchema,
   FailJobOptionsSchema,
   FailJobStepOptionsSchema,
   FetchOptionsSchema,
@@ -59,6 +65,9 @@ import {
   GetJobStepsResultSchema,
   GetJobsOptionsSchema,
   GetJobsResultSchema,
+  GetMetricsOptionsSchema,
+  GetMetricsResultSchema,
+  InsertMetricOptionsSchema,
   JobIdResultSchema,
   JobSchema,
   JobStatusResultSchema,
@@ -68,6 +77,7 @@ import {
   NumberResultSchema,
   RecoverJobsOptionsSchema,
   RetryJobOptionsSchema,
+  TimeTravelJobOptionsSchema,
 } from './schemas.js'
 
 // Re-export types from schemas for backward compatibility
@@ -83,6 +93,7 @@ export type {
   DelayJobStepOptions,
   DeleteJobOptions,
   DeleteJobsOptions,
+  DeleteMetricsOptions,
   FailJobOptions,
   FailJobStepOptions,
   FetchOptions,
@@ -91,6 +102,9 @@ export type {
   GetJobStepsResult,
   GetJobsOptions,
   GetJobsResult,
+  GetMetricsOptions,
+  GetMetricsResult,
+  InsertMetricOptions,
   Job,
   JobFilters,
   JobSort,
@@ -98,9 +112,15 @@ export type {
   JobStatusResult,
   JobStep,
   JobStepStatusResult,
+  Metric,
+  MetricFilters,
+  MetricSort,
+  MetricSortField,
+  MetricType,
   RecoverJobsOptions,
   RetryJobOptions,
   SortOrder,
+  TimeTravelJobOptions,
 } from './schemas.js'
 
 // ============================================================================
@@ -400,6 +420,30 @@ export abstract class Adapter extends EventEmitter<AdapterEvents> {
     }
   }
 
+  /**
+   * Time travel a job to restart from a specific step.
+   * The job must be in completed, failed, or cancelled status.
+   * Resets the job and ancestor steps to active status, deletes subsequent steps,
+   * and preserves completed parallel siblings.
+   *
+   * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+   */
+  async timeTravelJob(options: TimeTravelJobOptions): Promise<boolean> {
+    try {
+      await this.start()
+      const parsedOptions = TimeTravelJobOptionsSchema.parse(options)
+      const result = await this._timeTravelJob(parsedOptions)
+      const success = BooleanResultSchema.parse(result)
+      if (success) {
+        await this._notify('job-available', { jobId: parsedOptions.jobId })
+      }
+      return success
+    } catch (error) {
+      this.#logger?.error(error, 'Error in Adapter.timeTravelJob()')
+      throw error
+    }
+  }
+
   /**
    * Delete a job by its ID.
    * Active jobs cannot be deleted.
@@ -659,6 +703,17 @@ export abstract class Adapter extends EventEmitter<AdapterEvents> {
    */
   protected abstract _retryJob(options: RetryJobOptions): Promise<string | null>
 
+  /**
+   * Internal method to time travel a job to restart from a specific step.
+   * The job must be in completed, failed, or cancelled status.
+   * Resets the job and ancestor steps to active status, deletes subsequent steps,
+   * and preserves completed parallel siblings.
+   *
+   * @param options - Validated time travel options
+   * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+   */
+  protected abstract _timeTravelJob(options: TimeTravelJobOptions): Promise<boolean>
+
   /**
    * Internal method to delete a job by its ID.
    * Active jobs cannot be deleted.
@@ -937,6 +992,102 @@ export abstract class Adapter extends EventEmitter<AdapterEvents> {
    */
   protected abstract _getActions(): Promise<GetActionsResult>
 
+  // ============================================================================
+  // Metrics Methods
+  // ============================================================================
+
+  /**
+   * Insert multiple metric records in a single batch operation.
+   * Note: This method bypasses telemetry tracing to prevent infinite loops.
+   *
+   * @param metrics - Array of metric data to insert
+   * @returns Promise resolving to the number of metrics inserted
+   */
+  async insertMetrics(metrics: InsertMetricOptions[]): Promise<number> {
+    try {
+      if (metrics.length === 0) {
+        return 0
+      }
+      await this.start()
+      const parsedMetrics = metrics.map((m) => InsertMetricOptionsSchema.parse(m))
+      const result = await this._insertMetrics(parsedMetrics)
+      return NumberResultSchema.parse(result)
+    } catch (error) {
+      this.#logger?.error(error, 'Error in Adapter.insertMetrics()')
+      throw error
+    }
+  }
+
+  /**
+   * Get metrics for a job or step.
+   * Note: This method bypasses telemetry tracing to prevent infinite loops.
+   *
+   * @param options - Query options including jobId/stepId, filters, sort, and pagination
+   * @returns Promise resolving to metrics result with pagination info
+   */
+  async getMetrics(options: GetMetricsOptions): Promise<GetMetricsResult> {
+    try {
+      await this.start()
+      const parsedOptions = GetMetricsOptionsSchema.parse(options)
+      // Validate that at least one of jobId or stepId is provided
+      if (!parsedOptions.jobId && !parsedOptions.stepId) {
+        throw new Error('At least one of jobId or stepId must be provided')
+      }
+      const result = await this._getMetrics(parsedOptions)
+      return GetMetricsResultSchema.parse(result)
+    } catch (error) {
+      this.#logger?.error(error, 'Error in Adapter.getMetrics()')
+      throw error
+    }
+  }
+
+  /**
+   * Delete all metrics for a job.
+   * Note: This method bypasses telemetry tracing to prevent infinite loops.
+   *
+   * @param options - Options containing the jobId
+   * @returns Promise resolving to the number of metrics deleted
+   */
+  async deleteMetrics(options: DeleteMetricsOptions): Promise<number> {
+    try {
+      await this.start()
+      const parsedOptions = DeleteMetricsOptionsSchema.parse(options)
+      const result = await this._deleteMetrics(parsedOptions)
+      return NumberResultSchema.parse(result)
+    } catch (error) {
+      this.#logger?.error(error, 'Error in Adapter.deleteMetrics()')
+      throw error
+    }
+  }
+
+  // ============================================================================
+  // Private Metrics Methods (to be implemented by adapters)
+  // ============================================================================
+
+  /**
+   * Internal method to insert multiple metric records in a single batch.
+   *
+   * @param metrics - Array of validated metric data
+   * @returns Promise resolving to the number of metrics inserted
+   */
+  protected abstract _insertMetrics(metrics: InsertMetricOptions[]): Promise<number>
+
+  /**
+   * Internal method to get metrics for a job or step.
+   *
+   * @param options - Validated query options
+   * @returns Promise resolving to metrics result with pagination info
+   */
+  protected abstract _getMetrics(options: GetMetricsOptions): Promise<GetMetricsResult>
+
+  /**
+   * Internal method to delete all metrics for a job.
+   *
+   * @param options - Validated options containing the jobId
+   * @returns Promise resolving to the number of metrics deleted
+   */
+  protected abstract _deleteMetrics(options: DeleteMetricsOptions): Promise<number>
+
   // ============================================================================
   // Protected Abstract Methods (to be implemented by adapters)
   // ============================================================================