duron 0.3.0-beta.6 → 0.3.0-beta.8

package/migrations/postgres/20260119153838_flimsy_thor_girl/snapshot.json

@@ -2,9 +2,7 @@
   "version": "8",
   "dialect": "postgres",
   "id": "4e93c0bf-b135-40b4-b130-0cf0968bffe3",
-  "prevIds": [
-    "00000000-0000-0000-0000-000000000000"
-  ],
+  "prevIds": ["00000000-0000-0000-0000-000000000000"],
   "ddl": [
     {
       "name": "duron",
@@ -1268,14 +1266,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "job_id"
-      ],
+      "columns": ["job_id"],
       "schemaTo": "duron",
       "tableTo": "jobs",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "job_steps_job_id_jobs_id_fkey",
@@ -1285,14 +1279,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "job_id"
-      ],
+      "columns": ["job_id"],
       "schemaTo": "duron",
       "tableTo": "jobs",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "metrics_job_id_jobs_id_fkey",
@@ -1302,14 +1292,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "step_id"
-      ],
+      "columns": ["step_id"],
       "schemaTo": "duron",
       "tableTo": "job_steps",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "metrics_step_id_job_steps_id_fkey",
@@ -1318,9 +1304,7 @@
       "table": "metrics"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "job_steps_pkey",
       "schema": "duron",
@@ -1328,9 +1312,7 @@
       "entityType": "pks"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "jobs_pkey",
       "schema": "duron",
@@ -1338,9 +1320,7 @@
       "entityType": "pks"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "metrics_pkey",
       "schema": "duron",
@@ -1349,11 +1329,7 @@
     },
     {
       "nameExplicit": true,
-      "columns": [
-        "job_id",
-        "name",
-        "parent_step_id"
-      ],
+      "columns": ["job_id", "name", "parent_step_id"],
       "nullsNotDistinct": true,
       "name": "unique_job_step_name_parent",
       "entityType": "uniques",
@@ -1383,4 +1359,4 @@
     }
   ],
   "renames": []
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duron",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/action-job.ts

@@ -61,7 +61,7 @@ export class ActionJob<TAction extends Action<any, any, any>> {
       adapter: options.database,
       telemetry: options.telemetry,
       logger: options.logger,
-      concurrencyLimit: options.action.concurrency,
+      concurrencyLimit: options.action.steps.concurrency,
     })
 
     this.#done = new Promise((resolve) => {

package/src/action.ts

@@ -133,18 +133,13 @@ export interface StepDefinitionHandlerContext<TInput extends z.ZodObject, TVaria
    * 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>,
-> {
+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.
@@ -358,9 +353,9 @@ export function createActionDefinitionSchema<
            * 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.
+           * If not provided, defaults to 100.
            */
-          concurrency: z.number().default(10).describe('How many steps can run concurrently for this action'),
+          concurrency: z.number().default(100).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()
@@ -368,7 +363,7 @@ export function createActionDefinitionSchema<
             .describe('How long a step can run for (milliseconds)'),
         })
         .default({
-          concurrency: 10,
+          concurrency: 100,
           retry: { limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 },
           expire: 5 * 60 * 1000,
         }),
@@ -417,11 +412,10 @@ 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'>
+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.

package/src/adapters/postgres/schema.ts

