@blokjs/runner 0.2.0

package/dist/monitoring/CircuitBreaker.js

@@ -0,0 +1,238 @@
+/**
+ * Circuit Breaker Pattern for Blok Triggers
+ *
+ * Prevents cascading failures by detecting repeated errors
+ * and temporarily disabling failing operations.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests flow through
+ * - OPEN: Failures exceeded threshold, requests are rejected
+ * - HALF_OPEN: Testing recovery, limited requests allowed
+ */
+export class CircuitBreaker {
+    state = "CLOSED";
+    failures = 0;
+    successes = 0;
+    consecutiveFailures = 0;
+    halfOpenAttempts = 0;
+    lastFailure = null;
+    lastSuccess = null;
+    lastStateChange = Date.now();
+    totalRequests = 0;
+    totalRejected = 0;
+    failureTimestamps = [];
+    config;
+    listeners = [];
+    resetTimer = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Execute a function through the circuit breaker.
+     * Throws CircuitOpenError if the circuit is open.
+     */
+    async execute(fn) {
+        if (!this.canExecute()) {
+            this.totalRejected++;
+            this.emit({
+                type: "request_rejected",
+                state: this.state,
+                timestamp: Date.now(),
+            });
+            throw new CircuitOpenError(`Circuit breaker is ${this.state}. Retry after ${this.getRetryAfterMs()}ms`, this.getRetryAfterMs());
+        }
+        this.totalRequests++;
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Check if the circuit allows execution without actually executing.
+     */
+    canExecute() {
+        switch (this.state) {
+            case "CLOSED":
+                return true;
+            case "OPEN":
+                if (Date.now() - this.lastStateChange >= this.config.resetTimeoutMs) {
+                    this.transitionTo("HALF_OPEN");
+                    return true;
+                }
+                return false;
+            case "HALF_OPEN":
+                return this.halfOpenAttempts < this.config.halfOpenMaxAttempts;
+        }
+    }
+    /**
+     * Get current circuit breaker statistics.
+     */
+    getStats() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            consecutiveFailures: this.consecutiveFailures,
+            lastFailure: this.lastFailure,
+            lastSuccess: this.lastSuccess,
+            lastStateChange: this.lastStateChange,
+            totalRequests: this.totalRequests,
+            totalRejected: this.totalRejected,
+        };
+    }
+    /**
+     * Get the current circuit state.
+     */
+    getState() {
+        // Check if OPEN should transition to HALF_OPEN
+        if (this.state === "OPEN" && Date.now() - this.lastStateChange >= this.config.resetTimeoutMs) {
+            this.transitionTo("HALF_OPEN");
+        }
+        return this.state;
+    }
+    /**
+     * Get estimated time before the circuit will attempt recovery.
+     */
+    getRetryAfterMs() {
+        if (this.state !== "OPEN")
+            return 0;
+        const elapsed = Date.now() - this.lastStateChange;
+        return Math.max(0, this.config.resetTimeoutMs - elapsed);
+    }
+    /**
+     * Manually reset the circuit to CLOSED state.
+     */
+    reset() {
+        this.transitionTo("CLOSED");
+        this.failures = 0;
+        this.successes = 0;
+        this.consecutiveFailures = 0;
+        this.halfOpenAttempts = 0;
+        this.failureTimestamps = [];
+        this.clearResetTimer();
+    }
+    /**
+     * Register an event listener.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Remove an event listener.
+     */
+    off(listener) {
+        this.listeners = this.listeners.filter((l) => l !== listener);
+    }
+    /**
+     * Clean up resources. Call when shutting down.
+     */
+    destroy() {
+        this.clearResetTimer();
+        this.listeners = [];
+    }
+    onSuccess() {
+        this.successes++;
+        this.consecutiveFailures = 0;
+        this.lastSuccess = Date.now();
+        this.emit({
+            type: "success",
+            state: this.state,
+            timestamp: Date.now(),
+        });
+        if (this.state === "HALF_OPEN") {
+            this.halfOpenAttempts++;
+            if (this.halfOpenAttempts >= this.config.halfOpenMaxAttempts) {
+                this.transitionTo("CLOSED");
+                this.failures = 0;
+                this.halfOpenAttempts = 0;
+                this.failureTimestamps = [];
+            }
+        }
+    }
+    onFailure(error) {
+        this.failures++;
+        this.consecutiveFailures++;
+        this.lastFailure = Date.now();
+        if (this.config.failureWindowMs) {
+            this.failureTimestamps.push(Date.now());
+            this.pruneOldFailures();
+        }
+        this.emit({
+            type: "failure",
+            state: this.state,
+            timestamp: Date.now(),
+            error,
+        });
+        if (this.state === "HALF_OPEN") {
+            this.transitionTo("OPEN");
+            this.halfOpenAttempts = 0;
+            this.scheduleResetTimer();
+            return;
+        }
+        const failureCount = this.config.failureWindowMs ? this.failureTimestamps.length : this.consecutiveFailures;
+        if (this.state === "CLOSED" && failureCount >= this.config.failureThreshold) {
+            this.transitionTo("OPEN");
+            this.scheduleResetTimer();
+        }
+    }
+    transitionTo(newState) {
+        const previousState = this.state;
+        if (previousState === newState)
+            return;
+        this.state = newState;
+        this.lastStateChange = Date.now();
+        this.emit({
+            type: "state_change",
+            state: newState,
+            previousState,
+            timestamp: Date.now(),
+        });
+    }
+    pruneOldFailures() {
+        if (!this.config.failureWindowMs)
+            return;
+        const cutoff = Date.now() - this.config.failureWindowMs;
+        this.failureTimestamps = this.failureTimestamps.filter((t) => t > cutoff);
+    }
+    scheduleResetTimer() {
+        this.clearResetTimer();
+        this.resetTimer = setTimeout(() => {
+            if (this.state === "OPEN") {
+                this.transitionTo("HALF_OPEN");
+            }
+        }, this.config.resetTimeoutMs);
+        if (this.resetTimer.unref) {
+            this.resetTimer.unref();
+        }
+    }
+    clearResetTimer() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = null;
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners should not throw
+            }
+        }
+    }
+}
+export class CircuitOpenError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = "CircuitOpenError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+//# sourceMappingURL=CircuitBreaker.js.map

