duron 0.2.2 → 0.3.0-beta.1

package/dist/telemetry/local.js

@@ -0,0 +1,180 @@
+import { TelemetryAdapter, } from './adapter.js';
+const DEFAULT_FLUSH_DELAY_MS = 1000;
+export class LocalTelemetryAdapter extends TelemetryAdapter {
+    #spanStartTimes = new Map();
+    #metricsQueue = [];
+    #flushTimer = null;
+    #flushPromise = null;
+    #flushDelayMs;
+    constructor(options) {
+        super();
+        this.#flushDelayMs = options?.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS;
+    }
+    get #database() {
+        const client = this.client;
+        if (!client) {
+            throw new Error('LocalTelemetryAdapter requires the Duron client to be set. This is done automatically by the Duron client.');
+        }
+        return client.database;
+    }
+    #queueMetric(options) {
+        this.#metricsQueue.push(options);
+        this.#scheduleFlush();
+    }
+    #scheduleFlush() {
+        if (this.#flushTimer) {
+            clearTimeout(this.#flushTimer);
+        }
+        this.#flushTimer = setTimeout(() => {
+            this.#flushTimer = null;
+            this.#flushPromise = this.#flushQueue().finally(() => {
+                this.#flushPromise = null;
+            });
+        }, this.#flushDelayMs);
+    }
+    async #flushQueue() {
+        if (this.#metricsQueue.length === 0) {
+            return;
+        }
+        const metrics = this.#metricsQueue.splice(0, this.#metricsQueue.length);
+        await this.#database.insertMetrics(metrics);
+    }
+    async #forceFlush() {
+        if (this.#flushTimer) {
+            clearTimeout(this.#flushTimer);
+            this.#flushTimer = null;
+        }
+        if (this.#flushPromise) {
+            await this.#flushPromise;
+        }
+        await this.#flushQueue();
+    }
+    async _start() {
+    }
+    async _stop() {
+        await this.#forceFlush();
+        this.#spanStartTimes.clear();
+    }
+    async _startJobSpan(options) {
+        const spanId = `job:${options.jobId}`;
+        this.#spanStartTimes.set(spanId, Date.now());
+        this.#queueMetric({
+            jobId: options.jobId,
+            name: 'duron.job.span.start',
+            value: Date.now(),
+            type: 'span_event',
+            attributes: {
+                actionName: options.actionName,
+                groupKey: options.groupKey,
+                spanId,
+            },
+        });
+        return {
+            id: spanId,
+            jobId: options.jobId,
+            stepId: null,
+            parentSpanId: null,
+        };
+    }
+    async _endJobSpan(span, options) {
+        const startTime = this.#spanStartTimes.get(span.id);
+        const duration = startTime ? Date.now() - startTime : 0;
+        this.#spanStartTimes.delete(span.id);
+        this.#queueMetric({
+            jobId: span.jobId,
+            name: 'duron.job.span.end',
+            value: duration,
+            type: 'span_event',
+            attributes: {
+                spanId: span.id,
+                status: options.status,
+                error: options.error?.message ?? null,
+                durationMs: duration,
+            },
+        });
+    }
+    async _startStepSpan(options) {
+        const spanId = `step:${options.stepId}`;
+        this.#spanStartTimes.set(spanId, Date.now());
+        this.#queueMetric({
+            jobId: options.jobId,
+            stepId: options.stepId,
+            name: 'duron.step.span.start',
+            value: Date.now(),
+            type: 'span_event',
+            attributes: {
+                stepName: options.stepName,
+                parentStepId: options.parentStepId,
+                parentSpanId: options.parentSpan?.id ?? null,
+                spanId,
+            },
+        });
+        return {
+            id: spanId,
+            jobId: options.jobId,
+            stepId: options.stepId,
+            parentSpanId: options.parentSpan?.id ?? null,
+        };
+    }
+    async _endStepSpan(span, options) {
+        const startTime = this.#spanStartTimes.get(span.id);
+        const duration = startTime ? Date.now() - startTime : 0;
+        this.#spanStartTimes.delete(span.id);
+        this.#queueMetric({
+            jobId: span.jobId,
+            stepId: span.stepId ?? undefined,
+            name: 'duron.step.span.end',
+            value: duration,
+            type: 'span_event',
+            attributes: {
+                spanId: span.id,
+                status: options.status,
+                error: options.error?.message ?? null,
+                durationMs: duration,
+            },
+        });
+    }
+    async _startDatabaseSpan(_options) {
+        return null;
+    }
+    async _endDatabaseSpan(_span, _options) {
+    }
+    async _recordMetric(options) {
+        this.#queueMetric({
+            jobId: options.jobId,
+            stepId: options.stepId,
+            name: options.name,
+            value: options.value,
+            type: 'metric',
+            attributes: options.attributes,
+        });
+    }
+    async _addSpanEvent(options) {
+        this.#queueMetric({
+            jobId: options.span.jobId,
+            stepId: options.span.stepId ?? undefined,
+            name: options.name,
+            value: Date.now(),
+            type: 'span_event',
+            attributes: {
+                spanId: options.span.id,
+                ...options.attributes,
+            },
+        });
+    }
+    async _addSpanAttribute(options) {
+        this.#queueMetric({
+            jobId: options.span.jobId,
+            stepId: options.span.stepId ?? undefined,
+            name: `attribute:${options.key}`,
+            value: typeof options.value === 'number' ? options.value : 0,
+            type: 'span_attribute',
+            attributes: {
+                spanId: options.span.id,
+                key: options.key,
+                value: String(options.value),
+            },
+        });
+    }
+}
+export const localTelemetryAdapter = (options) => new LocalTelemetryAdapter(options);

