veryfront 0.1.246 → 0.1.248

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

@@ -1,24 +1,34 @@
 /**************************
- * OpenTelemetry OTLP Setup for Grafana Cloud
+ * OpenTelemetry OTLP Setup
+ *
+ * Thin wrapper that delegates to the `ext-opentelemetry` extension via the
+ * `TracingExporter` contract.  When the extension is not installed, all span
+ * operations silently no-op.
  *
- * Configures the OTLP exporter to send traces to Grafana Cloud.
  * 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 (e.g., https://otlp-gateway-prod-eu-west-2.grafana.net/otlp)
- * - OTEL_EXPORTER_OTLP_HEADERS: Auth headers (e.g., Authorization=Basic ...)
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint
+ * - OTEL_EXPORTER_OTLP_HEADERS: Auth headers
  **************************/
 
 import { getOtelTracingConfig } from "../../config/env.js";
 import { serverLogger } from "../../utils/index.js";
-import { RUNTIME_VERSION } from "../../utils/version.js";
+import {
+  type Context,
+  context as shimContext,
+  defaultTextMapGetter,
+  defaultTextMapSetter,
+  getTracer,
+  propagation as shimPropagation,
+  type Span,
+  SpanKind,
+  SpanStatusCode,
+  trace as shimTrace,
+} from "./api-shim.js";
 
 const logger = serverLogger.component("otel");
 
