@beignet/core 0.0.1

package/src/server/server.ts

@@ -0,0 +1,1521 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  BEIGNET_ERROR_OWNER_HEADER,
+  type ContractErrorDefinition,
+  getContractHeaderSchemas,
+  type HttpContractConfig,
+  methodSupportsRequestBody,
+  parsePathTemplate,
+  type StandardSchema,
+} from "../contracts";
+import {
+  createErrorResponseBody,
+  isAppError,
+  isErrorResponseBody,
+  toErrorResponseBody,
+} from "../errors";
+import type { AnyPorts } from "../ports";
+import { AuthUnauthorizedError, GateAuthorizationError } from "../ports";
+import type {
+  ProvidedPortsOfList,
+  ProviderSetupResult,
+  ServiceProvider,
+} from "../providers";
+import type { ContractLike, ResolveContract } from "./contract-like";
+import { resolveContract } from "./contract-like";
+import { getRequestIdFromContext } from "./hooks/utils";
+import type {
+  Handler,
+  HandlerArgs,
+  HttpRequestLike,
+  HttpResponse,
+  HttpResponseLike,
+  ResolvedRoute,
+  ServerCaughtErrorHook,
+  ServerHook,
+  ServerUnhandledErrorMapper,
+} from "./http";
+import {
+  loadProviderConfig,
+  parseStandardSchema,
+  SchemaValidationError,
+} from "./providers";
+
+/**
+ * Route definition
+ */
+export type RouteDef<Ctx, CLike extends ContractLike = ContractLike> = {
+  contract: CLike;
+  handle: Handler<Ctx, ResolveContract<CLike>>;
+};
+
+const ROUTE_GROUP_KIND = "beignet.route-group";
+
+export type RouteGroup<
+  Ctx,
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+> = {
+  kind: typeof ROUTE_GROUP_KIND;
+  name: string;
+  routes: Routes;
+};
+
+type RouteInput<Ctx> =
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  | RouteDef<Ctx, any>
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  | RouteGroup<Ctx, readonly RouteDef<Ctx, any>[]>;
+
+type RoutesFromInput<Input> =
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  Input extends RouteGroup<any, infer Routes>
+    ? Routes
+    : // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+      Input extends RouteDef<any, any>
+      ? readonly [Input]
+      : readonly [];
+
+type FlattenRouteInputs<Inputs extends readonly unknown[]> =
+  number extends Inputs["length"]
+    ? // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+      readonly RouteDef<any, any>[]
+    : 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;
+};
+
+export type CreateServerOptions<
+  Ctx,
+  Ports extends AnyPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Providers extends readonly ServiceProvider<
+    unknown,
+    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+    StandardSchemaV1<any, any>,
+    AnyPorts
+  >[] = readonly [],
+> = {
+  ports: Ports;
+  providers?: Providers;
+
+  // config sources
+  providerEnv?: Record<string, string | undefined>;
+  providerConfig?: Record<string, unknown>;
+
+  createContext: (args: {
+    req: HttpRequestLike;
+    ports: Ports & ProvidedPortsOfList<Providers>;
+    contract?: HttpContractConfig;
+  }) => Ctx | Promise<Ctx>;
+  hooks?: ServerHook<Ctx, Ports & ProvidedPortsOfList<Providers>>[];
+  routes?: Routes;
+  onCaughtError?: ServerCaughtErrorHook<Ctx>;
+  mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
+};
+
+interface RouteBuilder<Ctx, C extends HttpContractConfig> {
+  handle: (
+    fn: Handler<Ctx, C>,
+  ) => (req: HttpRequestLike) => Promise<HttpResponse>;
+}
+
+export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
+  api: (req: HttpRequestLike) => Promise<HttpResponse>;
+  route: <CLike extends ContractLike>(
+    contractLike: CLike,
+  ) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+  contracts: readonly HttpContractConfig[];
+  stop: () => Promise<void>;
+  ports: Ports;
+}
+
+type ExecutionResult<Ctx> = {
+  ctx?: Ctx;
+  response: HttpResponse;
+  error?: unknown;
+  owner?: ResponseOwner;
+};
+
+type ResponseOwner = "route" | "framework" | "transport";
+
+type CompiledPath = {
+  keys: string[];
+  pattern: RegExp;
+  segments: ReturnType<typeof parsePathTemplate>["segments"];
+  normalizedPath: string;
+  shapeKey: string;
+};
+
+class PathDecodeError extends Error {
+  constructor() {
+    super("Malformed URL path");
+    this.name = "PathDecodeError";
+  }
+}
+
+function compilePath(path: string) {
+  const parsed = parsePathTemplate(path);
+  const regexParts = parsed.segments.map((segment) =>
+    segment.kind === "dynamic"
+      ? "([^/]+)"
+      : segment.value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+  );
+  const pattern = new RegExp(`^/${regexParts.join("/")}$`);
+  return { ...parsed, pattern };
+}
+
+function decodeMatchedParams(
+  keys: string[],
+  match: RegExpExecArray,
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  try {
+    keys.forEach((key, index) => {
+      params[key] = decodeURIComponent(match[index + 1]);
+    });
+  } catch (error) {
+    if (error instanceof URIError) {
+      throw new PathDecodeError();
+    }
+    throw error;
+  }
+  return params;
+}
+
+function compareRouteSpecificity(a: CompiledPath, b: CompiledPath): number {
+  const maxLength = Math.max(a.segments.length, b.segments.length);
+  for (let index = 0; index < maxLength; index++) {
+    const aSegment = a.segments[index];
+    const bSegment = b.segments[index];
+
+    if (!aSegment) return 1;
+    if (!bSegment) return -1;
+
+    if (aSegment.kind === bSegment.kind) continue;
+    return aSegment.kind === "static" ? -1 : 1;
+  }
+
+  return 0;
+}
+
+function errorResponse(
+  status: number,
+  code: string,
+  message: string,
+  details?: unknown,
+): HttpResponseLike {
+  return {
+    status,
+    body: createErrorResponseBody({ code, message, details }),
+  };
+}
+
+function normalizeResponse(res: HttpResponseLike): HttpResponseLike {
+  return {
+    status: res.status,
+    headers: res.headers,
+    body: res.body,
+  };
+}
+
+function isWebResponse(value: unknown): value is Response {
+  return typeof Response !== "undefined" && value instanceof Response;
+}
+
+function normalizeHttpResponse(res: HttpResponse): HttpResponse {
+  return isWebResponse(res) ? res : normalizeResponse(res);
+}
+
+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",
+    },
+  };
+}
+
+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;
+}
+
+function requestHeadersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    record[key.toLowerCase()] = value;
+  });
+  return record;
+}
+
+async function parseHeaderSchemas(
+  schemas: readonly StandardSchema[],
+  rawHeaders: Record<string, string>,
+): Promise<Record<string, unknown>> {
+  let parsedHeaders: Record<string, unknown> = rawHeaders;
+
+  for (const schema of schemas) {
+    const parsed = await parseStandardSchema(schema, rawHeaders);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      parsedHeaders = {
+        ...parsedHeaders,
+        ...(parsed as Record<string, unknown>),
+      };
+    } else {
+      parsedHeaders = parsed as Record<string, unknown>;
+    }
+  }
+
+  return parsedHeaders;
+}
+
+function responseForHooks(res: HttpResponse): HttpResponseLike {
+  if (!isWebResponse(res)) {
+    return normalizeResponse(res);
+  }
+
+  return {
+    status: res.status,
+    headers: headersToRecord(res.headers),
+  };
+}
+
+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"
+  );
+}
+
+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 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:
+        `Response validation failed for ${contract.method} ${contract.path} ` +
+        `(status ${res.status}, contract: ${contract.name})`,
+      details: {
+        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:
+            `Response validation failed for ${contract.method} ${contract.path} ` +
+            `(status ${res.status}, contract: ${contract.name})`,
+          details: { issues: error.issues },
+        });
+      }
+      throw error;
+    }
+  }
+}
+
+async function validateResponseAgainstContract<C extends HttpContractConfig>(
+  contract: C,
+  res: HttpResponseLike,
+): 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: {
+        status: res.status,
+        body: res.body,
+      },
+    });
+  }
+
+  const responseSchema = contract.responses[res.status];
+  if (responseSchema === null) {
+    if (res.body !== undefined && res.body !== null) {
+      throw new ResponseContractViolationError({
+        code: "RESPONSE_VALIDATION_ERROR",
+        message:
+          `Response validation failed for ${contract.method} ${contract.path} ` +
+          `(status ${res.status}, contract: ${contract.name})`,
+        details: {
+          issues: [
+            {
+              message:
+                "Response body must be empty for a null response schema.",
+            },
+          ],
+        },
+      });
+    }
+    return;
+  }
+
+  if (!responseSchema) 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:
+          `Response validation failed for ${contract.method} ${contract.path} ` +
+          `(status ${res.status}, contract: ${contract.name})`,
+        details: { issues: error.issues },
+      });
+    }
+    throw error;
+  }
+}
+
+async function finalizeResponse<C extends HttpContractConfig>(
+  contract: C,
+  res: HttpResponseLike,
+): Promise<HttpResponseLike> {
+  const normalized = normalizeResponse(res);
+  await validateResponseAgainstContract(contract, normalized);
+  return normalized;
+}
+
+function toContractViolationResponse(
+  error: ResponseContractViolationError,
+): HttpResponseLike {
+  return {
+    status: 500,
+    body: createErrorResponseBody({
+      code: error.code,
+      message: error.message,
+      details: error.details,
+    }),
+  };
+}
+
+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,
+    }),
+  };
+}
+
+async function parseBody(req: HttpRequestLike): Promise<unknown> {
+  const method = req.method.toUpperCase() as HttpContractConfig["method"];
+  if (!methodSupportsRequestBody(method)) {
+    return undefined;
+  }
+
+  const bodyReq = req.clone?.() ?? req;
+  const contentType = req.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    const text = await bodyReq.text();
+    if (text === "") return undefined;
+    return JSON.parse(text);
+  }
+
+  try {
+    const text = await bodyReq.text();
+    return text === "" ? undefined : text;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildHandler<
+  Ctx,
+  Ports extends AnyPorts,
+  C extends HttpContractConfig,
+  Providers extends readonly ServiceProvider<
+    unknown,
+    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+    StandardSchemaV1<any, any>,
+    AnyPorts
+  >[] = readonly [],
+  FinalPorts extends Ports & ProvidedPortsOfList<Providers> = Ports &
+    ProvidedPortsOfList<Providers>,
+>(
+  // biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
+  options: CreateServerOptions<Ctx, Ports, any, Providers>,
+  finalPorts: FinalPorts,
+  contract: C,
+  userHandler: Handler<Ctx, C>,
+  hooks: ServerHook<Ctx, FinalPorts>[],
+  optionsOverrides?: {
+    skipRoutePreparation?: boolean;
+  },
+): (
+  req: HttpRequestLike,
+  preMatchedParams?: Record<string, string>,
+) => Promise<HttpResponse> {
+  const compiled = compilePath(contract.path);
+
+  return async (
+    req: HttpRequestLike,
+    preMatchedParams?: Record<string, string>,
+  ) => {
+    let baseCtx: Ctx | undefined;
+    let pathValue: HandlerArgs<Ctx, C>["path"] | undefined;
+    let queryValue: HandlerArgs<Ctx, C>["query"] | undefined;
+    let headersValue: HandlerArgs<Ctx, C>["headers"] | undefined;
+    let bodyValue: HandlerArgs<Ctx, C>["body"] | undefined;
+    const startedAt = Date.now();
+
+    const resolveErrorResult = async (
+      error: unknown,
+      ctx?: Ctx,
+      path?: HandlerArgs<Ctx, C>["path"],
+      query?: HandlerArgs<Ctx, C>["query"],
+      headers?: HandlerArgs<Ctx, C>["headers"],
+      body?: HandlerArgs<Ctx, C>["body"],
+      resultOptions?: {
+        owner?: ResponseOwner;
+      },
+    ): Promise<ExecutionResult<Ctx>> => {
+      let currentError = error;
+
+      const notifyCaughtError = async (caught: unknown) => {
+        const args = {
+          err: caught,
+          req,
+          ctx,
+          contract,
+          path,
+          query,
+          headers,
+          body,
+        };
+        for (const hook of hooks) {
+          if (!hook.onCaughtError) continue;
+          try {
+            await hook.onCaughtError(args);
+          } catch {
+            // Observers must not change response behavior.
+          }
+        }
+        if (options.onCaughtError) {
+          try {
+            await options.onCaughtError(args);
+          } catch {
+            // Observers must not change response behavior.
+          }
+        }
+      };
+
+      await notifyCaughtError(currentError);
+
+      if (currentError instanceof ResponseContractViolationError) {
+        return {
+          ctx,
+          response: toContractViolationResponse(currentError),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
+      if (isAppError(currentError)) {
+        return {
+          ctx,
+          response: {
+            status: currentError.status,
+            body: toErrorResponseBody(currentError),
+          },
+          error: currentError,
+          owner: resultOptions?.owner ?? "route",
+        };
+      }
+
+      if (currentError instanceof AuthUnauthorizedError) {
+        return {
+          ctx,
+          response: errorResponse(401, currentError.code, currentError.message),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
+      if (currentError instanceof GateAuthorizationError) {
+        return {
+          ctx,
+          response: errorResponse(
+            currentError.status,
+            currentError.code,
+            currentError.message,
+            currentError.details,
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
+      for (const hook of hooks) {
+        if (!hook.mapUnhandledError) continue;
+        try {
+          const handled = await hook.mapUnhandledError({
+            err: currentError,
+            req,
+            ctx,
+            contract,
+            path,
+            query,
+            headers,
+            body,
+          });
+          if (handled) {
+            const response = normalizeHttpResponse(handled);
+            return {
+              ctx,
+              response,
+              error: currentError,
+              owner: responseOwnerFor(response, "framework"),
+            };
+          }
+        } catch (hookError) {
+          currentError = hookError;
+          await notifyCaughtError(currentError);
+        }
+      }
+
+      if (options.mapUnhandledError) {
+        try {
+          const handled = await options.mapUnhandledError({
+            err: currentError,
+            req,
+            ctx,
+            contract,
+            path,
+            query,
+            headers,
+            body,
+          });
+          if (handled) {
+            const response = normalizeHttpResponse(handled);
+            return {
+              ctx,
+              response,
+              error: currentError,
+              owner: responseOwnerFor(response, "framework"),
+            };
+          }
+        } catch (hookError) {
+          currentError = hookError;
+          await notifyCaughtError(currentError);
+        }
+      }
+
+      return {
+        ctx,
+        response: defaultErrorResponse(currentError, ctx),
+        error: currentError,
+        owner: "framework",
+      };
+    };
+
+    try {
+      const url = new URL(req.url);
+
+      let matchedParams: Record<string, string>;
+      if (preMatchedParams) {
+        matchedParams = preMatchedParams;
+      } else {
+        const match = compiled.pattern.exec(url.pathname);
+        if (
+          !match ||
+          contract.method.toUpperCase() !== req.method.toUpperCase()
+        ) {
+          return errorResponse(404, "NOT_FOUND", "Not found");
+        }
+        try {
+          matchedParams = decodeMatchedParams(compiled.keys, match);
+        } catch (error) {
+          if (error instanceof PathDecodeError) {
+            return errorResponse(400, "INVALID_PATH", "Malformed URL path");
+          }
+          throw error;
+        }
+      }
+      const rawHeaders = requestHeadersToRecord(req.headers);
+
+      const applyTransformHooks = async (
+        initialResult: ExecutionResult<Ctx>,
+        allowRetry: boolean,
+      ): Promise<ExecutionResult<Ctx>> => {
+        if (isWebResponse(initialResult.response)) {
+          return initialResult;
+        }
+
+        try {
+          let transformed = normalizeResponse(initialResult.response);
+          for (const hook of hooks) {
+            if (!hook.beforeSend) continue;
+            const nextResponse = await hook.beforeSend({
+              req,
+              ctx: initialResult.ctx,
+              contract,
+              path: pathValue,
+              query: queryValue,
+              headers: headersValue,
+              body: bodyValue,
+              response: transformed,
+              error: initialResult.error,
+            });
+            if (nextResponse) {
+              transformed = normalizeResponse(nextResponse);
+            }
+          }
+          return {
+            ...initialResult,
+            response: transformed,
+          };
+        } catch (error) {
+          const mapped = await resolveErrorResult(
+            error,
+            initialResult.ctx,
+            pathValue,
+            queryValue,
+            headersValue,
+            bodyValue,
+            { owner: "framework" },
+          );
+          if (!allowRetry) {
+            return mapped;
+          }
+          return applyTransformHooks(mapped, false);
+        }
+      };
+
+      let result: ExecutionResult<Ctx> | undefined;
+
+      for (const hook of hooks) {
+        if (!hook.onRequest) continue;
+        try {
+          const hookResult = await hook.onRequest({
+            req,
+            ports: finalPorts,
+            contract,
+            params: matchedParams,
+          });
+          if (hookResult) {
+            const response = normalizeHttpResponse(hookResult);
+            result = {
+              response,
+              owner: responseOwnerFor(response, "framework"),
+            };
+            break;
+          }
+        } catch (error) {
+          result = await resolveErrorResult(
+            error,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            { owner: "framework" },
+          );
+          break;
+        }
+      }
+
+      if (!result) {
+        if (optionsOverrides?.skipRoutePreparation) {
+          let createdCtx!: Ctx;
+          try {
+            createdCtx = await options.createContext({
+              req,
+              ports: finalPorts,
+              contract,
+            });
+            baseCtx = createdCtx;
+          } catch (error) {
+            result = await resolveErrorResult(
+              error,
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              { owner: "framework" },
+            );
+          }
+
+          if (!result) {
+            try {
+              result = {
+                ctx: createdCtx,
+                response: normalizeHttpResponse(
+                  await userHandler({
+                    req,
+                    ctx: createdCtx,
+                    contract,
+                    path: {} as HandlerArgs<Ctx, C>["path"],
+                    query: {} as HandlerArgs<Ctx, C>["query"],
+                    headers: rawHeaders as HandlerArgs<Ctx, C>["headers"],
+                    body: undefined as HandlerArgs<Ctx, C>["body"],
+                  }),
+                ),
+                owner: "framework",
+              };
+            } catch (error) {
+              result = await resolveErrorResult(
+                error,
+                createdCtx,
+                undefined,
+                undefined,
+                undefined,
+                undefined,
+                { owner: "framework" },
+              );
+            }
+          }
+        } else {
+          const rawQuery: Record<string, string | string[]> = {};
+          for (const key of new Set(url.searchParams.keys())) {
+            const values = url.searchParams.getAll(key);
+            rawQuery[key] = values.length === 1 ? values[0] : values;
+          }
+
+          // biome-ignore lint/suspicious/noExplicitAny: type is narrowed by schema validation below
+          let query: any = rawQuery;
+          if (contract.query) {
+            try {
+              query = await parseStandardSchema(contract.query, query);
+            } catch (error) {
+              result =
+                error instanceof SchemaValidationError
+                  ? {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid query parameters",
+                        { issues: error.issues },
+                      ),
+                      owner: "framework",
+                    }
+                  : {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid query parameters",
+                        (error as Error).message,
+                      ),
+                      owner: "framework",
+                    };
+            }
+          }
+
+          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
+          let path: any = matchedParams;
+          if (!result && contract.pathParams) {
+            try {
+              path = await parseStandardSchema(
+                contract.pathParams,
+                matchedParams,
+              );
+            } catch (error) {
+              result =
+                error instanceof SchemaValidationError
+                  ? {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid path parameters",
+                        { issues: error.issues },
+                      ),
+                      owner: "framework",
+                    }
+                  : {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid path parameters",
+                        (error as Error).message,
+                      ),
+                      owner: "framework",
+                    };
+            }
+          }
+
+          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
+          let headers: any = rawHeaders;
+          const headerSchemas = getContractHeaderSchemas(contract.headers);
+          if (!result && headerSchemas.length > 0) {
+            try {
+              headers = await parseHeaderSchemas(headerSchemas, rawHeaders);
+            } catch (error) {
+              result =
+                error instanceof SchemaValidationError
+                  ? {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid request headers",
+                        { issues: error.issues },
+                      ),
+                      owner: "framework",
+                    }
+                  : {
+                      response: errorResponse(
+                        422,
+                        "VALIDATION_ERROR",
+                        "Invalid request headers",
+                        (error as Error).message,
+                      ),
+                      owner: "framework",
+                    };
+            }
+          }
+
+          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
+          let body: any;
+          if (!result) {
+            try {
+              body = await parseBody(req);
+            } catch {
+              result = {
+                response: errorResponse(400, "INVALID_BODY", "Malformed JSON"),
+                owner: "framework",
+              };
+            }
+          }
+
+          if (!result && contract.body) {
+            try {
+              body = await parseStandardSchema(contract.body, body);
+            } catch (error) {
+              if (
+                body === undefined &&
+                error instanceof SchemaValidationError
+              ) {
+                result = {
+                  response: errorResponse(
+                    400,
+                    "MISSING_BODY",
+                    "Request body is required",
+                  ),
+                  owner: "framework",
+                };
+              } else {
+                result =
+                  error instanceof SchemaValidationError
+                    ? {
+                        response: errorResponse(
+                          422,
+                          "VALIDATION_ERROR",
+                          "Invalid request body",
+                          { issues: error.issues },
+                        ),
+                        owner: "framework",
+                      }
+                    : {
+                        response: errorResponse(
+                          422,
+                          "VALIDATION_ERROR",
+                          "Invalid request body",
+                          (error as Error).message,
+                        ),
+                        owner: "framework",
+                      };
+              }
+            }
+          }
+
+          if (!result) {
+            pathValue = path;
+            queryValue = query;
+            headersValue = headers;
+            bodyValue = body;
+
+            let createdCtx!: Ctx;
+            try {
+              createdCtx = await options.createContext({
+                req,
+                ports: finalPorts,
+                contract,
+              });
+              baseCtx = createdCtx;
+            } catch (error) {
+              result = await resolveErrorResult(
+                error,
+                undefined,
+                pathValue,
+                queryValue,
+                headersValue,
+                bodyValue,
+                { owner: "framework" },
+              );
+            }
+
+            if (!result) {
+              const baseArgs: HandlerArgs<Ctx, C> = {
+                req,
+                ctx: createdCtx,
+                contract,
+                path,
+                query,
+                headers,
+                body,
+              };
+
+              let currentCtx = createdCtx;
+              for (const hook of hooks) {
+                if (!hook.beforeHandle) continue;
+                try {
+                  const hookResult = await hook.beforeHandle({
+                    req,
+                    ctx: currentCtx,
+                    contract,
+                    path,
+                    query,
+                    headers,
+                    body,
+                  });
+                  if (isWebResponse(hookResult)) {
+                    result = {
+                      ctx: currentCtx,
+                      response: hookResult,
+                      owner: "transport",
+                    };
+                    break;
+                  }
+                  if (isHttpResponseLike(hookResult)) {
+                    result = {
+                      ctx: currentCtx,
+                      response: normalizeResponse(hookResult),
+                      owner: "framework",
+                    };
+                    break;
+                  }
+                  if (hookResult?.ctx !== undefined) {
+                    currentCtx = hookResult.ctx;
+                  }
+                  if (hookResult?.response) {
+                    const response = normalizeHttpResponse(hookResult.response);
+                    result = {
+                      ctx: currentCtx,
+                      response,
+                      owner: responseOwnerFor(response, "framework"),
+                    };
+                    break;
+                  }
+                } catch (error) {
+                  result = await resolveErrorResult(
+                    error,
+                    currentCtx,
+                    pathValue,
+                    queryValue,
+                    headersValue,
+                    bodyValue,
+                    { owner: "framework" },
+                  );
+                  break;
+                }
+              }
+
+              if (!result) {
+                try {
+                  result = {
+                    ctx: currentCtx,
+                    response: normalizeHttpResponse(
+                      await userHandler({ ...baseArgs, ctx: currentCtx }),
+                    ),
+                  };
+                } catch (error) {
+                  result = await resolveErrorResult(
+                    error,
+                    currentCtx,
+                    pathValue,
+                    queryValue,
+                    headersValue,
+                    bodyValue,
+                  );
+                }
+              }
+            }
+          }
+        }
+      }
+
+      result = await applyTransformHooks(result, true);
+
+      let finalResponse = normalizeHttpResponse(result.response);
+      let finalError = result.error;
+      let finalOwner = responseOwnerFor(finalResponse, result.owner);
+      if (finalOwner === "route" && !isWebResponse(finalResponse)) {
+        try {
+          finalResponse = await finalizeResponse(contract, finalResponse);
+        } catch (error) {
+          if (error instanceof ResponseContractViolationError) {
+            result = await applyTransformHooks(
+              {
+                ctx: result.ctx,
+                response: toContractViolationResponse(error),
+                error,
+                owner: "framework",
+              },
+              false,
+            );
+            finalResponse = normalizeHttpResponse(result.response);
+            finalError = result.error;
+            finalOwner = responseOwnerFor(finalResponse, result.owner);
+          } else {
+            throw error;
+          }
+        }
+      }
+      if (!isWebResponse(finalResponse)) {
+        finalResponse = withFrameworkErrorOwnerHeader(
+          finalResponse,
+          finalOwner,
+        );
+      }
+
+      const durationMs = Date.now() - startedAt;
+      for (const hook of hooks) {
+        if (!hook.afterSend) continue;
+        try {
+          await hook.afterSend({
+            req,
+            ctx: result.ctx,
+            contract,
+            path: pathValue,
+            query: queryValue,
+            headers: headersValue,
+            body: bodyValue,
+            response: responseForHooks(finalResponse),
+            error: finalError,
+            durationMs,
+          });
+        } catch {
+          // Ignore after-response hook failures; they should never change the response.
+        }
+      }
+
+      return finalResponse;
+    } catch (error) {
+      const result = await resolveErrorResult(
+        error,
+        baseCtx,
+        pathValue,
+        queryValue,
+        headersValue,
+        bodyValue,
+        {
+          owner: "framework",
+        },
+      );
+      const response = normalizeHttpResponse(result.response);
+      if (isWebResponse(response)) {
+        return response;
+      }
+      return withFrameworkErrorOwnerHeader(
+        response,
+        responseOwnerFor(response, result.owner),
+      );
+    }
+  };
+}
+
+export async function createServer<
+  Ctx,
+  Ports extends AnyPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Providers extends readonly ServiceProvider<
+    unknown,
+    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+    StandardSchemaV1<any, any>,
+    AnyPorts
+  >[] = readonly [],
+>(
+  options: CreateServerOptions<Ctx, Ports, Routes, Providers>,
+): Promise<ServerInstance<Ctx, Ports & ProvidedPortsOfList<Providers>>> {
+  type RegisteredRoute = ResolvedRoute<Ctx, HttpContractConfig> & {
+    compiled: CompiledPath;
+  };
+  const registry: RegisteredRoute[] = [];
+  type FinalPorts = Ports & ProvidedPortsOfList<Providers>;
+  const providers = (options.providers ?? []) as readonly ServiceProvider<
+    unknown,
+    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+    StandardSchemaV1<any, any>,
+    AnyPorts
+  >[];
+  const env = options.providerEnv ?? process.env;
+  const overrides = options.providerConfig ?? {};
+  const providerResults: ProviderSetupResult<AnyPorts>[] = [];
+  const finalPorts = { ...options.ports } as FinalPorts;
+  const hooks = [...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[])];
+  const contracts = options.routes ? contractsFromRoutes(options.routes) : [];
+
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    const errors: unknown[] = [];
+    for (let i = providerResults.length - 1; i >= 0; i -= 1) {
+      const result = providerResults[i];
+      try {
+        await result?.stop?.({
+          ports: finalPorts,
+        });
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+    if (errors.length) {
+      throw new AggregateError(errors, "Provider shutdown errors");
+    }
+  };
+
+  const registeredPaths = new Set<string>();
+  const registeredShapes = new Map<string, string>();
+
+  const registerRoute = <C extends HttpContractConfig>(
+    contract: C,
+    handler: Handler<Ctx, C>,
+  ): void => {
+    if (contract.body && !methodSupportsRequestBody(contract.method)) {
+      throw new Error(
+        `Request bodies are not supported for ${contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
+      );
+    }
+    const compiled = compilePath(contract.path);
+    const normalizedPath = compiled.normalizedPath;
+    const routeKey = `${contract.method.toUpperCase()} ${normalizedPath}`;
+    if (registeredPaths.has(routeKey)) {
+      throw new Error(
+        `Duplicate route: ${routeKey} is already registered. Each method + path combination must be unique.`,
+      );
+    }
+    const shapeRouteKey = `${contract.method.toUpperCase()} ${compiled.shapeKey}`;
+    const conflictingRoute = registeredShapes.get(shapeRouteKey);
+    if (conflictingRoute) {
+      throw new Error(
+        `Ambiguous route: ${routeKey} conflicts with ${conflictingRoute}. Dynamic parameter names are ignored during routing, so each method + path shape must be unique.`,
+      );
+    }
+    registeredPaths.add(routeKey);
+    registeredShapes.set(shapeRouteKey, routeKey);
+
+    const builtHandler = buildHandler(
+      options,
+      finalPorts,
+      contract,
+      handler,
+      hooks,
+    );
+    registry.push({
+      contract,
+      compiled,
+      handler: builtHandler,
+      match: (method, pathname) => {
+        if (contract.method.toUpperCase() !== method.toUpperCase()) {
+          return { matched: false as const };
+        }
+        const match = compiled.pattern.exec(pathname);
+        if (!match) return { matched: false as const };
+        return { matched: true as const };
+      },
+    });
+    registry.sort((a, b) => compareRouteSpecificity(a.compiled, b.compiled));
+  };
+
+  const createBuilder = <C extends HttpContractConfig>(
+    contract: C,
+    shouldRegister: boolean,
+  ): RouteBuilder<Ctx, C> => ({
+    handle: (fn) => {
+      const wrapped = buildHandler(options, finalPorts, contract, fn, hooks);
+      if (shouldRegister) registerRoute(contract, fn);
+      return wrapped;
+    },
+  });
+
+  if (options.routes) {
+    try {
+      for (const route of options.routes) {
+        const contract = resolveContract(route.contract);
+        registerRoute(contract, route.handle);
+      }
+    } catch (error) {
+      try {
+        await stop();
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          "Server initialization failed and provider cleanup failed",
+        );
+      }
+      throw error;
+    }
+  }
+
+  try {
+    for (const provider of providers) {
+      const cfg = await loadProviderConfig(provider, env, overrides);
+      const result = await provider.setup({
+        ports: finalPorts,
+        config: cfg,
+      });
+      if (result.ports) {
+        Object.assign(finalPorts, result.ports);
+      }
+      providerResults.push(result);
+    }
+
+    for (const result of providerResults) {
+      if (!result.start) continue;
+      await result.start({
+        ports: finalPorts,
+      });
+    }
+  } catch (error) {
+    try {
+      await stop();
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        "Server initialization failed and provider cleanup failed",
+      );
+    }
+    throw error;
+  }
+
+  const api = async (req: HttpRequestLike) => {
+    const url = new URL(req.url);
+
+    for (const entry of registry) {
+      const result = entry.match(req.method, url.pathname);
+      if (result.matched) {
+        return await entry.handler(req);
+      }
+    }
+
+    const notFoundContract: HttpContractConfig = {
+      kind: "http",
+      name: "notFound",
+      method: req.method.toUpperCase() as HttpContractConfig["method"],
+      path: url.pathname || "/",
+      pathParams: null,
+      query: null,
+      body: null,
+      responses: {},
+      metadata: {},
+    };
+
+    const notFoundHandler = buildHandler(
+      options,
+      finalPorts,
+      notFoundContract,
+      async () => errorResponse(404, "NOT_FOUND", "Not found"),
+      hooks,
+      { skipRoutePreparation: true },
+    );
+
+    return await notFoundHandler(req);
+  };
+
+  return {
+    api,
+    route: (contractLike) => {
+      const contract = resolveContract(contractLike);
+      return createBuilder(contract, true);
+    },
+    contracts,
+    stop,
+    ports: finalPorts,
+  };
+}
+
+/**
+ * Helper function to define routes with proper type inference.
+ * Eliminates the need for type assertions when passing routes to createServer.
+ *
+ * @example
+ * const routes = defineRoutes<AppContext>([
+ *   { contract: myContract, handle: async ({ query }) => { ... } }
+ * ]);
+ */
+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)) {
+      flattened.push(...route.routes);
+    } else {
+      flattened.push(route);
+    }
+  }
+
+  return flattened as unknown as FlattenRouteInputs<R>;
+}
+
+/**
+ * Extract contract configs from a route list. Use this to drive OpenAPI from
+ * the same route registration list that createServer receives.
+ */
+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>;
+}
+
+/**
+ * Helper function to group 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 colocated.
+ *
+ * @example
+ * const todoRoutes = defineRouteGroup<AppContext>({
+ *   name: "todos",
+ *   routes: [
+ *     { contract: listTodos, handle: async ({ ctx }) => { ... } }
+ *   ]
+ * });
+ */
+export function defineRouteGroup<
+  Ctx,
+  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
+  const R extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+>(group: { name: string; routes: R }): RouteGroup<Ctx, R> {
+  return {
+    kind: ROUTE_GROUP_KIND,
+    name: group.name,
+    routes: group.routes,
+  };
+}
+
+function isRouteGroup<Ctx>(route: RouteInput<Ctx>): route is RouteGroup<Ctx> {
+  return (
+    typeof route === "object" &&
+    route !== null &&
+    "kind" in route &&
+    route.kind === ROUTE_GROUP_KIND
+  );
+}