duron 0.3.0-beta.8 → 0.3.0

package/src/adapters/postgres/base.ts

@@ -24,7 +24,7 @@ import {
   type DelayJobStepOptions,
   type DeleteJobOptions,
   type DeleteJobsOptions,
-  type DeleteMetricsOptions,
+  type DeleteSpansOptions,
   type FailJobOptions,
   type FailJobStepOptions,
   type FetchOptions,
@@ -33,17 +33,17 @@ import {
   type GetJobStepsResult,
   type GetJobsOptions,
   type GetJobsResult,
-  type GetMetricsOptions,
-  type GetMetricsResult,
-  type InsertMetricOptions,
+  type GetSpansOptions,
+  type GetSpansResult,
+  type InsertSpanOptions,
   type Job,
   type JobSort,
   type JobStatusResult,
   type JobStep,
   type JobStepStatusResult,
-  type MetricSort,
   type RecoverJobsOptions,
   type RetryJobOptions,
+  type SpanSort,
   type TimeTravelJobOptions,
 } from '../adapter.js'
 import createSchema from './schema.js'
@@ -141,17 +141,28 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
    *
    * @returns Promise resolving to the job ID, or `null` if creation failed
    */
-  protected async _createJob({ queue, groupKey, input, timeoutMs, checksum, concurrencyLimit }: CreateJobOptions) {
+  protected async _createJob({
+    queue,
+    groupKey,
+    input,
+    timeoutMs,
+    checksum,
+    concurrencyLimit,
+    concurrencyStepLimit,
+    description,
+  }: CreateJobOptions) {
     const [result] = await this.db
       .insert(this.tables.jobsTable)
       .values({
         action_name: queue,
         group_key: groupKey,
+        description: description ?? null,
         checksum,
         input,
         status: JOB_STATUS_CREATED,
         timeout_ms: timeoutMs,
         concurrency_limit: concurrencyLimit,
+        concurrency_step_limit: concurrencyStepLimit,
       })
       .returning({ id: this.tables.jobsTable.id })
 
@@ -254,11 +265,13 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         SELECT
           j.action_name,
           j.group_key,
+          j.description,
           j.checksum,
           j.input,
           j.timeout_ms,
           j.created_at,
-          j.concurrency_limit
+          j.concurrency_limit,
+          j.concurrency_step_limit
         FROM ${this.tables.jobsTable} j
         WHERE j.id = ${jobId}
           AND j.status IN (${JOB_STATUS_COMPLETED}, ${JOB_STATUS_CANCELLED}, ${JOB_STATUS_FAILED})
@@ -283,15 +296,18 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         INSERT INTO ${this.tables.jobsTable} (
           action_name,
           group_key,
+          description,
           checksum,
           input,
           status,
           timeout_ms,
-          concurrency_limit
+          concurrency_limit,
+          concurrency_step_limit
         )
         SELECT
           ls.action_name,
           ls.group_key,
+          ls.description,
           ls.checksum,
           ls.input,
           ${JOB_STATUS_CREATED},
@@ -307,7 +323,8 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
               LIMIT 1
             ),
             ls.concurrency_limit
-          )
+          ),
+          ls.concurrency_step_limit
         FROM locked_source ls
         WHERE NOT EXISTS (SELECT 1 FROM existing_retry)
         RETURNING id
@@ -657,6 +674,7 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         j.id,
         j.action_name as "actionName",
         j.group_key as "groupKey",
+        j.description,
         j.input,
         j.output,
         j.error,
@@ -667,7 +685,8 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         j.finished_at as "finishedAt",
         j.created_at as "createdAt",
         j.updated_at as "updatedAt",