-interface ShutdownableProvider {
-  shutdown(): Promise<void>;
-}
-
 export interface OTLPConfig {
   serviceName: string;
   endpoint: string;
@@ -26,12 +36,6 @@ export interface OTLPConfig {
   enabled: boolean;
 }
 
-let initialized = false;
-let tracerProvider: ShutdownableProvider | null = null;
-
-let traceApi: typeof import("@opentelemetry/api") | null = null;
-let propagationApi: typeof import("@opentelemetry/core") | null = null;
-
 function parseHeaders(headerString: string | undefined): Record<string, string> {
   if (!headerString) return {};
 
@@ -61,114 +65,46 @@ function getConfig(): OTLPConfig {
   };
 }
 
-async function ensureApis(): Promise<void> {
-  if (traceApi && propagationApi) return;
-  traceApi = await import("@opentelemetry/api");
-  propagationApi = await import("@opentelemetry/core");
-}
-
-function setSpanErrorStatus(span: import("@opentelemetry/api").Span, error: unknown): void {
-  if (!traceApi) return;
+// ---------------------------------------------------------------------------
+// Legacy initialise / shutdown (now delegated to bootstrap.ts + ext)
+// ---------------------------------------------------------------------------
 
-  span.setStatus({
-    code: traceApi.SpanStatusCode.ERROR,
-    message: error instanceof Error ? error.message : String(error),
-  });
-
-  if (error instanceof Error) span.recordException(error);
-}
+let initialized = false;
 
 export async function initializeOTLP(): Promise<void> {
   if (initialized) {
     logger.debug("Already initialized");
     return;
   }
-
-  const config = getConfig();
-
-  if (!config.enabled) {
-    logger.debug("Tracing disabled (OTEL_TRACES_ENABLED != true)");
-    initialized = true;
-    return;
-  }
-
-  if (!config.endpoint) {
-    logger.warn("No OTEL_EXPORTER_OTLP_ENDPOINT configured, skipping");
-    initialized = true;
-    return;
-  }
-
-  try {
-    const { BasicTracerProvider, BatchSpanProcessor } = await import(
-      "@opentelemetry/sdk-trace-base"
-    );
-    const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
-    const { resourceFromAttributes } = await import("@opentelemetry/resources");
-    const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = await import(
-      "@opentelemetry/semantic-conventions"
-    );
-    const { AsyncLocalStorageContextManager } = await import("@opentelemetry/context-async-hooks");
-
-    const resource = resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: config.serviceName,
-      [ATTR_SERVICE_VERSION]: RUNTIME_VERSION,
-    });
-
-    const endpointBase = config.endpoint.replace(/\/$/, "");
-    const exporter = new OTLPTraceExporter({
-      url: `${endpointBase}/v1/traces`,
-      headers: config.headers,
-    });
-
-    const contextManager = new AsyncLocalStorageContextManager();
-    contextManager.enable();
-
-    const provider = new BasicTracerProvider({
-      resource,
-      spanProcessors: [new BatchSpanProcessor(exporter)],
-    });
-
-    // In OTel SDK v2, provider.register() is removed.
-    // Set global tracer provider and context manager via the API directly.
-    traceApi = await import("@opentelemetry/api");
-    traceApi.trace.setGlobalTracerProvider(provider);
-    traceApi.context.setGlobalContextManager(contextManager);
-
-    tracerProvider = provider;
-
-    initialized = true;
-    logger.info("OpenTelemetry OTLP tracing initialized", {
-      serviceName: config.serviceName,
-      endpoint: config.endpoint,
-    });
-
-    traceApi.trace.getTracer(config.serviceName);
-    logger.debug("Tracer obtained", { name: config.serviceName });
-
-    // Bridge trace context into the logger so every JSON log entry
-    // automatically includes traceId/spanId from the active span.
-    // Imported here (rather than per-entrypoint) so all callers of
-    // initializeOTLP benefit — CLI serve, production-server, proxy, etc.
-    await import("../../utils/logger/trace-bridge.js");
-  } catch (error) {
-    logger.error("Failed to initialize OTLP tracing", { error });
-    initialized = true; // Mark as initialized to prevent retries
-  }
+  // Actual provider setup is handled by ext-opentelemetry via bootstrap.
+  // This is kept for backward compatibility.
+  initialized = true;
+  logger.debug("OTLP setup delegated to ext-opentelemetry extension");
 }
 
 export async function shutdownOTLP(): Promise<void> {
-  if (!tracerProvider) return;
-
-  try {
-    await tracerProvider.shutdown();
-    logger.info("Tracer provider shutdown complete");
-  } catch (error) {
-    logger.warn("Error during tracer shutdown", { error });
-  }
+  // Actual shutdown is handled by the extension loader teardown.
+  logger.debug("OTLP shutdown delegated to ext-opentelemetry extension");
 }
 
 export function isOTLPEnabled(): boolean {
-  return initialized && tracerProvider !== null;
+  return initialized;
+}
+
+export async function initializeOTLPWithApis(): Promise<void> {
+  await initializeOTLP();
+}
+
+// ---------------------------------------------------------------------------
+// Span helpers — delegate to shim (which delegates to SDK if wired)
+// ---------------------------------------------------------------------------
+
+function setSpanErrorStatus(span: Span, error: unknown): void {
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error instanceof Error ? error.message : String(error),
+  });
+  if (error instanceof Error) span.recordException(error);
 }
 
 export async function withSpan<T>(
@@ -176,22 +112,21 @@ export async function withSpan<T>(
   fn: () => Promise<T>,
   attributes?: Record<string, string | number | boolean>,
 ): Promise<T> {
-  if (!traceApi || !isOTLPEnabled()) return fn();
-
-  const tracer = traceApi.trace.getTracer(getConfig().serviceName);
-  const parentContext = traceApi.context.active();
+  const config = getConfig();
+  const tracer = getTracer(config.serviceName);
+  const parentContext = shimContext.active();
 
   const span = tracer.startSpan(
     name,
-    { kind: traceApi.SpanKind.INTERNAL, attributes },
+    { kind: SpanKind.INTERNAL, attributes },
     parentContext,
   );
 
-  const spanContext = traceApi.trace.setSpan(parentContext, span);
+  const spanContext = shimTrace.setSpan(parentContext, span);
 
   try {
-    const result = await traceApi.context.with(spanContext, fn);
-    span.setStatus({ code: traceApi.SpanStatusCode.OK });
+    const result = await shimContext.with(spanContext, fn);
+    span.setStatus({ code: SpanStatusCode.OK });
     return result;
   } catch (error) {
     setSpanErrorStatus(span, error);
@@ -206,20 +141,19 @@ export function withSpanSync<T>(
   fn: () => T,
   attributes?: Record<string, string | number | boolean>,
 ): T {
-  if (!traceApi || !isOTLPEnabled()) return fn();
-
-  const tracer = traceApi.trace.getTracer(getConfig().serviceName);
-  const parentContext = traceApi.context.active();
+  const config = getConfig();
+  const tracer = getTracer(config.serviceName);
+  const parentContext = shimContext.active();
 
   const span = tracer.startSpan(
     name,
-    { kind: traceApi.SpanKind.INTERNAL, attributes },
+    { kind: SpanKind.INTERNAL, attributes },
     parentContext,
   );
 
   try {
     const result = fn();
-    span.setStatus({ code: traceApi.SpanStatusCode.OK });
+    span.setStatus({ code: SpanStatusCode.OK });
     return result;
   } catch (error) {
     setSpanErrorStatus(span, error);
@@ -229,31 +163,16 @@ export function withSpanSync<T>(
   }
 }
 
-export function extractContext(headers: Headers): unknown {
-  if (!traceApi || !propagationApi) return traceApi?.context?.active();
-
+export function extractContext(headers: Headers): Context | undefined {
   const carrier: Record<string, string> = {};
   for (const [k, v] of headers) carrier[k.toLowerCase()] = v;
 
-  if (!propagationApi.W3CTraceContextPropagator) return traceApi.context.active();
-
-  return new propagationApi.W3CTraceContextPropagator().extract(
-    traceApi.context.active(),
-    carrier,
-    traceApi.defaultTextMapGetter,
-  );
+  return shimPropagation.extract(shimContext.active(), carrier, defaultTextMapGetter);
 }
 
 export function injectContext(headers: Headers): void {
-  if (!traceApi || !propagationApi) return;
-
   const carrier: Record<string, string> = {};
-  new propagationApi.W3CTraceContextPropagator().inject(
-    traceApi.context.active(),
-    carrier,
-    traceApi.defaultTextMapSetter,
-  );
-
+  shimPropagation.inject(shimContext.active(), carrier, defaultTextMapSetter);
   for (const [k, v] of Object.entries(carrier)) headers.set(k, v);
 }
 
@@ -261,23 +180,22 @@ export function startServerSpan(
   method: string,
   path: string,
   parentContext?: unknown,
-): { span: unknown; context: unknown } | null {
-  if (!traceApi || !isOTLPEnabled()) return null;
-
-  const tracer = traceApi.trace.getTracer(getConfig().serviceName);
-  const ctx = (parentContext || traceApi.context.active()) as import("@opentelemetry/api").Context;
+): { span: Span; context: Context } | null {
+  const config = getConfig();
+  const tracer = getTracer(config.serviceName);
+  const ctx = (parentContext || shimContext.active()) as Context;
 
-  const span = tracer.startSpan(`${method} ${path}`, { kind: traceApi.SpanKind.SERVER }, ctx);
+  const span = tracer.startSpan(`${method} ${path}`, { kind: SpanKind.SERVER }, ctx);
   span.setAttribute("http.method", method);
   span.setAttribute("http.target", path);
 
-  return { span, context: traceApi.trace.setSpan(ctx, span) };
+  return { span, context: shimTrace.setSpan(ctx, span) };
 }
 
 export function endServerSpan(span: unknown, statusCode: number, error?: Error): void {
-  if (!span || !traceApi) return;
+  if (!span) return;
 
-  const otelSpan = span as import("@opentelemetry/api").Span;
+  const otelSpan = span as Span;
   otelSpan.setAttribute("http.status_code", statusCode);
 
   if (error) {
@@ -287,12 +205,12 @@ export function endServerSpan(span: unknown, statusCode: number, error?: Error):
   }
 
   if (statusCode >= 400) {
-    otelSpan.setStatus({ code: traceApi.SpanStatusCode.ERROR });
+    otelSpan.setStatus({ code: SpanStatusCode.ERROR });
     otelSpan.end();
     return;
   }
 
-  otelSpan.setStatus({ code: traceApi.SpanStatusCode.OK });
+  otelSpan.setStatus({ code: SpanStatusCode.OK });
   otelSpan.end();
 }
 
@@ -300,39 +218,29 @@ export function setSpanAttributes(
   span: unknown,
   attributes: Record<string, string | number | boolean>,
 ): void {
-  if (!span || !traceApi) return;
+  if (!span) return;
 
-  const otelSpan = span as import("@opentelemetry/api").Span;
+  const otelSpan = span as Span;
   for (const [key, value] of Object.entries(attributes)) otelSpan.setAttribute(key, value);
 }
 
 export function setActiveSpanAttributes(
   attributes: Record<string, string | number | boolean>,
 ): void {
-  if (!traceApi) return;
-
-  const span = traceApi.trace.getSpan(traceApi.context.active());
+  const span = shimTrace.getActiveSpan?.();
   if (!span) return;
 
   for (const [key, value] of Object.entries(attributes)) span.setAttribute(key, value);
 }
 
 export async function withContext<T>(spanContext: unknown, fn: () => Promise<T>): Promise<T> {
-  if (!traceApi) return fn();
-  return traceApi.context.with(spanContext as import("@opentelemetry/api").Context, fn);
+  return shimContext.with(spanContext as Context, fn);
 }
 
 export function getTraceContext(): { traceId?: string; spanId?: string } {
-  if (!traceApi) return {};
-
-  const span = traceApi.trace.getSpan(traceApi.context.active());
+  const span = shimTrace.getActiveSpan?.();
   if (!span) return {};
 
   const ctx = span.spanContext();
   return { traceId: ctx.traceId, spanId: ctx.spanId };
 }
-
-export async function initializeOTLPWithApis(): Promise<void> {
-  await initializeOTLP();
-  if (isOTLPEnabled()) await ensureApis();
-}

package/src/src/observability/tracing/types.ts

@@ -1,4 +1,4 @@
-import type { Context, Span, SpanKind, TextMapPropagator, Tracer } from "@opentelemetry/api";
+import type { Context, Span, SpanKind, TextMapPropagator, Tracer } from "./api-shim.js";
 
 export interface TracingConfig {
   enabled: boolean;

package/src/src/platform/compat/kv/factory.ts

@@ -1,9 +1,11 @@
 import * as dntShim from "../../../../_dnt.shims.js";
+import { tryResolve } from "../../../extensions/contracts.js";
 import { serverLogger } from "../../../utils/index.js";
 import { isDeno } from "../runtime.js";
 import { MemoryKv } from "./memory-adapter.js";
 import { SqliteKv } from "./sqlite-adapter.js";
-import type { Kv } from "./types.js";
+import type { Kv, SqliteDatabase } from "./types.js";
+import type { NodeCompat } from "../../../extensions/interfaces/node-compat.js";
 
 interface GlobalWithDenoKv {
   Deno?: {
@@ -25,12 +27,21 @@ export async function openKv(path?: string): Promise<Kv> {
     }
   }
 
-  try {
-    const Database = (await import("better-sqlite3")).default;
-    const db = new Database(path ?? ":memory:");
-    return new SqliteKv(db);
-  } catch (error) {
-    serverLogger.debug("SQLite not available, using memory KV:", error);
+  const nodeCompat = tryResolve<NodeCompat>("NodeCompat");
+  if (nodeCompat?.openSqliteDatabase) {
+    try {
+      const db = await nodeCompat.openSqliteDatabase(path);
+      // NodeCompatSqliteDatabase is structurally identical to SqliteDatabase;
+      // cast to satisfy the SqliteKv constructor's nominal type check.
+      return new SqliteKv(db as unknown as SqliteDatabase);
+    } catch (error) {
+      serverLogger.debug("NodeCompat.openSqliteDatabase failed, using memory KV:", error);
+    }
+  } else {
+    serverLogger.debug(
+      "NodeCompat extension not registered — SQLite KV unavailable. " +
+        "Install @veryfront/ext-node-compat to enable SQLite-backed KV.",
+    );
   }
 
   return new MemoryKv();

package/src/src/platform/compat/opaque-deps.ts

@@ -17,8 +17,10 @@
 import * as dntShim from "../../../_dnt.shims.js";
 
 
-import { isDeno, isDenoCompiled } from "./runtime.js";
+import { tryResolve } from "../../extensions/contracts.js";
+import { isDeno } from "./runtime.js";
 import { dynamicImport } from "./dynamic-import.js";
+import type { NodeCompat } from "../../extensions/interfaces/node-compat.js";
 
 function resolve(pkg: string, version: string): string {
   return isDeno ? `npm:${pkg}@${version}` : pkg;
@@ -27,14 +29,6 @@ function resolve(pkg: string, version: string): string {
 // deno-lint-ignore no-explicit-any -- callers assign to their own typed variable; any allows implicit narrowing at each call site
 type OpaqueModule = any;
 
-type KreuzbergModule = {
-  initWasm?: () => Promise<void>;
-  extractBytes: (
-    data: Uint8Array,
-    mimeType: string,
-  ) => Promise<{ content: string }>;
-};
-
 /** Lazily import `@huggingface/transformers` (+ onnxruntime, ~500MB). */
 export function importTransformers(): Promise<OpaqueModule> {
   return dynamicImport(resolve("@huggingface/transformers", "3.4.2"));
@@ -51,11 +45,12 @@ export function importClaudeAgentSDK(): Promise<OpaqueModule> {
 /**
  * Lazily import kreuzberg document extraction.
  *
- * Unlike the other opaque deps above, kreuzberg is a core framework
- * dependency that must work in compiled binaries. The Deno path uses
- * a regular `import()` (not `dynamicImport`) so `deno compile` can
- * trace and embed `@kreuzberg/wasm`. The Node/Bun path uses `dynamicImport`
- * to resolve `@kreuzberg/node` from the project's node_modules at runtime.
+ * Delegates to the `NodeCompat` extension contract (`@veryfront/ext-node-compat`)
+ * when available. Without the extension, throws an actionable error instructing
+ * the user to install `ext-node-compat`.
+ *
+ * Node/Bun path: `@kreuzberg/node` resolved from the project's node_modules at
+ * runtime — the extension handles that dynamic import internally.
  */
 export async function importKreuzberg(): Promise<{
   extractBytes: (
@@ -63,35 +58,12 @@ export async function importKreuzberg(): Promise<{
     mimeType: string,
   ) => Promise<{ content: string }>;
 }> {
-  if (isDeno) {
-    // Regular import — visible to deno compile, resolved via deno.json import map
-    const mod = await import("@kreuzberg/wasm") as unknown as KreuzbergModule;
-    if (isDenoCompiled) {
-      // Kreuzberg's initWasm() internally uses a computed dynamic import() to
-      // load the WASM glue module (kreuzberg_wasm.js). deno compile cannot
-      // trace computed import() paths, so the glue module is absent from the
-      // binary's embedded module graph. Pre-importing it here populates Deno's
-      // in-process module cache so the subsequent import() inside initWasm()
-      // resolves from cache instead of hitting the missing file.
-      await import("@kreuzberg/wasm/dist/pkg/kreuzberg_wasm.js");
-      // pdfium.js is not in @kreuzberg/wasm package exports, so we can't use
-      // an import map entry. Resolve its URL relative to the kreuzberg package
-      // and pre-import it so initWasm()'s `import("./pdfium.js")` resolves
-      // from the in-process module cache instead of hanging.
-      // Wrapped in try/catch because pdfium is only needed for PDF extraction;
-      // a failure here should not break extraction of other formats (DOCX, etc.).
-      try {
-        const kreuzbergUrl = import.meta.resolve("@kreuzberg/wasm");
-        await import(new URL("./pdfium.js", kreuzbergUrl).href);
-      } catch {
-        // expected: pdfium pre-import may fail if the file is missing or
-        // the package structure changed — PDF extraction will be degraded
-        // but other formats will still work.
-      }
-    }
-    await mod.initWasm?.();
-    return mod;
+  const nodeCompat = tryResolve<NodeCompat>("NodeCompat");
+  if (nodeCompat?.importKreuzberg) {
+    return nodeCompat.importKreuzberg();
   }
-  // Opaque import — resolved from node_modules at runtime
-  return dynamicImport("@kreuzberg/node");
+  throw new Error(
+    "Document extraction requires the NodeCompat extension. " +
+      "Install @veryfront/ext-node-compat and add it to your extensions configuration.",
+  );
 }