package/dist/telemetry/noop.d.ts

@@ -0,0 +1,16 @@
+import { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartStepSpanOptions, TelemetryAdapter } from './adapter.js';
+export declare class NoopTelemetryAdapter extends TelemetryAdapter {
+    protected _start(): Promise<void>;
+    protected _stop(): Promise<void>;
+    protected _startJobSpan(options: StartJobSpanOptions): Promise<Span>;
+    protected _endJobSpan(_span: Span, _options: EndSpanOptions): Promise<void>;
+    protected _startStepSpan(options: StartStepSpanOptions): Promise<Span>;
+    protected _endStepSpan(_span: Span, _options: EndSpanOptions): Promise<void>;
+    protected _startDatabaseSpan(_options: StartDatabaseSpanOptions): Promise<Span | null>;
+    protected _endDatabaseSpan(_span: Span, _options: EndSpanOptions): Promise<void>;
+    protected _recordMetric(_options: RecordMetricOptions): Promise<void>;
+    protected _addSpanEvent(_options: AddSpanEventOptions): Promise<void>;
+    protected _addSpanAttribute(_options: AddSpanAttributeOptions): Promise<void>;
+}
+export declare const noopTelemetryAdapter: () => NoopTelemetryAdapter;
+//# sourceMappingURL=noop.d.ts.map

package/dist/telemetry/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/telemetry/noop.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,gBAAgB,EACjB,MAAM,cAAc,CAAA;AAUrB,qBAAa,oBAAqB,SAAQ,gBAAgB;cAKxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAQtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS1D,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIjE,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS5D,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIlE,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cAI5E,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAQtE,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,iBAAiB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpF;AAQD,eAAO,MAAM,oBAAoB,4BAAmC,CAAA"}

package/dist/telemetry/noop.js

@@ -0,0 +1,39 @@
+import { TelemetryAdapter, } from './adapter.js';
+export class NoopTelemetryAdapter extends TelemetryAdapter {
+    async _start() {
+    }
+    async _stop() {
+    }
+    async _startJobSpan(options) {
+        return {
+            id: 'noop',
+            jobId: options.jobId,
+            stepId: null,
+            parentSpanId: null,
+        };
+    }
+    async _endJobSpan(_span, _options) {
+    }
+    async _startStepSpan(options) {
+        return {
+            id: 'noop',
+            jobId: options.jobId,
+            stepId: options.stepId,
+            parentSpanId: options.parentSpan?.id ?? null,
+        };
+    }
+    async _endStepSpan(_span, _options) {
+    }
+    async _startDatabaseSpan(_options) {
+        return null;
+    }
+    async _endDatabaseSpan(_span, _options) {
+    }
+    async _recordMetric(_options) {
+    }
+    async _addSpanEvent(_options) {
+    }
+    async _addSpanAttribute(_options) {
+    }
+}
+export const noopTelemetryAdapter = () => new NoopTelemetryAdapter();

package/dist/telemetry/opentelemetry.d.ts

