@mandujs/core 0.29.1 → 0.31.0

package/src/client/index.ts

@@ -112,7 +112,17 @@ export { Link, NavLink, type LinkProps, type NavLinkProps } from "./Link";
 export { Form, type FormProps, type FormState } from "./Form";
 
 // RPC Client
-export { createClient, RpcError, type RpcMethods, type RpcRequestOptions, type RpcClientOptions } from "./rpc";
+export {
+  createClient,
+  RpcError,
+  type RpcMethods,
+  type RpcRequestOptions,
+  type RpcClientOptions,
+  // Phase 18.κ — typed RPC proxy
+  createRpcClient,
+  RpcCallError,
+  type CreateRpcClientOptions,
+} from "./rpc";
 
 // useFetch Composable
 export { useFetch, type UseFetchOptions, type UseFetchReturn } from "./use-fetch";

package/src/client/rpc.ts

@@ -1,140 +1,293 @@
-/**
- * Mandu RPC Client
- * Contract 정의에서 타입 안전한 API 클라이언트 생성
- */
-
-// ========== Types ==========
-
-/** RPC 클라이언트 에러 */
-export class RpcError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly body: unknown
-  ) {
-    super(`API Error ${status}`);
-    this.name = "RpcError";
-  }
-}
-
-export interface RpcRequestOptions {
-  query?: Record<string, unknown>;
-  body?: unknown;
-  params?: Record<string, string>;
-  headers?: Record<string, string>;
-  signal?: AbortSignal;
-}
-
-export interface RpcClientOptions {
-  /** API base URL (기본: 현재 origin) */
-  baseUrl?: string;
-  /** 공통 헤더 */
-  headers?: Record<string, string>;
-  /** 커스텀 fetch (테스트용) */
-  fetch?: typeof globalThis.fetch;
-}
-
-// ========== Implementation ==========
-
-/**
- * Contract 기반 타입 안전 RPC 클라이언트 생성
- *
- * @example
- * ```typescript
- * import { createClient } from "@mandujs/core/client";
- * import type todoContract from "../spec/contracts/api-todos.contract";
- *
- * const api = createClient<typeof todoContract>("/api/todos");
- *
- * // 타입 추론 동작
- * const { todos } = await api.get({ query: { page: 2 } });
- * const { id } = await api.post({ body: { title: "New" } });
- * ```
- */
-export function createClient<TContract = unknown>(
-  path: string,
-  options?: RpcClientOptions
-): RpcMethods {
-  const baseFetch = options?.fetch ?? globalThis.fetch;
-  const baseUrl = options?.baseUrl ?? "";
-  const baseHeaders = options?.headers ?? {};
-
-  function makeRequest(method: string) {
-    return async (input?: RpcRequestOptions): Promise<unknown> => {
-      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
-
-      // URL 파라미터 치환
-      if (input?.params) {
-        let resolvedPath = url.pathname;
-        for (const [key, value] of Object.entries(input.params)) {
-          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
-        }
-        // 미해결 파라미터 검출
-        if (resolvedPath.includes(":")) {
-          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
-        }
-        url.pathname = resolvedPath;
-      }
-
-      // Query 파라미터
-      if (input?.query) {
-        for (const [key, value] of Object.entries(input.query)) {
-          if (value !== undefined && value !== null) {
-            url.searchParams.set(key, String(value));
-          }
-        }
-      }
-
-      const headers: Record<string, string> = {
-        ...baseHeaders,
-        ...input?.headers,
-        "Accept": "application/json",
-      };
-
-      const fetchOptions: RequestInit = {
-        method: method.toUpperCase(),
-        headers,
-        signal: input?.signal,
-      };
-
-      // Body (GET/HEAD 제외)
-      if (input?.body && method !== "GET" && method !== "HEAD") {
-        fetchOptions.body = JSON.stringify(input.body);
-        headers["Content-Type"] = "application/json";
-      }
-
-      const response = await baseFetch(url.toString(), fetchOptions);
-
-      if (!response.ok) {
-        let body: unknown;
-        try {
-          body = await response.json();
-        } catch {
-          body = await response.text().catch(() => null);
-        }
-        throw new RpcError(response.status, body);
-      }
-
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        return response.json();
-      }
-      return response.text();
-    };
-  }
-
-  return {
-    get: makeRequest("GET"),
-    post: makeRequest("POST"),
-    put: makeRequest("PUT"),
-    patch: makeRequest("PATCH"),
-    delete: makeRequest("DELETE"),
-  };
-}
-
-export interface RpcMethods {
-  get: (input?: RpcRequestOptions) => Promise<unknown>;
-  post: (input?: RpcRequestOptions) => Promise<unknown>;
-  put: (input?: RpcRequestOptions) => Promise<unknown>;
-  patch: (input?: RpcRequestOptions) => Promise<unknown>;
-  delete: (input?: RpcRequestOptions) => Promise<unknown>;
-}
+/**
+ * Mandu RPC Client
+ * Contract 정의에서 타입 안전한 API 클라이언트 생성
+ */
+
+// ========== Types ==========
+
+/** RPC 클라이언트 에러 */
+export class RpcError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown
+  ) {
+    super(`API Error ${status}`);
+    this.name = "RpcError";
+  }
+}
+
+export interface RpcRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export interface RpcClientOptions {
+  /** API base URL (기본: 현재 origin) */
+  baseUrl?: string;
+  /** 공통 헤더 */
+  headers?: Record<string, string>;
+  /** 커스텀 fetch (테스트용) */
+  fetch?: typeof globalThis.fetch;
+}
+
+// ========== Implementation ==========
+
+/**
+ * Contract 기반 타입 안전 RPC 클라이언트 생성
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@mandujs/core/client";
+ * import type todoContract from "../spec/contracts/api-todos.contract";
+ *
+ * const api = createClient<typeof todoContract>("/api/todos");
+ *
+ * // 타입 추론 동작
+ * const { todos } = await api.get({ query: { page: 2 } });
+ * const { id } = await api.post({ body: { title: "New" } });
+ * ```
+ */
+export function createClient<TContract = unknown>(
+  path: string,
+  options?: RpcClientOptions
+): RpcMethods {
+  const baseFetch = options?.fetch ?? globalThis.fetch;
+  const baseUrl = options?.baseUrl ?? "";
+  const baseHeaders = options?.headers ?? {};
+
+  function makeRequest(method: string) {
+    return async (input?: RpcRequestOptions): Promise<unknown> => {
+      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+
+      // URL 파라미터 치환
+      if (input?.params) {
+        let resolvedPath = url.pathname;
+        for (const [key, value] of Object.entries(input.params)) {
+          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+        }
+        // 미해결 파라미터 검출
+        if (resolvedPath.includes(":")) {
+          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
+        }
+        url.pathname = resolvedPath;
+      }
+
+      // Query 파라미터
+      if (input?.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+          if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+          }
+        }
+      }
+
+      const headers: Record<string, string> = {
+        ...baseHeaders,
+        ...input?.headers,
+        "Accept": "application/json",
+      };
+
+      const fetchOptions: RequestInit = {
+        method: method.toUpperCase(),
+        headers,
+        signal: input?.signal,
+      };
+
+      // Body (GET/HEAD 제외)
+      if (input?.body && method !== "GET" && method !== "HEAD") {
+        fetchOptions.body = JSON.stringify(input.body);
+        headers["Content-Type"] = "application/json";
+      }
+
+      const response = await baseFetch(url.toString(), fetchOptions);
+
+      if (!response.ok) {
+        let body: unknown;
+        try {
+          body = await response.json();
+        } catch {
+          body = await response.text().catch(() => null);
+        }
+        throw new RpcError(response.status, body);
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        return response.json();
+      }
+      return response.text();
+    };
+  }
+
+  return {
+    get: makeRequest("GET"),
+    post: makeRequest("POST"),
+    put: makeRequest("PUT"),
+    patch: makeRequest("PATCH"),
+    delete: makeRequest("DELETE"),
+  };
+}
+
+export interface RpcMethods {
+  get: (input?: RpcRequestOptions) => Promise<unknown>;
+  post: (input?: RpcRequestOptions) => Promise<unknown>;
+  put: (input?: RpcRequestOptions) => Promise<unknown>;
+  patch: (input?: RpcRequestOptions) => Promise<unknown>;
+  delete: (input?: RpcRequestOptions) => Promise<unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 18.κ — Typed RPC Client (tRPC-like)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// `createRpcClient<typeof postsRpc>()` returns a Proxy whose properties
+// are the RPC procedure names (`list`, `get`, …). Each access produces
+// an async function whose input type is the procedure's Zod input
+// type and whose return type is the procedure's Zod output type.
+//
+// Wire protocol:
+//   POST <baseUrl>/<method>
+//   body: { "input": <value> }
+//   response: { "ok": true, "data": <value> }
+//            | { "ok": false, "error": { code, message, issues? } }
+//
+// Errors throw {@link RpcCallError} with the structured fields
+// preserved so UI code can surface field-level validation issues.
+
+import type { RpcClient, RpcDefinition, RpcProcedureRecord, RpcWireEnvelope, RpcWireError } from "../contract/rpc";
+
+/** Options passed to {@link createRpcClient}. */
+export interface CreateRpcClientOptions {
+  /**
+   * Absolute or site-relative base URL for the RPC endpoint —
+   * typically `/api/rpc/<name>`. The method name is appended.
+   */
+  baseUrl: string;
+  /** Extra headers sent with every call. */
+  headers?: Record<string, string>;
+  /** Custom fetch (e.g. test double or node-fetch polyfill). */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Optional per-call AbortSignal factory. Useful when the proxy is
+   * shared across React components that want independent cancellation.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Typed error thrown by {@link createRpcClient} calls on non-OK
+ * envelopes. Carries the wire-level {@link RpcWireError} + HTTP
+ * status so callers can distinguish validation vs. handler errors
+ * without string-matching on `message`.
+ */
+export class RpcCallError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly error: RpcWireError
+  ) {
+    super(`[Mandu RPC] ${error.code}: ${error.message}`);
+    this.name = "RpcCallError";
+  }
+
+  /** Machine-readable code (forwarded from the server). */
+  get code(): string {
+    return this.error.code;
+  }
+
+  /** Field-level issues, if any. */
+  get issues(): RpcWireError["issues"] {
+    return this.error.issues;
+  }
+}
+
+/**
+ * Create a typed RPC client from an `RpcDefinition` type import.
+ *
+ * The implementation uses a `Proxy` so no codegen step is required —
+ * TypeScript infers call signatures from the imported `typeof` at
+ * compile time, and at runtime every property access produces a
+ * fetch wrapper.
+ *
+ * @example
+ * ```ts
+ * import { createRpcClient } from "@mandujs/core/client";
+ * import type { postsRpc } from "../server/rpc/posts";
+ *
+ * const api = createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" });
+ * const posts = await api.list({ limit: 20 });   // fully typed
+ * const post  = await api.get({ id: "abc" });    // fully typed
+ * ```
+ *
+ * Type-check failures at the call site are real compile errors:
+ * `api.list({ limit: "not-a-number" })` is a TS2322.
+ */
+export function createRpcClient<TDef extends RpcDefinition<RpcProcedureRecord>>(
+  options: CreateRpcClientOptions
+): RpcClient<TDef> {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const baseHeaders = options.headers ?? {};
+
+  const call = async (method: string, input: unknown): Promise<unknown> => {
+    const url = `${baseUrl}/${method}`;
+    const payload = input === undefined ? { input: undefined } : { input };
+    const response = await baseFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...baseHeaders,
+      },
+      body: JSON.stringify(payload),
+      signal: options.signal,
+    });
+
+    // Prefer JSON parse (every legitimate RPC response is JSON), but
+    // tolerate non-JSON failure paths (e.g. upstream proxy error).
+    let envelope: RpcWireEnvelope | null = null;
+    const text = await response.text();
+    try {
+      envelope = text.length > 0 ? (JSON.parse(text) as RpcWireEnvelope) : null;
+    } catch {
+      envelope = null;
+    }
+
+    if (envelope && envelope.ok === true) {
+      return envelope.data;
+    }
+
+    // Non-OK path — throw a structured error. Prefer server-emitted
+    // envelope; fall back to a synthesized one for transport errors.
+    let error: RpcWireError;
+    if (envelope && envelope.ok === false) {
+      error = envelope.error;
+    } else {
+      error = {
+        code: response.ok ? "BAD_RESPONSE" : `HTTP_${response.status}`,
+        message:
+          text.length > 0
+            ? text.slice(0, 500)
+            : `RPC call to ${url} failed with HTTP ${response.status}`,
+      };
+    }
+    throw new RpcCallError(response.status, error);
+  };
+
+  // A Proxy on a plain object: every property access returns a
+  // pre-curried call fn. Symbol keys (`Symbol.toStringTag`, etc.) fall
+  // through so `console.log(api)` does not throw.
+  const target = Object.create(null) as Record<string, unknown>;
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return undefined;
+      // Allow common non-method inspection hooks to no-op.
+      if (prop === "then") return undefined; // not thenable
+      if (prop === "toJSON") return undefined;
+      return (input?: unknown) => call(prop, input);
+    },
+  }) as RpcClient<TDef>;
+}
+

