@veryfront/ext-content-mdx 0.1.985

package/esm/src/observability/tracing/api-shim.js

@@ -0,0 +1,241 @@
+/**
+ * Thin in-process shim for `@opentelemetry/api`.
+ *
+ * Core files that previously imported directly from `@opentelemetry/api` now
+ * import from this module.  When the `ext-observability-opentelemetry` extension is present
+ * the real SDK provider is wired in via `setGlobalTracerProvider`; otherwise
+ * every call falls back to a no-op implementation so the core boots without the
+ * extension installed.
+ *
+ * **Tracing types and constants** (exported for call-site use):
+ *   `Span`, `Tracer`, `TracerProvider`, `Context`, `TextMapPropagator`
+ *   `SpanKind`, `SpanStatusCode`
+ *
+ * **Metrics types** (re-exported structural shapes for the metrics subsystem;
+ * not backed by a live SDK — the metrics subsystem is wired separately):
+ *   `Meter`, `Counter`, `Histogram`, `ObservableGauge`, `UpDownCounter`,
+ *   `ObservableResult`
+ *
+ * @module observability/tracing/api-shim
+ */
+// ---------------------------------------------------------------------------
+// Span kind + status constants
+// ---------------------------------------------------------------------------
+export const SpanKind = {
+    INTERNAL: 0,
+    SERVER: 1,
+    CLIENT: 2,
+    PRODUCER: 3,
+    CONSUMER: 4,
+};
+export const SpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+// ---------------------------------------------------------------------------
+// No-op provider (default when ext-observability-opentelemetry is not installed)
+// ---------------------------------------------------------------------------
+function createNoopContext() {
+    return {
+        getValue: () => undefined,
+        setValue(_key, _value) {
+            return this;
+        },
+        deleteValue(_key) {
+            return this;
+        },
+    };
+}
+const NOOP_CONTEXT = createNoopContext();
+const NOOP_SPAN_CONTEXT = {
+    traceId: "00000000000000000000000000000000",
+    spanId: "0000000000000000",
+    traceFlags: 0,
+};
+const NOOP_SPAN = {
+    setAttribute() {
+        return NOOP_SPAN;
+    },
+    setAttributes() {
+        return NOOP_SPAN;
+    },
+    setStatus() {
+        return NOOP_SPAN;
+    },
+    recordException() { },
+    addEvent() {
+        return NOOP_SPAN;
+    },
+    end() { },
+    spanContext() {
+        return NOOP_SPAN_CONTEXT;
+    },
+    updateName() { },
+};
+function createNoopTracer() {
+    return {
+        startSpan() {
+            return NOOP_SPAN;
+        },
+        startActiveSpan(_name, optionsOrFn, contextOrFn, fn) {
+            const callback = typeof optionsOrFn === "function"
+                ? optionsOrFn
+                : typeof contextOrFn === "function"
+                    ? contextOrFn
+                    : fn;
+            return callback(NOOP_SPAN);
+        },
+    };
+}
+function createNoopProvider() {
+    const noopTracer = createNoopTracer();
+    return { getTracer: () => noopTracer };
+}
+// ---------------------------------------------------------------------------
+// Global provider state
+// ---------------------------------------------------------------------------
+let _provider = createNoopProvider();
+let _providerRevision = 0;
+let _activeContext = NOOP_CONTEXT;
+let _propagator = null;
+/**
+ * Optional accessor for the currently active span. Wired by
+ * ext-observability-opentelemetry (via `setGlobalActiveSpanAccessor`) so `trace.getActiveSpan()`
+ * and `trace.getSpan()` return the real SDK span once the extension is active.
+ */
+let _activeSpanAccessor = null;
+/**
+ * Register the real OTel trace API's span accessors. Called by the
+ * ext-observability-opentelemetry extension after it wires the SDK so that the shim's
+ * `trace.getActiveSpan()` / `trace.getSpan()` can return real spans.
+ */
+export function setGlobalActiveSpanAccessor(accessor) {
+    _activeSpanAccessor = accessor;
+}
+/**
+ * Wire in the real SDK TracerProvider.
+ * Called from `src/server/bootstrap.ts` after `orchestrateExtensions()` runs.
+ */
+export function setGlobalTracerProvider(p) {
+    _provider = p;
+    _providerRevision++;
+}
+export function getGlobalTracerProvider() {
+    return _provider;
+}
+export function getTracerProviderRevision() {
+    return _providerRevision;
+}
+/**
+ * Get a tracer from the active provider.
+ * Returns the no-op tracer when ext-observability-opentelemetry is not installed.
+ */
+export function getTracer(name, version) {
+    return _provider.getTracer(name, version);
+}
+// ---------------------------------------------------------------------------
+// Context API
+// ---------------------------------------------------------------------------
+export const context = {
+    active() {
+        return _activeContext;
+    },
+    with(ctx, fn) {
+        const prev = _activeContext;
+        _activeContext = ctx;
+        try {
+            return fn();
+        }
+        finally {
+            _activeContext = prev;
+        }
+    },
+    setGlobalContextManager(_mgr) {
+        // no-op in shim; real SDK sets this via the real OTel API
+    },
+};
+// ---------------------------------------------------------------------------
+// Trace API (simplified subset used by core)
+// ---------------------------------------------------------------------------
+export const trace = {
+    getTracer(name, version) {
+        return _provider.getTracer(name, version);
+    },
+    setGlobalTracerProvider(p) {
+        _provider = p;
+        _providerRevision++;
+    },
+    getGlobalTracerProvider() {
+        return _provider;
+    },
+    setSpan(ctx, _span) {
+        return ctx;
+    },
+    getSpan(ctx) {
+        return _activeSpanAccessor?.getSpan(ctx);
+    },
+    getActiveSpan() {
+        return _activeSpanAccessor?.getActiveSpan();
+    },
+};
+// ---------------------------------------------------------------------------
+// Propagation API
+// ---------------------------------------------------------------------------
+export const propagation = {
+    setGlobalPropagator(p) {
+        _propagator = p;
+    },
+    extract(ctx, carrier, getter) {
+        if (!_propagator)
+            return ctx;
+        return _propagator.extract(ctx, carrier, getter);
+    },
+    inject(ctx, carrier, setter) {
+        if (!_propagator)
+            return;
+        _propagator.inject(ctx, carrier, setter);
+    },
+};
+// ---------------------------------------------------------------------------
+// defaultTextMapGetter / defaultTextMapSetter (used by proxy/tracing.ts)
+// ---------------------------------------------------------------------------
+export const defaultTextMapGetter = {
+    keys(carrier) {
+        return Object.keys(carrier);
+    },
+    get(carrier, key) {
+        return carrier[key];
+    },
+};
+export const defaultTextMapSetter = {
+    set(carrier, key, value) {
+        carrier[key] = value;
+    },
+};
+// ---------------------------------------------------------------------------
+// Metrics API registry (injected by ext-observability-opentelemetry when active)
+// ---------------------------------------------------------------------------
+let _metricsApi = null;
+/**
+ * Register the OTel Metrics API (from the SDK).
+ * Called by ext-observability-opentelemetry in its setup hook so the metrics subsystem
+ * can use `getMeter()` when available.
+ */
+export function setGlobalMetricsAPI(api) {
+    _metricsApi = api;
+}
+export function getGlobalMetricsAPI() {
+    return _metricsApi;
+}
+// ---------------------------------------------------------------------------
+// Reset for tests
+// ---------------------------------------------------------------------------
+export function _resetShimForTests() {
+    _provider = createNoopProvider();
+    _providerRevision++;
+    _activeContext = NOOP_CONTEXT;
+    _propagator = null;
+    _metricsApi = null;
+    _activeSpanAccessor = null;
+}

