veryfront 0.1.545 → 0.1.547

package/src/src/rendering/renderer.ts

@@ -1,593 +0,0 @@
-/**
- * Renderer
- *
- * A shared renderer that handles ANY project by injecting context at render time.
- * This eliminates the 7+ second cold start for new projects by sharing expensive
- * initialization (esbuild, MDX compiler) across all tenants.
- *
- * ## Architecture
- *
- * - **Shared Services** (initialized once, ~100ms):
- *   - ElementValidator - pure validation, no project state
- *   - CompilerService - late-binding MDX compilation
- *   - esbuild - already initialized by shared services
- *   - ContextAwareCacheCoordinator - cache with tenant-prefixed keys
- *
- * - **Per-Request Services** (created per-render, ~1ms):
- *   - PageResolver - needs projectDir, adapter, config
- *   - LayoutCollector - needs adapter, config
- *   - SSRRenderer - needs mode, adapter, projectDir
- *   - ComponentRegistry - needs projectId
- *   - etc.
- *
- * ## Tenant Isolation
- *
- * All tenant data is isolated through:
- * 1. Cache key prefixing (projectId:environment:releaseId:contentKey)
- * 2. Per-request service instances (no shared mutable state)
- * 3. RenderContext passed through the entire pipeline
- *
- * @module rendering/renderer
- */
-import * as dntShim from "../../_dnt.shims.js";
-
-
-import { rendererLogger } from "../utils/index.js";
-import { MDXCacheAdapter } from "../transforms/mdx/index.js";
-import { INITIALIZATION_ERROR, SERVICE_OVERLOADED } from "../errors/error-registry.js";
-import { withSpan } from "../observability/tracing/otlp-setup.js";
-import { buildQueryAwareCacheKey, type QueryParamCacheOptions } from "../cache/keys.js";
-import { getEnvNumber } from "../platform/compat/process.js";
-import {
-  createRenderContext,
-  createRenderContextFromEnriched,
-  type CreateRenderContextOptions,
-  type RenderContext,
-} from "./context/render-context.js";
-import {
-  areSharedServicesInitialized,
-  getSharedServices,
-  initializeSharedServices,
-  setSharedCompileMDX,
-  type SharedServicesOptions,
-} from "./shared/shared-services.js";
-import {
-  ContextAwareCacheCoordinator,
-  type ContextAwareCacheOptions,
-} from "./shared/context-aware-cache.js";
-import {
-  createComponentRegistry,
-  createLayoutCollector,
-  createLayoutCompiler,
-  createPageRenderer,
-  createPageResolver,
-  createSSRRenderer,
-  createVirtualModuleSystem,
-} from "./factories/service-factories.js";
-import { MDXCompiler } from "./orchestrator/mdx.js";
-import { LayoutOrchestrator } from "./orchestrator/layout.js";
-import { HTMLGenerator } from "./orchestrator/html.js";
-import { SSROrchestrator } from "./orchestrator/ssr-orchestrator.js";
-import { RenderPipeline } from "./orchestrator/pipeline.js";
-import { createLayoutComponentCache } from "./layouts/utils/component-loader.js";
-import type { PageDataResponse, RenderOptions, RenderResult } from "./orchestrator/types.js";
-import type { HandlerContext } from "../types/index.js";
-import { TimeoutError, withTimeoutThrow } from "./utils/stream-utils.js";
-import { Singleflight } from "../utils/singleflight.js";
-import {
-  acquireProjectSlot,
-  projectRenderCounts,
-  releaseProjectSlot,
-  RENDER_ACQUIRE_TIMEOUT_MS,
-  RENDER_PER_PROJECT_LIMIT,
-  renderSemaphore,
-} from "./renderer-concurrency.js";
-
-const logger = rendererLogger.component("renderer");
-
-/**
- * Master timeout for entire render pipeline (must be less than REQUEST_TIMEOUT_MS).
- * Configurable via RENDER_TIMEOUT_MS env var for cold-start scenarios.
- * Default increased to 60s to handle cold-start module transforms.
- */
-const DEFAULT_RENDER_PIPELINE_TIMEOUT_MS = 60_000;
-const RENDER_PIPELINE_TIMEOUT_MS = getEnvNumber("RENDER_TIMEOUT_MS") ??
-  DEFAULT_RENDER_PIPELINE_TIMEOUT_MS;
-
-/**
- * Options for initializing the Renderer
- */
-export interface RendererOptions {
-  /** Shared services options */
-  shared?: SharedServicesOptions;
-  /** Cache options */
-  cache?: ContextAwareCacheOptions;
-}
-
-/**
- * Cached render result for Singleflight deduplication.
- * Contains only the serializable parts of RenderResult (no stream).
- * Each caller gets a fresh RenderResult from this cached data.
- */
-interface CachedRenderData {
-  html: string;
-  frontmatter: RenderResult["frontmatter"];
-  headings?: RenderResult["headings"];
-  ssrHash?: string;
-  pageModule?: RenderResult["pageModule"];
-}
-
-/**
- * Renderer - Shared renderer for all projects
- *
- * Initialize once at startup, then use for any project by passing
- * a RenderContext to each render call.
- *
- * ## Singleflight Deduplication
- *
- * Uses Singleflight to deduplicate concurrent renders of the same page.
- * Key insight: We cache the HTML string, not the stream. Each caller gets
- * a fresh RenderResult with the same HTML but no stream (streams can only
- * be consumed once). This prevents "body already consumed" errors while
- * still avoiding duplicate render work.
- *
- * The Singleflight key includes: projectId, environment, releaseId, slug, colorScheme
- */
-export class Renderer {
-  private cache: ContextAwareCacheCoordinator;
-  private layoutComponentCache = createLayoutComponentCache();
-  private initialized = false;
-  private initializationPromise: Promise<void> | null = null;
-
-  /**
-   * Singleflight for render deduplication. Caches HTML string results so
-   * concurrent requests for the same page share the render work.
-   * Key format: {projectId}:{environment}:{releaseId}:{slug}:{colorScheme}
-   */
-  private renderFlight = new Singleflight<CachedRenderData>();
-
-  constructor(options: RendererOptions = {}) {
-    this.cache = new ContextAwareCacheCoordinator(options.cache);
-  }
-
-  async initialize(options?: SharedServicesOptions): Promise<void> {
-    if (this.initialized) return;
-    if (this.initializationPromise) return this.initializationPromise;
-
-    this.initializationPromise = (async () => {
-      const startTime = performance.now();
-      logger.debug("Initializing...");
-
-      await initializeSharedServices(options);
-
-      this.initialized = true;
-      logger.debug("Initialized", {
-        duration: `${(performance.now() - startTime).toFixed(2)}ms`,
-      });
-    })();
-
-    try {
-      await this.initializationPromise;
-    } finally {
-      this.initializationPromise = null;
-    }
-  }
-
-  renderPage(slug: string, ctx: RenderContext, options?: RenderOptions): Promise<RenderResult> {
-    return withSpan(
-      "renderer.renderPage",
-      async () => {
-        if (!this.initialized) {
-          throw INITIALIZATION_ERROR.create({
-            detail: "Renderer not initialized. Call initialize() first.",
-          });
-        }
-
-        const startTime = performance.now();
-        logger.debug("Rendering page", {
-          slug,
-          projectId: ctx.projectId,
-          environment: ctx.environment,
-        });
-
-        const cacheKey = this.buildCacheKey(slug, ctx, options);
-        const cacheResult = cacheKey
-          ? await this.cache.checkCache(slug, ctx, options?.colorScheme, cacheKey)
-          : { hit: false, cacheKey: "" };
-        if (cacheResult.hit && cacheResult.cachedResult) {
-          logger.debug("Cache hit", {
-            slug,
-            projectId: ctx.projectId,
-            colorScheme: options?.colorScheme,
-            duration: `${(performance.now() - startTime).toFixed(2)}ms`,
-          });
-          return cacheResult.cachedResult;
-        }
-
-        if (!(await acquireProjectSlot(ctx.projectId))) {
-          const activeCount = projectRenderCounts.get(ctx.projectId) ?? 0;
-          logger.error("Per-project render limit reached", {
-            slug,
-            projectId: ctx.projectId,
-            activeRenders: activeCount,
-            limit: RENDER_PER_PROJECT_LIMIT,
-          });
-          throw SERVICE_OVERLOADED.create({
-            detail:
-              `Per-project render limit reached (${activeCount}/${RENDER_PER_PROJECT_LIMIT} active). Try again shortly.`,
-            context: {
-              slug,
-              projectId: ctx.projectId,
-              activeRenders: activeCount,
-              limit: RENDER_PER_PROJECT_LIMIT,
-            },
-          });
-        }
-
-        const acquired = await renderSemaphore.tryAcquire(RENDER_ACQUIRE_TIMEOUT_MS);
-        if (!acquired) {
-          await releaseProjectSlot(ctx.projectId);
-          logger.error("Render capacity exceeded - service overloaded", {
-            slug,
-            projectId: ctx.projectId,
-            waiting: renderSemaphore.waiting,
-            available: renderSemaphore.available,
-          });
-          throw SERVICE_OVERLOADED.create({
-            detail:
-              `Render capacity exceeded (${renderSemaphore.waiting} waiting). Service is overloaded.`,
-            context: { slug, projectId: ctx.projectId, waiting: renderSemaphore.waiting },
-          });
-        }
-
-        try {
-          return await this.doRenderPage(slug, ctx, options, startTime, cacheKey);
-        } finally {
-          renderSemaphore.release();
-          await releaseProjectSlot(ctx.projectId);
-        }
-      },
-      {
-        "renderer.slug": slug,
-        "renderer.projectId": ctx.projectId,
-        "renderer.environment": ctx.environment,
-      },
-    );
-  }
-
-  /**
-   * Build a Singleflight key for render deduplication.
-   * Includes all context that affects rendering output.
-   */
-  private getSingleflightKey(
-    slug: string,
-    ctx: RenderContext,
-    colorScheme?: "light" | "dark",
-  ): string {
-    return `${ctx.projectId}:${ctx.environment}:${ctx.contentSourceId ?? "draft"}:${slug}:${
-      colorScheme ?? "default"
-    }`;
-  }
-
-  /**
-   * Compute a cache key that is query-aware and avoids caching personalized responses
-   * (Authorization / Cookie / x-api-key) unless the caller explicitly provides one.
-   *
-   * Query param handling is configurable via `config.cache.queryParams`:
-   * - "ignore-all": Ignore all query params (pages share cache regardless of URL params)
-   * - "include-all": Include all query params (default, each unique query = separate cache)
-   * - "include-list": Only include specified params
-   * - "exclude-list": Exclude common tracking params (utm_*, gclid, fbclid, etc.)
-   */
-  private buildCacheKey(
-    slug: string,
-    ctx: RenderContext,
-    options?: RenderOptions,
-  ): string | null {
-    if (options?.cacheKey) return options.cacheKey;
-
-    const req = options?.request;
-    if (req) {
-      const hasAuth = req.headers.has("authorization") ||
-        req.headers.has("cookie") ||
-        req.headers.has("x-api-key");
-      if (hasAuth) return null;
-    }
-
-    const url = options?.url;
-    if (!url) return slug;
-
-    // Get query param handling options from config
-    const queryParamOptions = ctx.config?.cache?.queryParams as QueryParamCacheOptions | undefined;
-
-    return buildQueryAwareCacheKey(slug, url, queryParamOptions);
-  }
-
-  private async doRenderPage(
-    slug: string,
-    ctx: RenderContext,
-    options: RenderOptions | undefined,
-    startTime: number,
-    cacheKey: string | null,
-  ): Promise<RenderResult> {
-    const effectiveKey = cacheKey ?? dntShim.crypto.randomUUID();
-    const flightKey = this.getSingleflightKey(effectiveKey, ctx, options?.colorScheme);
-    const isFollower = cacheKey ? this.renderFlight.has(flightKey) : false;
-
-    const runRender = async () => {
-      const services = this.createServicesForContext(ctx, options?.colorScheme);
-
-      let result: RenderResult;
-      try {
-        result = await withTimeoutThrow(
-          services.pipeline.renderPage(slug, {
-            ...options,
-            delivery: "string",
-            projectId: ctx.projectId,
-            projectSlug: ctx.projectSlug,
-            environment: ctx.environment,
-            contentSourceId: ctx.contentSourceId,
-            skipCacheCheck: true,
-            skipCachePersist: true,
-          }),
-          RENDER_PIPELINE_TIMEOUT_MS,
-          `Render pipeline for ${ctx.projectId}:${slug}`,
-        );
-      } catch (error) {
-        if (error instanceof TimeoutError) {
-          logger.error("Render pipeline timeout - aborting", {
-            slug,
-            projectId: ctx.projectId,
-            timeoutMs: RENDER_PIPELINE_TIMEOUT_MS,
-          });
-        }
-        throw error;
-      }
-
-      if (cacheKey) {
-        await this.cache.persistResult(result, slug, ctx, options?.colorScheme, cacheKey);
-      }
-
-      logger.debug("Render complete (leader)", {
-        slug,
-        projectId: ctx.projectId,
-        duration: `${(performance.now() - startTime).toFixed(2)}ms`,
-        htmlLength: result.html?.length ?? 0,
-      });
-
-      return {
-        html: result.html,
-        frontmatter: result.frontmatter,
-        headings: result.headings,
-        ssrHash: result.ssrHash,
-        pageModule: result.pageModule,
-      };
-    };
-
-    const cachedData = cacheKey
-      ? await this.renderFlight.do(flightKey, runRender)
-      : await runRender();
-
-    if (isFollower) {
-      logger.debug("Render deduplicated (follower)", {
-        slug,
-        projectId: ctx.projectId,
-        duration: `${(performance.now() - startTime).toFixed(2)}ms`,
-        htmlLength: cachedData.html?.length ?? 0,
-      });
-    }
-
-    return {
-      html: cachedData.html,
-      frontmatter: cachedData.frontmatter,
-      headings: cachedData.headings,
-      ssrHash: cachedData.ssrHash,
-      pageModule: cachedData.pageModule,
-      stream: null,
-    };
-  }
-
-  resolvePageData(
-    slug: string,
-    ctx: RenderContext,
-    options?: RenderOptions,
-  ): Promise<PageDataResponse> {
-    if (!this.initialized) {
-      throw INITIALIZATION_ERROR.create({
-        detail: "Renderer not initialized. Call initialize() first.",
-      });
-    }
-
-    const services = this.createServicesForContext(ctx);
-
-    return services.pipeline.resolvePageData(slug, {
-      ...options,
-      projectId: ctx.projectId,
-      projectSlug: ctx.projectSlug,
-      environment: ctx.environment,
-      contentSourceId: ctx.contentSourceId,
-    });
-  }
-
-  getAllPages(ctx: RenderContext): Promise<string[]> {
-    if (!this.initialized) {
-      throw INITIALIZATION_ERROR.create({
-        detail: "Renderer not initialized. Call initialize() first.",
-      });
-    }
-
-    return createPageResolver(ctx).getAllPages();
-  }
-
-  async clearCache(ctx: RenderContext, slug?: string): Promise<void> {
-    if (slug) {
-      await this.cache.clearSlug(slug, ctx);
-      return;
-    }
-    await this.cache.clearForContext(ctx);
-  }
-
-  async clearCacheForProject(projectId: string): Promise<void> {
-    logger.debug("Clearing render cache for project", { projectId });
-    await this.cache.clearForProject(projectId);
-  }
-
-  async destroy(): Promise<void> {
-    await this.cache.destroy();
-    this.initialized = false;
-    logger.debug("Destroyed");
-  }
-
-  private createServicesForContext(
-    ctx: RenderContext,
-    colorScheme?: "light" | "dark",
-  ): { pipeline: RenderPipeline } {
-    const shared = getSharedServices();
-
-    const mdxCacheAdapter = new MDXCacheAdapter({
-      config: ctx.config,
-      mode: ctx.mode,
-    });
-
-    const mdxCompiler = new MDXCompiler({
-      projectDir: ctx.projectDir,
-      mode: ctx.mode,
-      mdxCacheAdapter,
-    });
-
-    const compileMDX = mdxCompiler.compileMDX.bind(mdxCompiler);
-    setSharedCompileMDX(compileMDX);
-
-    const virtualModules = createVirtualModuleSystem(ctx);
-    const componentRegistry = createComponentRegistry(ctx, virtualModules);
-    const pageResolver = createPageResolver(ctx);
-    const layoutCollector = createLayoutCollector(ctx, compileMDX);
-    const layoutCompiler = createLayoutCompiler(ctx, compileMDX);
-    const ssrRenderer = createSSRRenderer(ctx);
-    const pageRenderer = createPageRenderer(ctx, { componentRegistry, compileMDX });
-
-    const layoutOrchestrator = new LayoutOrchestrator({
-      projectDir: ctx.projectDir,
-      projectId: ctx.projectId,
-      projectSlug: ctx.projectSlug,
-      contentSourceId: ctx.contentSourceId,
-      adapter: ctx.adapter,
-      config: ctx.config,
-      mode: ctx.mode,
-      moduleServerUrl: ctx.moduleServerUrl,
-      layoutCollector,
-      layoutCompiler,
-      layoutCache: this.layoutComponentCache,
-      componentRegistry: componentRegistry.getAllAsComponents(),
-    });
-
-    const htmlGenerator = new HTMLGenerator({
-      projectDir: ctx.projectDir,
-      adapter: ctx.adapter,
-      config: ctx.config,
-      mode: ctx.mode,
-    });
-
-    const ssrOrchestrator = new SSROrchestrator({
-      mode: ctx.mode,
-      debugMode: ctx.mode === "development",
-      elementValidator: shared.elementValidator,
-      ssrRenderer,
-      htmlGenerator,
-    });
-
-    const pipelineCacheCoordinator = {
-      checkCache: async (slug: string, cacheKey?: string) => {
-        const result = await this.cache.checkCache(slug, ctx, colorScheme, cacheKey);
-        return {
-          cachedResult: result.cachedResult,
-          depAwareSlug: slug,
-          moduleCacheKey: cacheKey ?? slug,
-          cachedModule: result.cachedResult?.pageModule,
-        };
-      },
-      persistResult: async (result: RenderResult, slug: string, cacheKey?: string) => {
-        await this.cache.persistResult(result, slug, ctx, colorScheme, cacheKey);
-      },
-      clearAll: () => this.cache.clearAll(),
-      clearSlug: (slug: string) => this.cache.clearSlug(slug, ctx),
-      destroy: () => this.cache.destroy(),
-    };
-
-    const pipeline = new RenderPipeline({
-      pageResolver,
-      cacheCoordinator: pipelineCacheCoordinator,
-      pageRenderer,
-      layoutOrchestrator,
-      ssrOrchestrator,
-      adapter: ctx.adapter,
-      mode: ctx.mode,
-      projectDir: ctx.projectDir,
-      queryParamOptions: ctx.config?.cache?.queryParams as QueryParamCacheOptions | undefined,
-    });
-
-    return { pipeline };
-  }
-}
-
-export {
-  createRenderContext,
-  createRenderContextFromEnriched,
-  type CreateRenderContextOptions,
-  type RenderContext,
-};
-
-let renderer: Renderer | null = null;
-
-export function getRenderer(): Renderer {
-  if (!renderer) {
-    throw INITIALIZATION_ERROR.create({
-      detail: "Renderer not initialized. Call initializeRenderer() first.",
-    });
-  }
-  return renderer;
-}
-
-export async function initializeRenderer(options?: RendererOptions): Promise<Renderer> {
-  if (renderer) return renderer;
-
-  renderer = new Renderer(options);
-  await renderer.initialize(options?.shared);
-  return renderer;
-}
-
-export function isRendererInitialized(): boolean {
-  return renderer !== null && areSharedServicesInitialized();
-}
-
-export async function destroyRenderer(): Promise<void> {
-  if (!renderer) return;
-
-  await renderer.destroy();
-  renderer = null;
-}
-
-export async function clearRendererCacheForProject(projectId: string): Promise<void> {
-  logger.debug("clearRendererCacheForProject called", {
-    projectId,
-    hasRenderer: !!renderer,
-  });
-
-  if (!renderer) {
-    logger.debug("No renderer instance, skipping project cache clear", { projectId });
-    return;
-  }
-
-  await renderer.clearCacheForProject(projectId);
-}
-
-export function renderPage(
-  slug: string,
-  handlerCtx: HandlerContext,
-  options?: RenderOptions,
-  contextOptions?: CreateRenderContextOptions,
-): Promise<RenderResult> {
-  const r = getRenderer();
-  const ctx = createRenderContext(handlerCtx, contextOptions);
-  return r.renderPage(slug, ctx, options);
-}