duron 0.3.0-beta.8 → 0.3.0

package/src/client.ts

@@ -1,3 +1,8 @@
+import { type Span, type Tracer, trace } from '@opentelemetry/api'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { BatchSpanProcessor, type SpanExporter, type SpanProcessor } from '@opentelemetry/sdk-trace-base'
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
 import pino, { type Logger } from 'pino'
 import { zocker } from 'zocker'
 import * as z from 'zod'
@@ -11,14 +16,14 @@ import type {
   GetJobStepsResult,
   GetJobsOptions,
   GetJobsResult,
-  GetMetricsOptions,
-  GetMetricsResult,
+  GetSpansOptions,
+  GetSpansResult,
   Job,
   JobStep,
 } from './adapters/adapter.js'
 import type { JobStatusResult, JobStepStatusResult } from './adapters/schemas.js'
 import { JOB_STATUS_CANCELLED, JOB_STATUS_COMPLETED, JOB_STATUS_FAILED, type JobStatus } from './constants.js'
-import { LocalTelemetryAdapter, noopTelemetryAdapter, type TelemetryAdapter } from './telemetry/index.js'
+import { LocalSpanExporter } from './telemetry/local-span-exporter.js'
 
 /**
  * Extracts the inferred type from an action's input/output schema.
@@ -30,10 +35,11 @@ type InferActionSchema<T> = T extends z.ZodTypeAny ? z.infer<T> : Record<string,
  * Result returned from waitForJob with untyped input and output.
  */
 export interface JobResult {
-  jobId: string
+  id: string
   actionName: string
   status: JobStatus
   groupKey: string
+  description: string | null
   input: unknown
   output: unknown
   error: Job['error']
@@ -43,102 +49,228 @@ export interface JobResult {
  * Result returned from runActionAndWait with typed input and output based on the action's Zod schemas.
  */
 export interface TypedJobResult<TAction extends Action<any, any, any>> {
-  jobId: string
+  id: string
   actionName: string
   status: JobStatus
   groupKey: string
+  description: string | null
   input: InferActionSchema<NonNullable<TAction['input']>>
   output: InferActionSchema<NonNullable<TAction['output']>>
   error: Job['error']
 }
 
-const BaseOptionsSchema = z.object({
+/**
+ * Telemetry context provided to action and step handlers.
+ * Provides access to OpenTelemetry APIs for recording traces and metrics.
+ */
+export interface TelemetryContext {
+  /**
+   * Get the active OpenTelemetry span for the current job/step.
+   * Use standard OTel Span methods: setAttribute, addEvent, recordException, etc.
+   */
+  getActiveSpan(): Span
+
+  /**
+   * Get an OpenTelemetry tracer for creating custom spans.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   */
+  getTracer(name: string): Tracer
+
+  /**
+   * Record a custom metric as a span event.
+   * This is a convenience method that stores metrics as span events
+   * which can be queried from the local database when telemetry.local is enabled.
+   *
+   * @param name - The metric name (e.g., 'tokens.input', 'latency.ms')
+   * @param value - The metric value
+   * @param attributes - Optional attributes for the metric
+   */
+  recordMetric(name: string, value: number, attributes?: Record<string, any>): void
+}
+
+/**
+ * Options for local telemetry storage.
+ */
+export interface LocalTelemetryOptions {
+  /**
+   * Delay in milliseconds before flushing spans to the database.
+   * Uses BatchSpanProcessor with this delay.
+   * @default 5000
+   */
+  flushDelayMs?: number
+}
+
+/**
+ * Telemetry configuration options.
+ * Uses OpenTelemetry SDK for tracing.
+ */
+export interface TelemetryOptions {
+  /**
+   * Enable local span storage in the database.
+   * When enabled, spans are stored in the database and can be queried via getSpans().
+   * Set to true for default options, or provide LocalTelemetryOptions for custom config.
+   */
+  local?: LocalTelemetryOptions | boolean
+
+  /**
+   * Additional span processors to add to the tracer provider.
+   * These are merged with the local processor (if enabled).
+   */
+  spanProcessors?: SpanProcessor[]
+
+  /**
+   * Additional span exporter to use.
+   * Will be wrapped in a BatchSpanProcessor and merged with other processors.
+   */
+  traceExporter?: SpanExporter
+
+  /**
+   * Service name for OpenTelemetry resource.
+   * @default 'duron'
+   */
+  serviceName?: string
+}
+
+/**
+ * Base configuration options for a Duron client instance.
+ * These options control job fetching, concurrency, and recovery behavior.
+ */
+export interface BaseOptionsInput {
   /**
    * Unique identifier for this Duron instance.
    * Used for multi-process coordination and job ownership.
-   * Defaults to a random UUID if not provided.
+   * If not provided, a random UUID will be generated.
+   *
+   * @example 'worker-1', 'api-server', 'background-processor'
    */
-  id: z.string().optional(),
+  id?: string
 
   /**
-   * Synchronization pattern for fetching jobs.
-   * - `'pull'`: Periodically poll the database for new jobs
-   * - `'push'`: Listen for database notifications when jobs are available
-   * - `'hybrid'`: Use both pull and push patterns (recommended)
-   * - `false`: Disable automatic job fetching (manual fetching only)
+   * Synchronization pattern for fetching jobs from the database.
+   *
+   * - `'pull'`: Periodically poll the database for new jobs at `pullInterval`
+   * - `'push'`: Listen for database notifications when jobs are available (real-time)
+   * - `'hybrid'`: Use both pull and push patterns (recommended for reliability)
+   * - `false`: Disable automatic job fetching (use `fetch()` manually)
    *
    * @default 'hybrid'
+   *
+   * @example
+   * ```typescript
+   * // Real-time job processing with fallback polling
+   * syncPattern: 'hybrid'
+   *
+   * // Disable auto-fetching for API-only servers
+   * syncPattern: false
+   * ```
    */
-  syncPattern: z.union([z.literal('pull'), z.literal('push'), z.literal('hybrid'), z.literal(false)]).default('hybrid'),
+  syncPattern?: 'pull' | 'push' | 'hybrid' | false
 
   /**
-   * Interval in milliseconds between pull operations when using pull or hybrid sync pattern.
+   * Interval in milliseconds between pull operations when using `'pull'` or `'hybrid'` sync pattern.
+   * Lower values mean faster job pickup but more database queries.
    *
    * @default 5000
    */
-  pullInterval: z.number().default(5_000),
+  pullInterval?: number
 
   /**
-   * Maximum number of jobs to fetch in a single batch.
+   * Maximum number of jobs to fetch in a single batch from the database.
+   * Higher values reduce database round-trips but may increase memory usage.
    *
    * @default 10
    */
-  batchSize: z.number().default(10),
+  batchSize?: number
 
   /**
    * Maximum number of jobs that can run concurrently per action.
-   * This controls the concurrency limit for the action's fastq queue.
+   * This controls the concurrency limit for each action's internal queue.
+   * Use this to prevent any single action from consuming all resources.
    *
    * @default 100
    */
-  actionConcurrencyLimit: z.number().default(100),
+  actionConcurrencyLimit?: number
 
   /**
    * Maximum number of jobs that can run concurrently per group key.
    * Jobs with the same group key will respect this limit.
-   * This can be overridden using action -> groups -> concurrency.
+   * This is the default value; it can be overridden per-job using `action.groups.concurrency`.
    *
    * @default 10
+   *
+   * @example
+   * ```typescript
+   * // Limit concurrent jobs per user to 2
+   * groupConcurrencyLimit: 2
+   * ```
    */
-  groupConcurrencyLimit: z.number().default(10),
+  groupConcurrencyLimit?: number
 
   /**
    * Whether to run database migrations on startup.
    * When enabled, Duron will automatically apply pending migrations when the adapter starts.
+   * Disable this if you manage migrations separately or use a read-only database connection.
    *
    * @default true
    */
-  migrateOnStart: z.boolean().default(true),
+  migrateOnStart?: boolean
 
   /**
    * Whether to recover stuck jobs on startup.
    * Stuck jobs are jobs that were marked as active but the process that owned them
-   * is no longer running.
+   * is no longer running (e.g., after a crash or restart).
+   * These jobs will be reset to 'created' status so they can be picked up again.
    *
    * @default true
    */
-  recoverJobsOnStart: z.boolean().default(true),
+  recoverJobsOnStart?: boolean
 
   /**
    * Enable multi-process mode for job recovery.
    * When enabled, Duron will ping other processes to check if they're alive
-   * before recovering their jobs.
+   * before recovering their jobs. This prevents recovering jobs from processes
+   * that are still running but slow to respond.
+   *
+   * Only enable this if you're running multiple Duron instances sharing the same database.
    *
    * @default false
    */
-  multiProcessMode: z.boolean().default(false),
+  multiProcessMode?: boolean
 
   /**
    * Timeout in milliseconds to wait for process ping responses in multi-process mode.
    * Processes that don't respond within this timeout will have their jobs recovered.
+   * Increase this value if your processes may be temporarily unresponsive under load.
    *
-   * @default 5000 (5 seconds)
+   * @default 5000
    */
-  processTimeout: z.number().default(5 * 1000), // 5 seconds
+  processTimeout?: number
+}
+
+const BaseOptionsSchema = z.object({
+  id: z.string().optional(),
+  syncPattern: z.union([z.literal('pull'), z.literal('push'), z.literal('hybrid'), z.literal(false)]).default('hybrid'),
+  pullInterval: z.number().default(5_000),
+  batchSize: z.number().default(10),
+  actionConcurrencyLimit: z.number().default(100),
+  groupConcurrencyLimit: z.number().default(10),
+  migrateOnStart: z.boolean().default(true),
+  recoverJobsOnStart: z.boolean().default(true),
+  multiProcessMode: z.boolean().default(false),
+  processTimeout: z.number().default(5 * 1000),
 })
 
+// Compile-time check: ensure BaseOptionsInput is assignable to the Zod schema's input type
+type _EnsureBaseOptionsCompatible = BaseOptionsInput extends z.input<typeof BaseOptionsSchema>
+  ? true
+  : 'ERROR: BaseOptionsInput does not match Zod schema input type'
+
+declare const _baseOptionsCheck: _EnsureBaseOptionsCompatible
+const _checkOptions: _EnsureBaseOptionsCompatible = true
+
 /**
- * Options for configuring a Duron instance.
+ * Options for configuring a Duron client instance.
  *
  * @template TActions - Record of action definitions keyed by action name
  * @template TVariables - Type of variables available to actions
@@ -146,7 +278,7 @@ const BaseOptionsSchema = z.object({
 export interface ClientOptions<
   TActions extends Record<string, Action<any, any, TVariables>>,
   TVariables = Record<string, unknown>,
-> extends z.input<typeof BaseOptionsSchema> {
+> extends BaseOptionsInput {
   /**
    * The database adapter to use for storing jobs and steps.
    * Required.
@@ -173,15 +305,25 @@ export interface ClientOptions<
   variables?: TVariables
 
   /**
-   * Optional telemetry adapter for observability.
-   * When provided, traces job and step execution with spans and allows recording custom metrics.
+   * Optional telemetry configuration for observability.
+   * Uses OpenTelemetry SDK for tracing.
+   *
+   * @example
+   * ```typescript
+   * // Enable local span storage (stored in the database)
+   * telemetry: { local: true }
+   *
+   * // Enable local storage with custom flush delay
+   * telemetry: { local: { flushDelayMs: 10000 } }
    *
-   * Available adapters:
-   * - `openTelemetryAdapter()` - Export traces to external systems (Jaeger, OTLP, etc.)
-   * - `localTelemetryAdapter({ database })` - Store metrics in the Duron database
-   * - `noopTelemetryAdapter()` - No-op adapter (default)
+   * // Export to external systems (e.g., OTLP)
+   * telemetry: { traceExporter: new OTLPTraceExporter() }
+   *
+   * // Both local storage and external export
+   * telemetry: { local: true, traceExporter: new OTLPTraceExporter() }
+   * ```
    */
-  telemetry?: TelemetryAdapter
+  telemetry?: TelemetryOptions
 }
 
 interface FetchOptions {
@@ -203,7 +345,10 @@ export class Client<
   #id: string
   #actions: TActions | null
   #database: Adapter
-  #telemetry: TelemetryAdapter
+  #tracerProvider: NodeTracerProvider | null = null
+  #tracer: Tracer
+  #telemetryOptions: TelemetryOptions | null = null
+  #localSpansEnabled: boolean = false
   #variables: Record<string, unknown>
   #logger: Logger
   #started: boolean = false
@@ -237,14 +382,66 @@ export class Client<
     this.#options = BaseOptionsSchema.parse(options)
     this.#id = options.id ?? globalThis.crypto.randomUUID()
     this.#database = options.database
-    this.#telemetry = options.telemetry ?? noopTelemetryAdapter()
+    this.#telemetryOptions = options.telemetry ?? null
     this.#actions = options.actions ?? null
     this.#variables = options?.variables ?? {}
     this.#logger = this.#normalizeLogger(options?.logger)
     this.#database.setId(this.#id)
     this.#database.setLogger(this.#logger)
-    this.#telemetry.setLogger(this.#logger)
-    this.#telemetry.setClient(this)
+
+    // Initialize OpenTelemetry TracerProvider if telemetry options are provided
+    // When no options are provided, the tracer will be a no-op (from OpenTelemetry API)
+    if (this.#telemetryOptions) {
+      this.#initTelemetry(this.#telemetryOptions)
+    }
+
+    // Get tracer from our provider if configured, otherwise use global no-op tracer
+    // This keeps telemetry scoped to this client instance rather than globally registered
+    this.#tracer = this.#tracerProvider?.getTracer('duron') ?? trace.getTracer('duron')
+  }
+
+  /**
+   * Initialize OpenTelemetry TracerProvider with configured processors.
+   */
+  #initTelemetry(options: TelemetryOptions): void {
+    const serviceName = options.serviceName ?? 'duron'
+    const processors: SpanProcessor[] = []
+
+    // Add local span exporter if enabled
+    if (options.local) {
+      const localOptions = typeof options.local === 'boolean' ? {} : options.local
+      const flushDelayMs = localOptions.flushDelayMs ?? 5000
+
+      const localExporter = new LocalSpanExporter({ adapter: this.#database })
+      processors.push(
+        new BatchSpanProcessor(localExporter, {
+          scheduledDelayMillis: flushDelayMs,
+        }),
+      )
+      this.#localSpansEnabled = true
+    }
+
+    // Add custom span processors
+    if (options.spanProcessors) {
+      processors.push(...options.spanProcessors)
+    }
+
+    // Add custom trace exporter wrapped in BatchSpanProcessor
+    if (options.traceExporter) {
+      processors.push(new BatchSpanProcessor(options.traceExporter))
+    }
+
+    // Only create TracerProvider if we have processors
+    if (processors.length > 0) {
+      this.#tracerProvider = new NodeTracerProvider({
+        resource: resourceFromAttributes({
+          [ATTR_SERVICE_NAME]: serviceName,
+        }),
+        spanProcessors: processors,
+      })
+      // Note: We do NOT call .register() here to avoid global state pollution
+      // The tracer is obtained directly from this provider instance
+    }
   }
 
   #normalizeLogger(logger?: Logger | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'): Logger {
@@ -268,10 +465,11 @@ export class Client<
   }
 
   /**
-   * Get the telemetry adapter instance.
+   * Get the OpenTelemetry tracer for creating custom spans.
+   * Always returns a tracer - it's a no-op tracer when no SDK is configured.
    */
-  get telemetry(): TelemetryAdapter {
-    return this.#telemetry
+  get tracer(): Tracer {
+    return this.#tracer
   }
 
   /**
@@ -282,11 +480,21 @@ export class Client<
   }
 
   /**
-   * Check if local telemetry is enabled.
-   * Returns true if using LocalTelemetryAdapter.
+   * Check if local span storage is enabled.
+   * Returns true if telemetry.local is enabled.
+   */
+  get spansEnabled(): boolean {
+    return this.#localSpansEnabled
+  }
+
+  /**
+   * Force flush any pending telemetry data.
+   * Useful in tests or when you need to ensure spans are exported before querying.
    */
-  get metricsEnabled(): boolean {
-    return this.#telemetry instanceof LocalTelemetryAdapter
+  async flushTelemetry(): Promise<void> {
+    if (this.#tracerProvider) {
+      await this.#tracerProvider.forceFlush()
+    }
   }
 
   /**
@@ -348,6 +556,12 @@ export class Client<
       concurrencyLimit = await action.groups.concurrency(concurrencyCtx)
     }
 
+    // Calculate description if provided
+    let description: string | null = null
+    if (action.description) {
+      description = await action.description(concurrencyCtx)
+    }
+
     // Create job in database
     const jobId = await this.#database.createJob({
       queue: action.name,
@@ -356,6 +570,8 @@ export class Client<
       timeoutMs: action.expire,
       checksum: action.checksum,
       concurrencyLimit,
+      concurrencyStepLimit: action.steps.concurrency,
+      description,
     })
 
     if (!jobId) {
@@ -497,10 +713,10 @@ export class Client<
    * Fetch and process jobs from the database.
    * Concurrency limits are determined from the latest job created for each groupKey.
    *
-   * @param options - Fetch options including batch size
+   * @param [options.batchSize] - Maximum number of jobs to fetch in this batch (defaults to `batchSize` from client options)
    * @returns Promise resolving to the array of fetched jobs
    */
-  async fetch(options: FetchOptions) {
+  async fetch(options: FetchOptions = {}) {
     await this.start()
 
     if (!this.#actions) {
@@ -705,10 +921,11 @@ export class Client<
           return null
         }
         return {
-          jobId: job.id,
+          id: job.id,
           actionName: job.actionName,
           status: job.status,
           groupKey: job.groupKey,
+          description: job.description,
           input: job.input,
           output: job.output,
           error: job.error,
@@ -770,19 +987,19 @@ export class Client<
   }
 
   /**
-   * Get metrics for a job or step.
-   * Only available when using LocalTelemetryAdapter.
+   * Get spans for a job or step.
+   * Only available when telemetry.local is enabled.
    *
-   * @param options - Query options including jobId/stepId, filters, sort, and pagination
-   * @returns Promise resolving to metrics result with pagination info
-   * @throws Error if not using LocalTelemetryAdapter
+   * @param options - Query options including jobId/stepId, filters, and sort
+   * @returns Promise resolving to spans result
+   * @throws Error if local telemetry is not enabled
    */
-  async getMetrics(options: GetMetricsOptions): Promise<GetMetricsResult> {
+  async getSpans(options: GetSpansOptions): Promise<GetSpansResult> {
     await this.start()
-    if (!this.metricsEnabled) {
-      throw new Error('Metrics are only available when using LocalTelemetryAdapter')
+    if (!this.spansEnabled) {
+      throw new Error('Spans are only available when telemetry.local is enabled')
     }
-    return this.#database.getMetrics(options)
+    return this.#database.getSpans(options)
   }
 
   /**
@@ -806,6 +1023,43 @@ export class Client<
             action.name,
             zocker(action.input as z.ZodObject)
               .override(z.ZodString, 'string')
+              .override(z.ZodBigInt, '4000' as any) // Convert BigInt to string for JSON serialization
+              .override(z.ZodNumber, (schema, _ctx) => {
+                const greaterThan = schema.def.checks?.find((check) => check._zod.def.check === 'greater_than')?._zod
+                  .def as unknown as { value: number; inclusive: boolean }
+                const lessThan = schema.def.checks?.find((check) => check._zod.def.check === 'less_than')?._zod
+                  .def as unknown as { value: number; inclusive: boolean }
+
+                if (greaterThan && lessThan) {
+                  const min = greaterThan.inclusive ? greaterThan.value : greaterThan.value + 1
+                  // For inclusive lessThan, we want to include the value, so max should be value + 1
+                  // For exclusive lessThan, we want to exclude the value, so max is the value itself
+                  const max = lessThan.inclusive ? lessThan.value + 1 : lessThan.value
+                  // Ensure min < max
+                  if (min >= max) {
+                    return Math.floor(min)
+                  }
+                  return Math.floor(Math.random() * (max - min) + min)
+                }
+
+                if (greaterThan) {
+                  const min = greaterThan.inclusive ? greaterThan.value : greaterThan.value + 1
+                  const max = min + 1000 // Use 1000 as default range
+                  return Math.floor(Math.random() * (max - min) + min)
+                }
+
+                if (lessThan) {
+                  // For inclusive lessThan, we want to include the value, so max should be value + 1
+                  // For exclusive lessThan, we want to exclude the value, so max is the value itself
+                  const max = lessThan.inclusive ? lessThan.value + 1 : lessThan.value
+                  return Math.floor(Math.random() * max)
+                }
+
+                return Math.floor(Math.random() * 1000)
+              })
+              .number({
+                extreme_value_chance: 0.01,
+              })
               .generate(),
           )
         }
@@ -847,9 +1101,6 @@ export class Client<
         return false
       }
 
-      // Start telemetry adapter
-      await this.#telemetry.start()
-
       if (this.#actions) {
         if (this.#options.recoverJobsOnStart) {
           await this.#database.recoverJobs({
@@ -920,8 +1171,10 @@ export class Client<
         }),
       )
 
-      // Stop telemetry adapter
-      await this.#telemetry.stop()
+      // Shutdown TracerProvider if configured
+      if (this.#tracerProvider) {
+        await this.#tracerProvider.shutdown()
+      }
 
       const dbStopped = await this.#database.stop()
       if (!dbStopped) {
@@ -965,10 +1218,11 @@ export class Client<
         // Transform to JobResult
         const result: JobResult | null = job
           ? {
-              jobId: job.id,
+              id: job.id,
               actionName: job.actionName,
               status: job.status,
               groupKey: job.groupKey,
+              description: job.description,
               input: job.input,
               output: job.output,
               error: job.error,
@@ -1051,7 +1305,7 @@ export class Client<
       actionManager = new ActionManager({
         action,
         database: this.#database,
-        telemetry: this.#telemetry,
+        tracer: this.#tracer,
         variables: this.#variables,
         logger: this.#logger,
         concurrencyLimit: this.#options.actionConcurrencyLimit,