@mandujs/core 0.29.1 → 0.31.0

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/middleware/index.ts

@@ -29,6 +29,13 @@ export {
   rateLimitMiddleware,
 } from "./bridge";
 
+export {
+  schedulerCron,
+  setActiveSchedulerRegistration,
+  getActiveSchedulerRegistration,
+  type SchedulerCronMiddlewareOptions,
+} from "./scheduler-cron";
+
 export { cors, type CorsMiddlewareOptions } from "./cors";
 export { jwt, type JwtMiddlewareOptions } from "./jwt";
 export { csrf, type CsrfMiddlewareOptions } from "./csrf";

package/src/middleware/scheduler-cron.ts

@@ -0,0 +1,96 @@
+/**
+ * `scheduler-cron` — request-level middleware that exposes the running
+ * scheduler registration on `ctx` so handlers can inspect job status or
+ * trigger an ad-hoc tick for debugging.
+ *
+ * This is intentionally a thin bridge — the cron jobs themselves are
+ * defined with {@link import("../scheduler").defineCron} and started at
+ * `startServer()` boot time. The middleware does NOT start or stop the
+ * scheduler; its only job is to make the `CronRegistration` handle
+ * available to downstream request handlers (e.g., an observability
+ * dashboard API that wants to render `status()`).
+ *
+ * The middleware is opt-in — it's NOT part of the default chain. Add it
+ * to `mandu.config.ts` `middleware: [...]` only if you have a route that
+ * needs `ctx.scheduler`.
+ *
+ * @example
+ * ```ts
+ * // mandu.config.ts
+ * import { defineConfig } from "@mandujs/core";
+ * import { schedulerCron } from "@mandujs/core/middleware";
+ * import { jobs } from "./jobs";
+ *
+ * export default defineConfig({
+ *   scheduler: { jobs },
+ *   middleware: [schedulerCron()],
+ * });
+ * ```
+ */
+
+import { defineMiddleware } from "./define";
+import type { Middleware } from "./define";
+import type { CronRegistration } from "../scheduler";
+
+/**
+ * Global handle to the active {@link CronRegistration}, set by
+ * `startServer()` when it boots the scheduler. `scheduler-cron` middleware
+ * reads this slot on every request so the registration is always the one
+ * actually running.
+ *
+ * We store it on `globalThis` rather than module-scope so that multiple
+ * bundles (e.g., `@mandujs/core` loaded twice in a monorepo hot-reload)
+ * still see the same handle — matches the registry pattern in
+ * `runtime/server.ts`.
+ */
+const GLOBAL_KEY = "__MANDU_SCHEDULER_REGISTRATION__";
+
+interface SchedulerGlobal {
+  [GLOBAL_KEY]?: CronRegistration | null;
+}
+
+export function setActiveSchedulerRegistration(reg: CronRegistration | null): void {
+  (globalThis as unknown as SchedulerGlobal)[GLOBAL_KEY] = reg;
+}
+
+export function getActiveSchedulerRegistration(): CronRegistration | null {
+  return (globalThis as unknown as SchedulerGlobal)[GLOBAL_KEY] ?? null;
+}
+
+export interface SchedulerCronMiddlewareOptions {
+  /**
+   * Custom header to stamp on the response with the current scheduler job
+   * count. Useful for smoke-checking that the scheduler is running in a
+   * given environment. Default: no header is added.
+   */
+  statusHeader?: string;
+}
+
+/**
+ * Creates a middleware that exposes the scheduler registration via a response
+ * header and (optionally) stamps a status header. The registration itself is
+ * wired into `ctx` via the request-level composition chain — downstream
+ * code reads it with {@link getActiveSchedulerRegistration}.
+ */
+export function schedulerCron(options: SchedulerCronMiddlewareOptions = {}): Middleware {
+  return defineMiddleware({
+    name: "scheduler-cron",
+    async handler(_req, next) {
+      const response = await next();
+      const reg = getActiveSchedulerRegistration();
+      if (reg && options.statusHeader) {
+        const status = reg.status();
+        const jobCount = Object.keys(status).length;
+        // Clone headers to avoid mutating an immutable response body.
+        const headers = new Headers(response.headers);
+        headers.set(options.statusHeader, String(jobCount));
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers,
+        });
+      }
+      return response;
+    },
+  });
+}

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";