@mandujs/core 0.20.10 → 0.22.0

package/src/filling/cookie-codec.ts

@@ -0,0 +1,299 @@
+/**
+ * Cookie codec abstraction.
+ *
+ * Two interchangeable implementations of the parse/serialize I/O layer used by
+ * `CookieManager`:
+ *
+ * - {@link LegacyCookieCodec}: pure-JS, runtime-neutral (works anywhere that
+ *   has `Request`/`Response`/`encodeURIComponent`).
+ * - {@link BunCookieMapCodec}: delegates to `Bun.CookieMap` (Bun >= 1.3).
+ *
+ * The public `CookieManager` API is codec-agnostic. The codec only owns the
+ * translation between a wire-format `Cookie:` header string and in-memory
+ * entries, and between `(name, value, options)` and a `Set-Cookie:` string.
+ *
+ * Design notes:
+ * - Signed cookies (HMAC-SHA256) and `getParsed` live on `CookieManager` and do
+ *   not go through the codec. Their format (`encodeURIComponent(value).sig`)
+ *   must stay stable regardless of codec.
+ * - `Bun.CookieMap` auto-injects `SameSite=Lax` when `sameSite` is omitted and
+ *   reorders attributes relative to the legacy serializer. The Bun codec
+ *   post-processes output to strip the implicit `SameSite=Lax` so behavior
+ *   matches the legacy codec exactly. Attribute order differs between codecs
+ *   but is semantically identical (RFC 6265 treats attributes as an unordered
+ *   set).
+ */
+
+import type { CookieOptions } from "./context";
+
+// ========== Interface ==========
+
+/**
+ * Low-level cookie wire-format codec.
+ *
+ * Implementations translate between `Cookie:` / `Set-Cookie:` string forms and
+ * in-memory values. They carry no state beyond the call and must be safe to
+ * share across concurrent requests.
+ */
+export interface CookieCodec {
+  /** Human-readable codec name for diagnostics and tests. */
+  readonly name: string;
+  /**
+   * Parse a raw `Cookie:` request header (RFC 6265) into a name→value map.
+   * Returns an empty map when `header` is null, empty, or unparseable.
+   *
+   * Values are URL-decoded. On decode failure the raw value is retained
+   * (matches legacy behavior so existing cookies in the wild keep working).
+   *
+   * For duplicate names the **first** occurrence wins; this matches RFC 6265
+   * §5.4's "the user agent SHOULD serve... the first match" guidance.
+   */
+  parseRequestHeader(header: string | null): Map<string, string>;
+  /**
+   * Serialize a single cookie into a `Set-Cookie:` header value.
+   *
+   * The returned string must not contain a leading `Set-Cookie:` prefix. Both
+   * name and value are URL-encoded to survive the header transport layer.
+   */
+  serializeSetCookie(name: string, value: string, options: CookieOptions): string;
+}
+
+// ========== Legacy (pure-JS) implementation ==========
+
+/**
+ * Runtime-neutral codec. Used when `Bun.CookieMap` is unavailable (Node.js,
+ * Deno, browsers, edge runtimes without Bun).
+ */
+export const LegacyCookieCodec: CookieCodec = {
+  name: "legacy",
+
+  parseRequestHeader(header: string | null): Map<string, string> {
+    const cookies = new Map<string, string>();
+    if (!header) return cookies;
+
+    const pairs = header.split(";");
+    for (const pair of pairs) {
+      const trimmed = pair.trim();
+      if (!trimmed) continue;
+      const eqIdx = trimmed.indexOf("=");
+      // RFC 6265 §4.2.1 requires cookie-pair = cookie-name "=" cookie-value.
+      // Bareword tokens (no '=') are not valid cookies; skip them.
+      if (eqIdx === -1) continue;
+      const rawName = trimmed.slice(0, eqIdx);
+      const rawValue = trimmed.slice(eqIdx + 1);
+      if (!rawName) continue;
+      const name = safeDecode(rawName);
+      // RFC 6265: first cookie wins on duplicate name.
+      if (cookies.has(name)) continue;
+      cookies.set(name, safeDecode(rawValue));
+    }
+    return cookies;
+  },
+
+  serializeSetCookie(name: string, value: string, options: CookieOptions): string {
+    const parts: string[] = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+
+    if (options.maxAge !== undefined) {
+      parts.push(`Max-Age=${options.maxAge}`);
+    }
+
+    if (options.expires) {
+      const expires =
+        options.expires instanceof Date
+          ? options.expires.toUTCString()
+          : options.expires;
+      parts.push(`Expires=${expires}`);
+    }
+
+    if (options.domain) {
+      parts.push(`Domain=${options.domain}`);
+    }
+
+    // Default path matches legacy behavior and most browser defaults.
+    parts.push(options.path ? `Path=${options.path}` : "Path=/");
+
+    if (options.secure) parts.push("Secure");
+    if (options.httpOnly) parts.push("HttpOnly");
+
+    if (options.sameSite) {
+      parts.push(`SameSite=${capitalize(options.sameSite)}`);
+    }
+
+    if (options.partitioned) parts.push("Partitioned");
+
+    return parts.join("; ");
+  },
+};
+
+// ========== Bun.CookieMap-backed implementation ==========
+
+interface BunCookieInit {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number | Date;
+  secure?: boolean;
+  httpOnly?: boolean;
+  partitioned?: boolean;
+  sameSite?: "strict" | "lax" | "none" | "Strict" | "Lax" | "None";
+  maxAge?: number;
+}
+
+interface BunCookieMapCtor {
+  new (init?: string): {
+    get(name: string): string | null;
+    entries(): IterableIterator<[string, string]>;
+    set(init: BunCookieInit): void;
+    toSetCookieHeaders(): string[];
+  };
+}
+
+/**
+ * Attempt to resolve `Bun.CookieMap` from the ambient runtime. Returns the
+ * constructor when available, or `null` on non-Bun runtimes or older Bun
+ * builds that lack the API.
+ */
+function resolveBunCookieMap(): BunCookieMapCtor | null {
+  // `Bun` is only present in Bun's runtime. Access via `globalThis` to avoid
+  // ReferenceError under other runtimes while still allowing bundlers to
+  // tree-shake based on the dynamic lookup.
+  const bun = (globalThis as unknown as { Bun?: { CookieMap?: unknown } }).Bun;
+  const Ctor = bun?.CookieMap;
+  if (typeof Ctor !== "function") return null;
+  return Ctor as BunCookieMapCtor;
+}
+
+/**
+ * Factory for the Bun-native codec. Returns `null` if `Bun.CookieMap` is not
+ * available, allowing callers to fall back to the legacy codec.
+ */
+export function createBunCookieMapCodec(): CookieCodec | null {
+  const CookieMap = resolveBunCookieMap();
+  if (!CookieMap) return null;
+
+  return {
+    name: "bun-cookiemap",
+
+    parseRequestHeader(header: string | null): Map<string, string> {
+      const cookies = new Map<string, string>();
+      if (!header) return cookies;
+      // Bun.CookieMap handles URL-decoding and whitespace, and iterates
+      // entries in insertion order.
+      const map = new CookieMap(header);
+      for (const [name, value] of map.entries()) {
+        if (!name) continue;
+        // First-wins semantics to match LegacyCookieCodec and RFC 6265.
+        if (!cookies.has(name)) cookies.set(name, value);
+      }
+      return cookies;
+    },
+
+    serializeSetCookie(name: string, value: string, options: CookieOptions): string {
+      const map = new CookieMap();
+      const init: BunCookieInit = { name, value };
+
+      if (options.maxAge !== undefined) init.maxAge = options.maxAge;
+      // NOTE: we deliberately omit `expires` from the Bun.CookieMap init and
+      // append our own Expires attribute below. Bun 1.3.10's CookieMap emits
+      // `Expires` in a non-standard form (e.g. `Tue, 15 Jun 2026 ... -0000`
+      // for a Monday — day-of-week mismatch) that breaks byte-parity with the
+      // legacy codec and is technically not RFC 7231 IMF-fixdate. Using
+      // `Date.toUTCString()` matches the legacy impl exactly.
+      if (options.domain) init.domain = options.domain;
+      init.path = options.path ?? "/";
+      if (options.secure) init.secure = true;
+      if (options.httpOnly) init.httpOnly = true;
+      if (options.partitioned) init.partitioned = true;
+      if (options.sameSite) init.sameSite = options.sameSite;
+
+      map.set(init);
+      const headers = map.toSetCookieHeaders();
+      if (headers.length === 0) {
+        // Defensive: Bun.CookieMap should always yield one header after set().
+        return LegacyCookieCodec.serializeSetCookie(name, value, options);
+      }
+      let header = headers[0];
+
+      // Bun.CookieMap auto-injects `SameSite=Lax` when sameSite is unspecified.
+      // The legacy codec omits SameSite in that case; preserve that behavior.
+      if (!options.sameSite) {
+        header = stripDefaultSameSite(header);
+      }
+
+      // Append RFC 7231-compliant Expires after Bun's other attributes.
+      if (options.expires !== undefined) {
+        const expiresValue =
+          options.expires instanceof Date
+            ? options.expires.toUTCString()
+            : options.expires;
+        header += `; Expires=${expiresValue}`;
+      }
+
+      return header;
+    },
+  };
+}
+
+/**
+ * Remove the trailing `; SameSite=Lax` that Bun injects when sameSite is not
+ * specified. Only strips an **exact, isolated** attribute so explicit
+ * `SameSite=Lax` from the caller survives (caller would have set
+ * `options.sameSite='lax'` and this function is skipped anyway).
+ */
+function stripDefaultSameSite(header: string): string {
+  // Prefer trailing position (Bun's current emit order).
+  if (header.endsWith("; SameSite=Lax")) {
+    return header.slice(0, -"; SameSite=Lax".length);
+  }
+  // Defensive: handle middle-position insertion if Bun reorders attributes.
+  const middle = header.indexOf("; SameSite=Lax;");
+  if (middle !== -1) {
+    return header.slice(0, middle) + header.slice(middle + "; SameSite=Lax".length);
+  }
+  return header;
+}
+
+// ========== Codec selection ==========
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * URL-decode a cookie token, preserving the raw value if the encoding is
+ * malformed. Matches the forgiving behavior of most cookie parsers (browsers,
+ * `cookie` npm package, Bun.CookieMap) so malformed cookies from clients do
+ * not crash server-side code.
+ */
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+let activeCodec: CookieCodec = resolveDefaultCodec();
+
+function resolveDefaultCodec(): CookieCodec {
+  return createBunCookieMapCodec() ?? LegacyCookieCodec;
+}
+
+/**
+ * Return the active codec. Resolved once at module load and overridable via
+ * {@link _setCodecForTesting}.
+ */
+export function getCookieCodec(): CookieCodec {
+  return activeCodec;
+}
+
+/**
+ * Test-only escape hatch for forcing a specific codec. Pass a codec to
+ * override, or omit to restore the runtime-detected default.
+ *
+ * @internal
+ */
+export function _setCodecForTesting(codec?: CookieCodec): void {
+  activeCodec = codec ?? resolveDefaultCodec();
+}