@@ -0,0 +1,24 @@
+import type { TracerProvider } from '@opentelemetry/api';
+import { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartStepSpanOptions, TelemetryAdapter } from './adapter.js';
+export interface OpenTelemetryAdapterOptions {
+    serviceName?: string;
+    tracerProvider?: TracerProvider;
+    traceDatabaseQueries?: boolean;
+}
+export declare class OpenTelemetryAdapter extends TelemetryAdapter {
+    #private;
+    constructor(options?: OpenTelemetryAdapterOptions);
+    protected _start(): Promise<void>;
+    protected _stop(): Promise<void>;
+    protected _startJobSpan(options: StartJobSpanOptions): Promise<Span>;
+    protected _endJobSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    protected _startStepSpan(options: StartStepSpanOptions): Promise<Span>;
+    protected _endStepSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    protected _startDatabaseSpan(options: StartDatabaseSpanOptions): Promise<Span | null>;
+    protected _endDatabaseSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    protected _recordMetric(options: RecordMetricOptions): Promise<void>;
+    protected _addSpanEvent(options: AddSpanEventOptions): Promise<void>;
+    protected _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>;
+}
+export declare const openTelemetryAdapter: (options?: OpenTelemetryAdapterOptions) => OpenTelemetryAdapter;
+//# sourceMappingURL=opentelemetry.d.ts.map

package/dist/telemetry/opentelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opentelemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/opentelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAElF,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,gBAAgB,EACjB,MAAM,cAAc,CAAA;AAMrB,MAAM,WAAW,2BAA2B;IAK1C,WAAW,CAAC,EAAE,MAAM,CAAA;IAMpB,cAAc,CAAC,EAAE,cAAc,CAAA;IAM/B,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAcD,qBAAa,oBAAqB,SAAQ,gBAAgB;;gBAO5C,OAAO,GAAE,2BAAgC;cAWrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAYvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAStB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cA8B1D,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B/D,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cA4C5D,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2BhE,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cA8B3E,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAyBpE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAe1D,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAO1D,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;CAMnF;AASD,eAAO,MAAM,oBAAoB,GAAI,UAAU,2BAA2B,yBAAsC,CAAA"}

package/dist/telemetry/opentelemetry.js

