@mandujs/core 0.29.0 → 0.30.0

package/src/config/mandu.ts

@@ -170,6 +170,16 @@ export interface ManduConfig {
     minify?: boolean;
     sourcemap?: boolean;
     splitting?: boolean;
+    /**
+     * Phase 18.η — emit `.mandu/analyze/report.html` + `report.json` after
+     * a successful build. Equivalent to `mandu build --analyze`. Default:
+     * `false`. Report artefacts are self-contained (no CDN, no external
+     * JS) and safe to commit to a private dashboard or inspect locally.
+     *
+     * The CLI `--analyze` flag wins over this field; `--analyze=json`
+     * writes JSON only (useful for CI, skips the HTML render cost).
+     */
+    analyze?: boolean;
   };
   dev?: {
     hmr?: boolean;
@@ -286,6 +296,64 @@ export interface ManduConfig {
     heapEndpoint?: boolean;
     /** `/_mandu/metrics` Prometheus text exposure toggle. */
     metricsEndpoint?: boolean;
+    /**
+     * Phase 18.θ — OpenTelemetry-compatible request tracing.
+     *
+     * When enabled, every request opens a root server span
+     * (`http.request`) that chains child spans for middleware, loader,
+     * SSR, and sandbox execution. The root span's trace-id is
+     * propagated across AsyncLocalStorage and stamped onto outgoing
+     * fetches via `traceparent`.
+     *
+     * Exporters:
+     *   - `"console"` (default) — pretty-prints spans to stderr, useful
+     *     in `mandu dev`.
+     *   - `"otlp"` — POSTs OTLP/HTTP JSON to `endpoint/v1/traces`.
+     *     Compatible with Honeycomb, Grafana Tempo, AWS X-Ray (via the
+     *     OTel Collector), and the standalone OpenTelemetry Collector.
+     *
+     * Setting the `MANDU_OTEL_ENDPOINT` env var overrides both
+     * `enabled` and `exporter` at runtime (shortcut for ops that want
+     * to enable tracing without a config change).
+     *
+     * Default: disabled (zero overhead when `observability.tracing` is
+     * omitted).
+     */
+    tracing?: {
+      enabled?: boolean;
+      exporter?: "console" | "otlp";
+      endpoint?: string;
+      headers?: Record<string, string>;
+      serviceName?: string;
+    };
+  };
+  /**
+   * Phase 18.ζ — ISR / tag-based cache invalidation.
+   *
+   *   - `defaultMaxAge`   : fresh TTL (seconds) applied when a loader
+   *                         does not emit its own `_cache` / `ctx.cache`
+   *                         metadata. Set to a positive integer to enable
+   *                         automatic caching across every non-dynamic
+   *                         route (Next.js `export const revalidate`
+   *                         equivalent). Default `undefined` (no auto).
+   *   - `defaultSwr`      : stale-while-revalidate window (seconds)
+   *                         appended after the fresh TTL. Serves stale
+   *                         HTML instantly while background regeneration
+   *                         runs. Default `0`.
+   *   - `maxEntries`      : LRU bound for the in-memory store. Default
+   *                         `1000`.
+   *   - `store`           : backend. Currently `"memory"` only; reserved
+   *                         for future `"redis"` adapter.
+   *
+   * Disable entirely by omitting this block. Revalidation APIs live in
+   * `@mandujs/core/runtime`: `revalidate(tag)`, `revalidateTag(tag)`,
+   * `revalidatePath(path)`.
+   */
+  cache?: {
+    defaultMaxAge?: number;
+    defaultSwr?: number;
+    maxEntries?: number;
+    store?: "memory";
   };
   plugins?: ManduPlugin[];
   hooks?: Partial<ManduHooks>;

package/src/config/validate.ts

@@ -105,6 +105,13 @@ const BuildConfigSchema = z
      * module exports `generateStaticParams` is prerendered).
      */
     prerender: z.boolean().default(true),
+    /**
+     * Phase 18.η — opt into post-build bundle analyzer artefacts
+     * (`.mandu/analyze/report.html` + `report.json`). Default `false`.
+     * CLI `--analyze` overrides this at runtime; config is the "always on
+     * for this project" switch.
+     */
+    analyze: z.boolean().default(false),
   })
   .strict();
 
@@ -229,10 +236,28 @@ const TestConfigSchema = z
  * default so the runtime can distinguish "not set" (use mode default)
  * from "explicit false" (force off even in dev).
  */