package/src/config/mandu.ts

@@ -3,6 +3,8 @@ import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
+import type { RpcDefinition, RpcProcedureRecord } from "../contract/rpc";
+import type { CronDef } from "../scheduler";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
@@ -170,6 +172,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 +298,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>;
@@ -305,6 +375,53 @@ export interface ManduConfig {
    * @see `docs/architect/middleware-composition.md`
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.κ — tRPC-like typed RPC endpoints.
+   *
+   * Keys become URL segments: `endpoints.posts` is served from
+   * `/api/rpc/posts/<method>`. Each value is a `defineRpc()` result —
+   * a tagged object carrying Zod input/output schemas and handler
+   * functions. The runtime dispatcher (`runtime/server.ts`) registers
+   * every declared endpoint at `startServer()` time and validates
+   * both request inputs and handler outputs against the schemas.
+   *
+   * Wire protocol: `POST /api/rpc/<name>/<method>` with JSON body
+   * `{ "input": <value> }`; returns `{ ok: true, data }` or
+   * `{ ok: false, error: { code, message, issues? } }`.
+   *
+   * Client: `createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" })`.
+   *
+   * @see `docs/architect/typed-rpc.md`
+   * @see `@mandujs/core/contract/rpc` for `defineRpc`.
+   * @see `@mandujs/core/client/rpc` for `createRpcClient`.
+   */
+  rpc?: {
+    endpoints?: Record<string, RpcDefinition<RpcProcedureRecord>>;
+  };
+  /**
+   * Phase 18.λ — declarative cron job scheduler.
+   *
+   * `scheduler.jobs` is an array of {@link CronDef} objects (from
+   * `@mandujs/core/scheduler`). At `startServer()` boot time the runtime
+   * filters the set by `runOn === "bun"` (or `runOn` omitted) and registers
+   * each surviving job with `Bun.cron`. At build time, when
+   * `--target=workers` is set, the CLI filters by `runOn === "workers"` (or
+   * omitted) and emits the schedule strings into the generated
+   * `wrangler.toml` `[triggers] crons = [...]` block.
+   *
+   * Schedule strings are validated synchronously at `defineCron` time, so
+   * malformed crontabs fail boot instead of silently never firing.
+   *
+   * `scheduler.disabled` is an escape hatch for environments where cron
+   * should not fire (e.g., a read-only replica). Default: `false`.
+   *
+   * @see `docs/architect/cron-scheduler.md`
+   * @see `@mandujs/core/scheduler` for `defineCron`.
+   */
+  scheduler?: {
+    jobs?: CronDef[];
+    disabled?: boolean;
+  };
 }
 
 export const CONFIG_FILES = [