@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/dist/telemetry/facade.js

@@ -0,0 +1,654 @@
+import { randomUUID as nodeRandomUUID } from "node:crypto";
+import { context, ROOT_CONTEXT, SpanKind, SpanStatusCode, TraceFlags, trace, } from "@opentelemetry/api";
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+import { claimTelemetryFirstStart, createTelemetryConsentGate, getTelemetrySnapshot, } from "../config/telemetry.js";
+import { getCurrentVersion } from "../utils/self-update.js";
+import { MAX_ACCOUNT_POOL_SIZE } from "./contracts.js";
+import { createPostHogTelemetryClient } from "./posthog-client.js";
+import { LOG_ATTRIBUTE_KEYS, SPAN_ATTRIBUTE_KEYS, reconstructAnalyticsEvent, sanitizeException, toOtelAttributes, } from "./privacy.js";
+import { flushTelemetryRuntimeWithin, isTelemetryRuntimeActive, shutdownTelemetryRuntimeWithin, startTelemetryRuntime, } from "./runtime.js";
+const HEARTBEAT_INTERVAL_MS = 60 * 60 * 1_000;
+const SCOPE = "cc-router";
+const PROXY_REQUEST_PATHS = new Set(["/v1/messages", "/v1/responses"]);
+export function runtimeMode() {
+    if (process.env["CC_ROUTER_SERVICE"] === "1")
+        return "service";
+    if (process.env["CC_ROUTER_DAEMON"] === "1")
+        return "daemon";
+    return "foreground";
+}
+function osFamily() {
+    switch (process.platform) {
+        case "darwin": return "macos";
+        case "linux": return "linux";
+        case "win32": return "windows";
+        default: return "other";
+    }
+}
+export function modelFamilyOf(model) {
+    const value = model.toLowerCase();
+    if (value.includes("fable"))
+        return "fable";
+    if (value.includes("sonnet"))
+        return "sonnet";
+    if (value.includes("opus"))
+        return "opus";
+    if (value.includes("haiku"))
+        return "haiku";
+    if (value.includes("codex") || value.startsWith("gpt-"))
+        return "codex";
+    return "other";
+}
+export function httpFailureReason(status) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 403)
+        return "forbidden";
+    if (status === 429)
+        return "rate_limited";
+    if (status >= 500)
+        return "upstream_5xx";
+    return "upstream_4xx";
+}
+export function httpOutcome(status) {
+    if (status === 429)
+        return "rate_limited";
+    if (status >= 400)
+        return "upstream_error";
+    return "complete";
+}
+function errorProperty(error, key) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    try {
+        return Object.getOwnPropertyDescriptor(error, key)?.value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Classify only explicit, allowlisted transport failures without parsing text. */
+export function classifyExpectedRuntimeFailure(error) {
+    const directCode = errorProperty(error, "code");
+    const causeCode = errorProperty(errorProperty(error, "cause"), "code");
+    const code = typeof directCode === "string" ? directCode : causeCode;
+    if (code === "ETIMEDOUT")
+        return "timeout";
+    if (["EAI_AGAIN", "ECONNREFUSED", "ECONNRESET", "ENETUNREACH", "ENOTFOUND", "EPIPE"]
+        .includes(String(code))) {
+        return "network_failure";
+    }
+    try {
+        if (error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+            return "timeout";
+        }
+    }
+    catch {
+        // Exotic thrown values remain unexpected.
+    }
+    return undefined;
+}
+function severityNumber(severity) {
+    switch (severity) {
+        case "info": return SeverityNumber.INFO;
+        case "warn": return SeverityNumber.WARN;
+        case "error": return SeverityNumber.ERROR;
+        case "fatal": return SeverityNumber.FATAL;
+    }
+}
+function isRandomUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function clampedAccountCount(value) {
+    if (!Number.isFinite(value))
+        return undefined;
+    return Math.max(0, Math.min(MAX_ACCOUNT_POOL_SIZE, Math.floor(value)));
+}
+function expectedSetupFailureOutcome(reason) {
+    switch (reason) {
+        case "unauthorized":
+        case "forbidden":
+        case "upstream_4xx":
+        case "upstream_5xx":
+        case "unexpected_response_shape":
+            return "upstream_error";
+        case "rate_limited": return "rate_limited";
+        case "timeout": return "timeout";
+        case "user_cancelled": return "cancelled";
+        case "other": return "other";
+        default: return undefined;
+    }
+}
+let sharedGate;
+let sharedAnalytics;
+function sharedConsentGate() {
+    return sharedGate ??= createTelemetryConsentGate(getTelemetrySnapshot, () => {
+        try {
+            sharedAnalytics?.discardPending();
+        }
+        catch { /* isolated */ }
+    });
+}
+/** Logs and analytics work without the proxy's tracing runtime. */
+function ensureRuntime() {
+    try {
+        if (isTelemetryRuntimeActive())
+            return;
+        startTelemetryRuntime({ tracing: false, runtimeMode: runtimeMode() });
+    }
+    catch {
+        // Telemetry transport failures never reach application code.
+    }
+}
+function spanAttributes(operation, attributes) {
+    return {
+        "cc_router.operation": operation,
+        ...toOtelAttributes(SPAN_ATTRIBUTE_KEYS, attributes),
+    };
+}
+function finalizeSpan(span, status, endTimeMs) {
+    try {
+        span.setStatus({ code: status === "error" ? SpanStatusCode.ERROR : SpanStatusCode.OK });
+    }
+    catch {
+        // Telemetry finalization never changes application behavior.
+    }
+    try {
+        span.end(endTimeMs);
+    }
+    catch {
+        // A broken tracer must not replace the callback value or error identity.
+    }
+}
+const NOOP_SPAN_HANDLE = {
+    annotate: () => undefined,
+    end: () => undefined,
+};
+const NOOP_ACTIVE_SPAN = {
+    annotate: () => undefined,
+    fail: () => undefined,
+};
+/**
+ * Start a closed-schema span whose lifetime is owned by an event-driven body.
+ * The handle never exposes the OTel span or accepts arbitrary attributes.
+ */
+export function startTelemetrySpan(operation, attributes) {
+    try {
+        if (!sharedConsentGate().getSnapshot())
+            return NOOP_SPAN_HANDLE;
+        const span = trace.getTracer(SCOPE).startSpan(operation, {
+            attributes: spanAttributes(operation, attributes),
+        });
+        let ended = false;
+        return {
+            annotate(next) {
+                if (ended)
+                    return;
+                try {
+                    span.setAttributes(toOtelAttributes(SPAN_ATTRIBUTE_KEYS, next));
+                }
+                catch {
+                    // Body telemetry never changes response handling.
+                }
+            },
+            end(status) {
+                if (ended)
+                    return;
+                ended = true;
+                finalizeSpan(span, status);
+            },
+        };
+    }
+    catch {
+        return NOOP_SPAN_HANDLE;
+    }
+}
+/**
+ * Run one closed runtime operation as the active span. The callback runs
+ * exactly once; a rejection or an explicit `span.fail()` marks the span failed.
+ */
+export function withTelemetrySpan(operation, attributes, callback) {
+    let started = false;
+    try {
+        if (!sharedConsentGate().getSnapshot())
+            return callback(NOOP_ACTIVE_SPAN);
+        return trace.getTracer(SCOPE).startActiveSpan(operation, { attributes: spanAttributes(operation, attributes) }, async (span) => {
+            started = true;
+            let failed = false;
+            let outcomeSet = false;
+            const handle = {
+                annotate(next) {
+                    if (next.outcome !== undefined)
+                        outcomeSet = true;
+                    try {
+                        span.setAttributes(toOtelAttributes(SPAN_ATTRIBUTE_KEYS, next));
+                    }
+                    catch { /* optional */ }
+                },
+                fail(next) {
+                    failed = true;
+                    if (next)
+                        handle.annotate(next);
+                    // A generic outcome only when no failure path classified one.
+                    if (!outcomeSet)
+                        handle.annotate({ outcome: "upstream_error" });
+                },
+            };
+            try {
+                const value = await callback(handle);
+                finalizeSpan(span, failed ? "error" : "ok");
+                return value;
+            }
+            catch (error) {
+                finalizeSpan(span, "error");
+                throw error;
+            }
+        });
+    }
+    catch (error) {
+        if (started)
+            return Promise.reject(error);
+        return callback(NOOP_ACTIVE_SPAN);
+    }
+}
+export function annotateActiveSpan(operation, attributes) {
+    try {
+        if (!sharedConsentGate().getSnapshot())
+            return;
+        trace.getActiveSpan()?.setAttributes(spanAttributes(operation, attributes));
+    }
+    catch {
+        // Span enrichment is optional.
+    }
+}
+/** How long a closed response's span waits for the route's final verdict. */
+const REQUEST_SPAN_SETTLE_GRACE_MS = 1_500;
+const requestSpans = new WeakMap();
+function endRequestSpan(state) {
+    if (state.ended)
+        return;
+    state.ended = true;
+    if (state.timer !== undefined)
+        clearTimeout(state.timer);
+    try {
+        state.span.setAttributes(toOtelAttributes(SPAN_ATTRIBUTE_KEYS, { httpStatusCode: state.response.statusCode }));
+    }
+    catch {
+        // Response telemetry never changes the response itself.
+    }
+    const failed = state.outcome !== undefined
+        ? state.outcome !== "complete"
+        : state.response.statusCode >= 500;
+    // The span ends when the response did, even if the verdict arrived later.
+    finalizeSpan(state.span, failed ? "error" : "ok", state.closedAt);
+}
+/**
+ * Record the route's final verdict for the request span. The HTTP status alone
+ * cannot tell a relayed stream that failed midway from a complete one, so the
+ * span stays open (bounded) until the route settles it or the grace expires.
+ */
+export function settleProxyRequestSpan(response, attributes) {
+    try {
+        const state = requestSpans.get(response);
+        if (!state || state.ended)
+            return;
+        state.span.setAttributes(toOtelAttributes(SPAN_ATTRIBUTE_KEYS, attributes));
+        if (attributes.outcome !== undefined)
+            state.outcome = attributes.outcome;
+        state.settled = true;
+        if (state.closedAt !== undefined)
+            endRequestSpan(state);
+    }
+    catch {
+        // Span enrichment is optional.
+    }
+}
+/** Wrap the two inference routes in a server span; every other route passes through. */
+export function telemetryRequestMiddleware() {
+    return (request, response, next) => {
+        let continued = false;
+        const proceed = () => {
+            if (continued)
+                return;
+            continued = true;
+            next();
+        };
+        try {
+            if (!PROXY_REQUEST_PATHS.has(request.path) || !sharedConsentGate().getSnapshot()) {
+                proceed();
+                return;
+            }
+            const attributes = {
+                ...(request.method === "GET" || request.method === "POST"
+                    ? { httpMethod: request.method }
+                    : {}),
+                route: request.path === "/v1/messages" ? "messages" : "responses",
+            };
+            trace.getTracer(SCOPE).startActiveSpan("proxy.request", { kind: SpanKind.SERVER, attributes: spanAttributes("proxy.request", attributes) }, span => {
+                const state = { span, response, ended: false, settled: false };
+                requestSpans.set(response, state);
+                const closed = () => {
+                    if (state.closedAt !== undefined)
+                        return;
+                    state.closedAt = Date.now();
+                    if (state.settled) {
+                        endRequestSpan(state);
+                        return;
+                    }
+                    state.timer = setTimeout(() => endRequestSpan(state), REQUEST_SPAN_SETTLE_GRACE_MS);
+                    state.timer.unref?.();
+                };
+                response.once("finish", closed);
+                response.once("close", closed);
+                proceed();
+            });
+        }
+        catch {
+            proceed();
+        }
+    };
+}
+export function createTelemetryFacade(dependencies = {}) {
+    const now = dependencies.now ?? Date.now;
+    const uuid = dependencies.randomUUID ?? nodeRandomUUID;
+    const getSnapshot = dependencies.getSnapshot;
+    let gate;
+    // Lazy: binding the consent generation must not read the state file at import.
+    const consent = () => gate ??= getSnapshot
+        ? createTelemetryConsentGate(getSnapshot, () => {
+            try {
+                dependencies.analytics?.discardPending();
+            }
+            catch { /* isolated */ }
+        })
+        : sharedConsentGate();
+    const immediate = new Set();
+    const analytics = () => {
+        if (dependencies.analytics)
+            return dependencies.analytics;
+        try {
+            // The gate (not the raw state reader) feeds the transport so queued
+            // batches are dropped after an opt-out, not just new captures.
+            return sharedAnalytics ??= createPostHogTelemetryClient({
+                getSnapshot: () => consent().getSnapshot(),
+            });
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const activeAnalytics = () => dependencies.analytics ?? sharedAnalytics;
+    const metadata = () => ({
+        serviceVersion: getCurrentVersion(),
+        osFamily: osFamily(),
+        runtimeMode: runtimeMode(),
+    });
+    const trackImmediate = (operation) => {
+        const contained = Promise.resolve(operation).catch(() => undefined);
+        immediate.add(contained);
+        void contained.then(() => { immediate.delete(contained); });
+    };
+    const boundedDeadline = (deadlineMs) => Number.isFinite(deadlineMs)
+        ? Math.max(0, Math.min(10_000, Math.floor(deadlineMs)))
+        : 0;
+    const settleWithin = async (operations, deadlineMs) => {
+        if (operations.length === 0)
+            return;
+        let timer;
+        await Promise.race([
+            Promise.allSettled(operations).then(() => undefined),
+            new Promise(resolve => {
+                timer = setTimeout(resolve, boundedDeadline(deadlineMs));
+                timer.unref?.();
+            }),
+        ]).catch(() => undefined).finally(() => clearTimeout(timer));
+    };
+    const emitLog = (body, severity, attributes) => {
+        try {
+            ensureRuntime();
+            const emit = () => {
+                logs.getLogger(SCOPE).emit({
+                    body,
+                    severityNumber: severityNumber(severity),
+                    severityText: severity.toUpperCase(),
+                    timestamp: now(),
+                    attributes: toOtelAttributes(LOG_ATTRIBUTE_KEYS, attributes),
+                });
+            };
+            const active = trace.getActiveSpan()?.spanContext();
+            // Trace correlation would drop this record when the active span is
+            // unsampled, so an unsampled parent is detached instead.
+            if (active && (active.traceFlags & TraceFlags.SAMPLED) !== 0)
+                emit();
+            else
+                context.with(ROOT_CONTEXT, emit);
+        }
+        catch {
+            // Remote logging is best effort only.
+        }
+    };
+    const captureAnalytics = (snapshot, event, properties, diagnosticId) => {
+        try {
+            ensureRuntime();
+            const safe = reconstructAnalyticsEvent({ event, properties }, {
+                installationId: snapshot.state.installId,
+                ...(diagnosticId === undefined ? {} : { diagnosticId }),
+            });
+            const client = safe && analytics();
+            if (safe && client)
+                client.captureAnalytics(safe, snapshot.state.consentGeneration);
+        }
+        catch {
+            // Application behavior never depends on telemetry capture.
+        }
+    };
+    const recordSafeLog = (input) => {
+        const snapshot = consent().getSnapshot();
+        if (!snapshot)
+            return;
+        const { severity, diagnosticId, ...attributes } = input;
+        emitLog("runtime.failure", severity, {
+            ...attributes,
+            ...metadata(),
+            diagnosticId: diagnosticId !== undefined && isRandomUuid(diagnosticId) ? diagnosticId : undefined,
+        });
+    };
+    const recordUnexpectedException = (error, exceptionContext, diagnosticId) => {
+        const snapshot = consent().getSnapshot();
+        if (!snapshot)
+            return undefined;
+        try {
+            const candidate = diagnosticId ?? uuid();
+            if (!isRandomUuid(candidate) || candidate === snapshot.state.installId)
+                return undefined;
+            const exception = sanitizeException(error, exceptionContext, {
+                installationId: snapshot.state.installId,
+                diagnosticId: candidate,
+            });
+            if (!exception)
+                return undefined;
+            if (exceptionContext.category === "runtime") {
+                // Raw detail stays local; only the correlation key is exported.
+                console.error(`[cc-router] Unexpected runtime failure (diagnostic ID: ${exception.diagnosticId})`, error);
+            }
+            const client = analytics();
+            if (client) {
+                if (exceptionContext.category === "setup") {
+                    trackImmediate(client.captureExceptionImmediate(exception, snapshot.state.consentGeneration));
+                }
+                else {
+                    client.captureException(exception, snapshot.state.consentGeneration);
+                }
+            }
+            return exception.diagnosticId;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /** Neither flush nor shutdown may outlive its deadline or reject. */
+    const settleTelemetry = async (kind, deadlineMs) => {
+        try {
+            if (!consent().getSnapshot()) {
+                try {
+                    activeAnalytics()?.discardPending();
+                }
+                catch { /* isolated */ }
+            }
+            else {
+                await settleWithin([...immediate], deadlineMs);
+            }
+            const client = activeAnalytics();
+            await Promise.all([
+                (kind === "flush" ? client?.flushWithin(deadlineMs) : client?.shutdownWithin(deadlineMs))
+                    ?.catch(() => undefined),
+                (kind === "flush"
+                    ? flushTelemetryRuntimeWithin(deadlineMs)
+                    : shutdownTelemetryRuntimeWithin(deadlineMs)).catch(() => undefined),
+            ]);
+        }
+        catch {
+            // Telemetry lifecycle failures never change application behavior.
+        }
+    };
+    const setupProperties = (input, extra = {}) => ({ ...input, ...extra, ...metadata() });
+    return {
+        recordApplicationStart() {
+            try {
+                const current = consent().getSnapshot();
+                const claimed = claimTelemetryFirstStart();
+                if (!current || !claimed?.enabled)
+                    return;
+                if (current.state.installId !== claimed.state.installId)
+                    return;
+                if (current.state.consentGeneration !== claimed.state.consentGeneration)
+                    return;
+                captureAnalytics(claimed, "app.first_start", metadata());
+            }
+            catch {
+                // First-start attribution never affects CLI startup.
+            }
+        },
+        recordProxyStarted(accountCount) {
+            const snapshot = consent().getSnapshot();
+            if (!snapshot)
+                return;
+            captureAnalytics(snapshot, "proxy.started", {
+                ...metadata(),
+                accountPoolSize: clampedAccountCount(accountCount),
+            });
+        },
+        startProxyHeartbeat(getAccountCount) {
+            if (!consent().getSnapshot())
+                return;
+            try {
+                const timer = setInterval(() => {
+                    try {
+                        const snapshot = consent().getSnapshot();
+                        if (!snapshot)
+                            return;
+                        captureAnalytics(snapshot, "proxy.heartbeat", {
+                            ...metadata(),
+                            accountPoolSize: clampedAccountCount(getAccountCount()),
+                        });
+                    }
+                    catch {
+                        // Timer callbacks remain failure-isolated.
+                    }
+                }, HEARTBEAT_INTERVAL_MS);
+                timer.unref?.();
+            }
+            catch {
+                // Failure to schedule telemetry must not affect proxy startup.
+            }
+        },
+        recordSafeLog,
+        recordUpstreamStatus(operation, provider, httpStatusCode, extra) {
+            recordSafeLog({
+                operation,
+                provider,
+                severity: "warn",
+                reason: httpFailureReason(httpStatusCode),
+                outcome: httpOutcome(httpStatusCode),
+                httpStatusCode,
+                attempt: extra?.attempt,
+                operationDurationMs: extra?.durationMs,
+            });
+        },
+        recordRuntimeError(error, errorContext, extra) {
+            const expected = classifyExpectedRuntimeFailure(error);
+            if (!expected) {
+                recordUnexpectedException(error, {
+                    category: "runtime",
+                    reason: "other",
+                    operation: errorContext.operation,
+                    provider: errorContext.provider,
+                    runtimeMode: runtimeMode(),
+                });
+                return;
+            }
+            recordSafeLog({
+                operation: errorContext.operation,
+                provider: errorContext.provider,
+                severity: "error",
+                reason: expected,
+                outcome: expected === "timeout" ? "timeout" : "upstream_error",
+                attempt: extra?.attempt,
+                operationDurationMs: extra?.durationMs,
+            });
+        },
+        recordUnexpectedException,
+        recordSetupStage(input) {
+            const snapshot = consent().getSnapshot();
+            if (!snapshot)
+                return;
+            const properties = setupProperties(input);
+            emitLog("account.setup.diagnostic", "info", properties);
+            captureAnalytics(snapshot, input.stage === "attempt_start" ? "account_setup.started" : "account_setup.stage_completed", properties, input.diagnosticId);
+        },
+        recordSetupStageFailure(input) {
+            if (!consent().getSnapshot())
+                return;
+            const outcome = expectedSetupFailureOutcome(input.reason);
+            emitLog("account.setup.diagnostic", "warn", setupProperties(input, outcome === undefined ? {} : { outcome }));
+        },
+        recordSetupResult(input) {
+            const snapshot = consent().getSnapshot();
+            if (!snapshot)
+                return;
+            const cancelled = input.result === "cancelled";
+            const properties = setupProperties({
+                ...input,
+                stage: cancelled ? "cancellation" : "success",
+                reason: cancelled ? "user_cancelled" : undefined,
+            }, { outcome: cancelled ? "cancelled" : "complete" });
+            emitLog("account.setup.diagnostic", "info", properties);
+            captureAnalytics(snapshot, cancelled ? "account_setup.cancelled" : "account_setup.succeeded", properties, input.diagnosticId);
+        },
+        recordExpectedSetupFailure(input) {
+            const snapshot = consent().getSnapshot();
+            if (!snapshot)
+                return;
+            const outcome = expectedSetupFailureOutcome(input.reason);
+            const properties = setupProperties(input, outcome === undefined ? {} : { outcome });
+            emitLog("account.setup.diagnostic", "warn", properties);
+            captureAnalytics(snapshot, "account_setup.failed", properties, input.diagnosticId);
+        },
+        flushTelemetryWithin: (deadlineMs) => settleTelemetry("flush", deadlineMs),
+        shutdownTelemetryWithin: (deadlineMs) => settleTelemetry("shutdown", deadlineMs),
+    };
+}
+const telemetry = createTelemetryFacade();
+export const recordApplicationStart = telemetry.recordApplicationStart;
+export const recordProxyStarted = telemetry.recordProxyStarted;
+export const startProxyHeartbeat = telemetry.startProxyHeartbeat;
+export const recordSafeLog = telemetry.recordSafeLog;
+export const recordUpstreamStatus = telemetry.recordUpstreamStatus;
+export const recordRuntimeError = telemetry.recordRuntimeError;
+export const recordUnexpectedException = telemetry.recordUnexpectedException;
+export const recordSetupStage = telemetry.recordSetupStage;
+export const recordSetupStageFailure = telemetry.recordSetupStageFailure;
+export const recordSetupResult = telemetry.recordSetupResult;
+export const recordExpectedSetupFailure = telemetry.recordExpectedSetupFailure;
+export const flushTelemetryWithin = telemetry.flushTelemetryWithin;
+export const shutdownTelemetryWithin = telemetry.shutdownTelemetryWithin;