duron 0.2.2 → 0.3.0-beta.1

package/src/adapters/schemas.ts

@@ -55,6 +55,8 @@ export const JobSchema = z.object({
 export const JobStepSchema = z.object({
   id: z.string(),
   jobId: z.string(),
+  parentStepId: z.string().nullable().default(null),
+  parallel: z.boolean().default(false),
   name: z.string(),
   output: z.any().nullable().default(null),
   status: StepStatusSchema,
@@ -113,8 +115,6 @@ export const GetJobsOptionsSchema = z.object({
 
 export const GetJobStepsOptionsSchema = z.object({
   jobId: z.string(),
-  page: z.number().int().positive().optional(),
-  pageSize: z.number().int().positive().optional(),
   search: z.string().optional(),
   updatedAfter: DateSchema.optional(),
 })
@@ -183,6 +183,13 @@ export const DeleteJobOptionsSchema = z.object({
 
 export const DeleteJobsOptionsSchema = GetJobsOptionsSchema.optional()
 
+export const TimeTravelJobOptionsSchema = z.object({
+  /** The ID of the job to time travel */
+  jobId: z.string(),
+  /** The ID of the step to restart from */
+  stepId: z.string(),
+})
+
 // ============================================================================
 // Step Option Schemas
 // ============================================================================
@@ -190,6 +197,10 @@ export const DeleteJobsOptionsSchema = GetJobsOptionsSchema.optional()
 export const CreateOrRecoverJobStepOptionsSchema = z.object({
   /** The ID of the job this step belongs to */
   jobId: z.string(),
+  /** The ID of the parent step (null for root steps) */
+  parentStepId: z.string().nullable().default(null),
+  /** Whether this step runs in parallel (independent from siblings during time travel) */
+  parallel: z.boolean().default(false),
   /** The name of the step */
   name: z.string(),
   /** Timeout in milliseconds for the step */
@@ -258,8 +269,6 @@ export const GetJobsResultSchema = z.object({
 export const GetJobStepsResultSchema = z.object({
   steps: z.array(JobStepWithoutOutputSchema),
   total: z.number().int().nonnegative(),
-  page: z.number().int().positive(),
-  pageSize: z.number().int().positive(),
 })
 
 export const ActionStatsSchema = z.object({
@@ -285,6 +294,63 @@ export const JobStepStatusResultSchema = z.object({
   updatedAt: DateSchema,
 })
 
+// ============================================================================
+// Metrics Schemas
+// ============================================================================
+
+export const MetricTypeSchema = z.enum(['metric', 'span_event', 'span_attribute'])
+
+export const MetricSchema = z.object({
+  id: z.string(),
+  jobId: z.string(),
+  stepId: z.string().nullable(),
+  name: z.string(),
+  value: z.number(),
+  attributes: z.record(z.string(), z.any()),
+  type: MetricTypeSchema,
+  timestamp: DateSchema,
+  createdAt: DateSchema,
+})
+
+export const MetricSortFieldSchema = z.enum(['name', 'value', 'timestamp', 'createdAt'])
+
+export const MetricSortSchema = z.object({
+  field: MetricSortFieldSchema,
+  order: SortOrderSchema,
+})
+
+export const MetricFiltersSchema = z.object({
+  name: z.union([z.string(), z.array(z.string())]).optional(),
+  type: z.union([MetricTypeSchema, z.array(MetricTypeSchema)]).optional(),
+  attributesFilter: z.record(z.string(), z.any()).optional(),
+  timestampRange: z.array(DateSchema).length(2).optional(),
+})
+
+export const InsertMetricOptionsSchema = z.object({
+  jobId: z.string(),
+  stepId: z.string().optional(),
+  name: z.string(),
+  value: z.number(),
+  attributes: z.record(z.string(), z.any()).optional(),
+  type: MetricTypeSchema,
+})
+
+export const GetMetricsOptionsSchema = z.object({
+  jobId: z.string().optional(),
+  stepId: z.string().optional(),
+  filters: MetricFiltersSchema.optional(),
+  sort: MetricSortSchema.optional(),
+})
+
+export const GetMetricsResultSchema = z.object({
+  metrics: z.array(MetricSchema),
+  total: z.number().int().nonnegative(),
+})
+
+export const DeleteMetricsOptionsSchema = z.object({
+  jobId: z.string(),
+})
+
 // ============================================================================
 // Type Exports
 // ============================================================================
@@ -313,9 +379,19 @@ export type CancelJobOptions = z.infer<typeof CancelJobOptionsSchema>
 export type RetryJobOptions = z.infer<typeof RetryJobOptionsSchema>
 export type DeleteJobOptions = z.infer<typeof DeleteJobOptionsSchema>
 export type DeleteJobsOptions = z.infer<typeof DeleteJobsOptionsSchema>
-export type CreateOrRecoverJobStepOptions = z.infer<typeof CreateOrRecoverJobStepOptionsSchema>
+export type CreateOrRecoverJobStepOptions = z.input<typeof CreateOrRecoverJobStepOptionsSchema>
 export type CompleteJobStepOptions = z.infer<typeof CompleteJobStepOptionsSchema>
 export type FailJobStepOptions = z.infer<typeof FailJobStepOptionsSchema>
 export type DelayJobStepOptions = z.infer<typeof DelayJobStepOptionsSchema>
 export type CancelJobStepOptions = z.infer<typeof CancelJobStepOptionsSchema>
 export type CreateOrRecoverJobStepResult = z.infer<typeof CreateOrRecoverJobStepResultSchema>
+export type TimeTravelJobOptions = z.infer<typeof TimeTravelJobOptionsSchema>
+export type MetricType = z.infer<typeof MetricTypeSchema>
+export type Metric = z.infer<typeof MetricSchema>
+export type MetricSortField = z.infer<typeof MetricSortFieldSchema>
+export type MetricSort = z.infer<typeof MetricSortSchema>
+export type MetricFilters = z.infer<typeof MetricFiltersSchema>
+export type InsertMetricOptions = z.infer<typeof InsertMetricOptionsSchema>
+export type GetMetricsOptions = z.infer<typeof GetMetricsOptionsSchema>
+export type GetMetricsResult = z.infer<typeof GetMetricsResultSchema>
+export type DeleteMetricsOptions = z.infer<typeof DeleteMetricsOptionsSchema>

package/src/client.ts

@@ -11,11 +11,14 @@ import type {
   GetJobStepsResult,
   GetJobsOptions,
   GetJobsResult,
+  GetMetricsOptions,
+  GetMetricsResult,
   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'
 
 const BaseOptionsSchema = z.object({
   /**
@@ -136,6 +139,17 @@ export interface ClientOptions<
    * These can be accessed in action handlers using `ctx.var`.
    */
   variables?: TVariables
+
+  /**
+   * Optional telemetry adapter for observability.
+   * When provided, traces job and step execution with spans and allows recording custom metrics.
+   *
+   * Available adapters:
+   * - `openTelemetryAdapter()` - Export traces to external systems (Jaeger, OTLP, etc.)
+   * - `localTelemetryAdapter({ database })` - Store metrics in the Duron database
+   * - `noopTelemetryAdapter()` - No-op adapter (default)
+   */
+  telemetry?: TelemetryAdapter
 }
 
 interface FetchOptions {
@@ -157,6 +171,7 @@ export class Client<
   #id: string
   #actions: TActions | null
   #database: Adapter
+  #telemetry: TelemetryAdapter
   #variables: Record<string, unknown>
   #logger: Logger
   #started: boolean = false
@@ -190,11 +205,14 @@ 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.#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)
   }
 
   #normalizeLogger(logger?: Logger | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'): Logger {
@@ -217,6 +235,28 @@ export class Client<
     return this.#logger
   }
 
+  /**
+   * Get the telemetry adapter instance.
+   */
+  get telemetry(): TelemetryAdapter {
+    return this.#telemetry
+  }
+
+  /**
+   * Get the database adapter instance.
+   */
+  get database(): Adapter {
+    return this.#database
+  }
+
+  /**
+   * Check if local telemetry is enabled.
+   * Returns true if using LocalTelemetryAdapter.
+   */
+  get metricsEnabled(): boolean {
+    return this.#telemetry instanceof LocalTelemetryAdapter
+  }
+
   /**
    * Get the current configuration of this Duron instance.
    *
@@ -361,6 +401,21 @@ export class Client<
     return this.#database.retryJob({ jobId })
   }
 
+  /**
+   * 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 jobId - The ID of the job to time travel
+   * @param stepId - The ID of the step to restart from
+   * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+   */
+  async timeTravelJob(jobId: string, stepId: string): Promise<boolean> {
+    await this.start()
+    return this.#database.timeTravelJob({ jobId, stepId })
+  }
+
   /**
    * Delete a job by its ID.
    * Active jobs cannot be deleted.
@@ -548,6 +603,22 @@ export class Client<
     return this.#database.getActions()
   }
 
+  /**
+   * Get metrics for a job or step.
+   * Only available when using LocalTelemetryAdapter.
+   *
+   * @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
+   */
+  async getMetrics(options: GetMetricsOptions): Promise<GetMetricsResult> {
+    await this.start()
+    if (!this.metricsEnabled) {
+      throw new Error('Metrics are only available when using LocalTelemetryAdapter')
+    }
+    return this.#database.getMetrics(options)
+  }
+
   /**
    * Get action metadata including input schemas and mock data.
    * This is useful for generating UI forms or mock data.
@@ -610,6 +681,9 @@ export class Client<
         return false
       }
 
+      // Start telemetry adapter
+      await this.#telemetry.start()
+
       if (this.#actions) {
         if (this.#options.recoverJobsOnStart) {
           await this.#database.recoverJobs({
@@ -680,6 +754,9 @@ export class Client<
         }),
       )
 
+      // Stop telemetry adapter
+      await this.#telemetry.stop()
+
       const dbStopped = await this.#database.stop()
       if (!dbStopped) {
         return false
@@ -795,6 +872,7 @@ export class Client<
       actionManager = new ActionManager({
         action,
         database: this.#database,
+        telemetry: this.#telemetry,
         variables: this.#variables,
         logger: this.#logger,
         concurrencyLimit: this.#options.actionConcurrencyLimit,

package/src/errors.ts

@@ -126,6 +126,38 @@ export class ActionCancelError extends DuronError {
   }
 }
 
+/**
+ * Error thrown when a parent step completes with unhandled (non-awaited) child steps.
+ *
+ * This error indicates a bug in the action handler where child steps were started
+ * but not properly awaited. All child steps must be awaited before the parent returns.
+ */
+export class UnhandledChildStepsError extends NonRetriableError {
+  /**
+   * The name of the parent step that completed with unhandled children.
+   */
+  public readonly stepName: string
+
+  /**
+   * The number of unhandled child steps.
+   */
+  public readonly pendingCount: number
+
+  /**
+   * Create a new UnhandledChildStepsError.
+   *
+   * @param stepName - The name of the parent step
+   * @param pendingCount - The number of unhandled child steps
+   */
+  constructor(stepName: string, pendingCount: number) {
+    super(
+      `Parent step "${stepName}" completed with ${pendingCount} unhandled child step(s). All child steps must be awaited before the parent returns.`,
+    )
+    this.stepName = stepName
+    this.pendingCount = pendingCount
+  }
+}
+
 /**
  * Checks if an error is a DuronError instance.
  */
@@ -137,7 +169,19 @@ export function isDuronError(error: unknown): error is DuronError {
  * Checks if an error is a NonRetriableError instance.
  */
 export function isNonRetriableError(error: unknown): error is NonRetriableError {
-  return error instanceof NonRetriableError || error instanceof ActionCancelError || error instanceof ActionTimeoutError
+  return (
+    error instanceof NonRetriableError ||
+    error instanceof ActionCancelError ||
+    error instanceof ActionTimeoutError ||
+    error instanceof UnhandledChildStepsError
+  )
+}
+
+/**
+ * Checks if an error is an UnhandledChildStepsError instance.
+ */
+export function isUnhandledChildStepsError(error: unknown): error is UnhandledChildStepsError {
+  return error instanceof UnhandledChildStepsError
 }
 
 /**

package/src/index.ts

@@ -1,10 +1,18 @@
 import type { Action } from './action.js'
 import { Client, type ClientOptions } from './client.js'
 
-export { defineAction } from './action.js'
+export {
+  createStep,
+  defineAction,
+  type StepDefinition,
+  type StepDefinitionHandlerContext,
+  type StepDefinitionInput,
+} from './action.js'
+export * from './client.js'
 export * from './constants.js'
-export { NonRetriableError } from './errors.js'
+export { NonRetriableError, UnhandledChildStepsError } from './errors.js'
 export * from './server.js'
+export * from './telemetry/index.js'
 
 export const duron = <
   TActions extends Record<string, Action<any, any, TVariables>>,

package/src/server.ts

@@ -2,17 +2,20 @@ import { Elysia } from 'elysia'
 import { jwtVerify, SignJWT } from 'jose'
 import { z } from 'zod'
 
-import type { GetJobStepsOptions, GetJobsOptions } from './adapters/adapter.js'
+import type { GetJobStepsOptions, GetJobsOptions, GetMetricsOptions } from './adapters/adapter.js'
 import {
   GetActionsResultSchema,
   GetJobStepsResultSchema,
   GetJobsResultSchema,
+  GetMetricsResultSchema,
   JobSchema,
   JobSortFieldSchema,
   JobStatusResultSchema,
   JobStatusSchema,
   JobStepSchema,
   JobStepStatusResultSchema,
+  MetricSortFieldSchema,
+  MetricTypeSchema,
   SortOrderSchema,
 } from './adapters/schemas.js'
 import type { Client } from './client.js'
@@ -61,14 +64,10 @@ export class UnauthorizedError extends Error {
 
 export const GetJobStepsQuerySchema = z
   .object({
-    page: z.coerce.number().int().min(1).optional(),
-    pageSize: z.coerce.number().int().min(1).max(1000).optional(),
     search: z.string().optional(),
     fUpdatedAfter: z.coerce.date().optional(),
   })
   .transform((data) => ({
-    page: data.page,
-    pageSize: data.pageSize,
     search: data.search,
     updatedAfter: data.fUpdatedAfter,
   }))
@@ -177,6 +176,50 @@ export const GetActionsMetadataResponseSchema = z.array(
 export type GetJobsQueryInput = z.input<typeof GetJobsQuerySchema>
 export type GetJobStepsQueryInput = z.input<typeof GetJobStepsQuerySchema>
 
+// Metrics query schema
+export const GetMetricsQuerySchema = z
+  .object({
+    // Filters
+    fName: z.union([z.string(), z.array(z.string())]).optional(),
+    fType: z.union([MetricTypeSchema, z.array(MetricTypeSchema)]).optional(),
+    fTimestampRange: z.array(z.coerce.date()).length(2).optional(),
+    fAttributesFilter: z.record(z.string(), z.any()).optional(),
+
+    // Sort - format: "field:asc" or "field:desc"
+    sort: z.string().optional(),
+  })
+  .transform((data) => {
+    const filters: any = {}
+
+    if (data.fName) filters.name = data.fName
+    if (data.fType) filters.type = data.fType
+    if (data.fTimestampRange) filters.timestampRange = data.fTimestampRange
+    if (data.fAttributesFilter) filters.attributesFilter = data.fAttributesFilter
+
+    // Parse sort string: "field:asc" -> { field: 'field', order: 'asc' }
+    let sort: { field: z.infer<typeof MetricSortFieldSchema>; order: z.infer<typeof SortOrderSchema> } | undefined
+    if (data.sort) {
+      const [field, order] = data.sort.split(':').map((s) => s.trim())
+      if (field && order) {
+        const fieldResult = MetricSortFieldSchema.safeParse(field)
+        const orderResult = SortOrderSchema.safeParse(order.toLowerCase())
+        if (fieldResult.success && orderResult.success) {
+          sort = {
+            field: fieldResult.data,
+            order: orderResult.data,
+          }
+        }
+      }
+    }
+
+    return {
+      filters: Object.keys(filters).length > 0 ? filters : undefined,
+      sort,
+    }
+  })
+
+export type GetMetricsQueryInput = z.input<typeof GetMetricsQuerySchema>
+
 export const ErrorResponseSchema = z.object({
   error: z.string(),
   message: z.string().optional(),
@@ -201,6 +244,15 @@ export const RetryJobResponseSchema = z.object({
   newJobId: z.string(),
 })
 
+export const TimeTravelJobBodySchema = z.object({
+  stepId: z.uuid(),
+})
+
+export const TimeTravelJobResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string(),
+})
+
 // ============================================================================
 // Server Factory
 // ============================================================================
@@ -216,6 +268,14 @@ export interface CreateServerOptions<P extends string> {
    */
   prefix?: P
 
+  /**
+   * Enable metrics endpoints (/jobs/:id/metrics, /steps/:id/metrics).
+   * Only works when client is configured with LocalTelemetryAdapter.
+   * When true, enables the dashboard to show metrics buttons.
+   * @default auto-detected from client.metricsEnabled
+   */
+  metricsEnabled?: boolean
+
   login?: {
     onLogin: (body: { email: string; password: string }) => Promise<boolean>
     jwtSecret: string | Uint8Array
@@ -237,12 +297,15 @@ export interface CreateServerOptions<P extends string> {
  * @param options - Configuration options
  * @returns Elysia server instance
  */
-export function createServer<P extends string>({ client, prefix, login }: CreateServerOptions<P>) {
+export function createServer<P extends string>({ client, prefix, login, metricsEnabled }: CreateServerOptions<P>) {
   // Convert string secret to Uint8Array if needed
   const secretKey = typeof login?.jwtSecret === 'string' ? new TextEncoder().encode(login?.jwtSecret) : login?.jwtSecret
 
   const routePrefix = (prefix ?? '/api') as P
 
+  // Auto-detect metricsEnabled from client if not explicitly set
+  const isMetricsEnabled = metricsEnabled ?? client.metricsEnabled
+
   return new Elysia({
     prefix: routePrefix,
   })
@@ -345,8 +408,6 @@ export function createServer<P extends string>({ client, prefix, login }: Create
       async ({ params, query }) => {
         const options: GetJobStepsOptions = {
           jobId: params.id,
-          page: query.page,
-          pageSize: query.pageSize,
           search: query.search,
           updatedAfter: query.updatedAfter,
         }
@@ -490,6 +551,32 @@ export function createServer<P extends string>({ client, prefix, login }: Create
         auth: true,
       },
     )
+    .post(
+      '/jobs/:id/time-travel',
+      async ({ params, body }) => {
+        const success = await client.timeTravelJob(params.id, body.stepId)
+        if (!success) {
+          throw new Error(
+            `Could not time travel job ${params.id}. The job may not be in a terminal state or the step may not exist.`,
+          )
+        }
+        return {
+          success: true,
+          message: `Job ${params.id} has been time traveled to step ${body.stepId}`,
+        }
+      },
+      {
+        params: JobIdParamsSchema,
+        body: TimeTravelJobBodySchema,
+        response: {
+          200: TimeTravelJobResponseSchema,
+          400: ErrorResponseSchema,
+          500: ErrorResponseSchema,
+          401: ErrorResponseSchema,
+        },
+        auth: true,
+      },
+    )
     .delete(
       '/jobs/:id',
       async ({ params }) => {
@@ -579,6 +666,74 @@ export function createServer<P extends string>({ client, prefix, login }: Create
         auth: true,
       },
     )
+    .get(
+      '/config',
+      async () => {
+        return {
+          metricsEnabled: isMetricsEnabled,
+          authEnabled: !!login,
+        }
+      },
+      {
+        response: {
+          200: z.object({
+            metricsEnabled: z.boolean(),
+            authEnabled: z.boolean(),
+          }),
+          500: ErrorResponseSchema,
+        },
+      },
+    )
+    .get(
+      '/jobs/:id/metrics',
+      async ({ params, query }) => {
+        if (!isMetricsEnabled) {
+          throw new Error('Metrics are not enabled. Use LocalTelemetryAdapter to enable metrics.')
+        }
+        const options: GetMetricsOptions = {
+          jobId: params.id,
+          filters: query.filters,
+          sort: query.sort,
+        }
+        return client.getMetrics(options)
+      },
+      {
+        params: JobIdParamsSchema,
+        query: GetMetricsQuerySchema,
+        response: {
+          200: GetMetricsResultSchema,
+          400: ErrorResponseSchema,
+          500: ErrorResponseSchema,
+          401: ErrorResponseSchema,
+        },
+        auth: true,
+      },
+    )
+    .get(
+      '/steps/:id/metrics',
+      async ({ params, query }) => {
+        if (!isMetricsEnabled) {
+          throw new Error('Metrics are not enabled. Use LocalTelemetryAdapter to enable metrics.')
+        }
+        const options: GetMetricsOptions = {
+          stepId: params.id,
+          filters: query.filters,
+          sort: query.sort,
+        }
+        return client.getMetrics(options)
+      },
+      {
+        params: StepIdParamsSchema,
+        query: GetMetricsQuerySchema,
+        response: {
+          200: GetMetricsResultSchema,
+          400: ErrorResponseSchema,
+          500: ErrorResponseSchema,
+          401: ErrorResponseSchema,
+        },
+        auth: true,
+      },
+    )
     .post(
       '/actions/:actionName/run',
       async ({ params, body }) => {