package/dist/monitoring/CircuitBreaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.js","sourceRoot":"","sources":["../../src/monitoring/CircuitBreaker.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/DistributedTracer.d.ts

@@ -0,0 +1,125 @@
+/**
+ * DistributedTracer - OpenTelemetry distributed tracing for Blok workflows
+ *
+ * Creates spans for workflow and node execution, propagates trace context
+ * across runtime boundaries, and correlates logs with traces via trace_id/span_id.
+ *
+ * Uses the OpenTelemetry API so any configured TracerProvider (OTLP, Jaeger,
+ * Zipkin, Datadog, etc.) receives the spans automatically.
+ *
+ * Works as a no-op when no TracerProvider is registered (graceful degradation).
+ *
+ * @example
+ * ```typescript
+ * import { DistributedTracer } from "@blokjs/runner";
+ *
+ * const tracer = new DistributedTracer({ serviceName: "blok-http" });
+ *
+ * // Start a workflow span
+ * const span = tracer.startWorkflowSpan("user-api", "/users/:id", { requestId: "abc" });
+ *
+ * // Start a child node span
+ * const nodeSpan = tracer.startNodeSpan("db-query", "postgres", span);
+ * // ... node execution ...
+ * tracer.endNodeSpan(nodeSpan, true);
+ *
+ * // End workflow span
+ * tracer.endWorkflowSpan(span, true);
+ * ```
+ */
+import { type Span } from "@opentelemetry/api";
+export interface DistributedTracerConfig {
+    /** Service name for the tracer */
+    serviceName: string;
+    /** Service version (default: "0.0.1") */
+    serviceVersion?: string;
+    /** Whether to record node-level spans (default: true) */
+    traceNodes?: boolean;
+    /** Whether to add request/response data as span attributes (default: false — may contain PII) */
+    recordPayloads?: boolean;
+    /** Max attribute value length (default: 256) */
+    maxAttributeLength?: number;
+}
+export interface WorkflowSpanAttributes {
+    requestId?: string;
+    triggerType?: string;
+    triggerName?: string;
+    env?: string;
+}
+export interface NodeSpanAttributes {
+    nodeType?: string;
+    runtimeKind?: string;
+    inputSize?: number;
+    outputSize?: number;
+}
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+export declare class DistributedTracer {
+    private config;
+    private tracer;
+    private workflowSpanCount;
+    private nodeSpanCount;
+    private errorSpanCount;
+    constructor(config: DistributedTracerConfig);
+    /**
+     * Start a span for a workflow execution.
+     * This is the root span for a request flowing through a workflow.
+     */
+    startWorkflowSpan(workflowName: string, workflowPath: string, attrs?: WorkflowSpanAttributes): Span;
+    /**
+     * End a workflow span with success/failure status.
+     */
+    endWorkflowSpan(span: Span, success: boolean, error?: Error): void;
+    /**
+     * Start a child span for node execution within a workflow.
+     * The parent context is taken from the provided workflow span.
+     */
+    startNodeSpan(nodeName: string, nodeType: string, parentSpan: Span, attrs?: NodeSpanAttributes): Span;
+    /**
+     * End a node span with success/failure status.
+     */
+    endNodeSpan(span: Span, success: boolean, error?: Error, attrs?: NodeSpanAttributes): void;
+    /**
+     * Start a span for a runtime adapter call (e.g., gRPC to Python, Docker exec).
+     * Used when a node delegates to a non-in-process runtime.
+     */
+    startRuntimeSpan(runtimeKind: string, nodeName: string, parentSpan: Span): Span;
+    /**
+     * End a runtime span.
+     */
+    endRuntimeSpan(span: Span, success: boolean, error?: Error): void;
+    /**
+     * Add an event to a span (e.g., "input validated", "cache hit").
+     */
+    addSpanEvent(span: Span, name: string, attrs?: Record<string, string | number | boolean>): void;
+    /**
+     * Set an attribute on a span.
+     */
+    setSpanAttribute(span: Span, key: string, value: string | number | boolean): void;
+    /**
+     * Extract trace context (trace_id, span_id) from a span for log correlation.
+     * Returns { traceId, spanId, traceFlags } or null if the span is not recording.
+     */
+    extractTraceContext(span: Span): TraceContext | null;
+    /**
+     * Get W3C Trace Context headers for propagation across service boundaries.
+     * Pass these headers when calling remote runtimes (gRPC, HTTP, Docker).
+     */
+    getTraceHeaders(span: Span): Record<string, string>;
+    /**
+     * Get stats about tracer usage.
+     */
+    getStats(): {
+        workflowSpanCount: number;
+        nodeSpanCount: number;
+        errorSpanCount: number;
+        totalSpans: number;
+    };
+    /**
+     * Reset stats. Useful for testing.
+     */
+    resetStats(): void;
+}

