veryfront 0.0.81 → 0.0.83

package/src/proxy/tracing.ts

@@ -0,0 +1,237 @@
+/**
+ * OpenTelemetry OTLP tracing for proxy.
+ * Env: OTEL_TRACES_ENABLED, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS
+ */
+import * as dntShim from "../_dnt.shims.js";
+
+
+import type { Context, Span, Tracer } from "@opentelemetry/api";
+
+// Inline cross-runtime getEnv to avoid dependency on src/platform/compat (not copied in Docker)
+function getEnv(key: string): string | undefined {
+  // Deno
+  if (typeof dntShim.Deno !== "undefined" && dntShim.Deno.env?.get) {
+    return dntShim.Deno.env.get(key);
+  }
+  // Node.js / Bun
+  const nodeProcess = (dntShim.dntGlobalThis as { process?: { env?: Record<string, string> } }).process;
+  return nodeProcess?.env?.[key];
+}
+
+let initialized = false;
+let tracerProvider: { shutdown: () => Promise<void> } | null = null;
+let tracer: Tracer | null = null;
+
+interface OTLPConfig {
+  serviceName: string;
+  endpoint: string;
+  headers?: Record<string, string>;
+  enabled: boolean;
+}
+
+function parseHeaders(headerString: string | undefined): Record<string, string> {
+  if (!headerString) return {};
+  const headers: Record<string, string> = {};
+  for (const part of headerString.split(",")) {
+    const [key, ...valueParts] = part.split("=");
+    if (key && valueParts.length > 0) {
+      headers[key.trim()] = valueParts.join("=").trim();
+    }
+  }
+  return headers;
+}
+
+function getConfig(): OTLPConfig {
+  return {
+    enabled: getEnv("OTEL_TRACES_ENABLED") === "true",
+    serviceName: getEnv("OTEL_SERVICE_NAME") || "veryfront-proxy",
+    endpoint: getEnv("OTEL_EXPORTER_OTLP_ENDPOINT") || "",
+    headers: parseHeaders(getEnv("OTEL_EXPORTER_OTLP_HEADERS")),
+  };
+}
+
+let traceApi: typeof import("@opentelemetry/api") | null = null;
+let propagationApi: typeof import("@opentelemetry/core") | null = null;
+
+async function loadApis(): Promise<void> {
+  if (traceApi) return;
+  traceApi = await import("@opentelemetry/api");
+  propagationApi = await import("@opentelemetry/core");
+}
+
+export async function initializeOTLP(): Promise<void> {
+  if (initialized) return;
+
+  const config = getConfig();
+
+  if (!config.enabled) {
+    initialized = true;
+    return;
+  }
+
+  if (!config.endpoint) {
+    console.warn("[otel] No endpoint configured");
+    initialized = true;
+    return;
+  }
+
+  try {
+    const { trace } = await import("@opentelemetry/api");
+    const { BasicTracerProvider, BatchSpanProcessor } = await import(
+      "@opentelemetry/sdk-trace-base"
+    );
+    const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+    const { Resource } = await import("@opentelemetry/resources");
+    const { ATTR_SERVICE_NAME } = await import("@opentelemetry/semantic-conventions");
+
+    const resource = new Resource({ [ATTR_SERVICE_NAME]: config.serviceName });
+    const exporter = new OTLPTraceExporter({
+      url: `${config.endpoint}/v1/traces`,
+      headers: config.headers,
+    });
+
+    const provider = new BasicTracerProvider({ resource });
+    provider.addSpanProcessor(new BatchSpanProcessor(exporter));
+    provider.register();
+
+    tracerProvider = provider;
+    tracer = trace.getTracer(config.serviceName);
+    initialized = true;
+
+    await loadApis();
+
+    console.log("[otel] Initialized", {
+      serviceName: config.serviceName,
+      endpoint: config.endpoint,
+    });
+  } catch (error) {
+    console.error("[otel] Init failed", { error });
+    initialized = true;
+  }
+}
+
+export async function shutdownOTLP(): Promise<void> {
+  if (tracerProvider) {
+    try {
+      await tracerProvider.shutdown();
+      console.log("[otel] Shutdown complete");
+    } catch (error) {
+      console.warn("[otel] Shutdown error", { error });
+    }
+  }
+}
+
+export function isOTLPEnabled(): boolean {
+  return initialized && tracerProvider !== null;
+}
+
+export function extractContext(headers: dntShim.Headers): Context | undefined {
+  if (!traceApi || !propagationApi) return undefined;
+  const carrier: Record<string, string> = {};
+  headers.forEach((v, k) => (carrier[k.toLowerCase()] = v));
+  return new propagationApi.W3CTraceContextPropagator().extract(
+    traceApi.context.active(),
+    carrier,
+    traceApi.defaultTextMapGetter,
+  );
+}
+
+export function injectContext(headers: dntShim.Headers): void {
+  if (!traceApi || !propagationApi) return;
+  const carrier: Record<string, string> = {};
+  new propagationApi.W3CTraceContextPropagator().inject(
+    traceApi.context.active(),
+    carrier,
+    traceApi.defaultTextMapSetter,
+  );
+  Object.entries(carrier).forEach(([k, v]) => headers.set(k, v));
+}
+
+export function startServerSpan(
+  method: string,
+  path: string,
+  parentContext?: Context,
+): { span: Span; context: Context } | null {
+  if (!traceApi || !tracer) return null;
+  const ctx = parentContext || traceApi.context.active();
+  const span = tracer.startSpan(`${method} ${path}`, { kind: traceApi.SpanKind.SERVER }, ctx);
+  return { span, context: traceApi.trace.setSpan(ctx, span) };
+}
+
+export function endSpan(span: Span | undefined, statusCode: number, error?: Error): void {
+  if (!span || !traceApi) return;
+  span.setAttribute("http.status_code", statusCode);
+  if (error) {
+    span.setStatus({ code: traceApi.SpanStatusCode.ERROR, message: error.message });
+    span.recordException(error);
+  } else if (statusCode >= 400) {
+    span.setStatus({ code: traceApi.SpanStatusCode.ERROR });
+  }
+  span.end();
+}
+
+export function withContext<T>(spanContext: Context, fn: () => Promise<T>): Promise<T> {
+  if (!traceApi) return fn();
+  return traceApi.context.with(spanContext, fn);
+}
+
+export function getTraceContext(): { traceId?: string; spanId?: string } {
+  if (!traceApi) return {};
+  const span = traceApi.trace.getSpan(traceApi.context.active());
+  if (!span) return {};
+  const ctx = span.spanContext();
+  return { traceId: ctx.traceId, spanId: ctx.spanId };
+}
+
+/**
+ * Span names for proxy tracing.
+ */
+export const ProxySpanNames = {
+  PROXY_REQUEST: "proxy.request",
+  PROXY_PROCESS: "proxy.process",
+  PROXY_TOKEN_FETCH: "proxy.token_fetch",
+  PROXY_DOMAIN_LOOKUP: "proxy.domain_lookup",
+  OAUTH_TOKEN_REQUEST: "oauth.token_request",
+  HTTP_CLIENT_FETCH: "http.client.fetch",
+} as const;
+
+/**
+ * Execute an async function within a tracing span.
+ * If tracing is disabled, executes the function directly.
+ */
+export async function withSpan<T>(
+  name: string,
+  fn: () => Promise<T>,
+  attributes?: Record<string, string | number | boolean>,
+): Promise<T> {
+  if (!traceApi || !tracer) {
+    return await fn();
+  }
+
+  const parentContext = traceApi.context.active();
+  const span = tracer.startSpan(name, {
+    kind: traceApi.SpanKind.INTERNAL,
+    attributes,
+  }, parentContext);
+
+  const spanContext = traceApi.trace.setSpan(parentContext, span);
+
+  try {
+    const result = await traceApi.context.with(spanContext, fn);
+    span.setStatus({ code: traceApi.SpanStatusCode.OK });
+    return result;
+  } catch (error) {
+    span.setStatus({
+      code: traceApi.SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    if (error instanceof Error) {
+      span.recordException(error);
+    }
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+export { initializeOTLP as initializeOTLPWithApis };

package/src/src/cache/backend.ts

@@ -587,6 +587,68 @@ export function createCacheBackend(config: CacheBackendConfig = {}): Promise<Cac
   );
 }
 
+/**
+ * Check if a cache backend supports distributed (cross-pod) caching.
+ *
+ * Use this instead of checking `backend.type === "memory"` directly,
+ * which is a leaky abstraction that exposes implementation details.
+ */
+export function isDistributedBackend(backend: CacheBackend): boolean {
+  return backend.type !== "memory";
+}
+
+/**
+ * Create a lazy-initialized distributed cache accessor.
+ *
+ * This encapsulates the common pattern of:
+ * 1. Lazy-init a cache backend via Singleflight
+ * 2. Skip if memory-only (not useful for cross-pod sharing)
+ * 3. Return null if init fails
+ *
+ * @param factory - Function that creates the cache backend
+ * @param name - Log prefix for debug messages
+ * @returns A function that returns the distributed cache backend or null
+ */
+export function createDistributedCacheAccessor(
+  factory: () => Promise<CacheBackend>,
+  name: string,
+): () => Promise<CacheBackend | null> {
+  let backend: CacheBackend | null | undefined;
+  const singleflight = new (class {
+    private promise: Promise<CacheBackend | null> | null = null;
+    do(fn: () => Promise<CacheBackend | null>): Promise<CacheBackend | null> {
+      if (!this.promise) {
+        this.promise = fn().finally(() => {
+          this.promise = null;
+        });
+      }
+      return this.promise;
+    }
+  })();
+
+  return () => {
+    if (backend !== undefined) return Promise.resolve(backend);
+
+    return singleflight.do(async () => {
+      try {
+        const b = await factory();
+        if (!isDistributedBackend(b)) {
+          backend = null;
+          logger.debug(`[${name}] No distributed cache available (memory only)`);
+          return null;
+        }
+        backend = b;
+        logger.debug(`[${name}] Distributed cache initialized`, { type: b.type });
+        return b;
+      } catch (error) {
+        logger.debug(`[${name}] Failed to initialize distributed cache`, { error });
+        backend = null;
+        return null;
+      }
+    });
+  };
+}
+
 /** Convenience wrappers for common cache patterns. */
 export const CacheBackends = {
   /** Transform cache for compiled code. */
@@ -609,6 +671,9 @@ export const CacheBackends = {
   httpModule: () =>
     createCacheBackend({ keyPrefix: "http-module", circuitBreakerName: "api-cache-http" }),
 
+  /** SSR module cache for React loader (cross-pod sharing). */
+  ssrModule: () => createCacheBackend({ keyPrefix: "ssr-module" }),
+
   /** Project CSS cache for Tailwind CSS output (cross-pod sharing). */
   projectCSS: () => createCacheBackend({ keyPrefix: "project-css" }),
 };

package/src/src/cache/cache-key-builder.ts

@@ -119,12 +119,3 @@ export function extractCacheKeyContext(handlerCtx: HandlerContext): CacheKeyCont
 }
 
 export type { MultiProjectRequestContextType as MultiProjectRequestContext };
-
-/**
- * @deprecated Use tryGetCacheKeyContext() which auto-detects context
- */
-export function extractCacheKeyContextFromRequestContext(
-  reqCtx: MultiProjectRequestContextType,
-): CacheKeyContext {
-  return extractCacheKeyContextFromMultiProjectContext(reqCtx);
-}

package/src/src/cache/hash.ts

@@ -0,0 +1,205 @@
+/**
+ * Standardized Cache Hashing Utilities
+ *
+ * Provides consistent hashing for cache keys across the codebase.
+ * All cache keys should use these utilities to ensure:
+ * - Consistent format with type prefixes
+ * - Collision resistance between different cache types
+ * - Easy debugging and key parsing
+ *
+ * Key format: `{type}:{hash}` or `{type}:{version}:{hash}`
+ *
+ * @module cache/hash
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { simpleHash } from "../utils/hash-utils.js";
+
+/**
+ * Cache key types for different cache domains.
+ * Using type prefixes prevents collisions between different caches.
+ */
+export type CacheKeyType =
+  | "http" // HTTP module cache (esm.sh bundles)
+  | "mod" // Module transform cache
+  | "esm" // ESM resolution cache
+  | "render" // Render result cache
+  | "mdx" // MDX bundle cache
+  | "css" // CSS/Tailwind cache
+  | "file" // File content cache
+  | "config"; // Configuration cache
+
+/**
+ * Fast, synchronous hash function for cache keys.
+ *
+ * Uses DJB2 algorithm - good distribution, very fast.
+ * Returns a positive number suitable for string conversion.
+ *
+ * @param input - String to hash
+ * @returns Positive integer hash
+ */
+export function fastHash(input: string): number {
+  let hash = 5381;
+
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) + hash) ^ input.charCodeAt(i);
+  }
+
+  return hash >>> 0; // Convert to unsigned 32-bit
+}
+
+/**
+ * Convert a hash number to a compact string representation.
+ *
+ * Uses base36 for compact output (0-9, a-z).
+ */
+export function hashToString(hash: number): string {
+  return hash.toString(36);
+}
+
+/**
+ * Fast synchronous hash that returns a string.
+ *
+ * Combines fastHash + hashToString for convenience.
+ */
+export function hashString(input: string): string {
+  return hashToString(fastHash(input));
+}
+
+/**
+ * Generate a cache key with type prefix.
+ *
+ * Format: `{type}:{hash}`
+ *
+ * @example
+ * ```typescript
+ * getCacheKey("http", "https://esm.sh/react@18.3.1")
+ * // Returns: "http:1abc2def"
+ *
+ * getCacheKey("mod", "pages/index.tsx")
+ * // Returns: "mod:xyz789"
+ * ```
+ */
+export function getCacheKey(type: CacheKeyType, input: string): string {
+  const hash = hashString(input);
+  return `${type}:${hash}`;
+}
+
+/**
+ * Generate a versioned cache key with type prefix.
+ *
+ * Format: `{type}:v{version}:{hash}`
+ *
+ * @example
+ * ```typescript
+ * getVersionedCacheKey("mod", 12, "pages/index.tsx:abc123")
+ * // Returns: "mod:v12:xyz789"
+ * ```
+ */
+export function getVersionedCacheKey(
+  type: CacheKeyType,
+  version: number | string,
+  input: string,
+): string {
+  const hash = hashString(input);
+  return `${type}:v${version}:${hash}`;
+}
+
+/**
+ * Generate a cache key with multiple components.
+ *
+ * Useful for keys that depend on multiple inputs.
+ * Components are joined with colons before hashing.
+ *
+ * @example
+ * ```typescript
+ * getCompoundCacheKey("mod", ["projectId", "filePath", "contentHash"])
+ * // Returns: "mod:abc123"
+ * ```
+ */
+export function getCompoundCacheKey(type: CacheKeyType, components: string[]): string {
+  const combined = components.join(":");
+  return getCacheKey(type, combined);
+}
+
+/**
+ * Parse a cache key into its components.
+ *
+ * @returns The type prefix and hash, or null if invalid format
+ */
+export function parseCacheKey(
+  key: string,
+): { type: string; hash: string; version?: string } | null {
+  const parts = key.split(":");
+
+  if (parts.length < 2) return null;
+
+  const type = parts[0]!;
+  const rest = parts.slice(1);
+
+  // Check for version: type:vN:hash
+  if (rest[0]?.startsWith("v") && /^v\d+$/.test(rest[0])) {
+    return {
+      type,
+      version: rest[0].slice(1),
+      hash: rest.slice(1).join(":"),
+    };
+  }
+
+  return {
+    type,
+    hash: rest.join(":"),
+  };
+}
+
+/**
+ * SHA-256 async hash for content-addressed keys.
+ *
+ * Use this when you need cryptographic strength (e.g., content hashes).
+ * For cache keys where speed matters more, use hashString().
+ */
+export async function sha256Hash(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await dntShim.crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Short SHA-256 hash (8 characters).
+ *
+ * Good balance between collision resistance and key length.
+ */
+export async function sha256Short(input: string): Promise<string> {
+  const full = await sha256Hash(input);
+  return full.slice(0, 8);
+}
+
+/**
+ * Generate HTTP bundle filename from URL.
+ *
+ * Consistent with existing http-cache.ts format: `http-{hash}.mjs`
+ */
+export function getHttpBundleFilename(normalizedUrl: string): string {
+  const hash = simpleHash(normalizedUrl);
+  return `http-${hash}.mjs`;
+}
+
+/**
+ * Extract hash from HTTP bundle filename.
+ *
+ * @returns The hash string, or null if not a valid bundle filename
+ */
+export function parseHttpBundleFilename(filename: string): string | null {
+  const match = filename.match(/^http-(\d+)\.mjs$/);
+  return match?.[1] ?? null;
+}
+
+/**
+ * Check if a value looks like a cache key.
+ */
+export function isCacheKey(value: string): boolean {
+  return /^[a-z]+:[a-z0-9]+/.test(value);
+}

package/src/src/cache/index.ts

@@ -1,4 +1,7 @@
 export * from "./backend.js";
+export * from "./multi-tier.js";
+export * from "./module-cache.js";
+export * from "./hash.js";
 
 export {
   type CacheKeyContext,