@@ -119,7 +119,9 @@ export default function createSchema(schemaName: string) {
       index('idx_job_steps_output_fts').using('gin', sql`to_tsvector('english', ${table.output}::text)`),
       // Unique constraint - step name is unique within a parent (name + parentStepId)
       // nullsNotDistinct ensures NULL parent_step_id values are treated as equal for uniqueness
-      unique('unique_job_step_name_parent').on(table.job_id, table.name, table.parent_step_id).nullsNotDistinct(),
+      unique('unique_job_step_name_parent')
+        .on(table.job_id, table.name, table.parent_step_id)
+        .nullsNotDistinct(),
       check(
         'job_steps_status_check',
         sql`${table.status} IN ${sql.raw(`(${STEP_STATUSES.map((s) => `'${s}'`).join(',')})`)}`,

package/src/step-manager.ts

@@ -23,7 +23,46 @@ import {
   serializeError,
   UnhandledChildStepsError,
 } from './errors.js'
-import type { ObserveContext, Span, TelemetryAdapter } from './telemetry/adapter.js'
+import type { ObserveContext, Span, TelemetryAdapter, Tracer, TracerSpan } from './telemetry/adapter.js'
+
+// ============================================================================
+// Noop Tracer (for fallback observe context)
+// ============================================================================
+
+const noopTracerSpan: TracerSpan = {
+  setAttribute() {
+    // No-op
+  },
+  setAttributes() {
+    // No-op
+  },
+  addEvent() {
+    // No-op
+  },
+  recordException() {
+    // No-op
+  },
+  setStatusOk() {
+    // No-op
+  },
+  setStatusError() {
+    // No-op
+  },
+  end() {
+    // No-op
+  },
+  isRecording() {
+    return false
+  },
+}
+
+const createNoopTracer = (name: string): Tracer => ({
+  name,
+  startSpan(): TracerSpan {
+    return noopTracerSpan
+  },
+})
+
 import pRetry from './utils/p-retry.js'
 import waitForAbort from './utils/wait-for-abort.js'
 
@@ -251,6 +290,9 @@ export class StepManager {
       addSpanEvent: () => {
         // No-op
       },
+      getTracer: (name: string) => {
+        return createNoopTracer(name)
+      },
     }
   }
 
@@ -261,6 +303,21 @@ export class StepManager {
    * @returns Promise resolving to the step result
    */
   async push(task: TaskStep): Promise<any> {
+    // Warn about potential starvation when child steps are queued and all slots are occupied
+    if (task.parentStepId !== null && this.#queue.running() >= this.#queue.concurrency) {
+      this.#logger.warn(
+        {
+          jobId: this.#jobId,
+          actionName: this.#actionName,
+          stepName: task.name,
+          parentStepId: task.parentStepId,
+          running: this.#queue.running(),
+          waiting: this.#queue.length(),
+          concurrency: this.#queue.concurrency,
+        },
+        '[StepManager] Potential starvation: child step queued while all concurrency slots are occupied by parent steps. Consider increasing steps.concurrency.',
+      )
+    }
     return this.#queue.push(task)
   }
 

package/src/telemetry/adapter.ts

@@ -108,6 +108,106 @@ export interface AddSpanAttributeOptions {
   value: string | number | boolean
 }
 
+/**
+ * Options for starting a custom span with the tracer.
+ */
+export interface StartSpanOptions {
+  /**
+   * Span kind (internal, client, server, producer, consumer).
+   * @default 'internal'
+   */
+  kind?: 'internal' | 'client' | 'server' | 'producer' | 'consumer'
+
+  /**
+   * Initial attributes for the span.
+   */
+  attributes?: Record<string, string | number | boolean>
+
+  /**
+   * Parent span to use for context propagation.
+   * If not provided, uses the current active context.
+   */
+  parentSpan?: TracerSpan
+}
+
+/**
+ * A span created by the Tracer for manual instrumentation.
+ */
+export interface TracerSpan {
+  /**
+   * Set an attribute on the span.
+   *
+   * @param key - The attribute key
+   * @param value - The attribute value
+   */
+  setAttribute(key: string, value: string | number | boolean): void
+
+  /**
+   * Set multiple attributes on the span.
+   *
+   * @param attributes - The attributes to set
+   */
+  setAttributes(attributes: Record<string, string | number | boolean>): void
+
+  /**
+   * Add an event to the span.
+   *
+   * @param name - The event name
+   * @param attributes - Optional event attributes
+   */
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): void
+
+  /**
+   * Record an exception on the span.
+   *
+   * @param error - The error to record
+   */
+  recordException(error: Error): void
+
+  /**
+   * Set the span status to OK.
+   */
+  setStatusOk(): void
+
+  /**
+   * Set the span status to error.
+   *
+   * @param message - Optional error message
+   */
+  setStatusError(message?: string): void
+
+  /**
+   * End the span.
+   * After calling this, no more operations can be performed on the span.
+   */
+  end(): void
+
+  /**
+   * Check if this span is recording.
+   */
+  isRecording(): boolean
+}
+
+/**
+ * A Tracer provides methods for creating spans.
+ * Similar to OpenTelemetry's Tracer interface.
+ */
+export interface Tracer {
+  /**
+   * The name of this tracer.
+   */
+  readonly name: string
+
+  /**
+   * Start a new span.
+   *
+   * @param name - The name of the span
+   * @param options - Optional span configuration
+   * @returns A TracerSpan for manual instrumentation
+   */
+  startSpan(name: string, options?: StartSpanOptions): TracerSpan
+}
+
 /**
  * Observe context provided to action and step handlers.
  */
@@ -136,6 +236,37 @@ export interface ObserveContext {
    * @param attributes - Optional event attributes
    */
   addSpanEvent(name: string, attributes?: Record<string, any>): void
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = ctx.observe.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('external-api-call', {
+   *   kind: 'client',
+   *   attributes: { 'api.endpoint': '/users' }
+   * })
+   *
+   * try {
+   *   const result = await fetch('https://api.example.com/users')
+   *   span.setStatusOk()
+   *   return result
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   *   throw error
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer
 }
 
 // ============================================================================
@@ -369,6 +500,41 @@ export abstract class TelemetryAdapter {
     return this._addSpanAttribute(options)
   }
 
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  /**
+   * Get a tracer for manual instrumentation.
+   * Similar to OpenTelemetry's `trace.getTracer()` method.
+   *
+   * @param name - The name of the tracer (typically your service or library name)
+   * @returns A Tracer for creating custom spans
+   *
+   * @example
+   * ```typescript
+   * const tracer = telemetry.getTracer('my-service')
+   *
+   * const span = tracer.startSpan('process-order', {
+   *   attributes: { 'order.id': orderId }
+   * })
+   *
+   * try {
+   *   // Do some work
+   *   span.addEvent('order.validated')
+   *   span.setStatusOk()
+   * } catch (error) {
+   *   span.recordException(error)
+   *   span.setStatusError(error.message)
+   * } finally {
+   *   span.end()
+   * }
+   * ```
+   */
+  getTracer(name: string): Tracer {
+    return this._getTracer(name)
+  }
+
   // ============================================================================
   // Context Methods
   // ============================================================================
@@ -404,6 +570,9 @@ export abstract class TelemetryAdapter {
           this.#logger?.error(err, 'Error adding span event')
         })
       },
