duron 0.1.0

package/src/action-job.ts

@@ -0,0 +1,201 @@
+import type { Logger } from 'pino'
+
+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 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
+  variables: Record<string, unknown>
+  logger: Logger
+}
+
+/**
+ * ActionJob represents a single job execution for an action.
+ * Manages the execution lifecycle, timeout handling, and cancellation.
+ *
+ * @template TAction - The action type being executed
+ */
+export class ActionJob<TAction extends Action<any, any, any>> {
+  #job: { id: string; input: any; groupKey: string; timeoutMs: number; actionName: string }
+  #action: TAction
+  #database: Adapter
+  #variables: Record<string, unknown>
+  #logger: Logger
+  #stepManager: StepManager
+  #abortController: AbortController
+  #timeoutId: NodeJS.Timeout | null = null
+  #done: Promise<void>
+  #resolve: (() => void) | null = null
+
+  // ============================================================================
+  // Constructor
+  // ============================================================================
+
+  /**
+   * Create a new ActionJob instance.
+   *
+   * @param options - Configuration options for the action job
+   */
+  constructor(options: ActionJobOptions<TAction>) {
+    this.#job = options.job
+    this.#action = options.action
+    this.#database = options.database
+    this.#variables = options.variables
+    this.#logger = options.logger
+    this.#abortController = new AbortController()
+
+    // Create StepManager for this job
+    this.#stepManager = new StepManager({
+      jobId: options.job.id,
+      actionName: options.job.actionName,
+      adapter: options.database,
+      logger: options.logger,
+      concurrencyLimit: options.action.concurrency,
+    })
+
+    this.#done = new Promise((resolve) => {
+      this.#resolve = resolve
+    })
+  }
+
+  // ============================================================================
+  // Public API Methods
+  // ============================================================================
+
+  /**
+   * Execute the action job.
+   * Creates the action context, sets up timeout, executes the handler,
+   * validates output, and marks the job as completed or failed.
+   *
+   * @returns Promise resolving to the action result
+   * @throws ActionTimeoutError if the job times out
+   * @throws ActionCancelError if the job is cancelled
+   * @throws Error if the job fails or output validation fails
+   */
+  async execute() {
+    try {
+      // Create a child logger for this job
+      const jobLogger = this.#logger.child({
+        jobId: this.#job.id,
+        actionName: this.#action.name,
+      })
+
+      // Create action context with step manager
+      const ctx = this.#stepManager.createActionContext(
+        this.#job,
+        this.#action,
+        this.#variables as any,
+        this.#abortController.signal,
+        jobLogger,
+      )
+
+      this.#timeoutId = setTimeout(() => {
+        const timeoutError = new ActionTimeoutError(this.#action.name, this.#job.timeoutMs)
+        this.#abortController.abort(timeoutError)
+      }, this.#job.timeoutMs)
+
+      this.#timeoutId?.unref?.()
+
+      // Execute handler with timeout - race between handler and abort signal
+      const abortWaiter = waitForAbort(this.#abortController.signal)
+      let result: any = null
+      await Promise.race([
+        this.#action
+          .handler(ctx)
+          .then((res) => {
+            if (res !== undefined) {
+              result = res
+            }
+          })
+          .finally(() => {
+            abortWaiter.release()
+          }),
+        abortWaiter.promise,
+      ])
+
+      // Validate output if schema is provided
+      if (this.#action.output) {
+        result = this.#action.output.parse(result, {
+          error: () => 'Error parsing action output',
+          reportInput: true,
+        })
+      }
+
+      // Complete job
+      const completed = await this.#database.completeJob({ jobId: this.#job.id, output: result })
+      if (!completed) {
+        throw new Error('Job not completed')
+      }
+
+      // Log action completion
+      this.#logger.debug(
+        { jobId: this.#job.id, actionName: this.#action.name },
+        '[ActionJob] Action finished executing',
+      )
+
+      return result
+    } catch (error) {
+      if (
+        isCancelError(error) ||
+        (error instanceof Error && error.name === 'AbortError' && isCancelError(error.cause))
+      ) {
+        this.#logger.warn({ jobId: this.#job.id, actionName: this.#action.name }, '[ActionJob] Job cancelled')
+        await this.#database.cancelJob({ jobId: this.#job.id })
+        return
+      }
+
+      const message =
+        error instanceof ActionTimeoutError
+          ? '[ActionJob] Job timed out'
+          : error instanceof StepTimeoutError
+            ? '[ActionJob] Step timed out'
+            : '[ActionJob] Job failed'
+
+      this.#logger.error({ jobId: this.#job.id, actionName: this.#action.name }, message)
+      await this.#database.failJob({ jobId: this.#job.id, error: serializeError(error) })
+      throw error
+    } finally {
+      this.#clear()
+      this.#resolve?.()
+    }
+  }
+
+  /**
+   * Wait for the job execution to complete.
+   * Returns a promise that resolves when the job finishes (successfully or with error).
+   *
+   * @returns Promise that resolves when the job is done
+   */
+  waitForDone(): Promise<void> {
+    return this.#done
+  }
+
+  /**
+   * Cancel the job execution.
+   * Clears the timeout and aborts the action handler.
+   */
+  cancel() {
+    this.#clear()
+    const cancelError = new ActionCancelError(this.#action.name, this.#job.id)
+    this.#abortController.abort(cancelError)
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Clear the timeout timer.
+   */
+  #clear() {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId)
+      this.#timeoutId = null
+    }
+  }
+}

