@mandujs/core 0.53.3 → 0.54.0

package/src/middleware/session.ts

@@ -1,174 +1,174 @@
-/**
- * Session Middleware Plugin
- *
- * Thin wrapper around the existing `SessionStorage` contract
- * (`packages/core/src/filling/session.ts`). Attaches an already-fetched
- * {@link Session} to the request context so handlers can do:
- *
- *   const session = ctx.get<Session>("session");
- *   session.set("userId", user.id);
- *   await saveSession(ctx);
- *
- * ...instead of threading storage + cookies through manually.
- *
- * Commit is **caller-driven**: the middleware pipeline has no after-response
- * hook that can mutate the outgoing Response, so auto-commit-on-exit is not
- * possible. Handlers must call `saveSession(ctx)` or `destroySession(ctx)`
- * explicitly before returning a response. `loginUser` / `logoutUser`
- * (Phase 2.4) will wrap those calls.
- *
- * @example
- * ```typescript
- * import { session, saveSession } from "@mandujs/core/middleware";
- * import { createCookieSessionStorage } from "@mandujs/core";
- *
- * const storage = createCookieSessionStorage({
- *   cookie: { secrets: [process.env.SESSION_SECRET!] },
- * });
- *
- * export default Mandu.filling()
- *   .use(session({ storage }))
- *   .post(async (ctx) => {
- *     const s = ctx.get<Session>("session");
- *     s.set("userId", "42");
- *     await saveSession(ctx);
- *     return ctx.ok({ ok: true });
- *   });
- * ```
- */
-import type { ManduContext } from "../filling/context";
-import type { Session, SessionStorage } from "../filling/session";
-
-// ========== Types ==========
-
-export interface SessionMiddlewareOptions {
-  /** The storage implementation. Create via `createCookieSessionStorage(...)`. */
-  storage: SessionStorage;
-  /** Context key under which the Session is attached. Default: `"session"`. */
-  attachAs?: string;
-  /** Context key under which the storage is attached (for helpers). Default: `"_sessionStorage"`. */
-  storageKey?: string;
-}
-
-/** Middleware signature matching `jwt.ts` / `csrf.ts`. */
-type Middleware = (ctx: ManduContext) => Promise<Response | void>;
-
-// ========== Defaults ==========
-
-const DEFAULT_ATTACH_KEY = "session";
-const DEFAULT_STORAGE_KEY = "_sessionStorage";
-
-// ========== Middleware ==========
-
-/**
- * Attach a `Session` (and its storage) to the context for the duration of the
- * request.
- *
- * Does NOT auto-commit on exit — the middleware pipeline has no after-response
- * hook that can both (a) run after the handler returns and (b) mutate the
- * outgoing Response. Handlers persist explicitly via {@link saveSession} or
- * {@link destroySession}.
- */
-export function session(options: SessionMiddlewareOptions): Middleware {
-  if (!options || !options.storage) {
-    throw new Error("[Mandu Session] `storage` is required (use createCookieSessionStorage)");
-  }
-  const {
-    storage,
-    attachAs = DEFAULT_ATTACH_KEY,
-    storageKey = DEFAULT_STORAGE_KEY,
-  } = options;
-
-  return async (ctx: ManduContext): Promise<Response | void> => {
-    const s = await storage.getSession(ctx.cookies);
-    ctx.set(attachAs, s);
-    ctx.set(storageKey, storage);
-  };
-}
-
-// ========== Helpers ==========
-
-/**
- * Commit the attached session via its storage, applying the resulting
- * `Set-Cookie` header to `ctx.cookies` so the next `ctx.json/ok/redirect`
- * picks it up automatically.
- *
- * No-op when the session is not dirty (unless `force: true`). Throws when the
- * session middleware has not been installed on this request.
- *
- * IMPORTANT ordering: `ctx.json()` / `ctx.ok()` snapshot pending cookies at
- * the moment they build their Response. Call `saveSession` **before** any
- * response-producing method so the Set-Cookie makes it onto the wire.
- */
-export async function saveSession(
-  ctx: ManduContext,
-  options?: { force?: boolean; attachAs?: string; storageKey?: string }
-): Promise<void> {
-  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
-  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
-
-  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
-
-  if (!options?.force && !s.isDirty()) {
-    return;
-  }
-
-  const setCookie = await storage.commitSession(s);
-  ctx.cookies.appendRawSetCookie(setCookie);
-  s.markClean();
-}
-
-/**
- * Destroy the attached session: clears in-memory data AND emits an
- * expiring Set-Cookie so the browser drops its copy.
- *
- * Throws when the session middleware has not been installed on this request.
- *
- * Same ordering caveat as {@link saveSession}: call before the
- * response-producing method.
- */
-export async function destroySession(
-  ctx: ManduContext,
-  options?: { attachAs?: string; storageKey?: string }
-): Promise<void> {
-  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
-  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
-
-  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
-
-  const setCookie = await storage.destroySession(s);
-  // Wipe in-memory state first so subsequent handler code in the same request
-  // sees an empty session (prevents accidental re-use of stale data between
-  // destroy and response emit).
-  s.clear();
-  ctx.cookies.appendRawSetCookie(setCookie);
-  // destroy() emits a new cookie; the session is now "clean" relative to that
-  // just-written state — any further mutation would re-dirty it.
-  s.markClean();
-}
-
-// ========== Internal ==========
-
-/**
- * Fetch the Session + SessionStorage from context keys, throwing a clear
- * error when the middleware was not installed.
- *
- * Uses a plain `Error` rather than `AuthenticationError` because missing
- * middleware is a wiring mistake (500-class server error), not an end-user
- * auth failure (401).
- */
-function resolveSessionAndStorage(
-  ctx: ManduContext,
-  attachAs: string,
-  storageKey: string
-): { session: Session; storage: SessionStorage } {
-  const s = ctx.get<Session>(attachAs);
-  const storage = ctx.get<SessionStorage>(storageKey);
-  if (!s || !storage) {
-    throw new Error(
-      "[Mandu Session] saveSession/destroySession called without session() middleware installed. " +
-        "Add `.use(session({ storage }))` to your filling chain."
-    );
-  }
-  return { session: s, storage };
-}
+/**
+ * Session Middleware Plugin
+ *
+ * Thin wrapper around the existing `SessionStorage` contract
+ * (`packages/core/src/filling/session.ts`). Attaches an already-fetched
+ * {@link Session} to the request context so handlers can do:
+ *
+ *   const session = ctx.get<Session>("session");
+ *   session.set("userId", user.id);
+ *   await saveSession(ctx);
+ *
+ * ...instead of threading storage + cookies through manually.
+ *
+ * Commit is **caller-driven**: the middleware pipeline has no after-response
+ * hook that can mutate the outgoing Response, so auto-commit-on-exit is not
+ * possible. Handlers must call `saveSession(ctx)` or `destroySession(ctx)`
+ * explicitly before returning a response. `loginUser` / `logoutUser`
+ * (Phase 2.4) will wrap those calls.
+ *
+ * @example
+ * ```typescript
+ * import { session, saveSession } from "@mandujs/core/middleware";
+ * import { createCookieSessionStorage } from "@mandujs/core";
+ *
+ * const storage = createCookieSessionStorage({
+ *   cookie: { secrets: [process.env.SESSION_SECRET!] },
+ * });
+ *
+ * export default Mandu.filling()
+ *   .use(session({ storage }))
+ *   .post(async (ctx) => {
+ *     const s = ctx.get<Session>("session");
+ *     s.set("userId", "42");
+ *     await saveSession(ctx);
+ *     return ctx.ok({ ok: true });
+ *   });
+ * ```
+ */
+import type { ManduContext } from "../filling/context";
+import type { Session, SessionStorage } from "../filling/session";
+
+// ========== Types ==========
+
+export interface SessionMiddlewareOptions {
+  /** The storage implementation. Create via `createCookieSessionStorage(...)`. */
+  storage: SessionStorage;
+  /** Context key under which the Session is attached. Default: `"session"`. */
+  attachAs?: string;
+  /** Context key under which the storage is attached (for helpers). Default: `"_sessionStorage"`. */
+  storageKey?: string;
+}
+
+/** Middleware signature matching `jwt.ts` / `csrf.ts`. */
+type Middleware = (ctx: ManduContext) => Promise<Response | void>;
+
+// ========== Defaults ==========
+
+const DEFAULT_ATTACH_KEY = "session";
+const DEFAULT_STORAGE_KEY = "_sessionStorage";
+
+// ========== Middleware ==========
+
+/**
+ * Attach a `Session` (and its storage) to the context for the duration of the
+ * request.
+ *
+ * Does NOT auto-commit on exit — the middleware pipeline has no after-response
+ * hook that can both (a) run after the handler returns and (b) mutate the
+ * outgoing Response. Handlers persist explicitly via {@link saveSession} or
+ * {@link destroySession}.
+ */
+export function session(options: SessionMiddlewareOptions): Middleware {
+  if (!options || !options.storage) {
+    throw new Error("[Mandu Session] `storage` is required (use createCookieSessionStorage)");
+  }
+  const {
+    storage,
+    attachAs = DEFAULT_ATTACH_KEY,
+    storageKey = DEFAULT_STORAGE_KEY,
+  } = options;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    const s = await storage.getSession(ctx.cookies);
+    ctx.set(attachAs, s);
+    ctx.set(storageKey, storage);
+  };
+}
+
+// ========== Helpers ==========
+
+/**
+ * Commit the attached session via its storage, applying the resulting
+ * `Set-Cookie` header to `ctx.cookies` so the next `ctx.json/ok/redirect`
+ * picks it up automatically.
+ *
+ * No-op when the session is not dirty (unless `force: true`). Throws when the
+ * session middleware has not been installed on this request.
+ *
+ * IMPORTANT ordering: `ctx.json()` / `ctx.ok()` snapshot pending cookies at
+ * the moment they build their Response. Call `saveSession` **before** any
+ * response-producing method so the Set-Cookie makes it onto the wire.
+ */
+export async function saveSession(
+  ctx: ManduContext,
+  options?: { force?: boolean; attachAs?: string; storageKey?: string }
+): Promise<void> {
+  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
+
+  if (!options?.force && !s.isDirty()) {
+    return;
+  }
+
+  const setCookie = await storage.commitSession(s);
+  ctx.cookies.appendRawSetCookie(setCookie);
+  s.markClean();
+}
+
+/**
+ * Destroy the attached session: clears in-memory data AND emits an
+ * expiring Set-Cookie so the browser drops its copy.
+ *
+ * Throws when the session middleware has not been installed on this request.
+ *
+ * Same ordering caveat as {@link saveSession}: call before the
+ * response-producing method.
+ */
+export async function destroySession(
+  ctx: ManduContext,
+  options?: { attachAs?: string; storageKey?: string }
+): Promise<void> {
+  const attachAs = options?.attachAs ?? DEFAULT_ATTACH_KEY;
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const { session: s, storage } = resolveSessionAndStorage(ctx, attachAs, storageKey);
+
+  const setCookie = await storage.destroySession(s);
+  // Wipe in-memory state first so subsequent handler code in the same request
+  // sees an empty session (prevents accidental re-use of stale data between
+  // destroy and response emit).
+  s.clear();
+  ctx.cookies.appendRawSetCookie(setCookie);
+  // destroy() emits a new cookie; the session is now "clean" relative to that
+  // just-written state — any further mutation would re-dirty it.
+  s.markClean();
+}
+
+// ========== Internal ==========
+
+/**
+ * Fetch the Session + SessionStorage from context keys, throwing a clear
+ * error when the middleware was not installed.
+ *
+ * Uses a plain `Error` rather than `AuthenticationError` because missing
+ * middleware is a wiring mistake (500-class server error), not an end-user
+ * auth failure (401).
+ */
+function resolveSessionAndStorage(
+  ctx: ManduContext,
+  attachAs: string,
+  storageKey: string
+): { session: Session; storage: SessionStorage } {
+  const s = ctx.get<Session>(attachAs);
+  const storage = ctx.get<SessionStorage>(storageKey);
+  if (!s || !storage) {
+    throw new Error(
+      "[Mandu Session] saveSession/destroySession called without session() middleware installed. " +
+        "Add `.use(session({ storage }))` to your filling chain."
+    );
+  }
+  return { session: s, storage };
+}