+/**
+ * Phase 18.θ — tracing sub-block. All fields optional; omitting the
+ * whole block keeps tracing disabled and incurs zero runtime overhead.
+ * `endpoint` and `headers` are only meaningful when `exporter === "otlp"`
+ * but we don't make that a cross-field refine — runtime falls back to
+ * console with a warning when `"otlp"` is requested without an endpoint.
+ */
+const TracingConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    exporter: z.enum(["console", "otlp"]).optional(),
+    endpoint: z.string().url().optional(),
+    headers: z.record(z.string()).optional(),
+    serviceName: z.string().min(1).optional(),
+  })
+  .strict();
+
 const ObservabilityConfigSchema = z
   .object({
     heapEndpoint: z.boolean().optional(),
     metricsEndpoint: z.boolean().optional(),
+    tracing: TracingConfigSchema.optional(),
   })
   .strict();
 
@@ -293,6 +318,23 @@ const MiddlewareSchema = z.custom<Middleware>(
   }
 );
 
+/**
+ * Phase 18.ζ — ISR / cache config (strict).
+ *
+ * All fields optional. Omitting the block leaves caching disabled unless
+ * individual routes opt in via `filling.loader(fn, { revalidate })` or
+ * loader-level `_cache` metadata. Setting `defaultMaxAge` makes every
+ * non-dynamic route auto-cache with that fresh TTL.
+ */
+const CacheConfigSchema = z
+  .object({
+    defaultMaxAge: z.number().int().nonnegative().optional(),
+    defaultSwr: z.number().int().nonnegative().optional(),
+    maxEntries: z.number().int().positive().optional(),
+    store: z.enum(["memory"]).optional(),
+  })
+  .strict();
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -322,6 +364,8 @@ export const ManduConfigSchema = z
     seo: SeoConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     observability: ObservabilityConfigSchema.default({}),
