duron 0.3.0-beta.10 → 0.3.0-beta.12

package/dist/action-job.d.ts

@@ -1,7 +1,7 @@
+import { type Tracer } from '@opentelemetry/api';
 import type { Logger } from 'pino';
 import type { Action } from './action.js';
 import type { Adapter } from './adapters/adapter.js';
-import type { TelemetryAdapter } from './telemetry/adapter.js';
 export interface ActionJobOptions<TAction extends Action<any, any, any>> {
     job: {
         id: string;
@@ -12,15 +12,46 @@ export interface ActionJobOptions<TAction extends Action<any, any, any>> {
     };
     action: TAction;
     database: Adapter;
-    telemetry: TelemetryAdapter;
+    tracer: Tracer;
     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 declare class ActionJob<TAction extends Action<any, any, any>> {
     #private;
+    /**
+     * Create a new ActionJob instance.
+     *
+     * @param options - Configuration options for the action job
+     */
     constructor(options: ActionJobOptions<TAction>);
+    /**
+     * 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
+     */
     execute(): Promise<any>;
+    /**
+     * 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>;
+    /**
+     * Cancel the job execution.
+     * Clears the timeout and aborts the action handler.
+     */
     cancel(): void;
 }
 //# sourceMappingURL=action-job.d.ts.map

package/dist/action-job.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-job.d.ts","sourceRoot":"","sources":["../src/action-job.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,KAAK,EAAQ,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAGpE,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACrE,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IACxF,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,CAAA;CACf;AAQD,qBAAa,SAAS,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;;gBAuB9C,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC;IAsCxC,OAAO;IAkIb,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,MAAM;CAmBP"}
+{"version":3,"file":"action-job.d.ts","sourceRoot":"","sources":["../src/action-job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAA;AACrG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAKpD,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACrE,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IACxF,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,qBAAa,SAAS,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;;IAkB1D;;;;OAIG;gBACS,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC;IA4B9C;;;;;;;;;OASG;IACG,OAAO;IAgIb;;;;;OAKG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,MAAM;CAmBP"}

package/dist/action-job.js

@@ -1,11 +1,18 @@
+import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
 import { ActionCancelError, ActionTimeoutError, isCancelError, isTimeoutError, serializeError } from './errors.js';
 import { StepManager } from './step-manager.js';
 import waitForAbort from './utils/wait-for-abort.js';
+/**
+ * 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 {
     #job;
     #action;
     #database;
-    #telemetry;
+    #tracer;
     #variables;
     #logger;
     #stepManager;
@@ -13,20 +20,29 @@ export class ActionJob {
     #timeoutId = null;
     #done;
     #resolve = null;
-    #jobSpan = null;
+    #jobSpan;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new ActionJob instance.
+     *
+     * @param options - Configuration options for the action job
+     */
     constructor(options) {
         this.#job = options.job;
         this.#action = options.action;
         this.#database = options.database;
-        this.#telemetry = options.telemetry;
+        this.#tracer = options.tracer;
         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,
-            telemetry: options.telemetry,
+            tracer: options.tracer,
             logger: options.logger,
             concurrencyLimit: options.action.steps.concurrency,
         });
@@ -34,31 +50,52 @@ export class ActionJob {
             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() {
-        this.#jobSpan = await this.#telemetry.startJobSpan({
-            jobId: this.#job.id,
-            actionName: this.#action.name,
-            groupKey: this.#job.groupKey,
-            input: this.#job.input,
+        // Start job span - uses no-op tracer if no SDK is configured
+        this.#jobSpan = this.#tracer.startSpan(`job:${this.#action.name}`, {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                'duron.job.id': this.#job.id,
+                'duron.action.name': this.#action.name,
+                'duron.group.key': this.#job.groupKey,
+            },
         });
+        // 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({
                 jobId: this.#job.id,
                 actionName: this.#action.name,
             });
-            const observeContext = this.#telemetry.createObserveContext(this.#job.id, null, this.#jobSpan);
-            const ctx = this.#stepManager.createActionContext(this.#job, this.#action, this.#variables, this.#abortController.signal, jobLogger, observeContext);
+            // Create action context with step manager
+            const ctx = this.#stepManager.createActionContext(this.#job, this.#action, this.#variables, this.#abortController.signal, jobLogger);
             this.#timeoutId = setTimeout(() => {
                 const timeoutError = new ActionTimeoutError(this.#action.name, this.#job.id, 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 = null;
+            // Execute handler within the job span context so that child spans inherit the trace
+            const spanContext = trace.setSpan(context.active(), this.#jobSpan);
             await Promise.race([
-                this.#action
-                    .handler(ctx)
+                context
+                    .with(spanContext, () => this.#action.handler(ctx))
                     .then((res) => {
                     if (res !== undefined) {
                         result = res;
@@ -69,42 +106,54 @@ export class ActionJob {
                 }),
                 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');
-            await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'ok' });
+            // End job span successfully
+            this.#jobSpan.setStatus({ code: SpanStatusCode.OK });
+            this.#jobSpan.end();
             return result;
         }
         catch (error) {
+            // Abort all running steps when an error occurs
+            // This ensures cascading failure and stops any steps still running
             if (!this.#abortController.signal.aborted) {
                 this.#abortController.abort(error);
             }
+            // Wait for step manager to drain (all steps to settle)
             await this.#stepManager.drain();
             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 });
-                if (this.#jobSpan) {
-                    await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'cancelled' });
-                }
+                // End job span as cancelled
+                this.#jobSpan.setStatus({ code: SpanStatusCode.ERROR, message: 'Job cancelled' });
+                this.#jobSpan.end();
                 return;
             }