package/esm/src/observability/tracing/otlp-setup.d.ts

@@ -0,0 +1,56 @@
+/**************************
+ * OpenTelemetry OTLP Setup
+ *
+ * Thin wrapper that delegates to the `ext-observability-opentelemetry` extension via the
+ * `TracingExporter` contract.  When the extension is not installed, all span
+ * operations silently no-op.
+ *
+ * Reads configuration from environment variables:
+ * - OTEL_TRACES_ENABLED: "true" to enable tracing
+ * - OTEL_SERVICE_NAME: Service name for traces
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint
+ * - OTEL_EXPORTER_OTLP_HEADERS: Auth headers
+ **************************/
+import { type Context, type Span } from "./api-shim.js";
+/** Configuration used by otlpconfig. */
+export interface OTLPConfig {
+    serviceName: string;
+    endpoint: string;
+    headers?: Record<string, string>;
+    enabled: boolean;
+}
+/** Initialize OTLP tracing export. */
+export declare function initializeOTLP(): Promise<void>;
+/** Shut down OTLP tracing export. */
+export declare function shutdownOTLP(): Promise<void>;
+/** Check whether OTLP export is enabled. */
+export declare function isOTLPEnabled(): boolean;
+/** Initialize OTLP tracing with explicit API adapters. */
+export declare function initializeOTLPWithApis(): Promise<void>;
+/** Applies span. */
+export declare function withSpan<T>(name: string, fn: () => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+/** Applies span sync. */
+export declare function withSpanSync<T>(name: string, fn: () => T, attributes?: Record<string, string | number | boolean>): T;
+/** Context for extract. */
+export declare function extractContext(headers: Headers): Context | undefined;
+/** Context for inject. */
+export declare function injectContext(headers: Headers): void;
+/** Starts server span. */
+export declare function startServerSpan(method: string, path: string, parentContext?: unknown): {
+    span: Span;
+    context: Context;
+} | null;
+/** End an active server tracing span. */
+export declare function endServerSpan(span: unknown, statusCode: number, error?: Error): void;
+/** Sets span attributes. */
+export declare function setSpanAttributes(span: unknown, attributes: Record<string, string | number | boolean>): void;
+/** Sets active span attributes. */
+export declare function setActiveSpanAttributes(attributes: Record<string, string | number | boolean>): void;
+/** Context for with. */
+export declare function withContext<T>(spanContext: unknown, fn: () => Promise<T>): Promise<T>;
+/** Context for get trace. */
+export declare function getTraceContext(): {
+    traceId?: string;
+    spanId?: string;
+};
+//# sourceMappingURL=otlp-setup.d.ts.map

package/esm/src/observability/tracing/otlp-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-setup.d.ts","sourceRoot":"","sources":["../../../../src/src/observability/tracing/otlp-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;4BAY4B;AAI5B,OAAO,EACL,KAAK,OAAO,EAOZ,KAAK,IAAI,EAKV,MAAM,eAAe,CAAC;AAKvB,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AA6DD,sCAAsC;AACtC,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CASpD;AAED,qCAAqC;AACrC,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlD;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,0DAA0D;AAC1D,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE5D;AAcD,oBAAoB;AACpB,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED,yBAAyB;AACzB,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,CAAC,EACX,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,CAAC,CAoBH;AAED,2BAA2B;AAC3B,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAKpE;AAED,0BAA0B;AAC1B,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAIpD;AAED,0BAA0B;AAC1B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,OAAO,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CASzC;AAED,yCAAyC;AACzC,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAoBpF;AAED,4BAA4B;AAC5B,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACpD,IAAI,CAKN;AAED,mCAAmC;AACnC,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACpD,IAAI,CAKN;AAED,wBAAwB;AACxB,wBAAsB,WAAW,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE3F;AAED,6BAA6B;AAC7B,wBAAgB,eAAe,IAAI;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAMvE"}

package/esm/src/observability/tracing/otlp-setup.js

@@ -0,0 +1,206 @@
+/**************************
+ * OpenTelemetry OTLP Setup
+ *
+ * Thin wrapper that delegates to the `ext-observability-opentelemetry` extension via the
+ * `TracingExporter` contract.  When the extension is not installed, all span
+ * operations silently no-op.
+ *
+ * Reads configuration from environment variables:
+ * - OTEL_TRACES_ENABLED: "true" to enable tracing
+ * - OTEL_SERVICE_NAME: Service name for traces
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint
+ * - OTEL_EXPORTER_OTLP_HEADERS: Auth headers
+ **************************/
+import { isTruthyEnvValue } from "../../utils/constants/env.js";
+import { serverLogger } from "../../utils/logger/logger.js";
+import { context as shimContext, defaultTextMapGetter, defaultTextMapSetter, getTracer, getTracerProviderRevision, propagation as shimPropagation, SpanKind, SpanStatusCode, trace as shimTrace, } from "./api-shim.js";
+import { getHostTelemetryEnv } from "./telemetry-env.js";
+const logger = serverLogger.component("otel");
+function parseHeaders(headerString) {
+    if (!headerString)
+        return {};
+    if (headerString.startsWith("Basic "))
+        return { Authorization: headerString };
+    if (headerString.startsWith("Authorization=")) {
+        return { Authorization: headerString.substring("Authorization=".length) };
+    }
+    const headers = {};
+    for (const part of headerString.split(",")) {
+        const [key, ...valueParts] = part.split("=");
+        if (!key || valueParts.length === 0)
+            continue;
+        headers[key.trim()] = valueParts.join("=").trim();
+    }
+    return headers;
+}
+function getConfig() {
+    // Span helpers can run during module initialization and test setup, before
+    // bootstrap has loaded .env files. Read tracing env directly here so no-op
+    // spans do not force early EnvironmentConfig initialization.
+    return {
+        enabled: isTruthyEnvValue(getHostTelemetryEnv("VERYFRONT_OTEL")) ||
+            isTruthyEnvValue(getHostTelemetryEnv("OTEL_TRACES_ENABLED")),
+        serviceName: getHostTelemetryEnv("OTEL_SERVICE_NAME") || "veryfront",
+        endpoint: getHostTelemetryEnv("OTEL_EXPORTER_OTLP_ENDPOINT") || "",
+        headers: parseHeaders(getHostTelemetryEnv("OTEL_EXPORTER_OTLP_HEADERS")),
+    };
+}
+let cachedTracingRuntime;
+function getTracingRuntime() {
+    const providerRevision = getTracerProviderRevision();
+    if (!cachedTracingRuntime || cachedTracingRuntime.providerRevision !== providerRevision) {
+        const config = getConfig();
+        cachedTracingRuntime = {
+            providerRevision,
+            config,
+            tracer: getTracer(config.serviceName),
+        };
+    }
+    return cachedTracingRuntime;
+}
+// ---------------------------------------------------------------------------
+// Legacy initialise / shutdown (now delegated to bootstrap.ts + ext)
+// ---------------------------------------------------------------------------
+let initialized = false;
+/** Initialize OTLP tracing export. */
+export async function initializeOTLP() {
+    if (initialized) {
+        logger.debug("Already initialized");
+        return;
+    }
+    // Actual provider setup is handled by ext-observability-opentelemetry via bootstrap.
+    // This is kept for backward compatibility.
+    initialized = true;
+    logger.debug("OTLP setup delegated to ext-observability-opentelemetry extension");
+}
+/** Shut down OTLP tracing export. */
+export async function shutdownOTLP() {
+    // Actual shutdown is handled by the extension loader teardown.
+    logger.debug("OTLP shutdown delegated to ext-observability-opentelemetry extension");
+}
+/** Check whether OTLP export is enabled. */
+export function isOTLPEnabled() {
+    return initialized;
+}
+/** Initialize OTLP tracing with explicit API adapters. */
+export async function initializeOTLPWithApis() {
+    await initializeOTLP();
+}
+// ---------------------------------------------------------------------------
+// Span helpers — delegate to shim (which delegates to SDK if wired)
+// ---------------------------------------------------------------------------
+function setSpanErrorStatus(span, error) {
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+    });
+    if (error instanceof Error)
+        span.recordException(error);
+}
+/** Applies span. */
+export async function withSpan(name, fn, attributes) {
+    const { tracer } = getTracingRuntime();
+    const parentContext = shimContext.active();
+    const span = tracer.startSpan(name, { kind: SpanKind.INTERNAL, attributes }, parentContext);
+    const spanContext = shimTrace.setSpan(parentContext, span);
+    try {
+        const result = await shimContext.with(spanContext, fn);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        setSpanErrorStatus(span, error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/** Applies span sync. */
+export function withSpanSync(name, fn, attributes) {
+    const { tracer } = getTracingRuntime();
+    const parentContext = shimContext.active();
+    const span = tracer.startSpan(name, { kind: SpanKind.INTERNAL, attributes }, parentContext);
+    try {
+        const result = fn();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        setSpanErrorStatus(span, error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/** Context for extract. */
+export function extractContext(headers) {
+    const carrier = {};
+    for (const [k, v] of headers)
+        carrier[k.toLowerCase()] = v;
+    return shimPropagation.extract(shimContext.active(), carrier, defaultTextMapGetter);
+}
+/** Context for inject. */
+export function injectContext(headers) {
+    const carrier = {};
+    shimPropagation.inject(shimContext.active(), carrier, defaultTextMapSetter);
+    for (const [k, v] of Object.entries(carrier))
+        headers.set(k, v);
+}
+/** Starts server span. */
+export function startServerSpan(method, path, parentContext) {
+    const { tracer } = getTracingRuntime();
+    const ctx = (parentContext || shimContext.active());
+    const span = tracer.startSpan(`${method} ${path}`, { kind: SpanKind.SERVER }, ctx);
+    span.setAttribute("http.method", method);
+    span.setAttribute("http.target", path);
+    return { span, context: shimTrace.setSpan(ctx, span) };
+}
+/** End an active server tracing span. */
+export function endServerSpan(span, statusCode, error) {
+    if (!span)
+        return;
+    const otelSpan = span;
+    otelSpan.setAttribute("http.status_code", statusCode);
+    if (error) {
+        setSpanErrorStatus(otelSpan, error);
+        otelSpan.end();
+        return;
+    }
+    if (statusCode >= 400) {
+        otelSpan.setStatus({ code: SpanStatusCode.ERROR });
+        otelSpan.end();
+        return;
+    }
+    otelSpan.setStatus({ code: SpanStatusCode.OK });
+    otelSpan.end();
+}
+/** Sets span attributes. */
+export function setSpanAttributes(span, attributes) {
+    if (!span)
+        return;
+    const otelSpan = span;
+    for (const [key, value] of Object.entries(attributes))
+        otelSpan.setAttribute(key, value);
+}
+/** Sets active span attributes. */
+export function setActiveSpanAttributes(attributes) {
+    const span = shimTrace.getActiveSpan?.();
+    if (!span)
+        return;
+    for (const [key, value] of Object.entries(attributes))
+        span.setAttribute(key, value);
+}
+/** Context for with. */
+export async function withContext(spanContext, fn) {
+    return shimContext.with(spanContext, fn);
+}
+/** Context for get trace. */
+export function getTraceContext() {
+    const span = shimTrace.getActiveSpan?.();
+    if (!span)
+        return {};
+    const ctx = span.spanContext();
+    return { traceId: ctx.traceId, spanId: ctx.spanId };
+}

package/esm/src/observability/tracing/telemetry-env.d.ts

@@ -0,0 +1,3 @@
+export declare function getHostTelemetryEnv(key: string): string | undefined;
+export declare function isReservedSharedRuntimeTelemetryEnvKey(key: string): boolean;
+//# sourceMappingURL=telemetry-env.d.ts.map

package/esm/src/observability/tracing/telemetry-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-env.d.ts","sourceRoot":"","sources":["../../../../src/src/observability/tracing/telemetry-env.ts"],"names":[],"mappings":"AAMA,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED,wBAAgB,sCAAsC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3E"}

package/esm/src/observability/tracing/telemetry-env.js

@@ -0,0 +1,10 @@
+import { getHostEnv } from "../../platform/compat/process.js";
+const RESERVED_SHARED_RUNTIME_TELEMETRY_ENV_KEYS = new Set([
+    "VERYFRONT_OTEL",
+]);
+export function getHostTelemetryEnv(key) {
+    return getHostEnv(key);
+}
+export function isReservedSharedRuntimeTelemetryEnvKey(key) {
+    return key.startsWith("OTEL_") || RESERVED_SHARED_RUNTIME_TELEMETRY_ENV_KEYS.has(key);
+}