+    /** Phase 18.ζ — ISR / tag-based cache invalidation. Optional. */
+    cache: CacheConfigSchema.optional(),
     plugins: z.array(ManduPluginSchema).optional(),
     hooks: ManduHooksSchema.optional(),
     /**

package/src/filling/context.ts

@@ -12,6 +12,14 @@ import { ContractValidator, type ContractValidatorOptions } from "../contract/va
 import { getCookieCodec } from "./cookie-codec";
 import { type FillingDeps, globalDeps } from "./deps";
 import { createSSEConnection, type SSEOptions, type SSEConnection } from "./sse";
+import {
+  getActiveSpan,
+  getTracer,
+  runWithSpan,
+  type Span,
+  type SpanAttributes,
+  type SpanOptions,
+} from "../observability/tracing";
 
 type ContractInput<
   TContract extends ContractSchema,
@@ -285,12 +293,45 @@ async function hmacSign(data: string, secret: string): Promise<string> {
 
 // ========== ManduContext ==========
 
+/**
+ * Phase 18.ζ — 로더가 캐시 메타데이터를 선언하기 위한 플루언트 헬퍼.
+ *
+ * 내부적으로는 `ctx._cacheMeta` 에 누적하며, 서버 런타임이 loader 실행
+ * 직후 읽어 `_cache` 블록과 동일하게 해석한다. 반환 데이터에 `_cache` 를
+ * 끼워넣는 방식과 동일한 의미지만, 타입 안정성이 더 높다.
+ *
+ * @example
+ * ```ts
+ * .loader(async (ctx) => {
+ *   ctx.cache.tag("posts").tag("posts:42").maxAge(3600).swr(86400);
+ *   return { post: await db.getPost(42) };
+ * })
+ * ```
+ */
+export interface CacheHelper {
+  tag(...tags: string[]): CacheHelper;
+  maxAge(seconds: number): CacheHelper;
+  /** alias for maxAge — Next.js parity */
+  revalidate(seconds: number): CacheHelper;
+  swr(seconds: number): CacheHelper;
+  /** alias for swr */
+  staleWhileRevalidate(seconds: number): CacheHelper;
+  /** 현재까지 누적된 메타데이터 스냅샷 (런타임 내부용) */
+  readonly meta: {
+    tags: string[];
+    maxAge?: number;
+    staleWhileRevalidate?: number;
+  };
+}
+
 export class ManduContext {
   private store: Map<string, unknown> = new Map();
   private _params: Record<string, string>;
   private _query: Record<string, string>;
   private _cookies: CookieManager;
   private _deps: FillingDeps;
+  private _cacheMeta: { tags: string[]; maxAge?: number; staleWhileRevalidate?: number } = { tags: [] };
+  private _cacheHelper: CacheHelper | null = null;
 
   constructor(
     public readonly request: Request,
@@ -303,6 +344,59 @@ export class ManduContext {
     this._deps = deps ?? globalDeps.get();
   }
 
+  /**
+   * Phase 18.ζ — 로더 내부에서 호출하는 캐시 메타데이터 플루언트 헬퍼.
+   * 누적 호출 가능: `ctx.cache.tag("a", "b").maxAge(60).swr(300)`
+   */
+  get cache(): CacheHelper {
+    if (this._cacheHelper) return this._cacheHelper;
+    const meta = this._cacheMeta;
+    const helper: CacheHelper = {
+      tag: (...tags: string[]) => {
+        for (const t of tags) {
+          if (typeof t === "string" && t.length > 0 && !meta.tags.includes(t)) {
+            meta.tags.push(t);
+          }
+        }
+        return helper;
+      },
+      maxAge: (seconds: number) => {
+        if (Number.isFinite(seconds) && seconds >= 0) meta.maxAge = seconds;
+        return helper;
+      },
+      revalidate: (seconds: number) => helper.maxAge(seconds),
+      swr: (seconds: number) => {
+        if (Number.isFinite(seconds) && seconds >= 0) meta.staleWhileRevalidate = seconds;
+        return helper;
+      },
+      staleWhileRevalidate: (seconds: number) => helper.swr(seconds),
+      get meta() {
+        return {
+          tags: [...meta.tags],
+          maxAge: meta.maxAge,
+          staleWhileRevalidate: meta.staleWhileRevalidate,
+        };
+      },
+    };
+    this._cacheHelper = helper;
+    return helper;
+  }
+
+  /**
+   * Phase 18.ζ — 서버 런타임이 loader 종료 후 누적된 메타 스냅샷을 읽는다.
+   * 내부 전용. 유저 코드는 `ctx.cache` 를 사용할 것.
+   */
+  getCacheMetaSnapshot(): { tags: string[]; maxAge?: number; staleWhileRevalidate?: number } | null {
+    if (this._cacheMeta.tags.length === 0 && this._cacheMeta.maxAge === undefined && this._cacheMeta.staleWhileRevalidate === undefined) {
+      return null;
+    }
+    return {
+      tags: [...this._cacheMeta.tags],
+      maxAge: this._cacheMeta.maxAge,
+      staleWhileRevalidate: this._cacheMeta.staleWhileRevalidate,
+    };
+  }
+
   /**
    * DNA-002: 의존성 접근
    *
@@ -631,6 +725,78 @@ export class ManduContext {
   has(key: string): boolean {
     return this.store.has(key);
   }
+
+  // ============================================
+  // 🥟 Tracing (Phase 18.θ)
+  // ============================================
+
+  /**
+   * The currently-active tracing span for this request, or `undefined`
+   * when tracing is disabled. Looked up via AsyncLocalStorage so it
+   * stays accurate across nested awaits — a loader that opens a child
+   * span before hitting an external API will see `ctx.span` return
+   * that child span until the child's `end()` fires.
+   *
+   * When tracing is disabled this reads as `undefined` (the runtime
+   * never opens a recording span), keeping the hot path free of
+   * extra allocations.
+   */
+  get span(): Span | undefined {
+    const active = getActiveSpan();
+    return active && active.recording ? active : undefined;
+  }
+
+  /**
+   * Open a child span scoped to the async context of `fn`. The span
+   * auto-ends when the returned promise resolves; if `fn` throws, the
+   * span is marked `status=error` with the thrown message, the span
+   * is ended, and the error re-thrown.
+   *
+   * When tracing is disabled this degenerates to just `await fn(noopSpan)`
+   * with no allocation in the hot path — callers don't have to branch
+   * on `ctx.span` themselves.
+   *
+   * @example
+   *   const users = await ctx.startSpan("db.users.findAll", async (span) => {
+   *     span.setAttribute("db.system", "postgres");
+   *     return await sql\`SELECT * FROM users\`;
+   *   });
+   */
+  async startSpan<T>(
+    name: string,
+    fn: (span: Span) => Promise<T> | T,
+    opts: SpanOptions = {}
+  ): Promise<T> {
+    const tracer = getTracer();
+    if (!tracer.enabled) {
+      // Fast path: invoke fn with a shared no-op span (type-shape
+      // identical, zero allocations).
+      const { startSpan } = tracer;
+      const span = startSpan.call(tracer, name, opts);
+      return await fn(span);
+    }
+    const span = tracer.startSpan(name, opts);
+    try {
+      const result = await runWithSpan(span, () => fn(span));
+      if (span.status === "unset") span.setStatus("ok");
+      return result;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      span.setStatus("error", msg);
+      throw err;
+    } finally {
+      span.end();
+    }
+  }
+
+  /**
+   * Set attributes on the active request span (if any). Convenience
+   * wrapper so user code doesn't have to null-check `ctx.span`
+   * themselves.
+   */
+  setSpanAttributes(attrs: SpanAttributes): void {
+    this.span?.setAttributes(attrs);
+  }
 }
 
 /** Route context for error reporting */

package/src/filling/filling.ts

@@ -72,8 +72,17 @@ export interface LoaderOptions<T = unknown> {
 
 /** Loader 캐시/ISR 옵션 */
 export interface LoaderCacheOptions {
-  /** 캐시 유지 시간 (초). 0이면 캐시 안 함, Infinity면 영구 */
+  /**
+   * Fresh 캐시 유지 시간 (초). `maxAge` 의 별칭 — Next.js `revalidate`
+   * API 와 호환성을 유지한다. 0 이면 캐시 안 함.
+   */
   revalidate?: number;
+  /**
+   * Phase 18.ζ — fresh 창을 지난 뒤 캐시를 계속 서빙할 stale-while-revalidate
+   * 창 길이 (초). 지정 시 `revalidate` 구간 후 이 기간만큼 STALE 응답을
+   * 즉시 반환하고 백그라운드에서 재생성한다.
+   */
+  staleWhileRevalidate?: number;
   /** 온디맨드 무효화 태그 */
   tags?: string[];
 }

package/src/index.ts

@@ -38,6 +38,38 @@ export { type GuardViolation } from "./guard";
 export { type Severity } from "./guard";
 export { Image, type ImageProps } from "./components/Image";
 
+// Phase 18.θ — `Tracer` is exported by both `runtime/trace.ts` (the
+// legacy lifecycle trace collector) and `observability/tracing.ts` (the
+// new OTel tracer). `export *` from both yields TS2308 ambiguity, so
+// explicitly re-export the new one as canonical. The legacy runtime
+// tracer remains accessible via the `runtime/trace` subpath export
+// (`createTracer`, `TraceEvent`, etc. are unchanged).
+export {
+  Tracer,
+  ConsoleSpanExporter,
+  OtlpHttpSpanExporter,
+  encodeOtlpJson,
+  parseTraceparent,
+  formatTraceparent,
+  newTraceId,
+  newSpanId,
+  getActiveSpan,
+  runWithSpan,
+  injectTraceContext,
+  getTracer,
+  setTracer,
+  resetTracer,
+  createTracerFromConfig,
+  type Span,
+  type SpanAttributes,
+  type SpanExporter,
+  type SpanKind,
+  type SpanOptions,
+  type SpanStatus,
+  type TraceparentFields,
+  type TracerConfig,
+} from "./observability/tracing";
+
 // Consolidated Mandu namespace
 import { ManduFilling, ManduContext, ManduFillingFactory, createSSEConnection } from "./filling";
 import { createContract, defineHandler, defineRoute, createClient, contractFetch, createClientContract, querySchema, bodySchema, apiError } from "./contract";

package/src/observability/index.ts

@@ -35,3 +35,29 @@ export {
   type HeapSnapshot,
   type CacheName,
 } from "./metrics";
+// Phase 18.θ: OpenTelemetry-compatible request tracing
+export {
+  Tracer,
+  ConsoleSpanExporter,
+  OtlpHttpSpanExporter,
+  encodeOtlpJson,
+  parseTraceparent,
+  formatTraceparent,
+  newTraceId,
+  newSpanId,
+  getActiveSpan,
+  runWithSpan,
+  injectTraceContext,
+  getTracer,
+  setTracer,
+  resetTracer,
+  createTracerFromConfig,
+  type Span,
+  type SpanAttributes,
+  type SpanExporter,
+  type SpanKind,
+  type SpanOptions,
+  type SpanStatus,
+  type TraceparentFields,
+  type TracerConfig,
+} from "./tracing";