@beignet/core 0.0.1

package/src/server/hooks/cors.ts

@@ -0,0 +1,87 @@
+/**
+ * CORS hook utilities for @beignet/core/server
+ */
+
+import type { HttpRequestLike, ServerHook } from "../types";
+
+export interface CorsConfig {
+  origins?: string[] | "*";
+  methods?: string[];
+  headers?: string[];
+  credentials?: boolean;
+}
+
+const DEFAULT_CORS: Required<CorsConfig> = {
+  origins: "*",
+  methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  headers: ["Content-Type", "Authorization"],
+  credentials: false,
+};
+
+function appendVaryOrigin(headers: Record<string, string>): void {
+  const varyKey =
+    Object.keys(headers).find((key) => key.toLowerCase() === "vary") ?? "Vary";
+  const current = headers[varyKey];
+  const values = current?.split(",").map((value) => value.trim().toLowerCase());
+  if (values?.includes("origin")) return;
+
+  headers[varyKey] = current ? `${current}, Origin` : "Origin";
+}
+
+export function applyCorsHeaders(
+  headers: Record<string, string>,
+  req: HttpRequestLike,
+  corsConfig: CorsConfig,
+): void {
+  const origins = corsConfig.origins ?? DEFAULT_CORS.origins;
+  const methods = corsConfig.methods ?? DEFAULT_CORS.methods;
+  const allowedHeaders = corsConfig.headers ?? DEFAULT_CORS.headers;
+  const credentials = corsConfig.credentials ?? DEFAULT_CORS.credentials;
+
+  if (credentials && origins === "*") {
+    const requestOrigin = req.headers.get("Origin");
+    if (requestOrigin) {
+      headers["Access-Control-Allow-Origin"] = requestOrigin;
+      appendVaryOrigin(headers);
+    }
+  } else if (origins === "*") {
+    headers["Access-Control-Allow-Origin"] = "*";
+  } else if (Array.isArray(origins)) {
+    const requestOrigin = req.headers.get("Origin");
+    if (requestOrigin && origins.includes(requestOrigin)) {
+      headers["Access-Control-Allow-Origin"] = requestOrigin;
+      appendVaryOrigin(headers);
+    }
+  }
+
+  headers["Access-Control-Allow-Methods"] = methods.join(", ");
+  headers["Access-Control-Allow-Headers"] = allowedHeaders.join(", ");
+
+  if (credentials) {
+    headers["Access-Control-Allow-Credentials"] = "true";
+  }
+}
+
+export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
+  return {
+    name: "cors",
+    onRequest: ({ req }) => {
+      if (req.method !== "OPTIONS") return undefined;
+      const headers: Record<string, string> = {};
+      applyCorsHeaders(headers, req, config);
+      return {
+        status: 204,
+        headers,
+        body: null,
+      };
+    },
+    beforeSend: ({ req, response }) => {
+      const headers = { ...(response.headers ?? {}) };
+      applyCorsHeaders(headers, req, config);
+      return {
+        ...response,
+        headers,
+      };
+    },
+  };
+}

package/src/server/hooks/errors.ts