package/src/middleware/timeout.ts

@@ -1,55 +1,55 @@
-/**
- * Timeout Middleware Plugin
- * filling.use(timeout(5000))
- */
-
-import type { MiddlewarePlugin } from "../filling/filling";
-import type { ManduContext } from "../filling/context";
-
-export interface TimeoutMiddlewareOptions {
-  /** 타임아웃 (ms) */
-  ms: number;
-  /** 타임아웃 시 응답 메시지 */
-  message?: string;
-  /** 타임아웃 시 HTTP 상태 코드 (기본: 408) */
-  status?: number;
-}
-
-/**
- * 요청 타임아웃 미들웨어
- *
- * @example
- * ```typescript
- * import { timeout } from "@mandujs/core/middleware";
- *
- * export default Mandu.filling()
- *   .use(timeout({ ms: 5000 }))
- *   .get(async (ctx) => { ... });
- * ```
- */
-export function timeout(options: TimeoutMiddlewareOptions | number): MiddlewarePlugin {
-  const config = typeof options === "number"
-    ? { ms: options, message: "Request Timeout", status: 408 }
-    : { message: "Request Timeout", status: 408, ...options };
-
-  return {
-    beforeHandle: async (ctx: ManduContext): Promise<Response | void> => {
-      // 타임아웃 타이머 설정 — 핸들러가 완료 전에 만료되면 408 반환
-      ctx.set("_timeout_timer", setTimeout(() => {
-        ctx.set("_timeout_expired", true);
-      }, config.ms));
-    },
-    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
-      // 타이머 정리
-      const timer = ctx.get<ReturnType<typeof setTimeout>>("_timeout_timer");
-      if (timer) clearTimeout(timer);
-
-      // 타임아웃 만료 확인
-      if (ctx.get<boolean>("_timeout_expired")) {
-        return ctx.json({ error: config.message }, config.status);
-      }
-
-      return response;
-    },
-  };
-}
+/**
+ * Timeout Middleware Plugin
+ * filling.use(timeout(5000))
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+
+export interface TimeoutMiddlewareOptions {
+  /** 타임아웃 (ms) */
+  ms: number;
+  /** 타임아웃 시 응답 메시지 */
+  message?: string;
+  /** 타임아웃 시 HTTP 상태 코드 (기본: 408) */
+  status?: number;
+}
+
+/**
+ * 요청 타임아웃 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { timeout } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(timeout({ ms: 5000 }))
+ *   .get(async (ctx) => { ... });
+ * ```
+ */
+export function timeout(options: TimeoutMiddlewareOptions | number): MiddlewarePlugin {
+  const config = typeof options === "number"
+    ? { ms: options, message: "Request Timeout", status: 408 }
+    : { message: "Request Timeout", status: 408, ...options };
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<Response | void> => {
+      // 타임아웃 타이머 설정 — 핸들러가 완료 전에 만료되면 408 반환
+      ctx.set("_timeout_timer", setTimeout(() => {
+        ctx.set("_timeout_expired", true);
+      }, config.ms));
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      // 타이머 정리
+      const timer = ctx.get<ReturnType<typeof setTimeout>>("_timeout_timer");
+      if (timer) clearTimeout(timer);
+
+      // 타임아웃 만료 확인
+      if (ctx.get<boolean>("_timeout_expired")) {
+        return ctx.json({ error: config.message }, config.status);
+      }
+
+      return response;
+    },
+  };
+}