package/dist/monitoring/DistributedTracer.js

@@ -0,0 +1,230 @@
+/**
+ * DistributedTracer - OpenTelemetry distributed tracing for Blok workflows
+ *
+ * Creates spans for workflow and node execution, propagates trace context
+ * across runtime boundaries, and correlates logs with traces via trace_id/span_id.
+ *
+ * Uses the OpenTelemetry API so any configured TracerProvider (OTLP, Jaeger,
+ * Zipkin, Datadog, etc.) receives the spans automatically.
+ *
+ * Works as a no-op when no TracerProvider is registered (graceful degradation).
+ *
+ * @example
+ * ```typescript
+ * import { DistributedTracer } from "@blokjs/runner";
+ *
+ * const tracer = new DistributedTracer({ serviceName: "blok-http" });
+ *
+ * // Start a workflow span
+ * const span = tracer.startWorkflowSpan("user-api", "/users/:id", { requestId: "abc" });
+ *
+ * // Start a child node span
+ * const nodeSpan = tracer.startNodeSpan("db-query", "postgres", span);
+ * // ... node execution ...
+ * tracer.endNodeSpan(nodeSpan, true);
+ *
+ * // End workflow span
+ * tracer.endWorkflowSpan(span, true);
+ * ```
+ */
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+export class DistributedTracer {
+    config;
+    tracer;
+    // Stats
+    workflowSpanCount = 0;
+    nodeSpanCount = 0;
+    errorSpanCount = 0;
+    constructor(config) {
+        this.config = {
+            serviceVersion: "0.0.1",
+            traceNodes: true,
+            recordPayloads: false,
+            maxAttributeLength: 256,
+            ...config,
+        };
+        this.tracer = trace.getTracer(this.config.serviceName, this.config.serviceVersion);
+    }
+    /**
+     * Start a span for a workflow execution.
+     * This is the root span for a request flowing through a workflow.
+     */
+    startWorkflowSpan(workflowName, workflowPath, attrs) {
+        this.workflowSpanCount++;
+        const span = this.tracer.startSpan(`workflow ${workflowName}`, {
+            kind: SpanKind.SERVER,
+            attributes: {
+                "blok.workflow.name": workflowName,
+                "blok.workflow.path": workflowPath,
+                "blok.component": "runner",
+                ...(attrs?.requestId && { "blok.request.id": attrs.requestId }),
+                ...(attrs?.triggerType && { "blok.trigger.type": attrs.triggerType }),
+                ...(attrs?.triggerName && { "blok.trigger.name": attrs.triggerName }),
+                ...(attrs?.env && { "deployment.environment": attrs.env }),
+            },
+        });
+        return span;
+    }
+    /**
+     * End a workflow span with success/failure status.
+     */
+    endWorkflowSpan(span, success, error) {
+        if (success) {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        else {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error?.message || "Workflow execution failed",
+            });
+            if (error) {
+                span.recordException(error);
+            }
+            this.errorSpanCount++;
+        }
+        span.end();
+    }
+    /**
+     * Start a child span for node execution within a workflow.
+     * The parent context is taken from the provided workflow span.
+     */
+    startNodeSpan(nodeName, nodeType, parentSpan, attrs) {
+        if (!this.config.traceNodes) {
+            return parentSpan;
+        }
+        this.nodeSpanCount++;
+        const parentContext = trace.setSpan(context.active(), parentSpan);
+        const span = this.tracer.startSpan(`node ${nodeName}`, {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                "blok.node.name": nodeName,
+                "blok.node.type": nodeType,
+                "blok.component": "node",
+                ...(attrs?.runtimeKind && { "blok.runtime.kind": attrs.runtimeKind }),
+                ...(attrs?.inputSize && { "blok.node.input_size": attrs.inputSize }),
+            },
+        }, parentContext);
+        return span;
+    }
+    /**
+     * End a node span with success/failure status.
+     */
+    endNodeSpan(span, success, error, attrs) {
+        if (attrs?.outputSize) {
+            span.setAttribute("blok.node.output_size", attrs.outputSize);
+        }
+        if (success) {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        else {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error?.message || "Node execution failed",
+            });
+            if (error) {
+                span.recordException(error);
+            }
+            this.errorSpanCount++;
+        }
+        span.end();
+    }
+    /**
+     * Start a span for a runtime adapter call (e.g., gRPC to Python, Docker exec).
+     * Used when a node delegates to a non-in-process runtime.
+     */
+    startRuntimeSpan(runtimeKind, nodeName, parentSpan) {
+        const parentContext = trace.setSpan(context.active(), parentSpan);
+        return this.tracer.startSpan(`runtime ${runtimeKind}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "blok.runtime.kind": runtimeKind,
+                "blok.node.name": nodeName,
+                "blok.component": "runtime-adapter",
+            },
+        }, parentContext);
+    }
+    /**
+     * End a runtime span.
+     */
+    endRuntimeSpan(span, success, error) {
+        if (success) {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        else {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error?.message || "Runtime execution failed",
+            });
+            if (error) {
+                span.recordException(error);
+            }
+            this.errorSpanCount++;
+        }
+        span.end();
+    }
+    /**
+     * Add an event to a span (e.g., "input validated", "cache hit").
+     */
+    addSpanEvent(span, name, attrs) {
+        span.addEvent(name, attrs);
+    }
+    /**
+     * Set an attribute on a span.
+     */
+    setSpanAttribute(span, key, value) {
+        if (typeof value === "string" && value.length > this.config.maxAttributeLength) {
+            span.setAttribute(key, `${value.substring(0, this.config.maxAttributeLength)}...`);
+        }
+        else {
+            span.setAttribute(key, value);
+        }
+    }
+    /**
+     * Extract trace context (trace_id, span_id) from a span for log correlation.
+     * Returns { traceId, spanId, traceFlags } or null if the span is not recording.
+     */
+    extractTraceContext(span) {
+        const spanContext = span.spanContext();
+        if (!spanContext || spanContext.traceId === "00000000000000000000000000000000") {
+            return null;
+        }
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+        };
+    }
+    /**
+     * Get W3C Trace Context headers for propagation across service boundaries.
+     * Pass these headers when calling remote runtimes (gRPC, HTTP, Docker).
+     */
+    getTraceHeaders(span) {
+        const ctx = span.spanContext();
+        if (!ctx || ctx.traceId === "00000000000000000000000000000000") {
+            return {};
+        }
+        // W3C traceparent format: version-traceId-spanId-flags
+        const traceparent = `00-${ctx.traceId}-${ctx.spanId}-${String(ctx.traceFlags).padStart(2, "0")}`;
+        return { traceparent };
+    }
+    /**
+     * Get stats about tracer usage.
+     */
+    getStats() {
+        return {
+            workflowSpanCount: this.workflowSpanCount,
+            nodeSpanCount: this.nodeSpanCount,
+            errorSpanCount: this.errorSpanCount,
+            totalSpans: this.workflowSpanCount + this.nodeSpanCount,
+        };
+    }
+    /**
+     * Reset stats. Useful for testing.
+     */
+    resetStats() {
+        this.workflowSpanCount = 0;
+        this.nodeSpanCount = 0;
+        this.errorSpanCount = 0;
+    }
+}
+//# sourceMappingURL=DistributedTracer.js.map

package/dist/monitoring/DistributedTracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistributedTracer.js","sourceRoot":"","sources":["../../src/monitoring/DistributedTracer.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/HealthCheck.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Health Check Infrastructure for Blok Triggers
+ *
+ * Provides standardized health check capabilities across all trigger types.
+ * Supports Kubernetes readiness/liveness probes and custom dependency checks.
+ */
+export type HealthStatus = "healthy" | "degraded" | "unhealthy";
+export interface HealthCheckResult {
+    status: HealthStatus;
+    timestamp: number;
+    uptime: number;
+    checks: Record<string, DependencyHealth>;
+}
+export interface DependencyHealth {
+    status: HealthStatus;
+    latency_ms?: number;
+    message?: string;
+    lastChecked: number;
+}
+export type DependencyCheckFn = () => Promise<DependencyHealth>;
+export declare class HealthCheck {
+    private startTime;
+    private dependencies;
+    private cachedResults;
+    private cacheMaxAge;
+    constructor(cacheMaxAgeMs?: number);
+    /**
+     * Register a named dependency health check.
+     */
+    registerDependency(name: string, checkFn: DependencyCheckFn): void;
+    /**
+     * Remove a registered dependency check.
+     */
+    removeDependency(name: string): void;
+    /**
+     * Run all dependency checks and return aggregated health.
+     */
+    check(): Promise<HealthCheckResult>;
+    /**
+     * Quick liveness check - is the process alive and responsive?
+     */
+    liveness(): {
+        status: "ok";
+        uptime: number;
+    };
+    /**
+     * Readiness check - are all dependencies healthy?
+     */
+    readiness(): Promise<{
+        ready: boolean;
+        status: HealthStatus;
+    }>;
+    private aggregateStatus;
+}