@veryfront/ext-content-mdx 0.1.1119 → 0.1.1122

package/esm/src/observability/tracing/api-shim.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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
+ */
+export type AttributePrimitive = string | number | boolean;
+export type AttributeValue = AttributePrimitive | readonly AttributePrimitive[] | undefined;
+export interface Span {
+    setAttribute(key: string, value: AttributeValue): Span;
+    setAttributes(attrs: Record<string, AttributeValue>): Span;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): Span;
+    recordException(err: unknown): void;
+    addEvent(name: string, attrs?: Record<string, AttributeValue>): Span;
+    end(endTime?: number): void;
+    spanContext(): SpanContext;
+    updateName(name: string): void;
+}
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+export interface Tracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, context?: Context): Span;
+    startActiveSpan<T>(name: string, fn: (span: Span) => T): T;
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, fn: (span: Span) => T): T;
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, context: Context, fn: (span: Span) => T): T;
+}
+export interface TracerProvider {
+    getTracer(name: string, version?: string): Tracer;
+}
+export interface Context {
+    getValue(key: symbol): unknown;
+    setValue(key: symbol, value: unknown): Context;
+    deleteValue(key: symbol): Context;
+}
+export interface TextMapGetter<C = Record<string, string>> {
+    keys(carrier: C): string[];
+    get(carrier: C, key: string): string | string[] | undefined;
+}
+export interface TextMapSetter<C = Record<string, string>> {
+    set(carrier: C, key: string, value: string): void;
+}
+export interface TextMapPropagator {
+    inject(context: Context, carrier: unknown, setter?: TextMapSetter<unknown>): void;
+    extract(context: Context, carrier: unknown, getter?: TextMapGetter<unknown>): Context;
+    fields(): string[];
+}
+export interface ContextAccessor {
+    active(): Context;
+    with<T>(ctx: Context, fn: () => T): T;
+}
+export interface ActiveSpanAccessor {
+    getActiveSpan(): Span | undefined;
+    getSpan(ctx: Context): Span | undefined;
+    setSpan?(ctx: Context, span: Span): Context;
+}
+export declare const SpanKind: {
+    readonly INTERNAL: 0;
+    readonly SERVER: 1;
+    readonly CLIENT: 2;
+    readonly PRODUCER: 3;
+    readonly CONSUMER: 4;
+};
+export type SpanKind = typeof SpanKind[keyof typeof SpanKind];
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+export type SpanStatusCode = typeof SpanStatusCode[keyof typeof SpanStatusCode];
+export interface ObservableResult {
+    observe(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface Counter {
+    add(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface UpDownCounter {
+    add(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface Histogram {
+    record(value: number, attributes?: Record<string, AttributeValue>): void;
+}
+export interface ObservableGauge {
+    addCallback(callback: (result: ObservableResult) => void): void;
+}
+export interface Meter {
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): Counter;
+    createUpDownCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): UpDownCounter;
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+        advice?: {
+            explicitBucketBoundaries?: number[];
+        };
+    }): Histogram;
+    createObservableGauge(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): ObservableGauge;
+    getMeter?: never;
+}
+export interface MetricsAPI {
+    getMeter(name: string | undefined, version?: string): Meter;
+}
+/**
+ * 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 declare function setGlobalActiveSpanAccessor(accessor: ActiveSpanAccessor): void;
+/**
+ * Register the real OTel context API. This lets the shim preserve active span
+ * context across async boundaries once the extension has installed the SDK's
+ * AsyncLocalStorageContextManager.
+ */
+export declare function setGlobalContextAccessor(accessor: ContextAccessor): void;
+/**
+ * Wire in the real SDK TracerProvider.
+ * Called from `src/server/bootstrap.ts` after `orchestrateExtensions()` runs.
+ */
+export declare function setGlobalTracerProvider(p: TracerProvider): void;
+export declare function getGlobalTracerProvider(): TracerProvider;
+export declare function getTracerProviderRevision(): number;
+/**
+ * Get a tracer from the active provider.
+ * Returns the no-op tracer when ext-observability-opentelemetry is not installed.
+ */
+export declare function getTracer(name: string, version?: string): Tracer;
+export declare const context: {
+    active(): Context;
+    with<T>(ctx: Context, fn: () => T): T;
+    setGlobalContextManager(_mgr: unknown): void;
+};
+export declare const trace: {
+    getTracer(name: string, version?: string): Tracer;
+    setGlobalTracerProvider(p: TracerProvider): void;
+    getGlobalTracerProvider(): TracerProvider;
+    setSpan(ctx: Context, _span: Span): Context;
+    getSpan(ctx: Context): Span | undefined;
+    getActiveSpan(): Span | undefined;
+};
+export declare const propagation: {
+    setGlobalPropagator(p: TextMapPropagator): void;
+    extract<C>(ctx: Context, carrier: C, getter?: TextMapGetter<C>): Context;
+    inject<C>(ctx: Context, carrier: C, setter?: TextMapSetter<C>): void;
+};
+export declare const defaultTextMapGetter: TextMapGetter<Record<string, string>>;
+export declare const defaultTextMapSetter: TextMapSetter<Record<string, string>>;
+/**
+ * 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 declare function setGlobalMetricsAPI(api: MetricsAPI): void;
+export declare function getGlobalMetricsAPI(): MetricsAPI | null;
+export declare function _resetShimForTests(): void;
+//# sourceMappingURL=api-shim.d.ts.map

package/esm/src/observability/tracing/api-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-shim.d.ts","sourceRoot":"","sources":["../../../../src/src/observability/tracing/api-shim.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,281 @@
+/**
+ * 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() {
+    const store = new Map();
+    return {
+        getValue: (key) => store.get(key),
+        setValue(key, value) {
+            store.set(key, value);
+            return this;
+        },
+        deleteValue(key) {
+            store.delete(key);
+            return this;
+        },
+    };
+}
+const NOOP_CONTEXT = createNoopContext();
+const EMPTY_TRACE_ID = "00000000000000000000000000000000";
+const EMPTY_SPAN_ID = "0000000000000000";
+const NOOP_SPAN_CONTEXT = {
+    traceId: EMPTY_TRACE_ID,
+    spanId: EMPTY_SPAN_ID,
+    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;
+let _contextAccessor = null;
+const ACTIVE_SPAN_CONTEXT_KEY = Symbol.for("veryfront.observability.active_span");
+/**
+ * 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;
+}
+/**
+ * Register the real OTel context API. This lets the shim preserve active span
+ * context across async boundaries once the extension has installed the SDK's
+ * AsyncLocalStorageContextManager.
+ */
+export function setGlobalContextAccessor(accessor) {
+    _contextAccessor = 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 _contextAccessor?.active() ?? _activeContext;
+    },
+    with(ctx, fn) {
+        if (_contextAccessor) {
+            return _contextAccessor.with(ctx, fn);
+        }
+        const prev = _activeContext;
+        _activeContext = ctx;
+        try {
+            const result = fn();
+            if (result && typeof result.finally === "function") {
+                return result.finally(() => {
+                    _activeContext = prev;
+                });
+            }
+            _activeContext = prev;
+            return result;
+        }
+        catch (error) {
+            _activeContext = prev;
+            throw error;
+        }
+    },
+    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) {
+        try {
+            const spanContext = _span.spanContext();
+            if (spanContext.traceId === EMPTY_TRACE_ID || spanContext.spanId === EMPTY_SPAN_ID) {
+                return ctx;
+            }
+        }
+        catch {
+            // Keep structural test doubles usable even when they omit spanContext().
+        }
+        if (_activeSpanAccessor?.setSpan) {
+            return _activeSpanAccessor.setSpan(ctx, _span);
+        }
+        return ctx.setValue(ACTIVE_SPAN_CONTEXT_KEY, _span);
+    },
+    getSpan(ctx) {
+        return _activeSpanAccessor?.getSpan(ctx) ??
+            ctx.getValue(ACTIVE_SPAN_CONTEXT_KEY);
+    },
+    getActiveSpan() {
+        return _activeSpanAccessor?.getActiveSpan() ?? trace.getSpan(context.active());
+    },
+};
+// ---------------------------------------------------------------------------
+// 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;
+    _contextAccessor = null;
+    _metricsApi = null;
+    _activeSpanAccessor = null;
+}

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

@@ -0,0 +1,63 @@
+/**************************
+ * 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 AttributeValue, type Context, type Span, SpanKind } 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>;
+export type WithSpanOptions = {
+    kind?: SpanKind;
+};
+/** Applies span. */
+export declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, AttributeValue>, options?: WithSpanOptions): Promise<T>;
+/** Applies span sync. */
+export declare function withSpanSync<T>(name: string, fn: () => T, attributes?: Record<string, AttributeValue>, options?: WithSpanOptions): 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, AttributeValue>): void;
+/** Adds an event to a span. */
+export declare function addSpanEvent(span: unknown, name: string, attributes?: Record<string, AttributeValue>): void;
+/** Sets active span attributes. */
+export declare function setActiveSpanAttributes(attributes: Record<string, AttributeValue>): void;
+/** Marks the active span as failed. */
+export declare function setActiveSpanErrorStatus(error: unknown): 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":"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"}