@beignet/core 0.0.33 → 0.0.35

package/src/server/response-finalization.ts

@@ -0,0 +1,385 @@
+import {
+  BEIGNET_ERROR_OWNER_HEADER,
+  type ContractErrorDefinition,
+  type HttpContractConfig,
+} from "../contracts/index.js";
+import {
+  createErrorResponseBody,
+  isErrorResponseBody,
+} from "../errors/index.js";
+import { getRequestIdFromContext } from "./hooks/utils.js";
+import type { HttpResponse, HttpResponseLike } from "./http.js";
+import type { ResponseFinalizerResponseOwner } from "./internal-hooks.js";
+import {
+  parseStandardSchema,
+  SchemaValidationError,
+} from "./providers/index.js";
+
+export type ResponseOwner = ResponseFinalizerResponseOwner;
+
+export function errorResponse(
+  status: number,
+  code: string,
+  message: string,
+  details?: unknown,
+): HttpResponseLike {
+  return {
+    status,
+    body: createErrorResponseBody({ code, message, details }),
+  };
+}
+
+function contractDiagnostics(contract: HttpContractConfig) {
+  return {
+    contract: contract.name,
+    method: contract.method,
+    path: contract.path,
+  };
+}
+
+export function normalizeResponse(res: HttpResponseLike): HttpResponseLike {
+  return {
+    status: res.status,
+    headers: res.headers,
+    body: res.body,
+  };
+}
+
+export function isWebResponse(value: unknown): value is Response {
+  return typeof Response !== "undefined" && value instanceof Response;
+}
+
+export function normalizeHttpResponse(res: HttpResponse): HttpResponse {
+  return isWebResponse(res) ? res : normalizeResponse(res);
+}
+
+export function withFrameworkErrorOwnerHeader(
+  res: HttpResponseLike,
+  owner: ResponseOwner,
+): HttpResponseLike {
+  if (
+    owner !== "framework" ||
+    res.status < 400 ||
+    !isErrorResponseBody(res.body)
+  ) {
+    return res;
+  }
+
+  return {
+    ...res,
+    headers: {
+      ...(res.headers ?? {}),
+      [BEIGNET_ERROR_OWNER_HEADER]: "framework",
+    },
+  };
+}
+
+export function responseOwnerFor(
+  res: HttpResponse,
+  owner?: ResponseOwner,
+): ResponseOwner {
+  if (isWebResponse(res)) return "transport";
+  return owner ?? "route";
+}
+
+function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    record[key] = value;
+  });
+  return record;
+}
+
+export function responseForHooks(res: HttpResponse): HttpResponseLike {
+  if (!isWebResponse(res)) {
+    return normalizeResponse(res);
+  }
+
+  return {
+    status: res.status,
+    headers: headersToRecord(res.headers),
+  };
+}
+
+/**
+ * Merge hook-applied header changes onto a native web Response.
+ *
+ * Starts from the native response's `Headers` so `set-cookie` multiplicity is
+ * preserved, then applies headers the beforeSend chain added or changed
+ * relative to the original headers-only view. The body stream passes through
+ * untouched; status and statusText are preserved.
+ */
+export function mergeNativeResponseHeaders(
+  nativeResponse: Response,
+  originalHeaders: Record<string, string>,
+  finalHeaders: Record<string, string>,
+): Response {
+  const originalByLowerKey = new Map<string, string>();
+  for (const [key, value] of Object.entries(originalHeaders)) {
+    originalByLowerKey.set(key.toLowerCase(), value);
+  }
+
+  let changed = false;
+  const merged = new Headers(nativeResponse.headers);
+  for (const [key, value] of Object.entries(finalHeaders)) {
+    const lowerKey = key.toLowerCase();
+    if (originalByLowerKey.get(lowerKey) === value) continue;
+    changed = true;
+    if (lowerKey === "set-cookie") {
+      merged.append(lowerKey, value);
+    } else {
+      merged.set(key, value);
+    }
+  }
+
+  if (!changed) {
+    return nativeResponse;
+  }
+
+  return new Response(nativeResponse.body, {
+    status: nativeResponse.status,
+    statusText: nativeResponse.statusText,
+    headers: merged,
+  });
+}
+
+export function isHttpResponseLike(value: unknown): value is HttpResponseLike {
+  return (
+    !isWebResponse(value) &&
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    typeof (value as { status?: unknown }).status === "number"
+  );
+}
+
+export class ResponseContractViolationError extends Error {
+  readonly code: "RESPONSE_VALIDATION_ERROR" | "UNDECLARED_RESPONSE_STATUS";
+  readonly details?: unknown;
+
+  constructor(args: {
+    code: "RESPONSE_VALIDATION_ERROR" | "UNDECLARED_RESPONSE_STATUS";
+    message: string;
+    details?: unknown;
+  }) {
+    super(args.message);
+    this.name = "ResponseContractViolationError";
+    this.code = args.code;
+    this.details = args.details;
+  }
+}
+
+function responseContractViolationMessage(
+  contract: HttpContractConfig,
+  status: number,
+): string {
+  return (
+    `Response validation failed for ${contract.method} ${contract.path} ` +
+    `(status ${status}, contract: ${contract.name})`
+  );
+}
+
+function declaredResponseStatuses(contract: HttpContractConfig): number[] {
+  return Object.keys(contract.responses)
+    .map((status) => Number(status))
+    .filter((status) => Number.isFinite(status))
+    .sort((a, b) => a - b);
+}
+
+function responseContractViolationDetails(
+  contract: HttpContractConfig,
+  status: number,
+  details?: Record<string, unknown>,
+) {
+  return {
+    ...contractDiagnostics(contract),
+    location: "response",
+    status,
+    declaredStatuses: declaredResponseStatuses(contract),
+    ...details,
+  };
+}
+
+function getDeclaredCatalogErrorsForStatus(
+  contract: HttpContractConfig,
+  status: number,
+): ContractErrorDefinition[] {
+  const errors = contract.metadata?.errors;
+  if (typeof errors !== "object" || errors === null) return [];
+
+  return Object.values(errors).filter(
+    (error): error is ContractErrorDefinition =>
+      typeof error === "object" &&
+      error !== null &&
+      typeof (error as { code?: unknown }).code === "string" &&
+      typeof (error as { status?: unknown }).status === "number" &&
+      typeof (error as { message?: unknown }).message === "string" &&
+      (error as { status: number }).status === status,
+  );
+}
+
+async function validateCatalogErrorResponse<C extends HttpContractConfig>(
+  contract: C,
+  res: HttpResponseLike,
+): Promise<void> {
+  const body = res.body;
+  if (res.status < 400 || !isErrorResponseBody(body)) return;
+
+  const declaredErrors = getDeclaredCatalogErrorsForStatus(
+    contract,
+    res.status,
+  );
+  if (declaredErrors.length === 0) return;
+
+  const matchingError = declaredErrors.find(
+    (error) => error.code === body.code,
+  );
+  if (!matchingError) {
+    throw new ResponseContractViolationError({
+      code: "RESPONSE_VALIDATION_ERROR",
+      message: responseContractViolationMessage(contract, res.status),
+      details: responseContractViolationDetails(contract, res.status, {
+        issues: [
+          {
+            message:
+              `Error response code "${body.code}" is not declared for status ${res.status}. ` +
+              `Expected one of: ${declaredErrors.map((error) => error.code).join(", ")}.`,
+          },
+        ],
+      }),
+    });
+  }
+
+  if (matchingError.details && body.details !== undefined) {
+    try {
+      await parseStandardSchema(matchingError.details, body.details);
+    } catch (error) {
+      if (error instanceof SchemaValidationError) {
+        throw new ResponseContractViolationError({
+          code: "RESPONSE_VALIDATION_ERROR",
+          message: responseContractViolationMessage(contract, res.status),
+          details: responseContractViolationDetails(contract, res.status, {
+            issues: error.issues,
+          }),
+        });
+      }
+      throw error;
+    }
+  }
+}
+
+async function validateResponseAgainstContract<C extends HttpContractConfig>(
+  contract: C,
+  res: HttpResponseLike,
+  responseValidationExemptStatus?: number,
+): Promise<void> {
+  const statusKey = String(res.status);
+  const hasDeclaredStatus = Object.hasOwn(contract.responses, statusKey);
+
+  if (!hasDeclaredStatus) {
+    if (Object.keys(contract.responses).length === 0) return;
+
+    throw new ResponseContractViolationError({
+      code: "UNDECLARED_RESPONSE_STATUS",
+      message:
+        `Handler returned undeclared status ${res.status} for ` +
+        `${contract.method} ${contract.path} (contract: ${contract.name})`,
+      details: responseContractViolationDetails(contract, res.status, {
+        returnedStatus: res.status,
+      }),
+    });
+  }
+
+  const responseSchema = contract.responses[res.status];
+  if (responseSchema === null) {
+    if (res.body !== undefined && res.body !== null) {
+      throw new ResponseContractViolationError({
+        code: "RESPONSE_VALIDATION_ERROR",
+        message: responseContractViolationMessage(contract, res.status),
+        details: responseContractViolationDetails(contract, res.status, {
+          issues: [
+            {
+              message:
+                "Response body must be empty for a null response schema.",
+            },
+          ],
+        }),
+      });
+    }
+    return;
+  }
+
+  if (!responseSchema) return;
+
+  // Binder routes whose use case output schema is the same object as the
+  // declared success response schema skip the redundant success-status parse.
+  // Error statuses and undeclared statuses are validated unchanged.
+  if (res.status === responseValidationExemptStatus) return;
+
+  try {
+    await parseStandardSchema(responseSchema, res.body);
+    await validateCatalogErrorResponse(contract, res);
+  } catch (error) {
+    if (error instanceof SchemaValidationError) {
+      throw new ResponseContractViolationError({
+        code: "RESPONSE_VALIDATION_ERROR",
+        message: responseContractViolationMessage(contract, res.status),
+        details: responseContractViolationDetails(contract, res.status, {
+          issues: error.issues,
+        }),
+      });
+    }
+    throw error;
+  }
+}
+
+export async function finalizeResponse<C extends HttpContractConfig>(
+  contract: C,
+  res: HttpResponseLike,
+  responseValidationExemptStatus?: number,
+): Promise<HttpResponseLike> {
+  const normalized = normalizeResponse(res);
+  await validateResponseAgainstContract(
+    contract,
+    normalized,
+    responseValidationExemptStatus,
+  );
+  return normalized;
+}
+
+export function toContractViolationResponse(
+  error: ResponseContractViolationError,
+): HttpResponseLike {
+  return {
+    status: 500,
+    body: createErrorResponseBody({
+      code: error.code,
+      message: error.message,
+      details: error.details,
+    }),
+  };
+}
+
+export function defaultErrorResponse(
+  err: unknown,
+  ctx?: unknown,
+): HttpResponseLike {
+  const requestId = getRequestIdFromContext(ctx);
+  return {
+    status: 500,
+    body: createErrorResponseBody({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Internal server error",
+      requestId,
+      details:
+        process.env.NODE_ENV !== "production" && err instanceof Error
+          ? {
+              error: {
+                message: err.message,
+                stack: err.stack,
+              },
+            }
+          : undefined,
+    }),
+  };
+}