@@ -0,0 +1,202 @@
+import { TelemetryAdapter, } from './adapter.js';
+export class OpenTelemetryAdapter extends TelemetryAdapter {
+    #serviceName;
+    #tracerProvider;
+    #traceDatabaseQueries;
+    #tracer = null;
+    #spanMap = new Map();
+    constructor(options = {}) {
+        super();
+        this.#serviceName = options.serviceName ?? 'duron';
+        this.#tracerProvider = options.tracerProvider ?? null;
+        this.#traceDatabaseQueries = options.traceDatabaseQueries ?? false;
+    }
+    async _start() {
+        const api = await import('@opentelemetry/api');
+        if (this.#tracerProvider) {
+            this.#tracer = this.#tracerProvider.getTracer(this.#serviceName);
+        }
+        else {
+            this.#tracer = api.trace.getTracer(this.#serviceName);
+        }
+    }
+    async _stop() {
+        this.#spanMap.clear();
+        this.#tracer = null;
+    }
+    async _startJobSpan(options) {
+        if (!this.#tracer) {
+            throw new Error('OpenTelemetry tracer not initialized');
+        }
+        const api = await import('@opentelemetry/api');
+        const otelSpan = this.#tracer.startSpan(`job:${options.actionName}`, {
+            kind: api.SpanKind.INTERNAL,
+            attributes: {
+                'duron.job.id': options.jobId,
+                'duron.job.action_name': options.actionName,
+                'duron.job.group_key': options.groupKey,
+            },
+        });
+        const spanId = `job:${options.jobId}`;
+        this.#spanMap.set(spanId, otelSpan);
+        const span = {
+            id: spanId,
+            jobId: options.jobId,
+            stepId: null,
+            parentSpanId: null,
+            otelSpan,
+        };
+        return span;
+    }
+    async _endJobSpan(span, options) {
+        const api = await import('@opentelemetry/api');
+        const extSpan = span;
+        const otelSpan = extSpan.otelSpan;
+        if (options.status === 'error') {
+            otelSpan.setStatus({
+                code: api.SpanStatusCode.ERROR,
+                message: options.error?.message ?? 'Unknown error',
+            });
+            if (options.error) {
+                otelSpan.recordException(options.error);
+            }
+        }
+        else if (options.status === 'cancelled') {
+            otelSpan.setStatus({
+                code: api.SpanStatusCode.OK,
+                message: 'Cancelled',
+            });
+            otelSpan.setAttribute('duron.job.cancelled', true);
+        }
+        else {
+            otelSpan.setStatus({ code: api.SpanStatusCode.OK });
+        }
+        otelSpan.end();
+        this.#spanMap.delete(span.id);
+    }
+    async _startStepSpan(options) {
+        if (!this.#tracer) {
+            throw new Error('OpenTelemetry tracer not initialized');
+        }
+        const api = await import('@opentelemetry/api');
+        let parentContext = api.context.active();
+        if (options.parentSpan) {
+            const parentExtSpan = options.parentSpan;
+            if (parentExtSpan.otelSpan) {
+                parentContext = api.trace.setSpan(api.context.active(), parentExtSpan.otelSpan);
+            }
+        }
+        const otelSpan = this.#tracer.startSpan(`step:${options.stepName}`, {
+            kind: api.SpanKind.INTERNAL,
+            attributes: {
+                'duron.job.id': options.jobId,
+                'duron.step.id': options.stepId,
+                'duron.step.name': options.stepName,
+                'duron.step.parent_step_id': options.parentStepId ?? undefined,
+            },
+        }, parentContext);
+        const spanId = `step:${options.stepId}`;
+        this.#spanMap.set(spanId, otelSpan);
+        const span = {
+            id: spanId,
+            jobId: options.jobId,
+            stepId: options.stepId,
+            parentSpanId: options.parentSpan?.id ?? null,
+            otelSpan,
+        };
+        return span;
+    }
+    async _endStepSpan(span, options) {
+        const api = await import('@opentelemetry/api');
+        const extSpan = span;
+        const otelSpan = extSpan.otelSpan;
+        if (options.status === 'error') {
+            otelSpan.setStatus({
+                code: api.SpanStatusCode.ERROR,
+                message: options.error?.message ?? 'Unknown error',
+            });
+            if (options.error) {
+                otelSpan.recordException(options.error);
+            }
+        }
+        else if (options.status === 'cancelled') {
+            otelSpan.setStatus({
+                code: api.SpanStatusCode.OK,
+                message: 'Cancelled',
+            });
+            otelSpan.setAttribute('duron.step.cancelled', true);
+        }
+        else {
+            otelSpan.setStatus({ code: api.SpanStatusCode.OK });
+        }
+        otelSpan.end();
+        this.#spanMap.delete(span.id);
+    }
+    async _startDatabaseSpan(options) {
+        if (!this.#traceDatabaseQueries || !this.#tracer) {
+            return null;
+        }
+        const api = await import('@opentelemetry/api');
+        const otelSpan = this.#tracer.startSpan(`db:${options.operation}`, {
+            kind: api.SpanKind.CLIENT,
+            attributes: {
+                'db.system': 'postgresql',
+                'db.operation': options.operation,
+                'db.statement': options.query,
+            },
+        });
+        const spanId = `db:${globalThis.crypto.randomUUID()}`;
+        this.#spanMap.set(spanId, otelSpan);
+        const span = {
+            id: spanId,
+            jobId: '',
+            stepId: null,
+            parentSpanId: null,
+            otelSpan,
+        };
+        return span;
+    }
+    async _endDatabaseSpan(span, options) {
+        const api = await import('@opentelemetry/api');
+        const extSpan = span;
+        const otelSpan = extSpan.otelSpan;
+        if (options.status === 'error') {
+            otelSpan.setStatus({
+                code: api.SpanStatusCode.ERROR,
+                message: options.error?.message ?? 'Unknown error',
+            });
+            if (options.error) {
+                otelSpan.recordException(options.error);
+            }
+        }
+        else {
+            otelSpan.setStatus({ code: api.SpanStatusCode.OK });
+        }
+        otelSpan.end();
+        this.#spanMap.delete(span.id);
+    }
+    async _recordMetric(options) {
+        const api = await import('@opentelemetry/api');
+        const activeSpan = api.trace.getActiveSpan();
+        if (activeSpan) {
+            activeSpan.addEvent('metric', {
+                'metric.name': options.name,
+                'metric.value': options.value,
+                ...options.attributes,
+            });
+        }
+    }
+    async _addSpanEvent(options) {
+        const extSpan = options.span;
+        if (extSpan.otelSpan) {
+            extSpan.otelSpan.addEvent(options.name, options.attributes);
+        }
+    }
+    async _addSpanAttribute(options) {
+        const extSpan = options.span;
+        if (extSpan.otelSpan) {
+            extSpan.otelSpan.setAttribute(options.key, options.value);
+        }
+    }
+}
+export const openTelemetryAdapter = (options) => new OpenTelemetryAdapter(options);

package/migrations/postgres/20260117231749_clumsy_penance/migration.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "duron"."job_steps" ADD COLUMN "parent_step_id" uuid;--> statement-breakpoint
+ALTER TABLE "duron"."job_steps" ADD COLUMN "branch" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+CREATE INDEX "idx_job_steps_parent_step_id" ON "duron"."job_steps" ("parent_step_id");