-        j.concurrency_limit as "concurrencyLimit"
+        j.concurrency_limit as "concurrencyLimit",
+        j.concurrency_step_limit as "concurrencyStepLimit"
     `),
     )
 
@@ -788,7 +807,7 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
       step_existed AS (
         SELECT EXISTS(
           SELECT 1 FROM ${this.tables.jobStepsTable} s
-          WHERE s.job_id = ${jobId} 
+          WHERE s.job_id = ${jobId}
             AND s.name = ${name}
             AND s.parent_step_id IS NOT DISTINCT FROM ${parentStepId}
         ) AS existed
@@ -1011,26 +1030,40 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
    * Internal method to get a job by its ID. Does not include step information.
    */
   protected async _getJobById(jobId: string): Promise<Job | null> {
+    const jobsTable = this.tables.jobsTable
+
+    // Calculate duration as a SQL expression (finishedAt - startedAt in milliseconds)
+    const durationMs = sql<number | null>`
+      CASE
+        WHEN ${jobsTable.started_at} IS NOT NULL AND ${jobsTable.finished_at} IS NOT NULL
+        THEN EXTRACT(EPOCH FROM (${jobsTable.finished_at} - ${jobsTable.started_at})) * 1000
+        ELSE NULL
+      END
+    `.as('duration_ms')
+
     const [job] = await this.db
       .select({
-        id: this.tables.jobsTable.id,
-        actionName: this.tables.jobsTable.action_name,
-        groupKey: this.tables.jobsTable.group_key,
-        input: this.tables.jobsTable.input,
-        output: this.tables.jobsTable.output,
-        error: this.tables.jobsTable.error,
-        status: this.tables.jobsTable.status,
-        timeoutMs: this.tables.jobsTable.timeout_ms,
-        expiresAt: this.tables.jobsTable.expires_at,
-        startedAt: this.tables.jobsTable.started_at,
-        finishedAt: this.tables.jobsTable.finished_at,
-        createdAt: this.tables.jobsTable.created_at,
-        updatedAt: this.tables.jobsTable.updated_at,
-        concurrencyLimit: this.tables.jobsTable.concurrency_limit,
-        clientId: this.tables.jobsTable.client_id,
+        id: jobsTable.id,
+        actionName: jobsTable.action_name,
+        groupKey: jobsTable.group_key,
+        description: jobsTable.description,
+        input: jobsTable.input,
+        output: jobsTable.output,
+        error: jobsTable.error,
+        status: jobsTable.status,
+        timeoutMs: jobsTable.timeout_ms,
+        expiresAt: jobsTable.expires_at,
+        startedAt: jobsTable.started_at,
+        finishedAt: jobsTable.finished_at,
+        createdAt: jobsTable.created_at,
+        updatedAt: jobsTable.updated_at,
+        concurrencyLimit: jobsTable.concurrency_limit,
+        concurrencyStepLimit: jobsTable.concurrency_step_limit,
+        clientId: jobsTable.client_id,
+        durationMs,
       })
-      .from(this.tables.jobsTable)
-      .where(eq(this.tables.jobsTable.id, jobId))
+      .from(jobsTable)
+      .where(eq(jobsTable.id, jobId))
       .limit(1)
 
     return job ?? null
@@ -1117,6 +1150,7 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
       filters.clientId
         ? inArray(jobsTable.client_id, Array.isArray(filters.clientId) ? filters.clientId : [filters.clientId])
         : undefined,
+      filters.description ? ilike(jobsTable.description, `%${filters.description}%`) : undefined,
       filters.createdAt && Array.isArray(filters.createdAt)
         ? between(
             sql`date_trunc('second', ${jobsTable.created_at})`,
@@ -1154,6 +1188,7 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         ? or(
             ilike(jobsTable.action_name, `%${fuzzySearch}%`),
             ilike(jobsTable.group_key, `%${fuzzySearch}%`),
+            ilike(jobsTable.description, `%${fuzzySearch}%`),
             ilike(jobsTable.client_id, `%${fuzzySearch}%`),
             sql`${jobsTable.id}::text ilike ${`%${fuzzySearch}%`}`,
             sql`to_tsvector('english', ${jobsTable.input}::text) @@ plainto_tsquery('english', ${fuzzySearch})`,
@@ -1194,6 +1229,15 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
       }
     }
 
+    // Calculate duration as a SQL expression (finishedAt - startedAt in milliseconds)
+    const durationMs = sql<number | null>`
+      CASE
+        WHEN ${jobsTable.started_at} IS NOT NULL AND ${jobsTable.finished_at} IS NOT NULL
+        THEN EXTRACT(EPOCH FROM (${jobsTable.finished_at} - ${jobsTable.started_at})) * 1000
+        ELSE NULL
+      END
+    `.as('duration_ms')
+
     const sortFieldMap: Record<JobSort['field'], any> = {
       createdAt: jobsTable.created_at,
       startedAt: jobsTable.started_at,
@@ -1201,6 +1245,8 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
       status: jobsTable.status,
       actionName: jobsTable.action_name,
       expiresAt: jobsTable.expires_at,
+      duration: durationMs,
+      description: jobsTable.description,
     }
 
     const jobs = await this.db
@@ -1208,6 +1254,7 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         id: jobsTable.id,
         actionName: jobsTable.action_name,
         groupKey: jobsTable.group_key,
+        description: jobsTable.description,
         input: jobsTable.input,
         output: jobsTable.output,
         error: jobsTable.error,
@@ -1219,7 +1266,9 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
         createdAt: jobsTable.created_at,
         updatedAt: jobsTable.updated_at,
         concurrencyLimit: jobsTable.concurrency_limit,
+        concurrencyStepLimit: jobsTable.concurrency_step_limit,
         clientId: jobsTable.client_id,
+        durationMs,
       })
       .from(jobsTable)
       .where(where)
@@ -1362,117 +1411,248 @@ export class PostgresBaseAdapter<Database extends DrizzleDatabase, Connection> e
   // ============================================================================
 
   /**
-   * Internal method to insert multiple metric records in a single batch.
+   * Internal method to insert multiple span records in a single batch.
    */
-  protected async _insertMetrics(metrics: InsertMetricOptions[]): Promise<number> {
-    if (metrics.length === 0) {
+  protected async _insertSpans(spans: InsertSpanOptions[]): Promise<number> {
+    if (spans.length === 0) {
       return 0
     }
 
-    const values = metrics.map((m) => ({
-      job_id: m.jobId,
-      step_id: m.stepId ?? null,
-      name: m.name,
-      value: m.value,
-      attributes: m.attributes ?? {},
-      type: m.type,
+    const values = spans.map((s) => ({
+      trace_id: s.traceId,
+      span_id: s.spanId,
+      parent_span_id: s.parentSpanId,
+      job_id: s.jobId,
+      step_id: s.stepId,
+      name: s.name,
+      kind: s.kind,
+      start_time_unix_nano: s.startTimeUnixNano,
+      end_time_unix_nano: s.endTimeUnixNano,
+      status_code: s.statusCode,
+      status_message: s.statusMessage,
+      attributes: s.attributes ?? {},
+      events: s.events ?? [],
     }))
 
     const result = await this.db
-      .insert(this.tables.metricsTable)
+      .insert(this.tables.spansTable)
       .values(values)
-      .returning({ id: this.tables.metricsTable.id })
+      .returning({ id: this.tables.spansTable.id })
 
     return result.length
   }
 
   /**
-   * Internal method to get metrics for a job or step.
+   * Internal method to get spans for a job or step.
+   * For step queries, uses a recursive CTE to find all descendant spans.
    */
-  protected async _getMetrics(options: GetMetricsOptions): Promise<GetMetricsResult> {
-    const metricsTable = this.tables.metricsTable
+  protected async _getSpans(options: GetSpansOptions): Promise<GetSpansResult> {
+    const spansTable = this.tables.spansTable
     const filters = options.filters ?? {}
 
-    // Build WHERE clause
-    const where = this._buildMetricsWhereClause(options.jobId, options.stepId, filters)
-
     // Build sort
-    const sortInput = options.sort ?? { field: 'timestamp', order: 'desc' }
-    const sortFieldMap: Record<MetricSort['field'], any> = {
-      name: metricsTable.name,
-      value: metricsTable.value,
-      timestamp: metricsTable.timestamp,
-      createdAt: metricsTable.created_at,
+    const sortInput = options.sort ?? { field: 'startTimeUnixNano', order: 'asc' }
+    const sortFieldMap: Record<SpanSort['field'], string> = {
+      name: 'name',
+      startTimeUnixNano: 'start_time_unix_nano',
+      endTimeUnixNano: 'end_time_unix_nano',
+    }
+    const sortField = sortFieldMap[sortInput.field]
+    const sortOrder = sortInput.order === 'asc' ? 'ASC' : 'DESC'
+
+    // For step queries, use a recursive CTE to get descendant spans
+    if (options.stepId) {
+      return this._getStepSpansRecursive(options.stepId, sortField, sortOrder, filters)
     }
 
+    // Build WHERE clause for job queries
+    const where = this._buildSpansWhereClause(options.jobId, undefined, filters)
+
     // Get total count
-    const total = await this.db.$count(metricsTable, where)
+    const total = await this.db.$count(spansTable, where)
     if (!total) {
       return {
-        metrics: [],
+        spans: [],
         total: 0,
       }
     }
 
-    const sortField = sortFieldMap[sortInput.field]
-    const orderByClause = sortInput.order === 'asc' ? asc(sortField) : desc(sortField)
+    const sortFieldColumn = sortFieldMap[sortInput.field]
+    const orderByClause =
+      sortInput.order === 'asc'
+        ? asc(spansTable[sortFieldColumn as keyof typeof spansTable] as any)
+        : desc(spansTable[sortFieldColumn as keyof typeof spansTable] as any)
 
-    const metrics = await this.db
+    const rows = await this.db
       .select({
-        id: metricsTable.id,
-        jobId: metricsTable.job_id,
-        stepId: metricsTable.step_id,
-        name: metricsTable.name,
-        value: metricsTable.value,
-        attributes: metricsTable.attributes,
-        type: metricsTable.type,
-        timestamp: metricsTable.timestamp,
-        createdAt: metricsTable.created_at,
+        id: spansTable.id,
+        traceId: spansTable.trace_id,
+        spanId: spansTable.span_id,
+        parentSpanId: spansTable.parent_span_id,
+        jobId: spansTable.job_id,
+        stepId: spansTable.step_id,
+        name: spansTable.name,
+        kind: spansTable.kind,
+        startTimeUnixNano: spansTable.start_time_unix_nano,
+        endTimeUnixNano: spansTable.end_time_unix_nano,
+        statusCode: spansTable.status_code,
+        statusMessage: spansTable.status_message,
+        attributes: spansTable.attributes,
+        events: spansTable.events,
       })
-      .from(metricsTable)
+      .from(spansTable)
       .where(where)
       .orderBy(orderByClause)
 
+    // Cast kind and statusCode to proper types, convert BigInt to string for JSON serialization
+    const spans = rows.map((row) => ({
+      ...row,
+      kind: row.kind as 0 | 1 | 2 | 3 | 4,
+      statusCode: row.statusCode as 0 | 1 | 2,
+      // Convert BigInt to string for JSON serialization
+      startTimeUnixNano: row.startTimeUnixNano?.toString() ?? null,
+      endTimeUnixNano: row.endTimeUnixNano?.toString() ?? null,
+    }))
+
     return {
-      metrics,
+      spans,
       total,
     }
   }
 
   /**
-   * Internal method to delete all metrics for a job.
+   * Get spans for a step using a recursive CTE to traverse the span hierarchy.
+   * This returns the step's span and all its descendant spans (children, grandchildren, etc.)
+   */
+  protected async _getStepSpansRecursive(
+    stepId: string,
+    sortField: string,
+    sortOrder: string,
+    _filters?: GetSpansOptions['filters'],
+  ): Promise<GetSpansResult> {
+    const schemaName = this.schema
+
+    // Use a recursive CTE to find all descendant spans
+    // 1. Base case: find the span with step_id = stepId
+    // 2. Recursive case: find all spans where parent_span_id = span_id of a span we've already found
+    const query = sql`
+      WITH RECURSIVE span_tree AS (
+        -- Base case: the span(s) for the step
+        SELECT * FROM ${sql.identifier(schemaName)}.spans WHERE step_id = ${stepId}::uuid
+        UNION ALL
+        -- Recursive case: children of spans we've found
+        SELECT s.* FROM ${sql.identifier(schemaName)}.spans s
+        INNER JOIN span_tree st ON s.parent_span_id = st.span_id
+      )
+      SELECT
+        id,
+        trace_id as "traceId",
+        span_id as "spanId",
+        parent_span_id as "parentSpanId",
+        job_id as "jobId",
+        step_id as "stepId",
+        name,
+        kind,
+        start_time_unix_nano as "startTimeUnixNano",
+        end_time_unix_nano as "endTimeUnixNano",
+        status_code as "statusCode",
+        status_message as "statusMessage",
+        attributes,
+        events
+      FROM span_tree
+      ORDER BY ${sql.identifier(sortField)} ${sql.raw(sortOrder)}
+    `
+
+    // Raw SQL returns numeric types as strings, so we type them as such
+    const rows = (await this.db.execute(query)) as unknown as Array<{
+      id: string | number
+      traceId: string
+      spanId: string
+      parentSpanId: string | null
+      jobId: string | null
+      stepId: string | null
+      name: string
+      kind: string | number
+      startTimeUnixNano: string | bigint | null
+      endTimeUnixNano: string | bigint | null
+      statusCode: string | number
+      statusMessage: string | null
+      attributes: Record<string, any>
+      events: Array<{ name: string; timeUnixNano: string; attributes?: Record<string, any> }>
+    }>
+
+    // Convert types: raw SQL returns numeric types as strings
+    const spans = rows.map((row) => ({
+      ...row,
+      // Convert id to number (bigserial comes as string from raw SQL)
+      id: typeof row.id === 'string' ? Number.parseInt(row.id, 10) : row.id,
+      // Convert kind and statusCode to proper types
+      kind: (typeof row.kind === 'string' ? Number.parseInt(row.kind, 10) : row.kind) as 0 | 1 | 2 | 3 | 4,
+      statusCode: (typeof row.statusCode === 'string' ? Number.parseInt(row.statusCode, 10) : row.statusCode) as
+        | 0
+        | 1
+        | 2,
+      // Convert BigInt to string for JSON serialization
+      startTimeUnixNano: row.startTimeUnixNano?.toString() ?? null,
+      endTimeUnixNano: row.endTimeUnixNano?.toString() ?? null,
+    }))
+
+    return {
+      spans,
+      total: spans.length,
+    }
+  }
+
+  /**
+   * Internal method to delete all spans for a job.
    */
-  protected async _deleteMetrics(options: DeleteMetricsOptions): Promise<number> {
+  protected async _deleteSpans(options: DeleteSpansOptions): Promise<number> {
     const result = await this.db
-      .delete(this.tables.metricsTable)
-      .where(eq(this.tables.metricsTable.job_id, options.jobId))
-      .returning({ id: this.tables.metricsTable.id })
+      .delete(this.tables.spansTable)
+      .where(eq(this.tables.spansTable.job_id, options.jobId))
+      .returning({ id: this.tables.spansTable.id })
 
     return result.length
   }
 
   /**
-   * Build WHERE clause for metrics queries.
+   * Build WHERE clause for spans queries (used for job queries only).
+   * When querying by jobId, we find all spans that share the same trace_id
+   * as spans with that job. This includes spans from external libraries that
+   * don't have the duron.job.id attribute but are part of the same trace.
+   *
+   * Note: Step queries are handled separately by _getStepSpansRecursive using
+   * a recursive CTE to traverse the span hierarchy.
    */
-  protected _buildMetricsWhereClause(jobId?: string, stepId?: string, filters?: GetMetricsOptions['filters']) {
-    const metricsTable = this.tables.metricsTable
+  protected _buildSpansWhereClause(jobId?: string, _stepId?: string, filters?: GetSpansOptions['filters']) {
+    const spansTable = this.tables.spansTable
+
+    // Build condition for finding spans by trace_id (includes external spans)
+    let traceCondition: ReturnType<typeof eq> | undefined
+
+    if (jobId) {
+      // Find all spans that share a trace_id with any span that has this job_id
+      // This includes external spans (like from AI SDK) that don't have duron.job.id
+      traceCondition = inArray(
+        spansTable.trace_id,
+        this.db.select({ traceId: spansTable.trace_id }).from(spansTable).where(eq(spansTable.job_id, jobId)),
+      )
+    }
 
     return and(
-      jobId ? eq(metricsTable.job_id, jobId) : undefined,
-      stepId ? eq(metricsTable.step_id, stepId) : undefined,
+      traceCondition,
       filters?.name
         ? Array.isArray(filters.name)
-          ? or(...filters.name.map((n) => ilike(metricsTable.name, `%${n}%`)))
-          : ilike(metricsTable.name, `%${filters.name}%`)
-        : undefined,
-      filters?.type
-        ? inArray(metricsTable.type, Array.isArray(filters.type) ? filters.type : [filters.type])
+          ? or(...filters.name.map((n) => ilike(spansTable.name, `%${n}%`)))
+          : ilike(spansTable.name, `%${filters.name}%`)
         : undefined,
-      filters?.timestampRange && filters.timestampRange.length === 2
-        ? between(metricsTable.timestamp, filters.timestampRange[0]!, filters.timestampRange[1]!)
+      filters?.kind ? inArray(spansTable.kind, Array.isArray(filters.kind) ? filters.kind : [filters.kind]) : undefined,
+      filters?.statusCode
+        ? inArray(spansTable.status_code, Array.isArray(filters.statusCode) ? filters.statusCode : [filters.statusCode])
         : undefined,
+      filters?.traceId ? eq(spansTable.trace_id, filters.traceId) : undefined,
       ...(filters?.attributesFilter && Object.keys(filters.attributesFilter).length > 0
-        ? this.#buildJsonbWhereConditions(filters.attributesFilter, metricsTable.attributes)
+        ? this.#buildJsonbWhereConditions(filters.attributesFilter, spansTable.attributes)
         : []),
     )
   }

package/src/adapters/postgres/schema.default.ts

@@ -1,5 +1,5 @@
 import createSchema from './schema.js'
 
-const { schema, jobsTable, jobStepsTable, metricsTable } = createSchema('duron')
+const { schema, jobsTable, jobStepsTable, spansTable } = createSchema('duron')
 
-export { schema, jobsTable, jobStepsTable, metricsTable }
+export { schema, jobsTable, jobStepsTable, spansTable }