reqon-dsl 0.2.0 → 0.4.0

package/dist/observability/logger.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Structured Logger - Enhanced logging with context and spans
+ *
+ * Provides structured logging capabilities with:
+ * - Hierarchical context (child loggers)
+ * - Timing spans for operations
+ * - Multiple output formats
+ * - Integration with event emitter
+ */
+import type { LogLevel, EventEmitter } from './events.js';
+/** Log entry structure */
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+    spanId?: string;
+    parentSpanId?: string;
+    duration?: number;
+}
+/** Span for timing operations */
+export interface Span {
+    /** End the span and return duration in ms */
+    end(): number;
+    /** Add context to the span */
+    addContext(context: Record<string, unknown>): void;
+    /** Create a child span */
+    child(name: string): Span;
+    /** Get span ID */
+    readonly id: string;
+}
+/** Output handler interface */
+export interface LogOutput {
+    write(entry: LogEntry): void;
+}
+/** Structured logger interface */
+export interface StructuredLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    /** Create a child logger with additional context */
+    child(context: Record<string, unknown>): StructuredLogger;
+    /** Create a timing span */
+    span(name: string): Span;
+    /** Set minimum log level */
+    setLevel(level: LogLevel): void;
+    /** Add an output handler */
+    addOutput(output: LogOutput): void;
+}
+/** Console output with human-readable formatting */
+export declare class ConsoleOutput implements LogOutput {
+    private prefix;
+    private colors;
+    constructor(options?: {
+        prefix?: string;
+        colors?: boolean;
+    });
+    write(entry: LogEntry): void;
+}
+/** JSON Lines output for log aggregation */
+export declare class JsonLinesOutput implements LogOutput {
+    private stream;
+    constructor(stream?: {
+        write: (line: string) => void;
+    });
+    write(entry: LogEntry): void;
+}
+/** Buffer output for testing */
+export declare class BufferOutput implements LogOutput {
+    readonly entries: LogEntry[];
+    write(entry: LogEntry): void;
+    clear(): void;
+    find(predicate: (entry: LogEntry) => boolean): LogEntry | undefined;
+    filter(predicate: (entry: LogEntry) => boolean): LogEntry[];
+}
+/** Event emitter output - bridges logs to events */
+export declare class EventOutput implements LogOutput {
+    private emitter;
+    constructor(emitter: EventEmitter);
+    write(entry: LogEntry): void;
+}
+export interface CreateLoggerOptions {
+    /** Logger prefix for console output */
+    prefix?: string;
+    /** Minimum log level */
+    level?: LogLevel;
+    /** Include console output */
+    console?: boolean;
+    /** Include JSON lines output */
+    jsonLines?: boolean;
+    /** Custom JSON lines stream */
+    jsonStream?: {
+        write: (line: string) => void;
+    };
+    /** Event emitter for bridging */
+    eventEmitter?: EventEmitter;
+    /** Initial context */
+    context?: Record<string, unknown>;
+    /** Silent mode (no outputs) */
+    silent?: boolean;
+}
+/**
+ * Create a structured logger with configured outputs
+ */
+export declare function createStructuredLogger(options?: CreateLoggerOptions): StructuredLogger;

package/dist/observability/logger.js