package/src/observability/logger-adapter.ts

@@ -1,36 +1,36 @@
-/**
- * Logger -> EventBus adapter
- * Bridges the existing logger sink pattern into the unified observability bus.
- */
-
-import { eventBus } from "./event-bus";
-import type { ObservabilitySeverity } from "./event-bus";
-import type { LogEntry, LogLevel } from "../runtime/logger";
-
-const LEVEL_MAP: Record<LogLevel, ObservabilitySeverity> = {
-  debug: "info",
-  info: "info",
-  warn: "warn",
-  error: "error",
-};
-
-export function connectLoggerToEventBus(loggerInstance: { sink?: (entry: LogEntry) => void } & Record<string, unknown>): void {
-  const originalSink = loggerInstance.sink as ((entry: LogEntry) => void) | undefined;
-  loggerInstance.sink = (entry: LogEntry) => {
-    originalSink?.(entry);
-    eventBus.emit({
-      type: "http",
-      severity: LEVEL_MAP[entry.level] ?? "info",
-      source: "logger",
-      message: `${entry.method} ${entry.path} ${entry.status ?? ""}`.trim(),
-      duration: entry.duration,
-      data: {
-        requestId: entry.requestId,
-        method: entry.method,
-        path: entry.path,
-        status: entry.status,
-        slow: entry.slow,
-      },
-    });
-  };
-}
+/**
+ * Logger -> EventBus adapter
+ * Bridges the existing logger sink pattern into the unified observability bus.
+ */
+
+import { eventBus } from "./event-bus";
+import type { ObservabilitySeverity } from "./event-bus";
+import type { LogEntry, LogLevel } from "../runtime/logger";
+
+const LEVEL_MAP: Record<LogLevel, ObservabilitySeverity> = {
+  debug: "info",
+  info: "info",
+  warn: "warn",
+  error: "error",
+};
+
+export function connectLoggerToEventBus(loggerInstance: { sink?: (entry: LogEntry) => void } & Record<string, unknown>): void {
+  const originalSink = loggerInstance.sink as ((entry: LogEntry) => void) | undefined;
+  loggerInstance.sink = (entry: LogEntry) => {
+    originalSink?.(entry);
+    eventBus.emit({
+      type: "http",
+      severity: LEVEL_MAP[entry.level] ?? "info",
+      source: "logger",
+      message: `${entry.method} ${entry.path} ${entry.status ?? ""}`.trim(),
+      duration: entry.duration,
+      data: {
+        requestId: entry.requestId,
+        method: entry.method,
+        path: entry.path,
+        status: entry.status,
+        slow: entry.slow,
+      },
+    });
+  };
+}