@bleedingdev/modern-js-server-runtime-extensions 0.0.0-trusted-publisher-bootstrap

package/dist/esm-node/runtimeFallbackSignal.mjs

@@ -0,0 +1,223 @@
+import "node:module";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION } from "./contractGateSnapshotStore.mjs";
+const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = '/_modern/contract-gates/runtime-fallback';
+const DEFAULT_RUNTIME_STATUS_ENDPOINT = '/_modern/runtime/status';
+const DEFAULT_RUNTIME_FALLBACK_GATE_NAME = 'runtime-mf-fallback-health';
+const DEFAULT_RUNTIME_FALLBACK_FAILURE_HOLD_MS = 300000;
+const DEFAULT_RUNTIME_FALLBACK_MAX_BODY_BYTES = 16384;
+const DEFAULT_RUNTIME_FALLBACK_AUTH_HEADER = 'x-modernjs-runtime-signal-token';
+const DEFAULT_RUNTIME_FALLBACK_TRUST_MAX_SIGNALS_PER_WINDOW = 30;
+const DEFAULT_RUNTIME_FALLBACK_TRUST_WINDOW_MS = 60000;
+const DEFAULT_RUNTIME_FALLBACK_TRUST_DEDUPE_WINDOW_MS = 10000;
+function resolveRuntimeFallbackSignalEndpoint(configuredEndpoint) {
+    const rawEndpoint = configuredEndpoint?.trim();
+    if (!rawEndpoint) return DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT;
+    if (rawEndpoint.startsWith('/')) return rawEndpoint;
+    try {
+        return new URL(rawEndpoint).pathname || DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT;
+    } catch (_error) {
+        return `/${rawEndpoint.replace(/^\/+/, '')}`;
+    }
+}
+function createRuntimeSignalError(message, code) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+function getUtf8ByteLength(input) {
+    if ("u" > typeof Buffer) return Buffer.byteLength(input);
+    return new TextEncoder().encode(input).length;
+}
+function normalizeRuntimeSignalOrigin(value) {
+    if ('string' != typeof value || 0 === value.trim().length) return;
+    try {
+        return new URL(value).origin;
+    } catch (_error) {
+        return;
+    }
+}
+function normalizeRuntimeSignalAppName(payload) {
+    if ('string' != typeof payload.appName) return 'unknown';
+    const normalized = payload.appName.trim();
+    return normalized.length > 0 ? normalized : 'unknown';
+}
+function normalizeRuntimeSignalRuntimeDigest(payload) {
+    if ('string' == typeof payload.runtimeDigest && payload.runtimeDigest.trim()) return payload.runtimeDigest.trim();
+    const metadata = payload.metadata;
+    if (metadata && 'object' == typeof metadata && !Array.isArray(metadata) && 'string' == typeof metadata.runtimeDigest) {
+        const digest = String(metadata.runtimeDigest).trim();
+        if (digest) return digest;
+    }
+}
+function normalizeRuntimeFallbackSignalAuthConfig(configured) {
+    const headerName = 'string' == typeof configured?.headerName && configured.headerName.trim() ? configured.headerName.trim().toLowerCase() : DEFAULT_RUNTIME_FALLBACK_AUTH_HEADER;
+    const expectedFromEnv = 'string' == typeof configured?.expectedValueEnv && configured.expectedValueEnv.trim().length > 0 ? process.env[configured.expectedValueEnv.trim()] : void 0;
+    const expectedFromConfig = 'string' == typeof configured?.expectedValue && configured.expectedValue.trim().length > 0 ? configured.expectedValue.trim() : void 0;
+    const expectedValue = expectedFromConfig || expectedFromEnv;
+    const enabled = configured?.enabled === true;
+    if (enabled && !expectedValue) throw new Error('[telemetry.canary.autopilot.runtimeFallbackSignal] auth.enabled is true but no expected token is configured');
+    return {
+        enabled,
+        headerName,
+        expectedValue
+    };
+}
+function normalizeRequiredRuntimeFallbackSignalAuthConfig(configured) {
+    if (configured?.enabled === false) throw new Error('[telemetry.canary.autopilot.runtimeFallbackSignal] the endpoint cannot be enabled with auth disabled; configure auth.expectedValue or auth.expectedValueEnv');
+    try {
+        return normalizeRuntimeFallbackSignalAuthConfig({
+            ...configured,
+            enabled: true
+        });
+    } catch (_error) {
+        throw new Error('[telemetry.canary.autopilot.runtimeFallbackSignal] enabling the endpoint requires an auth token; configure auth.expectedValue or auth.expectedValueEnv');
+    }
+}
+function safeTokenEquals(candidate, expected) {
+    const candidateDigest = createHash('sha256').update(candidate).digest();
+    const expectedDigest = createHash('sha256').update(expected).digest();
+    return timingSafeEqual(candidateDigest, expectedDigest);
+}
+function enforceRuntimeFallbackSignalAuthToken(token, authConfig) {
+    if (!authConfig.enabled) return;
+    if (!token || !authConfig.expectedValue || !safeTokenEquals(token, authConfig.expectedValue)) throw createRuntimeSignalError('runtime fallback signal auth failed', 'UNAUTHORIZED');
+}
+function enforceRuntimeFallbackSignalAuth(c, runtimeSignalConfig) {
+    enforceRuntimeFallbackSignalAuthToken(c.req.header(runtimeSignalConfig.auth.headerName), runtimeSignalConfig.auth);
+}
+function normalizeRuntimeFallbackTrustPolicy(configured) {
+    const allowedApps = Array.isArray(configured?.allowedApps) ? configured.allowedApps.map((item)=>'string' == typeof item ? item.trim() : '').filter(Boolean) : [];
+    const allowedEntryOrigins = Array.isArray(configured?.allowedEntryOrigins) ? configured.allowedEntryOrigins.map((item)=>normalizeRuntimeSignalOrigin(item)).filter((item)=>Boolean(item)) : [];
+    const expectedRuntimeDigestsRaw = configured?.expectedRuntimeDigests || {};
+    const expectedRuntimeDigests = {};
+    Object.entries(expectedRuntimeDigestsRaw).forEach(([appName, digest])=>{
+        if ('string' == typeof appName && appName.trim().length > 0 && 'string' == typeof digest && digest.trim().length > 0) expectedRuntimeDigests[appName.trim()] = digest.trim();
+    });
+    return {
+        allowedApps,
+        allowedEntryOrigins,
+        expectedRuntimeDigests,
+        enforceRuntimeDigest: configured?.enforceRuntimeDigest === true,
+        maxSignalsPerWindow: Math.max(1, Math.floor(configured?.maxSignalsPerWindow ?? DEFAULT_RUNTIME_FALLBACK_TRUST_MAX_SIGNALS_PER_WINDOW)),
+        windowMs: Math.max(1000, Math.floor(configured?.windowMs ?? DEFAULT_RUNTIME_FALLBACK_TRUST_WINDOW_MS)),
+        dedupeWindowMs: Math.max(0, Math.floor(configured?.dedupeWindowMs ?? DEFAULT_RUNTIME_FALLBACK_TRUST_DEDUPE_WINDOW_MS))
+    };
+}
+function createRuntimeFallbackSignalRuntimeState() {
+    return {
+        rateLimitBySource: new Map(),
+        dedupeByFingerprint: new Map()
+    };
+}
+function cleanupRuntimeFallbackSignalRuntimeState(now, runtimeState, trustPolicy) {
+    const dedupeExpiryMs = Math.max(trustPolicy.dedupeWindowMs, trustPolicy.windowMs, 1000);
+    runtimeState.dedupeByFingerprint.forEach((lastSeenAt, fingerprint)=>{
+        if (now - lastSeenAt > dedupeExpiryMs) runtimeState.dedupeByFingerprint.delete(fingerprint);
+    });
+    runtimeState.rateLimitBySource.forEach((state, source)=>{
+        if (now - state.windowStartedAt > 2 * trustPolicy.windowMs) runtimeState.rateLimitBySource.delete(source);
+    });
+}
+function enforceRuntimeFallbackSignalTrustPolicy(payload, runtimeSignalContext, source = {}) {
+    const { trustPolicy, runtimeState } = runtimeSignalContext;
+    const now = Date.now();
+    cleanupRuntimeFallbackSignalRuntimeState(now, runtimeState, trustPolicy);
+    const appName = normalizeRuntimeSignalAppName(payload);
+    const entryOrigin = normalizeRuntimeSignalOrigin(payload.entry);
+    const runtimeDigest = normalizeRuntimeSignalRuntimeDigest(payload);
+    if (trustPolicy.allowedApps.length > 0 && !trustPolicy.allowedApps.includes(appName)) throw createRuntimeSignalError(`runtime fallback signal app "${appName}" is not trusted`, 'UNTRUSTED_SOURCE');
+    if (trustPolicy.allowedEntryOrigins.length > 0) {
+        if (!entryOrigin || !trustPolicy.allowedEntryOrigins.includes(entryOrigin)) throw createRuntimeSignalError(`runtime fallback signal entry origin "${entryOrigin || 'unknown'}" is not trusted`, 'UNTRUSTED_SOURCE');
+    }
+    const expectedDigest = trustPolicy.expectedRuntimeDigests[appName];
+    if (expectedDigest && runtimeDigest !== expectedDigest) throw createRuntimeSignalError(`runtime fallback runtimeDigest mismatch for app "${appName}"`, 'UNTRUSTED_SOURCE');
+    if (trustPolicy.enforceRuntimeDigest && !runtimeDigest) throw createRuntimeSignalError(`runtime fallback signal for app "${appName}" is missing runtimeDigest`, 'UNTRUSTED_SOURCE');
+    const dedupeFingerprint = JSON.stringify({
+        appName,
+        entryOrigin: entryOrigin || 'unknown',
+        reason: payload.reason || 'runtime_fallback',
+        phase: payload.phase || 'unknown',
+        runtimeDigest: runtimeDigest || 'unknown'
+    });
+    const dedupeWindowMs = trustPolicy.dedupeWindowMs;
+    if (dedupeWindowMs > 0) {
+        const lastSeenAt = runtimeState.dedupeByFingerprint.get(dedupeFingerprint);
+        runtimeState.dedupeByFingerprint.set(dedupeFingerprint, now);
+        if ('number' == typeof lastSeenAt && now - lastSeenAt <= dedupeWindowMs) return {
+            deduped: true
+        };
+    } else runtimeState.dedupeByFingerprint.set(dedupeFingerprint, now);
+    const remoteAddress = source.remoteAddress?.trim();
+    const sourceKey = remoteAddress || 'unknown-remote';
+    const rateState = runtimeState.rateLimitBySource.get(sourceKey);
+    if (!rateState || now - rateState.windowStartedAt > trustPolicy.windowMs) runtimeState.rateLimitBySource.set(sourceKey, {
+        count: 1,
+        windowStartedAt: now
+    });
+    else {
+        if (rateState.count >= trustPolicy.maxSignalsPerWindow) throw createRuntimeSignalError(`runtime fallback signal rate-limited for source "${sourceKey}"`, 'RATE_LIMITED');
+        rateState.count += 1;
+    }
+    return {
+        deduped: false
+    };
+}
+async function parseRuntimeFallbackSignalPayload(c, maxBodyBytes) {
+    const contentLengthHeader = c.req.header('content-length');
+    if (contentLengthHeader) {
+        const contentLength = Number.parseInt(contentLengthHeader, 10);
+        if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) throw createRuntimeSignalError('runtime fallback signal payload too large', 'PAYLOAD_TOO_LARGE');
+    }
+    const rawBody = await c.req.raw.text();
+    const payload = parseRuntimeFallbackSignalPayloadFromRawBody(rawBody, maxBodyBytes);
+    return {
+        rawBody,
+        payload
+    };
+}
+function parseRuntimeFallbackSignalPayloadFromRawBody(rawBody, maxBodyBytes) {
+    if (!rawBody || 0 === rawBody.trim().length) throw createRuntimeSignalError('runtime fallback signal body is empty', 'INVALID_PAYLOAD');
+    if (getUtf8ByteLength(rawBody) > maxBodyBytes) throw createRuntimeSignalError('runtime fallback signal payload too large', 'PAYLOAD_TOO_LARGE');
+    let payload;
+    try {
+        payload = JSON.parse(rawBody);
+    } catch (_error) {
+        throw createRuntimeSignalError('runtime fallback signal body must be valid JSON', 'INVALID_PAYLOAD');
+    }
+    if (!payload || 'object' != typeof payload || Array.isArray(payload)) throw createRuntimeSignalError('runtime fallback signal body must be a JSON object', 'INVALID_PAYLOAD');
+    return payload;
+}
+function getRuntimeSignalErrorStatusCode(signalError) {
+    if ('PAYLOAD_TOO_LARGE' === signalError.code) return 413;
+    if ('INVALID_PAYLOAD' === signalError.code) return 400;
+    if ('UNAUTHORIZED' === signalError.code) return 401;
+    if ('RATE_LIMITED' === signalError.code) return 429;
+    if ('UNTRUSTED_SOURCE' === signalError.code) return 403;
+    return 500;
+}
+async function persistRuntimeFallbackContractGate(payload, runtimeSignalConfig) {
+    const now = Date.now();
+    const gateSnapshotStore = await runtimeSignalConfig.gateSnapshotStore;
+    const snapshot = await gateSnapshotStore.readSnapshot() || {};
+    const existingGates = snapshot.gates && 'object' == typeof snapshot.gates ? snapshot.gates : {};
+    const reason = 'string' == typeof payload.reason ? payload.reason : 'runtime_fallback';
+    const phase = 'string' == typeof payload.phase ? payload.phase : 'unknown';
+    const appName = 'string' == typeof payload.appName ? payload.appName : 'unknown';
+    const entry = 'string' == typeof payload.entry ? payload.entry : void 0;
+    snapshot.schemaVersion = 'number' == typeof snapshot.schemaVersion ? snapshot.schemaVersion : CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION;
+    snapshot.updatedAt = now;
+    snapshot.gates = {
+        ...existingGates,
+        [runtimeSignalConfig.gateName]: {
+            passed: false,
+            reason: `runtime_fallback:${reason} phase=${phase} app=${appName}${entry ? ` entry=${entry}` : ''}`,
+            updatedAt: now,
+            expiresAt: now + runtimeSignalConfig.failureHoldMs,
+            source: 'runtime-mf-fallback-signal',
+            metadata: payload
+        }
+    };
+    await gateSnapshotStore.writeSnapshot(snapshot);
+}
+export { DEFAULT_RUNTIME_FALLBACK_FAILURE_HOLD_MS, DEFAULT_RUNTIME_FALLBACK_GATE_NAME, DEFAULT_RUNTIME_FALLBACK_MAX_BODY_BYTES, DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, DEFAULT_RUNTIME_STATUS_ENDPOINT, createRuntimeFallbackSignalRuntimeState, createRuntimeSignalError, enforceRuntimeFallbackSignalAuth, enforceRuntimeFallbackSignalAuthToken, enforceRuntimeFallbackSignalTrustPolicy, getRuntimeSignalErrorStatusCode, normalizeRequiredRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackTrustPolicy, parseRuntimeFallbackSignalPayload, parseRuntimeFallbackSignalPayloadFromRawBody, persistRuntimeFallbackContractGate, resolveRuntimeFallbackSignalEndpoint };