-            const message = isTimeoutError(error)
-                ? '[ActionJob] Job timed out'
-                : '[ActionJob] Job failed';
+            const message = isTimeoutError(error) ? '[ActionJob] Job 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) });
-            if (this.#jobSpan) {
-                await this.#telemetry.endJobSpan(this.#jobSpan, { status: 'error', error });
+            // End job span with error
+            this.#jobSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (error instanceof Error) {
+                this.#jobSpan.recordException(error);
             }
+            this.#jobSpan.end();
             throw error;
         }
         finally {
@@ -112,14 +161,30 @@ export class ActionJob {
             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() {
         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);

package/dist/action-manager.d.ts

@@ -1,23 +1,65 @@
+import type { Tracer } from '@opentelemetry/api';
 import type { Logger } from 'pino';
 import type { Action } from './action.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;
+    tracer: Tracer;
     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 declare class ActionManager<TAction extends Action<any, any, any>> {
     #private;
+    /**
+     * Create a new ActionManager instance.
+     *
+     * @param options - Configuration options for the action manager
+     */
     constructor(options: ActionManagerOptions<TAction>);
+    /**
+     * Queue a job for execution.
+     *
+     * @param job - The job to queue
+     * @returns Promise that resolves when the job is queued
+     */
     push(job: Job): Promise<void>;
+    /**
+     * 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): boolean;
+    /**
+     * Cancel all active jobs.
+     */
     abortAll(): void;
+    /**
+     * Check if the queue is idle (no jobs being processed).
+     *
+     * @returns Promise resolving to `true` if idle, `false` otherwise
+     */
     idle(): Promise<boolean>;
+    /**
+     * Wait for the queue to drain (all jobs completed).
+     *
+     * @returns Promise that resolves when the queue is drained
+     */
     drain(): Promise<void>;
+    /**
+     * 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
+     */
     stop(): Promise<void>;
 }
 //# sourceMappingURL=action-manager.d.ts.map

package/dist/action-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-manager.d.ts","sourceRoot":"","sources":["../src/action-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACzE,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAQD,qBAAa,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;;gBAoBlD,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC;IA4B5C,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnC,SAAS,CAAC,KAAK,EAAE,MAAM;IAYvB,QAAQ,IAAI,IAAI;IAWV,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IASxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA+C5B"}
+{"version":3,"file":"action-manager.d.ts","sourceRoot":"","sources":["../src/action-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAEzD,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACzE,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;;IAe9D;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAsBlD;;;;;OAKG;IACG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM;IASvB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAMhB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAI9B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA+C5B"}

package/dist/action-manager.js

@@ -1,22 +1,37 @@
 import fastq from 'fastq';
 import { ActionJob } from './action-job.js';
+/**
+ * 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 {
     #action;
     #database;
-    #telemetry;
+    #tracer;
     #variables;
     #logger;
     #queue;
     #concurrencyLimit;
     #activeJobs = new Map();
     #stopped = false;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new ActionManager instance.
+     *
+     * @param options - Configuration options for the action manager
+     */
     constructor(options) {
         this.#action = options.action;
         this.#database = options.database;
-        this.#telemetry = options.telemetry;
+        this.#tracer = options.tracer;
         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) => {
             if (this.#stopped) {
                 return;
@@ -24,9 +39,24 @@ export class ActionManager {
             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) {
         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) {
         const actionJob = this.#activeJobs.get(jobId);
         if (actionJob) {
@@ -35,17 +65,36 @@ export class ActionManager {
         }
         return false;
     }
+    /**
+     * Cancel all active jobs.
+     */
     abortAll() {
         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() {
         return this.#queue.idle();
     }
+    /**
+     * Wait for the queue to drain (all jobs completed).
+     *
+     * @returns Promise that resolves when the queue is drained
+     */
     async drain() {
         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() {
         if (this.#stopped) {
             return;
@@ -55,7 +104,16 @@ export class ActionManager {
         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) {
+        // Create ActionJob for this job
         const actionJob = new ActionJob({
             job: {
                 id: job.id,
@@ -66,15 +124,18 @@ export class ActionManager {
             },
             action: this.#action,
             database: this.#database,
-            telemetry: this.#telemetry,
+            tracer: this.#tracer,
             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);
         }
     }