+      getTracer: (name: string) => {
+        return this.getTracer(name)
+      },
     }
   }
 
@@ -465,4 +634,9 @@ export abstract class TelemetryAdapter {
    * Internal method to add a span attribute.
    */
   protected abstract _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>
+
+  /**
+   * Internal method to get a tracer for manual instrumentation.
+   */
+  protected abstract _getTracer(name: string): Tracer
 }

package/src/telemetry/index.ts

@@ -9,8 +9,11 @@ export {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 export { LocalTelemetryAdapter, type LocalTelemetryAdapterOptions, localTelemetryAdapter } from './local.js'
 export { NoopTelemetryAdapter, noopTelemetryAdapter } from './noop.js'

package/src/telemetry/local.ts

@@ -7,8 +7,11 @@ import {
   type Span,
   type StartDatabaseSpanOptions,
   type StartJobSpanOptions,
+  type StartSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
 // ============================================================================
@@ -304,6 +307,96 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
       },
     })
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    const adapter = this
+
+    return {
+      name,
+
+      startSpan(spanName: string, options?: StartSpanOptions): TracerSpan {
+        const spanId = `tracer:${name}:${globalThis.crypto.randomUUID()}`
+        const startTime = Date.now()
+        let ended = false
+        const attributes: Record<string, string | number | boolean> = {
+          ...options?.attributes,
+        }
+
+        // Note: Local adapter tracer spans don't have a jobId context,
+        // so they can't be stored in the database. They're essentially no-ops
+        // but provide a consistent API for code that needs a tracer.
+        // For actual metrics storage, use ctx.observe within action/step handlers.
+
+        const tracerSpan: TracerSpan = {
+          setAttribute(key: string, value: string | number | boolean): void {
+            if (!ended) {
+              attributes[key] = value
+            }
+          },
+
+          setAttributes(attrs: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              Object.assign(attributes, attrs)
+            }
+          },
+
+          addEvent(eventName: string, eventAttrs?: Record<string, string | number | boolean>): void {
+            if (!ended) {
+              adapter.logger?.debug({ spanId, event: eventName, attributes: eventAttrs }, 'Tracer span event')
+            }
+          },
+
+          recordException(error: Error): void {
+            if (!ended) {
+              attributes['error.message'] = error.message
+              attributes['error.name'] = error.name
+              adapter.logger?.debug({ spanId, error: error.message }, 'Tracer span exception')
+            }
+          },
+
+          setStatusOk(): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'ok'
+            }
+          },
+
+          setStatusError(message?: string): void {
+            if (!ended) {
+              // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
+              attributes['status'] = 'error'
+              if (message) {
+                attributes['status.message'] = message
+              }
+            }
+          },
+
+          end(): void {
+            if (!ended) {
+              ended = true
+              const duration = Date.now() - startTime
+              adapter.logger?.debug(
+                { spanId, spanName, tracerName: name, durationMs: duration, attributes },
+                'Tracer span ended',
+              )
+            }
+          },
+
+          isRecording(): boolean {
+            return !ended
+          },
+        }
+
+        adapter.logger?.debug({ spanId, spanName, tracerName: name }, 'Tracer span started')
+
+        return tracerSpan
+      },
+    }
+  }
 }
 
 /**

package/src/telemetry/noop.ts

@@ -8,8 +8,41 @@ import {
   type StartJobSpanOptions,
   type StartStepSpanOptions,
   TelemetryAdapter,
+  type Tracer,
+  type TracerSpan,
 } from './adapter.js'
 
+// ============================================================================
+// Noop Tracer Span
+// ============================================================================
+
+const noopTracerSpan: TracerSpan = {
+  setAttribute() {
+    // No-op
+  },
+  setAttributes() {
+    // No-op
+  },
+  addEvent() {
+    // No-op
+  },
+  recordException() {
+    // No-op
+  },
+  setStatusOk() {
+    // No-op
+  },
+  setStatusError() {
+    // No-op
+  },
+  end() {
+    // No-op
+  },
+  isRecording() {
+    return false
+  },
+}
+
 // ============================================================================
 // Noop Telemetry Adapter
 // ============================================================================
@@ -84,6 +117,19 @@ export class NoopTelemetryAdapter extends TelemetryAdapter {
   protected async _addSpanAttribute(_options: AddSpanAttributeOptions): Promise<void> {
     // No-op
   }
+
+  // ============================================================================
+  // Tracer Methods
+  // ============================================================================
+
+  protected _getTracer(name: string): Tracer {
+    return {
+      name,
+      startSpan(): TracerSpan {
+        return noopTracerSpan
+      },
+    }
+  }
 }
 
 /**