package/dist/esm-node/telemetry.mjs

@@ -0,0 +1,276 @@
+import "node:module";
+import { parseTraceparent } from "@modern-js/create-request/server";
+import { logger } from "@modern-js/utils";
+import { ContractGateAutopilot } from "./contractGateAutopilot.mjs";
+import { DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH, resolveContractGateSnapshotPath, resolveContractGateSnapshotStore } from "./contractGateSnapshotStore.mjs";
+import { parseServerRuntimeExtensionsEnv } from "./env.mjs";
+import { DEFAULT_RUNTIME_FALLBACK_FAILURE_HOLD_MS, DEFAULT_RUNTIME_FALLBACK_GATE_NAME, DEFAULT_RUNTIME_FALLBACK_MAX_BODY_BYTES, DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, DEFAULT_RUNTIME_STATUS_ENDPOINT, createRuntimeFallbackSignalRuntimeState, createRuntimeSignalError, enforceRuntimeFallbackSignalAuth, enforceRuntimeFallbackSignalAuthToken, enforceRuntimeFallbackSignalTrustPolicy, getRuntimeSignalErrorStatusCode, normalizeRequiredRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackTrustPolicy, parseRuntimeFallbackSignalPayload, parseRuntimeFallbackSignalPayloadFromRawBody, persistRuntimeFallbackContractGate, resolveRuntimeFallbackSignalEndpoint } from "./runtimeFallbackSignal.mjs";
+import { TelemetryCanaryOrchestrator, TelemetryRegistry, TelemetryStartupHealthError, createOtlpTelemetryExporter, createTelemetryAwareMetrics, createVictoriaMetricsTelemetryExporter, maybeWarnLegacyOtlpEndpoint, toTelemetryEnvelope } from "./telemetryCore.mjs";
+function emitCanaryDecisionMetric(registry, decision, action) {
+    try {
+        registry.enqueueMetric({
+            name: `telemetry.canary.${action}`,
+            value: 1,
+            unit: 'count',
+            tags: {
+                action,
+                state: decision.state,
+                failures: String(decision.failures.length)
+            }
+        });
+    } catch (_error) {}
+}
+const hasEnabledTelemetryExporters = (config)=>Boolean(config?.exporters?.otlp?.enabled || config?.exporters?.victoriaMetrics?.enabled);
+const resolveTelemetrySloOptions = (sloConfig, warnSink = (message)=>logger.warn(message))=>({
+        queueUtilizationWarnThreshold: sloConfig?.queueUtilizationWarnThreshold,
+        queueDroppedWarnThreshold: sloConfig?.queueDroppedWarnThreshold,
+        alertCooldownMs: sloConfig?.alertCooldownMs,
+        onAlert: (alert)=>{
+            warnSink(`[telemetry.slo] ${alert.type} threshold=${alert.threshold} value=${alert.value} depth=${alert.queueDepth}/${alert.queueCapacity} dropped=${alert.totalDropped}`);
+        }
+    });
+const getRequestRemoteAddress = (c)=>{
+    const env = c.env;
+    const remoteAddress = env?.node?.req?.socket?.remoteAddress;
+    return 'string' == typeof remoteAddress && remoteAddress.trim().length > 0 ? remoteAddress.trim() : void 0;
+};
+const activeTelemetryLaneClosers = new Set();
+let telemetryBeforeExitHookInstalled = false;
+const ensureTelemetryBeforeExitHook = ()=>{
+    if (telemetryBeforeExitHookInstalled) return;
+    telemetryBeforeExitHookInstalled = true;
+    process.on('beforeExit', ()=>{
+        for (const close of [
+            ...activeTelemetryLaneClosers
+        ])close();
+    });
+};
+const injectTelemetryPlugin = ()=>({
+        name: '@modern-js/inject-telemetry',
+        setup (api) {
+            const serverConfig = api.getServerConfig();
+            const telemetryConfig = serverConfig?.server?.telemetry;
+            if (!telemetryConfig) return;
+            if (true !== telemetryConfig.enabled && !hasEnabledTelemetryExporters(telemetryConfig)) return;
+            const { middlewares, metaName, appDirectory } = api.getServerContext();
+            const serviceName = telemetryConfig.service || metaName || 'modern-js';
+            const moduleName = telemetryConfig.module || 'server';
+            const environmentName = telemetryConfig.environment || parseServerRuntimeExtensionsEnv().environmentName;
+            const registry = new TelemetryRegistry({
+                service: serviceName,
+                module: moduleName,
+                environment: environmentName,
+                samplingRate: telemetryConfig.samplingRate,
+                flushIntervalMs: telemetryConfig.flushIntervalMs,
+                maxBatchSize: telemetryConfig.maxBatchSize,
+                maxQueueSize: telemetryConfig.maxQueueSize,
+                redactionKeys: telemetryConfig.redactionKeys,
+                slo: resolveTelemetrySloOptions(telemetryConfig.slo)
+            });
+            let canaryOrchestrator;
+            let contractGateAutopilot;
+            let runtimeFallbackSignalConfig;
+            let runtimeStatusAuthConfig;
+            let gateSnapshotStorePromise;
+            const canaryConfig = telemetryConfig.canary;
+            if (canaryConfig?.enabled) {
+                const contractGates = canaryConfig.contractGates;
+                canaryOrchestrator = new TelemetryCanaryOrchestrator({
+                    registry,
+                    evaluationIntervalMs: canaryConfig.evaluationIntervalMs,
+                    minConsecutiveHealthyEvaluations: canaryConfig.minConsecutiveHealthyEvaluations,
+                    rollbackConsecutiveFailures: canaryConfig.rollbackConsecutiveFailures,
+                    maxQueueUtilization: canaryConfig.maxQueueUtilization,
+                    maxTotalDropped: canaryConfig.maxTotalDropped,
+                    maxUnhealthyExporters: canaryConfig.maxUnhealthyExporters,
+                    requiredContractGates: Object.keys(contractGates || {}),
+                    onPromote: (decision)=>{
+                        emitCanaryDecisionMetric(registry, decision, 'promote');
+                    },
+                    onRollback: (decision)=>{
+                        emitCanaryDecisionMetric(registry, decision, 'rollback');
+                    }
+                });
+                if (contractGates) canaryOrchestrator.setContractGates(contractGates);
+                const autopilotEnabled = canaryConfig.autopilot?.enabled ?? true;
+                if (autopilotEnabled) {
+                    const gateSnapshotPath = resolveContractGateSnapshotPath(appDirectory, canaryConfig.autopilot?.gateSnapshotPath);
+                    gateSnapshotStorePromise = resolveContractGateSnapshotStore({
+                        appDirectory,
+                        gateSnapshotPath: gateSnapshotPath || DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH,
+                        stateStore: canaryConfig.autopilot?.stateStore
+                    });
+                    const runtimeSignalConfig = canaryConfig.autopilot?.runtimeFallbackSignal;
+                    const runtimeSignalEnabled = runtimeSignalConfig?.enabled === true;
+                    if (runtimeSignalEnabled && gateSnapshotStorePromise) runtimeFallbackSignalConfig = {
+                        endpoint: resolveRuntimeFallbackSignalEndpoint(runtimeSignalConfig?.endpoint),
+                        gateName: runtimeSignalConfig?.gateName?.trim() || DEFAULT_RUNTIME_FALLBACK_GATE_NAME,
+                        gateSnapshotStore: gateSnapshotStorePromise,
+                        failureHoldMs: Math.max(1000, runtimeSignalConfig?.failureHoldMs ?? DEFAULT_RUNTIME_FALLBACK_FAILURE_HOLD_MS),
+                        maxBodyBytes: Math.max(512, runtimeSignalConfig?.maxBodyBytes ?? DEFAULT_RUNTIME_FALLBACK_MAX_BODY_BYTES),
+                        auth: normalizeRequiredRuntimeFallbackSignalAuthConfig(runtimeSignalConfig?.auth),
+                        trustPolicy: normalizeRuntimeFallbackTrustPolicy(runtimeSignalConfig?.trustPolicy),
+                        runtimeState: createRuntimeFallbackSignalRuntimeState()
+                    };
+                }
+                runtimeStatusAuthConfig = runtimeFallbackSignalConfig?.auth ?? normalizeRuntimeFallbackSignalAuthConfig(canaryConfig.autopilot?.runtimeFallbackSignal?.auth);
+            }
+            if (runtimeFallbackSignalConfig) {
+                const signalConfig = runtimeFallbackSignalConfig;
+                middlewares.push({
+                    name: 'telemetry-runtime-fallback-signal',
+                    path: signalConfig.endpoint,
+                    method: 'post',
+                    order: 'pre',
+                    handler: async (c)=>{
+                        try {
+                            enforceRuntimeFallbackSignalAuth(c, signalConfig);
+                            const { payload } = await parseRuntimeFallbackSignalPayload(c, signalConfig.maxBodyBytes);
+                            const trustResult = enforceRuntimeFallbackSignalTrustPolicy(payload, signalConfig, {
+                                remoteAddress: getRequestRemoteAddress(c)
+                            });
+                            if (trustResult.deduped) return c.json({
+                                ok: true,
+                                deduped: true
+                            }, 202);
+                            await persistRuntimeFallbackContractGate(payload, signalConfig);
+                            return c.json({
+                                ok: true
+                            }, 202);
+                        } catch (error) {
+                            const signalError = error;
+                            const status = getRuntimeSignalErrorStatusCode(signalError);
+                            return c.json({
+                                ok: false,
+                                error: signalError instanceof Error ? signalError.message : String(signalError)
+                            }, status);
+                        }
+                    }
+                });
+            }
+            middlewares.push({
+                name: 'telemetry-runtime-status',
+                path: DEFAULT_RUNTIME_STATUS_ENDPOINT,
+                method: 'get',
+                order: 'pre',
+                handler: async (c)=>{
+                    try {
+                        if (!runtimeStatusAuthConfig?.enabled) return c.json({
+                            ok: true,
+                            timestamp: Date.now()
+                        });
+                        enforceRuntimeFallbackSignalAuthToken(c.req.header(runtimeStatusAuthConfig.headerName), runtimeStatusAuthConfig);
+                        return c.json({
+                            ok: true,
+                            timestamp: Date.now(),
+                            telemetry: {
+                                queueStats: registry.getQueueStats(),
+                                exporterHealth: registry.getExporterHealth()
+                            },
+                            canary: canaryOrchestrator ? {
+                                enabled: true,
+                                ...canaryOrchestrator.getStatusSnapshot()
+                            } : {
+                                enabled: false
+                            },
+                            runtimeFallbackSignal: runtimeFallbackSignalConfig ? {
+                                enabled: true,
+                                endpoint: runtimeFallbackSignalConfig.endpoint,
+                                gateName: runtimeFallbackSignalConfig.gateName,
+                                failureHoldMs: runtimeFallbackSignalConfig.failureHoldMs,
+                                maxBodyBytes: runtimeFallbackSignalConfig.maxBodyBytes,
+                                auth: {
+                                    enabled: runtimeFallbackSignalConfig.auth.enabled,
+                                    headerName: runtimeFallbackSignalConfig.auth.headerName
+                                },
+                                trustPolicy: {
+                                    allowedApps: runtimeFallbackSignalConfig.trustPolicy.allowedApps,
+                                    allowedEntryOrigins: runtimeFallbackSignalConfig.trustPolicy.allowedEntryOrigins,
+                                    enforceRuntimeDigest: runtimeFallbackSignalConfig.trustPolicy.enforceRuntimeDigest,
+                                    expectedRuntimeDigestsCount: Object.keys(runtimeFallbackSignalConfig.trustPolicy.expectedRuntimeDigests).length,
+                                    maxSignalsPerWindow: runtimeFallbackSignalConfig.trustPolicy.maxSignalsPerWindow,
+                                    windowMs: runtimeFallbackSignalConfig.trustPolicy.windowMs,
+                                    dedupeWindowMs: runtimeFallbackSignalConfig.trustPolicy.dedupeWindowMs
+                                }
+                            } : {
+                                enabled: false
+                            }
+                        });
+                    } catch (error) {
+                        const signalError = error;
+                        return c.json({
+                            ok: false,
+                            error: signalError instanceof Error ? signalError.message : String(signalError)
+                        }, getRuntimeSignalErrorStatusCode(signalError));
+                    }
+                }
+            });
+            middlewares.push({
+                name: 'inject-telemetry',
+                handler: async (c, next)=>{
+                    const monitors = c.get('monitors');
+                    if (monitors) {
+                        const traceContext = parseTraceparent(c.req.header('traceparent'));
+                        const monitor = (event)=>{
+                            registry.enqueue(toTelemetryEnvelope(event, {
+                                service: serviceName,
+                                module: moduleName,
+                                environment: environmentName,
+                                traceId: traceContext?.traceId,
+                                spanId: traceContext?.spanId,
+                                attributes: {
+                                    requestMethod: c.req.method,
+                                    requestPath: c.req.path
+                                }
+                            }));
+                        };
+                        monitors.push(monitor);
+                    }
+                    await next();
+                }
+            });
+            let telemetryLaneClosed = false;
+            const closeTelemetryLane = async ()=>{
+                if (telemetryLaneClosed) return;
+                telemetryLaneClosed = true;
+                activeTelemetryLaneClosers.delete(closeTelemetryLane);
+                contractGateAutopilot?.stop();
+                canaryOrchestrator?.stop();
+                await registry.shutdown();
+            };
+            let prepared = false;
+            api.onPrepare(async ()=>{
+                if (prepared) return;
+                prepared = true;
+                const { nodeServer } = api.getServerContext();
+                if (nodeServer && 'function' == typeof nodeServer.once) nodeServer.once('close', ()=>{
+                    closeTelemetryLane();
+                });
+                activeTelemetryLaneClosers.add(closeTelemetryLane);
+                ensureTelemetryBeforeExitHook();
+                if (telemetryConfig.exporters?.otlp?.enabled) {
+                    maybeWarnLegacyOtlpEndpoint(telemetryConfig.exporters.otlp.endpoint);
+                    await registry.register(createOtlpTelemetryExporter(telemetryConfig.exporters.otlp));
+                }
+                if (telemetryConfig.exporters?.victoriaMetrics?.enabled) await registry.register(createVictoriaMetricsTelemetryExporter(telemetryConfig.exporters.victoriaMetrics));
+                await registry.startupHealthCheck({
+                    failLoud: telemetryConfig.failLoudStartup ?? true
+                });
+                if (!canaryOrchestrator) return;
+                canaryOrchestrator.start();
+                if (gateSnapshotStorePromise) {
+                    const gateSnapshotStore = await gateSnapshotStorePromise;
+                    contractGateAutopilot = new ContractGateAutopilot({
+                        orchestrator: canaryOrchestrator,
+                        gateSnapshotPath: resolveContractGateSnapshotPath(appDirectory, canaryConfig?.autopilot?.gateSnapshotPath),
+                        gateSnapshotStore,
+                        pollIntervalMs: canaryConfig?.autopilot?.pollIntervalMs,
+                        gateStaleAfterMs: canaryConfig?.autopilot?.gateStaleAfterMs
+                    });
+                }
+                if (contractGateAutopilot) await contractGateAutopilot.start();
+                canaryOrchestrator.evaluate();
+            });
+        }
+    });
+export { DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, DEFAULT_RUNTIME_STATUS_ENDPOINT, TelemetryCanaryOrchestrator, TelemetryRegistry, TelemetryStartupHealthError, createOtlpTelemetryExporter, createRuntimeFallbackSignalRuntimeState, createRuntimeSignalError, createTelemetryAwareMetrics, createVictoriaMetricsTelemetryExporter, enforceRuntimeFallbackSignalAuthToken, enforceRuntimeFallbackSignalTrustPolicy, getRuntimeSignalErrorStatusCode, hasEnabledTelemetryExporters, injectTelemetryPlugin, normalizeRequiredRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackTrustPolicy, parseRuntimeFallbackSignalPayloadFromRawBody, resolveRuntimeFallbackSignalEndpoint, resolveTelemetrySloOptions };