package/src/filling/deps.ts

@@ -80,10 +80,34 @@ export interface EventBusDeps {
  */
 export interface FillingDeps {
   /**
-   * 데이터베이스 접근
+   * 데이터베이스 접근 (legacy shape — query/transaction).
+   * Kept for backward compatibility. New code should prefer `sql` below.
    */
   db?: DbDeps;
 
+  /**
+   * Phase 4c — Bun.sql-backed `Db` handle.
+   *
+   * This is the tagged-template callable shape produced by
+   * `@mandujs/core/db`'s `createDb()`. Generated resource repos
+   * (`createXRepo(db)` from `*.repo.ts`) consume this directly.
+   *
+   * Typed as `unknown` here to avoid a circular type import from
+   * `@mandujs/core/db` into the filling layer. Consumers cast via
+   * `import type { Db } from "@mandujs/core/db"` at the call site:
+   *
+   * @example
+   * ```ts
+   * import type { Db } from "@mandujs/core/db";
+   * export default Mandu.filling().get((ctx) => {
+   *   const db = ctx.deps.sql as Db;
+   *   const repo = createUsersRepo(db);
+   *   return ctx.ok(await repo.findMany());
+   * });
+   * ```
+   */
+  sql?: unknown;
+
   /**
    * 캐시 접근
    */

package/src/filling/filling.ts

@@ -48,8 +48,19 @@ export interface MiddlewarePlugin {
   mapResponse?: MapResponseHandler;
 }
 
-/** Loader function type - SSR 데이터 로딩 */
-export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
+/**
+ * Loader function type — SSR data loader.
+ *
+ * Returns the route's data object `T`, or a `Response` to short-circuit
+ * the SSR pipeline (DX-3). A returned `Response` with a redirect-range
+ * status code becomes the final response — SSR is skipped and any pending
+ * `ctx.cookies` are merged into the outgoing headers. Use the
+ * `redirect(url)` helper for the common case; throwing a `Response` is
+ * also accepted (Remix idiom).
+ */
+export type Loader<T = unknown> = (
+  ctx: ManduContext
+) => T | Response | Promise<T | Response>;
 
 /** Loader 실행 옵션 */
 export interface LoaderOptions<T = unknown> {
@@ -231,10 +242,24 @@ export class ManduFilling<TLoaderData = unknown> {
     return this.config.renderMode ?? "dynamic";
   }
 
+  /**
+   * Execute the registered loader.
+   *
+   * Return shape:
+   *   - `TLoaderData` — normal loader data
+   *   - `Response` — the loader returned a Response (e.g. `redirect("/login")`).
+   *     Callers must check `instanceof Response` and short-circuit their
+   *     pipeline instead of treating the value as page data.
+   *   - `undefined` — no loader registered
+   *
+   * DX-3: the Response overload is explicit in the signature so downstream
+   * TypeScript consumers are forced to narrow before consuming data —
+   * prevents accidentally passing a Response into renderPageSSR.
+   */
   async executeLoader(
     ctx: ManduContext,
     options: LoaderOptions<TLoaderData> = {}
-  ): Promise<TLoaderData | undefined> {
+  ): Promise<TLoaderData | Response | undefined> {
     if (!this.config.loader) {
       return undefined;
     }