reqon-dsl 0.2.0 → 0.4.0

package/dist/observability/otel.js

@@ -0,0 +1,421 @@
+/**
+ * OpenTelemetry Integration - Trace and metrics export
+ *
+ * Provides adapters for exporting observability data to OpenTelemetry-compatible
+ * backends (Jaeger, Zipkin, OTLP, etc.)
+ *
+ * This is a lightweight implementation that doesn't require the full OTel SDK.
+ * For production use, consider using the official @opentelemetry packages.
+ */
+import { randomBytes } from 'node:crypto';
+// ============================================================================
+// Trace Context Management
+// ============================================================================
+/**
+ * Generate a 32-character hex trace ID
+ */
+export function generateTraceId() {
+    return randomHex(32);
+}
+/**
+ * Generate a 16-character hex span ID
+ */
+export function generateSpanId() {
+    return randomHex(16);
+}
+/**
+ * Generate `length` random hex characters using a CSPRNG. OTel trace/span IDs
+ * must be unpredictable and must never be all-zero (the all-zero ID is the
+ * "invalid" sentinel in the spec), so we regenerate in the vanishingly
+ * unlikely event of an all-zero draw.
+ */
+function randomHex(length) {
+    const byteLength = Math.ceil(length / 2);
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const hex = randomBytes(byteLength).toString('hex').slice(0, length);
+        if (!/^0+$/.test(hex))
+            return hex;
+    }
+    // Fallback (practically unreachable): force a non-zero leading nibble.
+    return '1'.padEnd(length, '0');
+}
+// ============================================================================
+// OpenTelemetry Span Builder
+// ============================================================================
+export class SpanBuilder {
+    traceId;
+    spans = [];
+    activeSpans = new Map();
+    constructor(traceId) {
+        this.traceId = traceId ?? generateTraceId();
+    }
+    getTraceId() {
+        return this.traceId;
+    }
+    startSpan(name, options = {}) {
+        const spanId = generateSpanId();
+        const now = Date.now();
+        const span = {
+            traceId: this.traceId,
+            spanId,
+            parentSpanId: options.parentSpanId,
+            name,
+            kind: options.kind ?? 'INTERNAL',
+            startTimeUnixNano: (now * 1_000_000).toString(),
+            endTimeUnixNano: '0',
+            attributes: options.attributes ? this.toAttributes(options.attributes) : [],
+            status: { code: 'UNSET' },
+            events: [],
+        };
+        this.activeSpans.set(spanId, { span, startTime: now });
+        return spanId;
+    }
+    endSpan(spanId, options = {}) {
+        const active = this.activeSpans.get(spanId);
+        if (!active)
+            return undefined;
+        const { span } = active;
+        const now = Date.now();
+        span.endTimeUnixNano = (now * 1_000_000).toString();
+        span.status = {
+            code: options.status ?? 'OK',
+            message: options.error,
+        };
+        if (options.attributes) {
+            span.attributes.push(...this.toAttributes(options.attributes));
+        }
+        this.activeSpans.delete(spanId);
+        this.spans.push(span);
+        return span;
+    }
+    addEvent(spanId, name, attributes) {
+        const active = this.activeSpans.get(spanId);
+        if (!active)
+            return;
+        active.span.events.push({
+            name,
+            timeUnixNano: (Date.now() * 1_000_000).toString(),
+            attributes: attributes ? this.toAttributes(attributes) : [],
+        });
+    }
+    getSpans() {
+        return [...this.spans];
+    }
+    toAttributes(attrs) {
+        return Object.entries(attrs).map(([key, value]) => ({
+            key,
+            value: typeof value === 'string'
+                ? { stringValue: value }
+                : typeof value === 'number'
+                    ? { intValue: value }
+                    : { boolValue: value },
+        }));
+    }
+}
+// ============================================================================
+// OpenTelemetry Event Adapter
+// ============================================================================
+/**
+ * Adapts observability events to OpenTelemetry spans
+ */
+export class OTelEventAdapter {
+    spanBuilder;
+    spanStack = [];
+    eventToSpan = new Map();
+    /**
+     * Pending fetch spans keyed by source+path. Fetch start/complete events
+     * don't carry a correlation id, so we queue the open span ids per endpoint
+     * (FIFO) instead of a single shared `fetch:current` slot. This keeps
+     * concurrent/paginated fetches from overwriting and leaking each other.
+     */
+    pendingFetchSpans = new Map();
+    constructor(traceId) {
+        this.spanBuilder = new SpanBuilder(traceId);
+    }
+    /**
+     * Process an observability event and update spans
+     */
+    processEvent(event) {
+        const { type } = event;
+        // Map event types to span operations
+        switch (type) {
+            case 'mission.start':
+                this.startMissionSpan(event);
+                break;
+            case 'mission.complete':
+            case 'mission.failed':
+                this.endMissionSpan(event);
+                break;
+            case 'stage.start':
+                this.startStageSpan(event);
+                break;
+            case 'stage.complete':
+                this.endStageSpan(event);
+                break;
+            case 'step.start':
+                this.startStepSpan(event);
+                break;
+            case 'step.complete':
+                this.endStepSpan(event);
+                break;
+            case 'fetch.start':
+                this.startFetchSpan(event);
+                break;
+            case 'fetch.complete':
+            case 'fetch.error':
+                this.endFetchSpan(event);
+                break;
+            default:
+                // Add as event to current span
+                this.addEventToCurrentSpan(event);
+        }
+    }
+    startMissionSpan(event) {
+        const spanId = this.spanBuilder.startSpan(`mission:${event.mission}`, {
+            kind: 'INTERNAL',
+            attributes: {
+                'reqon.execution_id': event.executionId,
+                'reqon.mission': event.mission,
+            },
+        });
+        this.spanStack.push(spanId);
+        this.eventToSpan.set('mission', spanId);
+    }
+    endMissionSpan(event) {
+        const spanId = this.eventToSpan.get('mission');
+        if (spanId) {
+            const payload = event.payload;
+            this.spanBuilder.endSpan(spanId, {
+                status: payload.success === false ? 'ERROR' : 'OK',
+                error: payload.error,
+            });
+            this.spanStack.pop();
+            this.eventToSpan.delete('mission');
+        }
+    }
+    startStageSpan(event) {
+        const payload = event.payload;
+        const parentSpanId = this.spanStack[this.spanStack.length - 1];
+        const spanId = this.spanBuilder.startSpan(`stage:${payload.stageName}`, {
+            kind: 'INTERNAL',
+            parentSpanId,
+            attributes: {
+                'reqon.stage.name': payload.stageName,
+                'reqon.stage.index': payload.stageIndex,
+            },
+        });
+        this.spanStack.push(spanId);
+        this.eventToSpan.set(`stage:${payload.stageIndex}`, spanId);
+    }
+    endStageSpan(event) {
+        const payload = event.payload;
+        const spanId = this.eventToSpan.get(`stage:${payload.stageIndex}`);
+        if (spanId) {
+            this.spanBuilder.endSpan(spanId, {
+                status: payload.success ? 'OK' : 'ERROR',
+                error: payload.error,
+            });
+            this.spanStack.pop();
+            this.eventToSpan.delete(`stage:${payload.stageIndex}`);
+        }
+    }
+    startStepSpan(event) {
+        const payload = event.payload;
+        const parentSpanId = this.spanStack[this.spanStack.length - 1];
+        const spanId = this.spanBuilder.startSpan(`step:${payload.stepType}`, {
+            kind: 'INTERNAL',
+            parentSpanId,
+            attributes: {
+                'reqon.step.type': payload.stepType,
+                'reqon.step.index': payload.stepIndex,
+                'reqon.action': payload.actionName,
+            },
+        });
+        this.spanStack.push(spanId);
+        this.eventToSpan.set(`step:${payload.actionName}:${payload.stepIndex}`, spanId);
+    }
+    endStepSpan(event) {
+        const payload = event.payload;
+        const key = `step:${payload.actionName}:${payload.stepIndex}`;
+        const spanId = this.eventToSpan.get(key);
+        if (spanId) {
+            this.spanBuilder.endSpan(spanId, {
+                status: payload.success ? 'OK' : 'ERROR',
+                error: payload.error,
+            });
+            this.spanStack.pop();
+            this.eventToSpan.delete(key);
+        }
+    }
+    fetchKey(source, path) {
+        return `${source ?? ''}${path ?? ''}`;
+    }
+    startFetchSpan(event) {
+        const payload = event.payload;
+        const parentSpanId = this.spanStack[this.spanStack.length - 1];
+        const spanId = this.spanBuilder.startSpan(`fetch:${payload.method} ${payload.path}`, {
+            kind: 'CLIENT',
+            parentSpanId,
+            attributes: {
+                'http.method': payload.method,
+                'http.url': payload.path,
+                'reqon.source': payload.source,
+            },
+        });
+        const key = this.fetchKey(payload.source, payload.path);
+        const queue = this.pendingFetchSpans.get(key);
+        if (queue) {
+            queue.push(spanId);
+        }
+        else {
+            this.pendingFetchSpans.set(key, [spanId]);
+        }
+    }
+    endFetchSpan(event) {
+        const payload = event.payload;
+        const key = this.fetchKey(payload.source, payload.path);
+        const queue = this.pendingFetchSpans.get(key);
+        const spanId = queue?.shift();
+        if (queue && queue.length === 0) {
+            this.pendingFetchSpans.delete(key);
+        }
+        if (spanId) {
+            this.spanBuilder.endSpan(spanId, {
+                status: payload.error ? 'ERROR' : 'OK',
+                error: payload.error,
+                attributes: payload.statusCode ? { 'http.status_code': payload.statusCode } : undefined,
+            });
+        }
+    }
+    addEventToCurrentSpan(event) {
+        const spanId = this.spanStack[this.spanStack.length - 1];
+        if (spanId) {
+            this.spanBuilder.addEvent(spanId, event.type, event.payload);
+        }
+    }
+    getSpans() {
+        return this.spanBuilder.getSpans();
+    }
+    getTraceId() {
+        return this.spanBuilder.getTraceId();
+    }
+}
+/**
+ * Export spans to an OTLP-compatible endpoint
+ */
+export class OTLPExporter {
+    config;
+    pendingSpans = [];
+    flushTimer;
+    constructor(config) {
+        this.config = config;
+    }
+    addSpans(spans) {
+        this.pendingSpans.push(...spans);
+    }
+    async flush() {
+        if (this.pendingSpans.length === 0)
+            return;
+        const spans = this.pendingSpans;
+        this.pendingSpans = [];
+        const payload = {
+            resourceSpans: [
+                {
+                    resource: {
+                        attributes: [
+                            {
+                                key: 'service.name',
+                                value: { stringValue: this.config.serviceName ?? 'reqon' },
+                            },
+                        ],
+                    },
+                    scopeSpans: [
+                        {
+                            scope: { name: 'reqon', version: '1.0.0' },
+                            spans,
+                        },
+                    ],
+                },
+            ],
+        };
+        try {
+            const response = await fetch(this.config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.config.headers,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                console.error(`OTLP export failed: ${response.status} ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            console.error('OTLP export error:', error);
+        }
+    }
+    startAutoFlush(intervalMs = 5000) {
+        this.flushTimer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, intervalMs);
+    }
+    stopAutoFlush() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+    }
+}
+// ============================================================================
+// Log Output for OTel
+// ============================================================================
+/**
+ * Log output that converts entries to OTel spans
+ */
+export class OTelLogOutput {
+    adapter;
+    exporter;
+    constructor(adapter, exporter) {
+        this.adapter = adapter;
+        this.exporter = exporter;
+    }
+    write(entry) {
+        // Only process span-related entries
+        if (entry.spanId) {
+            // Spans are handled by the event adapter
+            return;
+        }
+    }
+    getSpans() {
+        return this.adapter.getSpans();
+    }
+    async flush() {
+        if (this.exporter) {
+            this.exporter.addSpans(this.adapter.getSpans());
+            await this.exporter.flush();
+        }
+    }
+}
+// ============================================================================
+// Event Listener for OTel
+// ============================================================================
+/**
+ * Create an event listener that builds OTel spans
+ */
+export function createOTelListener(config) {
+    const adapter = new OTelEventAdapter();
+    const exporter = config ? new OTLPExporter(config) : undefined;
+    return {
+        adapter,
+        handler: (event) => {
+            adapter.processEvent(event);
+        },
+        flush: async () => {
+            if (exporter) {
+                exporter.addSpans(adapter.getSpans());
+                await exporter.flush();
+            }
+        },
+    };
+}

package/dist/parser/action-parser.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Action and step parsing
+ * Handles parsing of action definitions and all step types.
+ */
+import { type FieldDefinition, type SchemaDefinition } from 'vague-lang';
+import type { ActionDefinition, ActionStep, ForStep, MapStep, ValidateStep, StoreStep, MatchStep, MatchArm, FlowDirective, LetStep, ApplyStep, TransformDefinition, TransformVariant, WebhookStep, WebhookStorageConfig, PauseStep, StoreDefinition, FieldMapping } from '../ast/nodes.js';
+import { FetchParser } from './fetch-parser.js';
+export declare class ActionParser extends FetchParser {
+    /**
+     * Parse a store definition
+     */
+    parseStoreDefinition(): StoreDefinition;
+    /**
+     * Parse an action definition
+     */
+    parseAction(): ActionDefinition;
+    /**
+     * Parse a single action step
+     */
+    protected parseActionStep(): ActionStep;
+    /**
+     * Parse a for loop step
+     */
+    protected parseForStep(): ForStep;
+    /**
+     * Parse a map step
+     */
+    protected parseMapStep(): MapStep;
+    /**
+     * Parse a transform definition
+     */
+    parseTransform(): TransformDefinition;
+    /**
+     * Parse a single transform variant
+     */
+    protected parseTransformVariant(): TransformVariant;
+    /**
+     * Parse field mappings: { field: expression, ... }
+     */
+    protected parseFieldMappings(): FieldMapping[];
+    /**
+     * Parse apply step: apply TransformName to expression [as variableName]
+     */
+    protected parseApplyStep(): ApplyStep;
+    /**
+     * Parse validate step
+     */
+    protected parseValidateStep(): ValidateStep;
+    /**
+     * Parse store step
+     */
+    protected parseStoreStep(): StoreStep;
+    /**
+     * Parse a store option key, handling keyword tokens
+     */
+    private parseStoreOptionKey;
+    /**
+     * Parse match step (schema overloading)
+     */
+    protected parseMatchStep(): MatchStep;
+    /**
+     * Parse a match arm
+     */
+    protected parseMatchArm(): MatchArm;
+    /**
+     * Try to parse a flow directive
+     */
+    protected tryParseFlowDirective(): FlowDirective | undefined;
+    /**
+     * Parse let step (variable binding)
+     */
+    protected parseLetStep(): LetStep;
+    /**
+     * Parse wait step (webhook support)
+     */
+    protected parseWaitStep(): WebhookStep;
+    /**
+     * Parse a wait option key, handling keyword tokens
+     */
+    private parseWaitOptionKey;
+    /**
+     * Parse webhook storage config
+     */
+    protected parseWebhookStorageConfig(): WebhookStorageConfig;
+    /**
+     * Parse pause step: pause { duration: "7d", persist: FileStore, resume-on: timeout | webhook "/path" }
+     */
+    protected parsePauseStep(): PauseStep;
+    /**
+     * Parse pause option key, handling keyword tokens
+     */
+    private parsePauseOptionKey;
+    /**
+     * Parse pause resume triggers: timeout | webhook "/path"
+     */
+    private parsePauseResumeTriggers;
+    /**
+     * Parse a schema definition
+     */
+    parseSchema(): SchemaDefinition;
+    /**
+     * Parse a field definition
+     */
+    protected parseFieldDefinition(): FieldDefinition;
+}