duron 0.3.0-beta.8 → 0.3.0

package/src/errors.ts

@@ -1,8 +1,42 @@
+// Error codes for type checking without instanceof
+export const ERROR_CODES = {
+  DURON_ERROR: 'DURON_ERROR',
+  STEP_ALREADY_EXECUTED: 'STEP_ALREADY_EXECUTED',
+  NON_RETRIABLE: 'NON_RETRIABLE',
+  ACTION_TIMEOUT: 'ACTION_TIMEOUT',
+  STEP_TIMEOUT: 'STEP_TIMEOUT',
+  ACTION_CANCEL: 'ACTION_CANCEL',
+  UNHANDLED_CHILD_STEPS: 'UNHANDLED_CHILD_STEPS',
+} as const
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES]
+
+/**
+ * Metadata about the context where an error occurred.
+ */
+export interface ErrorMetadata {
+  jobId?: string
+  stepId?: string
+  parentStepId?: string | null
+  actionName?: string
+  stepName?: string
+}
+
 /**
  * Base class for all built-in errors in Duron.
  * All errors include a cause property that can be serialized.
  */
 export abstract class DuronError extends Error {
+  /**
+   * Error code for type checking without instanceof.
+   */
+  public readonly code: ErrorCode = ERROR_CODES.DURON_ERROR
+
+  /**
+   * Whether this error should prevent retries.
+   */
+  public readonly nonRetriable: boolean = false
+
   /**
    * The underlying cause of the error, if any.
    *
@@ -10,6 +44,11 @@ export abstract class DuronError extends Error {
    */
   public override readonly cause?: unknown
 
+  /**
+   * Metadata about the context where the error occurred.
+   */
+  public metadata: ErrorMetadata
+
   constructor(
     message: string,
     options?: {
@@ -19,10 +58,15 @@ export abstract class DuronError extends Error {
        * This will be serialized and stored in the database.
        */
       cause?: unknown
+      /**
+       * Metadata about the context where the error occurred.
+       */
+      metadata?: ErrorMetadata
     },
   ) {
     super(message)
     this.cause = options?.cause
+    this.metadata = options?.metadata ?? {}
     // Set the name to the class name
     this.name = this.constructor.name
     // Ensure stack trace points to the error location
@@ -30,12 +74,27 @@ export abstract class DuronError extends Error {
       Error.captureStackTrace(this, this.constructor)
     }
   }
+
+  /**
+   * Set or update metadata about the context where the error occurred.
+   * Merges with existing metadata (new values override existing ones).
+   *
+   * @param metadata - The metadata to set or merge
+   * @returns this - Returns the error instance for chaining
+   */
+  setMetadata(metadata: ErrorMetadata): this {
+    this.metadata = { ...this.metadata, ...metadata }
+    return this
+  }
 }
 
 /**
  * Error thrown when attempting to execute a step that has already been executed.
  */
 export class StepAlreadyExecutedError extends DuronError {
+  public override readonly code = ERROR_CODES.STEP_ALREADY_EXECUTED
+  public override readonly nonRetriable = true
+
   /**
    * Create a new StepAlreadyExecutedError.
    *
@@ -44,7 +103,9 @@ export class StepAlreadyExecutedError extends DuronError {
    * @param actionName - The name of the action containing the step
    */
   constructor(stepName: string, jobId: string, actionName: string) {
-    super(`Step "${stepName}" has already been executed for job "${jobId}" and action "${actionName}"`)
+    super(`Step "${stepName}" has already been executed for job "${jobId}" and action "${actionName}"`, {
+      metadata: { stepName, jobId, actionName },
+    })
   }
 }
 
@@ -55,28 +116,37 @@ export class StepAlreadyExecutedError extends DuronError {
  * without retrying, even if retry options are configured.
  */
 export class NonRetriableError extends DuronError {
-  // Constructor inherited from DuronError
+  public override readonly code: ErrorCode = ERROR_CODES.NON_RETRIABLE
+  public override readonly nonRetriable = true
 }
 
 /**
  * Error thrown when an action exceeds its timeout.
  */
 export class ActionTimeoutError extends DuronError {
+  public override readonly code = ERROR_CODES.ACTION_TIMEOUT
+  public override readonly nonRetriable = true
+
   /**
    * Create a new ActionTimeoutError.
    *
    * @param actionName - The name of the action that timed out
+   * @param jobId - The ID of the job containing the action
    * @param timeoutMs - The timeout value in milliseconds
    * @param options - Optional error options including cause
    */
   constructor(
     actionName: string,
+    jobId: string,
     timeoutMs: number,
     options?: {
       cause?: unknown
     },
   ) {
-    super(`Action "${actionName}" timed out after ${timeoutMs}ms`, options)
+    super(`Action "${actionName}" in job "${jobId}" timed out after ${timeoutMs}ms`, {
+      cause: options?.cause,
+      metadata: { actionName, jobId },
+    })
   }
 }
 
@@ -84,13 +154,16 @@ export class ActionTimeoutError extends DuronError {
  * Error thrown when a step exceeds its timeout.
  */
 export class StepTimeoutError extends DuronError {
+  public override readonly code = ERROR_CODES.STEP_TIMEOUT
+  public override readonly nonRetriable = false
+
   /**
    * Create a new StepTimeoutError.
    *
    * @param stepName - The name of the step that timed out
    * @param jobId - The ID of the job containing the step
    * @param timeoutMs - The timeout value in milliseconds
-   * @param options - Optional error options including cause
+   * @param options - Optional error options including cause and additional metadata
    */
   constructor(
     stepName: string,
@@ -98,9 +171,21 @@ export class StepTimeoutError extends DuronError {
     timeoutMs: number,
     options?: {
       cause?: unknown
+      stepId?: string
+      parentStepId?: string | null
+      actionName?: string
     },
   ) {
-    super(`Step "${stepName}" in job "${jobId}" timed out after ${timeoutMs}ms`, options)
+    super(`Step "${stepName}" in job "${jobId}" timed out after ${timeoutMs}ms`, {
+      cause: options?.cause,
+      metadata: {
+        stepName,
+        jobId,
+        stepId: options?.stepId,
+        parentStepId: options?.parentStepId,
+        actionName: options?.actionName,
+      },
+    })
   }
 }
 
@@ -108,6 +193,9 @@ export class StepTimeoutError extends DuronError {
  * Error thrown when an action is cancelled.
  */
 export class ActionCancelError extends DuronError {
+  public override readonly code = ERROR_CODES.ACTION_CANCEL
+  public override readonly nonRetriable = true
+
   /**
    * Create a new ActionCancelError.
    *
@@ -122,7 +210,10 @@ export class ActionCancelError extends DuronError {
       cause?: unknown
     },
   ) {
-    super(`Action "${actionName}" in job "${jobId}" was cancelled`, options)
+    super(`Action "${actionName}" in job "${jobId}" was cancelled`, {
+      cause: options?.cause,
+      metadata: { actionName, jobId },
+    })
   }
 }
 
@@ -133,10 +224,7 @@ export class ActionCancelError extends DuronError {
  * 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
+  public override readonly code = ERROR_CODES.UNHANDLED_CHILD_STEPS
 
   /**
    * The number of unhandled child steps.
@@ -148,12 +236,30 @@ export class UnhandledChildStepsError extends NonRetriableError {
    *
    * @param stepName - The name of the parent step
    * @param pendingCount - The number of unhandled child steps
+   * @param options - Optional metadata
    */
-  constructor(stepName: string, pendingCount: number) {
+  constructor(
+    stepName: string,
+    pendingCount: number,
+    options?: {
+      stepId?: string
+      parentStepId?: string | null
+      jobId?: string
+      actionName?: string
+    },
+  ) {
     super(
       `Parent step "${stepName}" completed with ${pendingCount} unhandled child step(s). All child steps must be awaited before the parent returns.`,
+      {
+        metadata: {
+          stepName,
+          stepId: options?.stepId,
+          parentStepId: options?.parentStepId,
+          jobId: options?.jobId,
+          actionName: options?.actionName,
+        },
+      },
     )
-    this.stepName = stepName
     this.pendingCount = pendingCount
   }
 }
@@ -162,45 +268,45 @@ export class UnhandledChildStepsError extends NonRetriableError {
  * Checks if an error is a DuronError instance.
  */
 export function isDuronError(error: unknown): error is DuronError {
-  return error instanceof DuronError
+  const code = (error as any)?.code
+  return code !== undefined && Object.values(ERROR_CODES).includes(code)
 }
 
 /**
  * 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 ||
-    error instanceof UnhandledChildStepsError
-  )
+  return (error as any)?.nonRetriable === true
 }
 
 /**
  * Checks if an error is an UnhandledChildStepsError instance.
  */
 export function isUnhandledChildStepsError(error: unknown): error is UnhandledChildStepsError {
-  return error instanceof UnhandledChildStepsError
+  return (error as any)?.code === ERROR_CODES.UNHANDLED_CHILD_STEPS
 }
 
 /**
  * Checks if an error is a timeout error (ActionTimeoutError or StepTimeoutError).
  */
 export function isTimeoutError(error: unknown): error is ActionTimeoutError | StepTimeoutError {
-  return error instanceof ActionTimeoutError || error instanceof StepTimeoutError
+  const code = (error as any)?.code
+  return code === ERROR_CODES.ACTION_TIMEOUT || code === ERROR_CODES.STEP_TIMEOUT
 }
 
 /**
  * Checks if an error is a cancel error (ActionCancelError or StepCancelError).
  */
 export function isCancelError(error: unknown): error is ActionCancelError {
-  return error instanceof ActionCancelError
+  return (error as any)?.code === ERROR_CODES.ACTION_CANCEL
 }
 
 export type SerializableError = {
   name: string
   message: string
+  code?: ErrorCode
+  nonRetriable?: boolean
+  metadata?: ErrorMetadata
   cause?: unknown
   stack?: string
 }
@@ -209,25 +315,30 @@ export type SerializableError = {
  * Serializes an error for storage in the database.
  * Handles DuronError instances specially to preserve their type information.
  */
-export function serializeError(error: unknown): {
-  name: string
-  message: string
-  cause?: unknown
-  stack?: string
-} {
-  if (error instanceof StepTimeoutError || error instanceof ActionTimeoutError) {
+export function serializeError(error: unknown): SerializableError {
+  const code = (error as any)?.code
+  const nonRetriable = (error as any)?.nonRetriable
+  const metadata = (error as any)?.metadata
+
+  if (isTimeoutError(error)) {
     return {
       name: error.name,
       message: error.message,
+      code,
+      nonRetriable,
+      metadata,
       cause: error.cause,
       stack: undefined,
     }
   }
 
-  if (error instanceof DuronError) {
+  if (isDuronError(error)) {
     return {
       name: error.name,
       message: error.message,
+      code,
+      nonRetriable,
+      metadata,
       cause: error.cause,
       stack: error.stack,
     }

package/src/index.ts

@@ -7,11 +7,13 @@ export {
   type StepDefinition,
   type StepDefinitionHandlerContext,
   type StepDefinitionInput,
+  type StepNameContext,
 } from './action.js'
 export * from './client.js'
 export * from './constants.js'
 export { NonRetriableError, UnhandledChildStepsError } from './errors.js'
 export * from './server.js'
+export type { TelemetryContext } from './step-manager.js'
 export * from './telemetry/index.js'
 
 export const duron = <

package/src/server.ts

@@ -2,21 +2,21 @@ import { Elysia } from 'elysia'
 import { jwtVerify, SignJWT } from 'jose'
 import { z } from 'zod'
 
-import type { GetJobStepsOptions, GetJobsOptions, GetMetricsOptions } from './adapters/adapter.js'
+import type { GetJobStepsOptions, GetJobsOptions, GetSpansOptions } from './adapters/adapter.js'
 import {
   GetActionsResultSchema,
   GetJobStepsResultSchema,
   GetJobsResultSchema,
-  GetMetricsResultSchema,
+  GetSpansResultSchema,
   JobSchema,
   JobSortFieldSchema,
   JobStatusResultSchema,
   JobStatusSchema,
   JobStepSchema,
   JobStepStatusResultSchema,
-  MetricSortFieldSchema,
-  MetricTypeSchema,
   SortOrderSchema,
+  SpanKindSchema,
+  SpanSortFieldSchema,
 } from './adapters/schemas.js'
 import type { Client } from './client.js'
 
@@ -86,6 +86,7 @@ export const GetJobsQuerySchema = z
     fActionName: z.union([z.string(), z.array(z.string())]).optional(),
     fGroupKey: z.union([z.string(), z.array(z.string())]).optional(),
     fClientId: z.union([z.string(), z.array(z.string())]).optional(),
+    fDescription: z.string().optional(),
     // Date filters: can be a single ISO string or JSON array [start, end] - both coerced to Date objects
     fCreatedAt: z.union([z.coerce.date(), z.array(z.coerce.date())]).optional(),
     fStartedAt: z.union([z.coerce.date(), z.array(z.coerce.date())]).optional(),
@@ -107,6 +108,7 @@ export const GetJobsQuerySchema = z
     if (data.fActionName) filters.actionName = data.fActionName
     if (data.fGroupKey) filters.groupKey = data.fGroupKey
     if (data.fClientId) filters.clientId = data.fClientId
+    if (data.fDescription) filters.description = data.fDescription
     if (data.fCreatedAt) filters.createdAt = data.fCreatedAt
     if (data.fStartedAt) filters.startedAt = data.fStartedAt
     if (data.fFinishedAt) filters.finishedAt = data.fFinishedAt
@@ -176,13 +178,13 @@ 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
+// Spans query schema
+export const GetSpansQuerySchema = 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(),
+    fKind: z.union([SpanKindSchema, z.array(SpanKindSchema)]).optional(),
+    fTraceId: z.string().optional(),
     fAttributesFilter: z.record(z.string(), z.any()).optional(),
 
     // Sort - format: "field:asc" or "field:desc"
@@ -192,16 +194,16 @@ export const GetMetricsQuerySchema = z
     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.fKind) filters.kind = data.fKind
+    if (data.fTraceId) filters.traceId = data.fTraceId
     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
+    let sort: { field: z.infer<typeof SpanSortFieldSchema>; 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 fieldResult = SpanSortFieldSchema.safeParse(field)
         const orderResult = SortOrderSchema.safeParse(order.toLowerCase())
         if (fieldResult.success && orderResult.success) {
           sort = {
@@ -218,7 +220,7 @@ export const GetMetricsQuerySchema = z
     }
   })
 
-export type GetMetricsQueryInput = z.input<typeof GetMetricsQuerySchema>
+export type GetSpansQueryInput = z.input<typeof GetSpansQuerySchema>
 
 export const ErrorResponseSchema = z.object({
   error: z.string(),
@@ -269,12 +271,12 @@ 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
+   * Enable spans endpoints (/jobs/:id/spans, /steps/:id/spans).
+   * Only works when client is configured with telemetry.local enabled.
+   * When true, enables the dashboard to show spans buttons.
+   * @default auto-detected from client.spansEnabled
    */
-  metricsEnabled?: boolean
+  spansEnabled?: boolean
 
   login?: {
     onLogin: (body: { email: string; password: string }) => Promise<boolean>
@@ -297,14 +299,14 @@ export interface CreateServerOptions<P extends string> {
  * @param options - Configuration options
  * @returns Elysia server instance
  */
-export function createServer<P extends string>({ client, prefix, login, metricsEnabled }: CreateServerOptions<P>) {
+export function createServer<P extends string>({ client, prefix, login, spansEnabled }: 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
+  // Auto-detect spansEnabled from client if not explicitly set
+  const isSpansEnabled = spansEnabled ?? client.spansEnabled
 
   return new Elysia({
     prefix: routePrefix,
@@ -670,14 +672,14 @@ export function createServer<P extends string>({ client, prefix, login, metricsE
       '/config',
       async () => {
         return {
-          metricsEnabled: isMetricsEnabled,
+          spansEnabled: isSpansEnabled,
           authEnabled: !!login,
         }
       },
       {
         response: {
           200: z.object({
-            metricsEnabled: z.boolean(),
+            spansEnabled: z.boolean(),
             authEnabled: z.boolean(),
           }),
           500: ErrorResponseSchema,
@@ -685,23 +687,23 @@ export function createServer<P extends string>({ client, prefix, login, metricsE
       },
     )
     .get(
-      '/jobs/:id/metrics',
+      '/jobs/:id/spans',
       async ({ params, query }) => {
-        if (!isMetricsEnabled) {
-          throw new Error('Metrics are not enabled. Use LocalTelemetryAdapter to enable metrics.')
+        if (!isSpansEnabled) {
+          throw new Error('Spans are not enabled. Enable telemetry.local to enable spans.')
         }
-        const options: GetMetricsOptions = {
+        const options: GetSpansOptions = {
           jobId: params.id,
           filters: query.filters,
           sort: query.sort,
         }
-        return client.getMetrics(options)
+        return client.getSpans(options)
       },
       {
         params: JobIdParamsSchema,
-        query: GetMetricsQuerySchema,
+        query: GetSpansQuerySchema,
         response: {
-          200: GetMetricsResultSchema,
+          200: GetSpansResultSchema,
           400: ErrorResponseSchema,
           500: ErrorResponseSchema,
           401: ErrorResponseSchema,
@@ -710,23 +712,23 @@ export function createServer<P extends string>({ client, prefix, login, metricsE
       },
     )
     .get(
-      '/steps/:id/metrics',
+      '/steps/:id/spans',
       async ({ params, query }) => {
-        if (!isMetricsEnabled) {
-          throw new Error('Metrics are not enabled. Use LocalTelemetryAdapter to enable metrics.')
+        if (!isSpansEnabled) {
+          throw new Error('Spans are not enabled. Enable telemetry.local to enable spans.')
         }
-        const options: GetMetricsOptions = {
+        const options: GetSpansOptions = {
           stepId: params.id,
           filters: query.filters,
           sort: query.sort,
         }
-        return client.getMetrics(options)
+        return client.getSpans(options)
       },
       {
         params: StepIdParamsSchema,
-        query: GetMetricsQuerySchema,
+        query: GetSpansQuerySchema,
         response: {
-          200: GetMetricsResultSchema,
+          200: GetSpansResultSchema,
           400: ErrorResponseSchema,
           500: ErrorResponseSchema,
           401: ErrorResponseSchema,