package/src/server/route-definitions.ts

@@ -0,0 +1,338 @@
+import type { ContractLike, ResolveContract } from "./contract-like.js";
+import { resolveContract } from "./contract-like.js";
+import type { AddedCtxFromHooks, Handler, RouteHook } from "./http.js";
+import type {
+  AnyUseCaseLike,
+  AnyUseCaseRouteDef,
+  UseCaseRouteDef,
+  ValidatedRouteInputs,
+} from "./use-case-route.js";
+
+/**
+ * Route registration that connects a contract to the handler implementing it.
+ *
+ * Most apps keep route definitions in `features/<feature>/routes.ts` and
+ * compose them with `defineRoutes(...)`.
+ */
+export type HandlerRouteDef<
+  Ctx,
+  CLike extends ContractLike = ContractLike,
+  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
+    Ctx,
+    object
+  >[],
+> = {
+  /**
+   * Contract builder or plain contract config for this route.
+   */
+  contract: CLike;
+  /**
+   * Route-scoped hooks that run after group hooks and before the handler.
+   */
+  hooks?: Hooks;
+  /**
+   * Handler that implements the contract.
+   */
+  handle: Handler<Ctx & AddedCtxFromHooks<Hooks>, ResolveContract<CLike>>;
+  useCase?: never;
+  input?: never;
+  status?: never;
+};
+
+/**
+ * Route registration for one contract.
+ *
+ * Routes either bind the contract directly to a use case (`{ contract,
+ * useCase }`) or implement a full handler (`{ contract, handle }`). The full
+ * handler form is the escape hatch for response headers, streaming, native
+ * `Response` values, and multi-status handling.
+ */
+export type RouteDef<
+  Ctx,
+  CLike extends ContractLike = ContractLike,
+  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
+    Ctx,
+    object
+  >[],
+> = HandlerRouteDef<Ctx, CLike, Hooks> | AnyUseCaseRouteDef<Ctx, CLike, Hooks>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type AnyRouteDef = RouteDef<any, any>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type PlainRouteDef<Ctx> = RouteDef<Ctx, any, readonly []>;
+
+// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
+type AnyContractRouteDef<Ctx> = RouteDef<Ctx, any>;
+
+const ROUTE_GROUP_KIND = "beignet.route-group";
+
+/**
+ * Named collection of related route registrations.
+ *
+ * Route groups colocate feature routes and can apply scoped route hooks to
+ * every route in the group. `defineRoutes(...)` flattens them before server
+ * registration while preserving those hooks.
+ */
+export type RouteGroup<
+  Ctx,
+  Routes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
+> = {
+  /**
+   * Internal marker used by `defineRoutes(...)`.
+   */
+  kind: typeof ROUTE_GROUP_KIND;
+  /**
+   * Human-readable group name.
+   */
+  name: string;
+  /**
+   * Hooks applied to every route in this group.
+   */
+  hooks?: readonly RouteHook<Ctx, object>[];
+  /**
+   * Route definitions in this group.
+   */
+  routes: Routes;
+};
+
+type RouteInput<Ctx> =
+  | AnyContractRouteDef<Ctx>
+  | AnyRouteDef
+  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
+
+type ContextualRouteInput<Ctx> =
+  | PlainRouteDef<Ctx>
+  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
+
+/**
+ * App-bound builder for one route registration.
+ */
+export type RouteDefinitionBuilder<Ctx> = {
+  <
+    CLike extends ContractLike,
+    UC extends AnyUseCaseLike,
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    route: UseCaseRouteDef<Ctx, CLike, UC, Hooks>,
+  ): UseCaseRouteDef<Ctx, CLike, UC, Hooks>;
+  <
+    CLike extends ContractLike,
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    route: HandlerRouteDef<Ctx, CLike, Hooks>,
+  ): HandlerRouteDef<Ctx, CLike, Hooks>;
+};
+
+/**
+ * App-bound builder for a named route group.
+ */
+export type RouteGroupBuilder<Ctx> = {
+  <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const R extends readonly PlainRouteDef<
+      Ctx & AddedCtxFromHooks<GroupHooks>
+    >[] = readonly PlainRouteDef<Ctx & AddedCtxFromHooks<GroupHooks>>[],
+  >(group: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: R & ValidatedRouteInputs<Ctx & AddedCtxFromHooks<GroupHooks>, R>;
+  }): RouteGroup<Ctx, R>;
+  <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const R extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
+  >(group: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: R & ValidatedRouteInputs<Ctx & AddedCtxFromHooks<GroupHooks>, R>;
+  }): RouteGroup<Ctx, R>;
+};
+
+/**
+ * Route declaration builders bound to an application context type.
+ */
+export interface Routes<Ctx> {
+  /** Define one route registration. */
+  defineRoute: RouteDefinitionBuilder<Ctx>;
+  /** Define a named group of related route registrations. */
+  defineRouteGroup: RouteGroupBuilder<Ctx>;
+}
+
+type RoutesFromInput<Input> =
+  Input extends RouteGroup<infer _Ctx, infer Routes>
+    ? Routes
+    : Input extends AnyRouteDef
+      ? readonly [Input]
+      : readonly [];
+
+type FlattenRouteInputs<Inputs extends readonly unknown[]> =
+  number extends Inputs["length"]
+    ? readonly AnyRouteDef[]
+    : Inputs extends readonly [infer First, ...infer Rest]
+      ? readonly [...RoutesFromInput<First>, ...FlattenRouteInputs<Rest>]
+      : readonly [];
+
+type ContractsFromRouteList<
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  Routes extends readonly RouteDef<any, any>[],
+> = {
+  readonly [Index in keyof Routes]: Routes[Index] extends RouteDef<
+    // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+    any,
+    infer CLike
+  >
+    ? ResolveContract<CLike>
+    : never;
+};
+
+/**
+ * Define one route registration with hook-aware handler typing.
+ *
+ * Direct route objects are still supported. Use this helper when route-scoped
+ * hooks enrich `ctx` for a single handler and you want TypeScript to infer the
+ * added fields.
+ */
+function createRouteBuilder<Ctx>(): RouteDefinitionBuilder<Ctx> {
+  function define<
+    CLike extends ContractLike,
+    UC extends AnyUseCaseLike,
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    route: UseCaseRouteDef<Ctx, CLike, UC, Hooks>,
+  ): UseCaseRouteDef<Ctx, CLike, UC, Hooks>;
+  function define<
+    CLike extends ContractLike,
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    route: HandlerRouteDef<Ctx, CLike, Hooks>,
+  ): HandlerRouteDef<Ctx, CLike, Hooks>;
+  function define(route: unknown): unknown {
+    return route;
+  }
+
+  return define;
+}
+
+/**
+ * Define and flatten route registrations with strong type inference.
+ *
+ * Pass route definitions and route groups here before `createServer(...)`.
+ * Group entries are flattened so downstream tooling receives one route list.
+ *
+ * @example
+ * ```ts
+ * const routes = defineRoutes<AppContext>([
+ *   { contract: listPosts, useCase: listPostsUseCase },
+ * ]);
+ * ```
+ */
+export function defineRoutes<
+  Ctx,
+  const R extends
+    readonly ContextualRouteInput<Ctx>[] = readonly ContextualRouteInput<Ctx>[],
+>(routes: R & ValidatedRouteInputs<Ctx, R>): FlattenRouteInputs<R>;
+export function defineRoutes<
+  Ctx,
+  const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
+>(routes: R & ValidatedRouteInputs<Ctx, R>): FlattenRouteInputs<R>;
+export function defineRoutes<
+  Ctx,
+  const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
+>(routes: R): FlattenRouteInputs<R> {
+  const flattened: RouteDef<Ctx>[] = [];
+
+  for (const route of routes) {
+    if (isRouteGroup(route)) {
+      for (const groupRoute of route.routes) {
+        flattened.push({
+          ...groupRoute,
+          hooks: [...(route.hooks ?? []), ...(groupRoute.hooks ?? [])],
+        });
+      }
+    } else {
+      flattened.push(route);
+    }
+  }
+
+  return flattened as unknown as FlattenRouteInputs<R>;
+}
+
+/**
+ * Extract contract configs from a route list.
+ *
+ * Use this to drive clients, OpenAPI, and docs from the same route list passed
+ * to `createServer(...)`.
+ */
+export function contractsFromRoutes<
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  const R extends readonly RouteDef<any, any>[],
+>(routes: R): ContractsFromRouteList<R> {
+  return routes.map((route) =>
+    resolveContract(route.contract),
+  ) as unknown as ContractsFromRouteList<R>;
+}
+
+/**
+ * Define a named group of related route registrations.
+ *
+ * Route groups are flattened by defineRoutes, so createServer still receives
+ * a regular route list while app code can keep feature route wiring and scoped
+ * hooks colocated.
+ *
+ * @example
+ * ```ts
+ * const { defineRouteGroup } = createRoutes<AppContext>();
+ * const todoRoutes = defineRouteGroup({
+ *   name: "todos",
+ *   hooks: [auth.optional()],
+ *   routes: [
+ *     { contract: listTodos, useCase: listTodosUseCase },
+ *   ]
+ * });
+ * ```
+ */
+function createRouteGroupBuilder<Ctx>(): RouteGroupBuilder<Ctx> {
+  const createGroup = <
+    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+    const GroupRoutes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
+  >(input: {
+    name: string;
+    hooks?: GroupHooks;
+    routes: GroupRoutes;
+  }): RouteGroup<Ctx, GroupRoutes> => ({
+    kind: ROUTE_GROUP_KIND,
+    name: input.name,
+    hooks: input.hooks,
+    routes: input.routes,
+  });
+
+  return createGroup as RouteGroupBuilder<Ctx>;
+}
+
+/**
+ * Create route declaration builders bound to an application context type.
+ *
+ * Call this once in `lib/routes.ts`, then import the app-bound builders from
+ * feature route files.
+ *
+ * @example
+ * ```ts
+ * export const { defineRoute, defineRouteGroup } =
+ *   createRoutes<AppContext>();
+ * ```
+ */
+export function createRoutes<Ctx>(): Routes<Ctx> {
+  return {
+    defineRoute: createRouteBuilder<Ctx>(),
+    defineRouteGroup: createRouteGroupBuilder<Ctx>(),
+  };
+}
+
+function isRouteGroup<Ctx>(route: RouteInput<Ctx>): route is RouteGroup<Ctx> {
+  return (
+    typeof route === "object" &&
+    route !== null &&
+    "kind" in route &&
+    route.kind === ROUTE_GROUP_KIND
+  );
+}