@@ -0,0 +1,126 @@
+/**
+ * Framework-agnostic error mapping utilities for @beignet/core/server
+ */
+
+import { createErrorResponseBody, type ErrorResponseBody } from "../../errors";
+import type { AppEnvironment } from "../health";
+import { getRequestIdFromContext } from "./utils";
+
+/**
+ * Re-export AppEnvironment for convenience
+ */
+export type { AppEnvironment } from "../health";
+
+/**
+ * Error mapping result
+ */
+export interface ErrorMappingResult {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Error mapping configuration
+ */
+export interface ErrorMappingConfig<Ctx> {
+  /** Custom error mapper function */
+  mapErrorToResponse?: (err: unknown, ctx: Ctx) => ErrorMappingResult;
+
+  /** Include stack traces in error responses (default: true in dev/test, false in production) */
+  includeStackInResponse?: boolean;
+
+  /** Application environment */
+  env?: AppEnvironment;
+}
+
+/**
+ * Create default error response body
+ */
+function createDefaultErrorBody(
+  err: unknown,
+  includeStack: boolean,
+  requestId?: string,
+): ErrorResponseBody {
+  return createErrorResponseBody({
+    code: "INTERNAL_SERVER_ERROR",
+    message: "Internal server error",
+    requestId,
+    details:
+      includeStack && err instanceof Error
+        ? {
+            error: {
+              message: err.message,
+              stack: err.stack,
+            },
+          }
+        : undefined,
+  });
+}
+
+/**
+ * Default error mapping function that handles unknown errors and converts them
+ * to a standard error response format.
+ *
+ * **Important:** This function does NOT handle AppError instances from @beignet/core/errors.
+ * AppError is handled separately in the router's error handling flow before reaching
+ * this function. This function is only called for truly unexpected errors that bypass normal
+ * error handling (e.g., unhandled exceptions, infrastructure errors).
+ *
+ * This function:
+ * 1. First tries the custom mapErrorToResponse if provided
+ * 2. Falls back to a default 500 error response
+ * 3. Optionally includes stack traces in development/test environments
+ *
+ * @param err - The error that was thrown (excluding AppError instances)
+ * @param ctx - The request context
+ * @param config - Error mapping configuration
+ * @returns An error mapping result with status, body, and optional headers
+ *
+ * @example
+ * ```ts
+ * const errorConfig = {
+ *   mapErrorToResponse: (err, ctx) => ({
+ *     status: 500,
+ *     body: {
+ *       code: "INTERNAL_SERVER_ERROR",
+ *       message: "Custom error",
+ *       requestId: ctx.requestId,
+ *     },
+ *   }),
+ *   includeStackInResponse: true,
+ *   env: "development",
+ * };
+ *
+ * const result = defaultMapErrorToResponse(error, ctx, errorConfig);
+ * ```
+ */
+export function defaultMapErrorToResponse<Ctx>(
+  err: unknown,
+  ctx: Ctx,
+  config: ErrorMappingConfig<Ctx>,
+): ErrorMappingResult {
+  // First, try the user's custom error handler
+  if (config.mapErrorToResponse) {
+    try {
+      return config.mapErrorToResponse(err, ctx);
+    } catch {
+      // Fall through to default error response below
+    }
+  }
+
+  // Determine if stack traces should be included
+  const includeStack =
+    config.includeStackInResponse ??
+    (config.env === "development" || config.env === "test");
+
+  // Default error response
+  const requestId = getRequestIdFromContext(ctx);
+  const body = createDefaultErrorBody(err, includeStack, requestId);
+
+  return {
+    status: 500,
+    body,
+    headers: { "Content-Type": "application/json" },
+  };
+}

package/src/server/hooks/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Hook utilities for @beignet/core/server
+ */
+
+import type { AnyPorts } from "../../ports";
+import type { ServerHook } from "../http";
+
+export {
+  type AuthHookArgs,
+  type AuthHookAssignArgs,
+  type AuthHookMode,
+  type AuthHookModeInput,
+  type AuthHooksOptions,
+  type AuthHookUnauthorizedArgs,
+  type CtxWithAuthPort,
+  createAuthHooks,
+} from "./auth";
+export {
+  applyCorsHeaders,
+  type CorsConfig,
+  createCorsHooks,
+} from "./cors";
+export {
+  defaultMapErrorToResponse,
+  type ErrorMappingConfig,
+  type ErrorMappingResult,
+} from "./errors";
+export {
+  createLoggingHooks,
+  type Logger,
+  type LoggingConfig,
+} from "./logging";
+export {
+  type CtxWithRateLimit,
+  createRateLimitHooks,
+  type RateLimitOptions,
+} from "./rate-limit";
+
+export function composeHooks<Ctx, Ports extends AnyPorts = AnyPorts>(
+  ...hooks: (ServerHook<Ctx, Ports> | readonly ServerHook<Ctx, Ports>[])[]
+): ServerHook<Ctx, Ports>[] {
+  return hooks.flatMap((hook) => (Array.isArray(hook) ? hook : [hook]));
+}

package/src/server/hooks/logging.ts

@@ -0,0 +1,121 @@
+/**
+ * Logging hook utilities for @beignet/core/server
+ */
+
+import type { HttpContractConfig } from "../../contracts";
+import type { HttpRequestLike, ServerHook } from "../types";
+import { getRequestIdFromContext } from "./utils";
+
+export interface Logger {
+  info: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  debug?: (...args: unknown[]) => void;
+}
+
+export interface LoggingConfig<Ctx> {
+  logger?: Logger;
+  requestIdHeader?: string;
+  onRequestStart?: (args: {
+    ctx?: Ctx;
+    req: HttpRequestLike;
+    contract?: HttpContractConfig;
+  }) => void;
+  onRequestEnd?: (args: {
+    ctx?: Ctx;
+    req: HttpRequestLike;
+    res: { status: number; headers: Record<string, string> };
+    durationMs: number;
+    contract?: HttpContractConfig;
+    error?: unknown;
+  }) => void;
+}
+
+export function createLoggingHooks<Ctx>(
+  config: LoggingConfig<Ctx>,
+): ServerHook<Ctx> {
+  const requestIdHeader = config.requestIdHeader;
+
+  return {
+    name: "logging",
+    onRequest: ({ req, contract }) => {
+      if (config.onRequestStart) {
+        try {
+          config.onRequestStart({ req, contract, ctx: undefined });
+        } catch {
+          // Ignore logging errors
+        }
+        return undefined;
+      }
+
+      if (!config.logger) return undefined;
+      try {
+        const url = new URL(req.url);
+        config.logger.info(
+          { method: req.method, url: url.pathname },
+          "Request start",
+        );
+      } catch {
+        // Ignore logging errors
+      }
+      return undefined;
+    },
+    ...(requestIdHeader
+      ? {
+          beforeSend: ({ ctx, response }) => {
+            const requestId = getRequestIdFromContext(ctx);
+            if (!requestId) {
+              return response;
+            }
+
+            return {
+              ...response,
+              headers: {
+                ...(response.headers ?? {}),
+                [requestIdHeader]: String(requestId),
+              },
+            };
+          },
+        }
+      : {}),
+    afterSend: ({ ctx, req, response, durationMs, contract, error }) => {
+      const headers = response.headers ?? {};
+      if (config.onRequestEnd) {
+        try {
+          config.onRequestEnd({
+            ctx,
+            req,
+            res: { status: response.status, headers },
+            durationMs,
+            contract,
+            error,
+          });
+        } catch {
+          // Ignore logging errors
+        }
+        return;
+      }
+
+      if (!config.logger) return;
+      try {
+        const url = new URL(req.url);
+        const requestId = getRequestIdFromContext(ctx);
+        const payload = {
+          method: req.method,
+          url: url.pathname,
+          status: response.status,
+          durationMs: Math.round(durationMs),
+          ...(requestId !== undefined ? { requestId } : {}),
+          ...(error !== undefined ? { error } : {}),
+        };
+        if (error !== undefined) {
+          config.logger.error(payload, "Request complete with error");
+          return;
+        }
+        config.logger.info(payload, "Request complete");
+      } catch {
+        // Ignore logging errors
+      }
+    },
+  };
+}

package/src/server/hooks/rate-limit.ts

@@ -0,0 +1,171 @@
+/**
+ * Rate limit hooks for @beignet/core/server
+ */
+
+import type { RateLimitScope } from "../../contracts";
+import { AppError, httpErrors } from "../../errors";
+import type { ActivityActor, RateLimitPort } from "../../ports";
+import type { HttpRequestLike, ServerHook } from "../types";
+
+export type RateLimitPorts = {
+  rateLimit: RateLimitPort;
+};
+
+export type CtxWithRateLimit = {
+  ports: RateLimitPorts;
+  actor?: ActivityActor;
+};
+
+type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
+
+export interface RateLimitOptions<Ctx> {
+  key?: (args: {
+    ctx: Ctx;
+    req: HttpRequestLike;
+    scope: RateLimitScope;
+  }) => string;
+  earlyKey?: (args: {
+    req: HttpRequestLike;
+    scope: EarlyRateLimitScope;
+  }) => string;
+  getClientIp?: (req: HttpRequestLike) => string | undefined;
+}
+
+function defaultGetClientIp(req: HttpRequestLike): string | undefined {
+  const xfwd = req.headers.get("x-forwarded-for") ?? "";
+  return xfwd.split(",")[0].trim() || undefined;
+}
+
+function emitUserKey(userId: string): string {
+  return `user:${userId}`;
+}
+
+function emitIpKey(ip: string): string {
+  return `ip:${ip}`;
+}
+
+function defaultRateLimitKey<Ctx extends CtxWithRateLimit>(
+  args: {
+    ctx: Ctx;
+    req: HttpRequestLike;
+    scope: RateLimitScope;
+  },
+  getClientIp: (req: HttpRequestLike) => string | undefined,
+): string {
+  const { ctx, req, scope } = args;
+
+  if (scope === "user" && ctx.actor?.type === "user" && ctx.actor.id) {
+    return emitUserKey(ctx.actor.id);
+  }
+
+  if (scope === "ip") {
+    const ip = getClientIp(req) || "unknown";
+    return emitIpKey(ip);
+  }
+
+  return "global";
+}
+
+function defaultEarlyRateLimitKey(
+  args: {
+    req: HttpRequestLike;
+    scope: EarlyRateLimitScope;
+  },
+  getClientIp: (req: HttpRequestLike) => string | undefined,
+): string {
+  if (args.scope === "ip") {
+    const ip = getClientIp(args.req) || "unknown";
+    return emitIpKey(ip);
+  }
+
+  return "global";
+}
+
+async function enforceRateLimit(
+  rateLimit: RateLimitPort,
+  args: {
+    key: string;
+    limit: number;
+    windowSec: number;
+    scope: RateLimitScope;
+  },
+): Promise<void> {
+  const result = await rateLimit.hit({
+    key: args.key,
+    limit: args.limit,
+    windowSec: args.windowSec,
+  });
+
+  if (result.allowed) {
+    return;
+  }
+
+  throw new AppError(
+    httpErrors.TooManyRequests,
+    {
+      key: args.key,
+      scope: args.scope,
+      retryAfterSeconds: result.retryAfterSeconds,
+      resetAt: result.resetAt?.toISOString() ?? null,
+    },
+    "Rate limit exceeded",
+  );
+}
+
+export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
+  options: RateLimitOptions<Ctx> = {},
+): ServerHook<Ctx, RateLimitPorts> {
+  const getClientIp = options.getClientIp ?? defaultGetClientIp;
+
+  return {
+    name: "rate-limit",
+    onRequest: async ({ contract, ports, req }) => {
+      const rlMeta = contract.metadata?.rateLimit;
+      if (!rlMeta) {
+        return undefined;
+      }
+
+      const scope: RateLimitScope = rlMeta.scope ?? "global";
+      if (scope === "user") {
+        return undefined;
+      }
+
+      const key =
+        options.earlyKey?.({ req, scope }) ??
+        defaultEarlyRateLimitKey({ req, scope }, getClientIp);
+
+      await enforceRateLimit(ports.rateLimit, {
+        key,
+        limit: rlMeta.max,
+        windowSec: rlMeta.windowSec,
+        scope,
+      });
+
+      return undefined;
+    },
+    beforeHandle: async ({ ctx, contract, req }) => {
+      const rlMeta = contract.metadata?.rateLimit;
+      if (!rlMeta) {
+        return undefined;
+      }
+
+      const scope: RateLimitScope = rlMeta.scope ?? "global";
+      if (scope !== "user") {
+        return undefined;
+      }
+
+      const key =
+        options.key?.({ ctx, req, scope }) ??
+        defaultRateLimitKey({ ctx, req, scope }, getClientIp);
+
+      await enforceRateLimit(ctx.ports.rateLimit, {
+        key,
+        limit: rlMeta.max,
+        windowSec: rlMeta.windowSec,
+        scope,
+      });
+
+      return undefined;
+    },
+  };
+}

package/src/server/hooks/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utilities for server hooks.
+ */
+
+/**
+ * Extract requestId from context object if it exists.
+ * This helper reduces type casting duplication throughout the codebase.
+ */
+export function getRequestIdFromContext(ctx: unknown): string | undefined {
+  if (ctx !== null && ctx !== undefined && typeof ctx === "object") {
+    const ctxRecord = ctx as Record<string, unknown>;
+    const requestId = ctxRecord.requestId;
+    return typeof requestId === "string" ? requestId : undefined;
+  }
+  return undefined;
+}

package/src/server/hooks.ts

@@ -0,0 +1 @@
+export * from "./hooks/index";