@@ -0,0 +1,266 @@
+/**
+ * Structured Logger - Enhanced logging with context and spans
+ *
+ * Provides structured logging capabilities with:
+ * - Hierarchical context (child loggers)
+ * - Timing spans for operations
+ * - Multiple output formats
+ * - Integration with event emitter
+ */
+import { randomBytes } from 'node:crypto';
+import { redactSecrets } from '../utils/redact.js';
+// ============================================================================
+// Span Implementation
+// ============================================================================
+class SpanImpl {
+    id;
+    name;
+    startTime;
+    context = {};
+    parentSpanId;
+    logger;
+    ended = false;
+    constructor(name, logger, parentSpanId) {
+        this.id = generateSpanId();
+        this.name = name;
+        this.startTime = Date.now();
+        this.parentSpanId = parentSpanId;
+        this.logger = logger;
+    }
+    end() {
+        if (this.ended)
+            return 0;
+        this.ended = true;
+        const duration = Date.now() - this.startTime;
+        this.logger.writeSpanEnd(this.name, this.id, this.parentSpanId, duration, this.context);
+        return duration;
+    }
+    addContext(context) {
+        Object.assign(this.context, context);
+    }
+    child(name) {
+        return new SpanImpl(name, this.logger, this.id);
+    }
+}
+function generateSpanId() {
+    // CSPRNG-backed, 16 hex chars. Never all-zero (the OTel "invalid" sentinel).
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const hex = randomBytes(8).toString('hex');
+        if (!/^0+$/.test(hex))
+            return hex;
+    }
+    return '1'.padEnd(16, '0');
+}
+// ============================================================================
+// Logger Implementation
+// ============================================================================
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+class StructuredLoggerImpl {
+    context;
+    outputs = [];
+    minLevel = 'info';
+    eventEmitter;
+    constructor(context = {}, outputs = [], minLevel = 'info', eventEmitter) {
+        this.context = context;
+        this.outputs = outputs;
+        this.minLevel = minLevel;
+        this.eventEmitter = eventEmitter;
+    }
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.minLevel];
+    }
+    log(level, message, context) {
+        if (!this.shouldLog(level))
+            return;
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            context: redactSecrets({ ...this.context, ...context }),
+        };
+        for (const output of this.outputs) {
+            try {
+                output.write(entry);
+            }
+            catch {
+                // Swallow output errors
+            }
+        }
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    error(message, context) {
+        this.log('error', message, context);
+    }
+    child(context) {
+        return new StructuredLoggerImpl({ ...this.context, ...context }, this.outputs, this.minLevel, this.eventEmitter);
+    }
+    span(name) {
+        const span = new SpanImpl(name, this);
+        this.debug(`span:start`, { spanName: name, spanId: span.id });
+        return span;
+    }
+    setLevel(level) {
+        this.minLevel = level;
+    }
+    addOutput(output) {
+        this.outputs.push(output);
+    }
+    /** Internal: write span end entry */
+    writeSpanEnd(name, spanId, parentSpanId, duration, spanContext) {
+        const entry = {
+            level: 'debug',
+            message: `span:end`,
+            timestamp: new Date().toISOString(),
+            context: redactSecrets({ ...this.context, spanName: name, ...spanContext }),
+            spanId,
+            parentSpanId,
+            duration,
+        };
+        for (const output of this.outputs) {
+            try {
+                output.write(entry);
+            }
+            catch {
+                // Swallow output errors
+            }
+        }
+    }
+    /** Get the event emitter if configured */
+    getEventEmitter() {
+        return this.eventEmitter;
+    }
+    /** Emit an event (convenience method) */
+    emit(type, payload) {
+        this.eventEmitter?.emit(type, payload);
+    }
+}
+// ============================================================================
+// Output Handlers
+// ============================================================================
+/** Console output with human-readable formatting */
+export class ConsoleOutput {
+    prefix;
+    colors;
+    constructor(options = {}) {
+        this.prefix = options.prefix ?? 'Reqon';
+        this.colors = options.colors ?? true;
+    }
+    write(entry) {
+        const prefix = `[${this.prefix}]`;
+        const levelStr = entry.level.toUpperCase().padEnd(5);
+        // Format context as key=value pairs
+        const contextStr = Object.keys(entry.context).length > 0 ? ` ${formatContext(entry.context)}` : '';
+        // Format duration if present
+        const durationStr = entry.duration !== undefined ? ` (${entry.duration}ms)` : '';
+        const message = `${prefix} ${levelStr} ${entry.message}${contextStr}${durationStr}`;
+        switch (entry.level) {
+            case 'debug':
+                console.debug(message);
+                break;
+            case 'info':
+                console.log(message);
+                break;
+            case 'warn':
+                console.warn(message);
+                break;
+            case 'error':
+                console.error(message);
+                break;
+        }
+    }
+}
+/** JSON Lines output for log aggregation */
+export class JsonLinesOutput {
+    stream;
+    constructor(stream) {
+        this.stream = stream ?? { write: (line) => console.log(line) };
+    }
+    write(entry) {
+        const json = JSON.stringify({
+            ...entry,
+            '@timestamp': entry.timestamp,
+        });
+        this.stream.write(json);
+    }
+}
+/** Buffer output for testing */
+export class BufferOutput {
+    entries = [];
+    write(entry) {
+        this.entries.push(entry);
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+    find(predicate) {
+        return this.entries.find(predicate);
+    }
+    filter(predicate) {
+        return this.entries.filter(predicate);
+    }
+}
+/** Event emitter output - bridges logs to events */
+export class EventOutput {
+    emitter;
+    constructor(emitter) {
+        this.emitter = emitter;
+    }
+    write(entry) {
+        // Map log entries to appropriate event types based on context
+        // This allows logs to flow into the event system
+        if (entry.context.eventType) {
+            this.emitter.emit(entry.context.eventType, {
+                ...entry.context,
+                message: entry.message,
+            });
+        }
+    }
+}
+/**
+ * Create a structured logger with configured outputs
+ */
+export function createStructuredLogger(options = {}) {
+    const outputs = [];
+    if (!options.silent) {
+        if (options.console !== false) {
+            outputs.push(new ConsoleOutput({ prefix: options.prefix }));
+        }
+        if (options.jsonLines) {
+            outputs.push(new JsonLinesOutput(options.jsonStream));
+        }
+        if (options.eventEmitter) {
+            outputs.push(new EventOutput(options.eventEmitter));
+        }
+    }
+    return new StructuredLoggerImpl(options.context ?? {}, outputs, options.level ?? 'info', options.eventEmitter);
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function formatContext(context) {
+    return Object.entries(context)
+        .filter(([key]) => !key.startsWith('_')) // Skip internal keys
+        .map(([key, value]) => {
+        if (typeof value === 'string') {
+            return `${key}="${value}"`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return `${key}=${value}`;
+        }
+        return `${key}=${JSON.stringify(value)}`;
+    })
+        .join(' ');
+}

package/dist/observability/otel.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 type { ObservabilityEvent } from './events.js';
+import type { LogEntry, LogOutput } from './logger.js';
+/** OTLP-compatible span structure */
+export interface OTelSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OTelAttribute[];
+    status: {
+        code: 'UNSET' | 'OK' | 'ERROR';
+        message?: string;
+    };
+    events: OTelSpanEvent[];
+}
+export interface OTelAttribute {
+    key: string;
+    value: {
+        stringValue?: string;
+        intValue?: number;
+        boolValue?: boolean;
+    };
+}
+export interface OTelSpanEvent {
+    name: string;
+    timeUnixNano: string;
+    attributes: OTelAttribute[];
+}
+/** Trace context for span correlation */
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+}
+/**
+ * Generate a 32-character hex trace ID
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a 16-character hex span ID
+ */
+export declare function generateSpanId(): string;
+export declare class SpanBuilder {
+    private traceId;
+    private spans;
+    private activeSpans;
+    constructor(traceId?: string);
+    getTraceId(): string;
+    startSpan(name: string, options?: {
+        kind?: OTelSpan['kind'];
+        parentSpanId?: string;
+        attributes?: Record<string, string | number | boolean>;
+    }): string;
+    endSpan(spanId: string, options?: {
+        status?: 'OK' | 'ERROR';
+        error?: string;
+        attributes?: Record<string, string | number | boolean>;
+    }): OTelSpan | undefined;
+    addEvent(spanId: string, name: string, attributes?: Record<string, string | number | boolean>): void;
+    getSpans(): OTelSpan[];
+    private toAttributes;
+}
+/**
+ * Adapts observability events to OpenTelemetry spans
+ */
+export declare class OTelEventAdapter {
+    private spanBuilder;
+    private spanStack;
+    private eventToSpan;
+    /**
+     * 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.
+     */
+    private pendingFetchSpans;
+    constructor(traceId?: string);
+    /**
+     * Process an observability event and update spans
+     */
+    processEvent(event: ObservabilityEvent): void;
+    private startMissionSpan;
+    private endMissionSpan;
+    private startStageSpan;
+    private endStageSpan;
+    private startStepSpan;
+    private endStepSpan;
+    private fetchKey;
+    private startFetchSpan;
+    private endFetchSpan;
+    private addEventToCurrentSpan;
+    getSpans(): OTelSpan[];
+    getTraceId(): string;
+}
+export interface OTLPExporterConfig {
+    endpoint: string;
+    headers?: Record<string, string>;
+    serviceName?: string;
+}
+/**
+ * Export spans to an OTLP-compatible endpoint
+ */
+export declare class OTLPExporter {
+    private config;
+    private pendingSpans;
+    private flushTimer?;
+    constructor(config: OTLPExporterConfig);
+    addSpans(spans: OTelSpan[]): void;
+    flush(): Promise<void>;
+    startAutoFlush(intervalMs?: number): void;
+    stopAutoFlush(): void;
+}
+/**
+ * Log output that converts entries to OTel spans
+ */
+export declare class OTelLogOutput implements LogOutput {
+    private adapter;
+    private exporter?;
+    constructor(adapter: OTelEventAdapter, exporter?: OTLPExporter);
+    write(entry: LogEntry): void;
+    getSpans(): OTelSpan[];
+    flush(): Promise<void>;
+}
+/**
+ * Create an event listener that builds OTel spans
+ */
+export declare function createOTelListener(config?: OTLPExporterConfig): {
+    adapter: OTelEventAdapter;
+    handler: (event: ObservabilityEvent) => void;
+    flush: () => Promise<void>;
+};