package/src/action-manager.ts

@@ -0,0 +1,166 @@
+import fastq from 'fastq'
+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'
+
+export interface ActionManagerOptions<TAction extends Action<any, any, any>> {
+  action: TAction
+  database: Adapter
+  variables: Record<string, unknown>
+  logger: Logger
+  concurrencyLimit: number
+}
+
+/**
+ * ActionManager manages the execution of jobs for a specific action.
+ * Uses a fastq queue to control concurrency and process jobs.
+ *
+ * @template TAction - The action type being managed
+ */
+export class ActionManager<TAction extends Action<any, any, any>> {
+  #action: TAction
+  #database: Adapter
+  #variables: Record<string, unknown>
+  #logger: Logger
+  #queue: fastq.queueAsPromised<Job, void>
+  #concurrencyLimit: number
+  #activeJobs = new Map<string, ActionJob<TAction>>()
+  #stopped: boolean = false
+
+  // ============================================================================
+  // Constructor
+  // ============================================================================
+
+  /**
+   * Create a new ActionManager instance.
+   *
+   * @param options - Configuration options for the action manager
+   */
+  constructor(options: ActionManagerOptions<TAction>) {
+    this.#action = options.action
+    this.#database = options.database
+    this.#variables = options.variables
+    this.#logger = options.logger
+    this.#concurrencyLimit = options.concurrencyLimit
+
+    // Create fastq queue with action concurrency limit
+    this.#queue = fastq.promise(async (job: Job) => {
+      if (this.#stopped) {
+        return
+      }
+
+      await this.#executeJob(job)
+    }, this.#concurrencyLimit)
+  }
+
+  // ============================================================================
+  // Public API Methods
+  // ============================================================================
+
+  /**
+   * Queue a job for execution.
+   *
+   * @param job - The job to queue
+   * @returns Promise that resolves when the job is queued
+   */
+  async push(job: Job): Promise<void> {
+    return this.#queue.push(job)
+  }
+
+  /**
+   * Cancel a specific job by ID.
+   *
+   * @param jobId - The ID of the job to cancel
+   * @returns If the manager has the job, it will be cancelled and true will be returned. Otherwise, false will be returned.
+   */
+  cancelJob(jobId: string) {
+    const actionJob = this.#activeJobs.get(jobId)
+    if (actionJob) {
+      actionJob.cancel()
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Cancel all active jobs.
+   */
+  abortAll(): void {
+    for (const actionJob of this.#activeJobs.values()) {
+      actionJob.cancel()
+    }
+  }
+
+  /**
+   * Check if the queue is idle (no jobs being processed).
+   *
+   * @returns Promise resolving to `true` if idle, `false` otherwise
+   */
+  async idle(): Promise<boolean> {
+    return this.#queue.idle()
+  }
+
+  /**
+   * Wait for the queue to drain (all jobs completed).
+   *
+   * @returns Promise that resolves when the queue is drained
+   */
+  async drain(): Promise<void> {
+    return this.#queue.drain()
+  }
+
+  /**
+   * Stop the action manager.
+   * Aborts all active jobs and waits for the queue to drain.
+   *
+   * @returns Promise that resolves when the action manager is stopped
+   */
+  async stop(): Promise<void> {
+    if (this.#stopped) {
+      return
+    }
+
+    this.#stopped = true
+    this.abortAll()
+    await this.#queue.killAndDrain()
+    await Promise.all(Array.from(this.#activeJobs.values()).map((actionJob) => actionJob.waitForDone()))
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Execute a job by creating an ActionJob and running it.
+   *
+   * @param job - The job to execute
+   */
+  async #executeJob(job: Job) {
+    // Create ActionJob for this job
+    const actionJob = new ActionJob({
+      job: {
+        id: job.id,
+        input: job.input,
+        groupKey: job.groupKey,
+        timeoutMs: job.timeoutMs,
+        actionName: job.actionName,
+      },
+      action: this.#action,
+      database: this.#database,
+      variables: this.#variables,
+      logger: this.#logger,
+    })
+    this.#activeJobs.set(job.id, actionJob)
+
+    try {
+      // Execute the job - all error handling is done inside ActionJob.execute()
+      await actionJob.execute()
+    } finally {
+      // Always cleanup, even if the job failed or was cancelled
+      // Errors are already handled in ActionJob.execute() (logging, failing job, etc.)
+      this.#activeJobs.delete(job.id)
+    }
+  }
+}

package/src/action.ts

@@ -0,0 +1,247 @@
+import type { Logger } from 'pino'
+import * as z from 'zod'
+
+import generateChecksum from './utils/checksum.js'
+
+export type RetryOptions = z.infer<typeof RetryOptionsSchema>
+
+export type StepOptions = z.infer<typeof StepOptionsSchema>
+
+export interface ActionHandlerContext<TInput extends z.ZodObject, TVariables = Record<string, unknown>> {
+  input: z.infer<TInput>
+  jobId: string
+  groupKey: string
+  var: TVariables
+  logger: Logger
+  step: <TResult>(
+    name: string,
+    cb: (ctx: StepHandlerContext) => Promise<TResult>,
+    options?: z.input<typeof StepOptionsSchema>,
+  ) => Promise<TResult>
+}
+
+export interface StepHandlerContext {
+  signal: AbortSignal
+}
+
+export interface ConcurrencyHandlerContext<TInput extends z.ZodObject, TVariables = Record<string, unknown>> {
+  input: z.infer<TInput>
+  var: TVariables
+}
+
+export type ActionDefinition<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+> = z.input<ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>>
+
+export type Action<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+> = z.infer<ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>>
+
+/**
+ * Retry configuration options for actions and steps.
+ */
+export const RetryOptionsSchema = z
+  .object({
+    /**
+     * Maximum number of retry attempts.
+     *
+     * @default 4
+     */
+    limit: z.number().default(4),
+
+    /**
+     * Exponential backoff factor.
+     * The delay between retries is calculated as: minTimeout * (factor ^ attemptNumber)
+     *
+     * @default 2
+     */
+    factor: z.number().default(2),
+
+    /**
+     * Minimum delay in milliseconds before the first retry.
+     *
+     * @default 1000
+     */
+    minTimeout: z.number().default(1000),
+
+    /**
+     * Maximum delay in milliseconds between retries.
+     * The calculated delay will be capped at this value.
+     *
+     * @default 30000
+     */
+    maxTimeout: z.number().default(30000),
+  })
+  .default({ limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 })
+  .describe('The retry options')
+
+/**
+ * Options for configuring a step within an action.
+ */
+export const StepOptionsSchema = z.object({
+  /**
+   * Retry configuration for this step.
+   * If not provided, uses the default retry options from the action or Duron instance.
+   */
+  retry: RetryOptionsSchema,
+
+  /**
+   * Timeout in milliseconds for this step.
+   * Steps that exceed this timeout will be cancelled.
+   *
+   * @default 300000 (5 minutes)
+   */
+  expire: z
+    .number()
+    .default(5 * 60 * 1000)
+    .describe('The expire time for the step (milliseconds)'),
+})
+
+/**
+ * Creates a Zod schema for validating action definitions.
+ *
+ * @template TInput - Zod schema for the action input
+ * @template TOutput - Zod schema for the action output
+ * @template TVariables - Type of variables available to the action
+ * @returns Zod schema for action definitions
+ */
+export function createActionDefinitionSchema<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+>() {
+  return z
+    .object({
+      /**
+       * Unique name for this action.
+       * Used as the queue name and must be unique across all actions.
+       * Required.
+       */
+      name: z.string().describe('The name of the action'),
+
+      /**
+       * Version of the action.
+       * Used to track changes to the action and generate the checksum.
+       */
+      version: z.string().describe('The version of the action').optional(),
+
+      /**
+       * Zod schema for validating the action input.
+       * If provided, input will be validated before the handler is called.
+       * If not provided, any input will be accepted.
+       */
+      input: z
+        .custom<TInput>((val: any) => {
+          return !val || ('_zod' in val && 'type' in val && val.type === 'object')
+        })
+        .optional(),
+
+      /**
+       * Zod schema for validating the action output.
+       * If provided, output will be validated after the handler completes.
+       * If not provided, any output will be accepted.
+       */
+      output: z
+        .custom<TOutput>((val: any) => {
+          return !val || ('_zod' in val && 'type' in val && val.type === 'object')
+        })
+        .optional(),
+
+      groups: z
+        .object({
+          /**
+           * Function to determine the group key for a job.
+           * Jobs with the same group key will respect the group concurrency limit.
+           * If not provided, all jobs for this action will use the '@default' group key.
+           *
+           * @param ctx - Context containing the input and variables
+           * @returns Promise resolving to the group key string
+           */
+          groupKey: z
+            .custom<(ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<string>>((val) => {
+              return !val || val instanceof Function
+            })
+            .optional(),
+
+          /**
+           * Function to determine the concurrency limit for a job.
+           * The concurrency limit is stored with each job and used during fetch operations.
+           * When fetching jobs, the latest job's concurrency limit is used for each groupKey.
+           * If not provided, defaults to 10.
+           *
+           * @param ctx - Context containing the input and variables
+           * @returns Promise resolving to the concurrency limit number
+           */
+          concurrency: z
+            .custom<(ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<number>>((val) => {
+              return !val || val instanceof Function
+            })
+            .optional(),
+        })
+        .optional(),
+
+      steps: z
+        .object({
+          /**
+           * Function to determine the concurrency limit for a step.
+           * The concurrency limit is stored with each step and used during fetch operations.
+           * When fetching steps, the latest step's concurrency limit is used for each stepKey.
+           * If not provided, defaults to 10.
+           */
+          concurrency: z.number().default(10).describe('How many steps can run concurrently for this action'),
+          retry: RetryOptionsSchema.describe('How to retry on failure for the steps of this action'),
+          expire: z
+            .number()
+            .default(5 * 60 * 1000)
+            .describe('How long a step can run for (milliseconds)'),
+        })
+        .default({
+          concurrency: 10,
+          retry: { limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 },
+          expire: 5 * 60 * 1000,
+        }),
+
+      concurrency: z.number().default(100).describe('How many jobs can run concurrently for this action'),
+
+      expire: z
+        .number()
+        .default(15 * 60 * 1000)
+        .describe('How long a job can run for (milliseconds)'),
+
+      /**
+       * The handler function that executes the action logic.
+       * Receives a context object with input, variables, and a step function.
+       * Must return a Promise that resolves to the action output.
+       * Required.
+       *
+       * @param ctx - Action handler context
+       * @returns Promise resolving to the action output
+       */
+      handler: z
+        .custom<(ctx: ActionHandlerContext<TInput, TVariables>) => Promise<z.infer<TOutput>>>((val) => {
+          return val instanceof Function
+        })
+        .describe('The handler for the action'),
+    })
+    .transform((def) => {
+      const checksum = [def.name, def.version, def.handler.toString()].filter(Boolean).join(':')
+      return {
+        ...def,
+        checksum: generateChecksum(checksum),
+      }
+    })
+}
+
+export const defineAction = <TVariables = Record<string, unknown>>() => {
+  return <TInput extends z.ZodObject, TOutput extends z.ZodObject>(
+    def: ActionDefinition<TInput, TOutput, TVariables>,
+  ) => {
+    return createActionDefinitionSchema<TInput, TOutput, TVariables>().parse(def, {
+      reportInput: true,
+    })
+  }
+}