@beignet/core 0.0.34 → 0.0.36

package/dist/server/server.js

@@ -1,1288 +1,20 @@
-import { BEIGNET_ERROR_OWNER_HEADER, getContractHeaderSchemas, methodSupportsRequestBody, parsePathTemplate, } from "../contracts/index.js";
+import { methodSupportsRequestBody, } from "../contracts/index.js";
 import { comparePathParamsToTemplate, formatPathParamsMismatch, getObjectSchemaShape, } from "../contracts/schema-shape.js";
-import { createErrorResponseBody, httpErrors, isAppError, isErrorResponseBody, toErrorResponseBody, } from "../errors/index.js";
-import { IdempotencyConflictError, IdempotencyInProgressError, } from "../idempotency/index.js";
-import { runWithMemoScope, } from "../memo/index.js";
-import { AuthUnauthorizedError, EntitlementRequiredError, GateAuthorizationError, isUnboundPort, TenantRequiredError, } from "../ports/index.js";
-import { createProviderInstrumentation, resolveProviderInstrumentationPort, } from "../providers/index.js";
-import { parseTraceparent, resolveTracingPort, runWithTracing, } from "../tracing/index.js";
+import { createErrorResponseBody } from "../errors/index.js";
+import { runWithMemoScope } from "../memo/index.js";
+import { isUnboundPort } from "../ports/index.js";
 import { createContextFinalizer, resolveServerContext } from "./context.js";
 import { resolveContract } from "./contract-like.js";
-import { getRequestIdFromContext } from "./hooks/utils.js";
 import { createServerInstrumentation } from "./instrumentation.js";
-import { getResponseFinalizerHook, } from "./internal-hooks.js";
-import { loadProviderConfig, parseStandardSchema, SchemaValidationError, } from "./providers/index.js";
-import { enterActiveRequestContext, readContextActor, readContextTenant, runWithActiveRequestContext, setActiveRequestIdentity, } from "./request-context.js";
+import { loadProviderConfig } from "./providers/index.js";
+import { enterActiveRequestContext, readContextActor, readContextTenant, runWithActiveRequestContext, } from "./request-context.js";
+import { buildHandler, createMemoScopeRecorder, createRequestExecutor, } from "./request-executor.js";
+import { errorResponse } from "./response-finalization.js";
+import { contractsFromRoutes, createRoutes, defineRoutes, } from "./route-definitions.js";
+import { compareRouteSpecificity, compilePath, } from "./route-matching.js";
 import { runRuntimeIntegrityCheck } from "./runtime-integrity.js";
 import { createUseCaseRouteHandler, isUseCaseRouteDef, } from "./use-case-route.js";
-const ROUTE_GROUP_KIND = "beignet.route-group";
-/**
- * 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.
- */
-export function defineRoute() {
-    function define(route) {
-        return route;
-    }
-    return define;
-}
-class PathDecodeError extends Error {
-    constructor() {
-        super("Malformed URL path");
-        this.name = "PathDecodeError";
-    }
-}
-function compilePath(path) {
-    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, match) {
-    const params = {};
-    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, b) {
-    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, code, message, details) {
-    return {
-        status,
-        body: createErrorResponseBody({ code, message, details }),
-    };
-}
-function contractDiagnostics(contract) {
-    return {
-        contract: contract.name,
-        method: contract.method,
-        path: contract.path,
-    };
-}
-function requestValidationDetails(contract, location, error) {
-    const details = {
-        ...contractDiagnostics(contract),
-        location,
-    };
-    if (error instanceof SchemaValidationError) {
-        return {
-            ...details,
-            issues: error.issues,
-        };
-    }
-    if (error instanceof Error) {
-        return {
-            ...details,
-            message: error.message,
-        };
-    }
-    return details;
-}
-function requestValidationError(contract, status, code, message, location, error) {
-    return errorResponse(status, code, message, requestValidationDetails(contract, location, error));
-}
-function normalizeResponse(res) {
-    return {
-        status: res.status,
-        headers: res.headers,
-        body: res.body,
-    };
-}
-function isWebResponse(value) {
-    return typeof Response !== "undefined" && value instanceof Response;
-}
-function normalizeHttpResponse(res) {
-    return isWebResponse(res) ? res : normalizeResponse(res);
-}
-function withFrameworkErrorOwnerHeader(res, owner) {
-    if (owner !== "framework" ||
-        res.status < 400 ||
-        !isErrorResponseBody(res.body)) {
-        return res;
-    }
-    return {
-        ...res,
-        headers: {
-            ...(res.headers ?? {}),
-            [BEIGNET_ERROR_OWNER_HEADER]: "framework",
-        },
-    };
-}
-function responseOwnerFor(res, owner) {
-    if (isWebResponse(res))
-        return "transport";
-    return owner ?? "route";
-}
-function headersToRecord(headers) {
-    const record = {};
-    headers.forEach((value, key) => {
-        record[key] = value;
-    });
-    return record;
-}
-function requestHeadersToRecord(headers) {
-    const record = {};
-    headers.forEach((value, key) => {
-        record[key.toLowerCase()] = value;
-    });
-    return record;
-}
-async function parseHeaderSchemas(schemas, rawHeaders) {
-    let parsedHeaders = rawHeaders;
-    for (const schema of schemas) {
-        const parsed = await parseStandardSchema(schema, rawHeaders);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            parsedHeaders = {
-                ...parsedHeaders,
-                ...parsed,
-            };
-        }
-        else {
-            parsedHeaders = parsed;
-        }
-    }
-    return parsedHeaders;
-}
-function responseForHooks(res) {
-    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.
- */
-function mergeNativeResponseHeaders(nativeResponse, originalHeaders, finalHeaders) {
-    const originalByLowerKey = new Map();
-    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,
-    });
-}
-function isHttpResponseLike(value) {
-    return (!isWebResponse(value) &&
-        typeof value === "object" &&
-        value !== null &&
-        "status" in value &&
-        typeof value.status === "number");
-}
-class ResponseContractViolationError extends Error {
-    code;
-    details;
-    constructor(args) {
-        super(args.message);
-        this.name = "ResponseContractViolationError";
-        this.code = args.code;
-        this.details = args.details;
-    }
-}
-function responseContractViolationMessage(contract, status) {
-    return (`Response validation failed for ${contract.method} ${contract.path} ` +
-        `(status ${status}, contract: ${contract.name})`);
-}
-function declaredResponseStatuses(contract) {
-    return Object.keys(contract.responses)
-        .map((status) => Number(status))
-        .filter((status) => Number.isFinite(status))
-        .sort((a, b) => a - b);
-}
-function responseContractViolationDetails(contract, status, details) {
-    return {
-        ...contractDiagnostics(contract),
-        location: "response",
-        status,
-        declaredStatuses: declaredResponseStatuses(contract),
-        ...details,
-    };
-}
-function getDeclaredCatalogErrorsForStatus(contract, status) {
-    const errors = contract.metadata?.errors;
-    if (typeof errors !== "object" || errors === null)
-        return [];
-    return Object.values(errors).filter((error) => typeof error === "object" &&
-        error !== null &&
-        typeof error.code === "string" &&
-        typeof error.status === "number" &&
-        typeof error.message === "string" &&
-        error.status === status);
-}
-async function validateCatalogErrorResponse(contract, res) {
-    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(contract, res, responseValidationExemptStatus) {
-    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;
-    }
-}
-async function finalizeResponse(contract, res, responseValidationExemptStatus) {
-    const normalized = normalizeResponse(res);
-    await validateResponseAgainstContract(contract, normalized, responseValidationExemptStatus);
-    return normalized;
-}
-function toContractViolationResponse(error) {
-    return {
-        status: 500,
-        body: createErrorResponseBody({
-            code: error.code,
-            message: error.message,
-            details: error.details,
-        }),
-    };
-}
-function defaultErrorResponse(err, ctx) {
-    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,
-        }),
-    };
-}
-const DEFAULT_REQUEST_BODY_MAX_BYTES = 1024 * 1024;
-class RequestBodyTooLargeError extends Error {
-    maxBytes;
-    actualBytes;
-    constructor(maxBytes, actualBytes) {
-        super("Request body exceeds the configured size limit.");
-        this.name = "RequestBodyTooLargeError";
-        this.maxBytes = maxBytes;
-        this.actualBytes = actualBytes;
-    }
-}
-function requestBodyLimit(options) {
-    const maxBytes = options?.maxBytes ?? DEFAULT_REQUEST_BODY_MAX_BYTES;
-    if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
-        throw new Error("createServer requestBody.maxBytes must be a positive number.");
-    }
-    return maxBytes;
-}
-function assertContentLengthWithinLimit(headers, maxBytes) {
-    const contentLength = headers.get("content-length");
-    if (contentLength === null)
-        return;
-    const actualBytes = Number(contentLength);
-    if (!Number.isFinite(actualBytes) || actualBytes < 0)
-        return;
-    if (actualBytes > maxBytes) {
-        throw new RequestBodyTooLargeError(maxBytes, actualBytes);
-    }
-}
-async function readLimitedRequestText(req, maxBytes) {
-    assertContentLengthWithinLimit(req.headers, maxBytes);
-    const body = req.raw?.body;
-    if (!body) {
-        const text = await req.text();
-        const actualBytes = new TextEncoder().encode(text).byteLength;
-        if (actualBytes > maxBytes) {
-            throw new RequestBodyTooLargeError(maxBytes, actualBytes);
-        }
-        return text;
-    }
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let received = 0;
-    let text = "";
-    try {
-        while (true) {
-            const result = await reader.read();
-            if (result.done)
-                break;
-            received += result.value.byteLength;
-            if (received > maxBytes) {
-                throw new RequestBodyTooLargeError(maxBytes, received);
-            }
-            text += decoder.decode(result.value, { stream: true });
-        }
-        text += decoder.decode();
-    }
-    finally {
-        reader.releaseLock();
-    }
-    return text;
-}
-async function parseBody(req, maxBytes) {
-    const method = req.method.toUpperCase();
-    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 readLimitedRequestText(bodyReq, maxBytes);
-        if (text === "")
-            return undefined;
-        return JSON.parse(text);
-    }
-    try {
-        const text = await readLimitedRequestText(bodyReq, maxBytes);
-        return text === "" ? undefined : text;
-    }
-    catch (error) {
-        if (error instanceof RequestBodyTooLargeError)
-            throw error;
-        return undefined;
-    }
-}
-/**
- * Build the per-request execution pipeline once.
- *
- * The returned executor takes the contract, compiled pattern, and user handler
- * per invocation so fallback responses (404/405) can reuse a single pipeline
- * across requests instead of rebuilding it per unmatched request.
- */
-function createRequestExecutor(
-// biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
-options, finalPorts, contextRuntime, hooks, routeHooks = [], optionsOverrides) {
-    const warnedNativeReplacementHooks = new WeakSet();
-    const maxRequestBodyBytes = requestBodyLimit(options.requestBody);
-    const executeRequest = async (target, req, preMatchedParams) => {
-        const { contract, handler: userHandler } = target;
-        let baseCtx;
-        let pathValue;
-        let queryValue;
-        let headersValue;
-        let bodyValue;
-        const startedAt = Date.now();
-        // Stage timings accumulate because retries re-enter the send phase and
-        // beforeHandle spans the route-hook and server-hook loops.
-        const stages = {
-            onRequestMs: 0,
-            parseMs: 0,
-            contextMs: 0,
-            beforeHandleMs: 0,
-            handlerMs: 0,
-            sendMs: 0,
-        };
-        const timeStage = async (stage, run) => {
-            const stageStartedAt = performance.now();
-            try {
-                return await run();
-            }
-            finally {
-                stages[stage] += performance.now() - stageStartedAt;
-            }
-        };
-        const resolveErrorResult = async (error, ctx, path, query, headers, body, resultOptions) => {
-            let currentError = error;
-            const notifyCaughtError = async (caught) => {
-                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,
-                        ...(currentError.headers
-                            ? { headers: { ...currentError.headers } }
-                            : {}),
-                        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 TenantRequiredError) {
-                return {
-                    ctx,
-                    response: errorResponse(currentError.status, currentError.code, currentError.message),
-                    error: currentError,
-                    owner: "framework",
-                };
-            }
-            if (currentError instanceof IdempotencyConflictError) {
-                return {
-                    ctx,
-                    response: errorResponse(httpErrors.IdempotencyConflict.status, httpErrors.IdempotencyConflict.code, currentError.message, {
-                        namespace: currentError.namespace,
-                        key: currentError.key,
-                    }),
-                    error: currentError,
-                    owner: "framework",
-                };
-            }
-            if (currentError instanceof IdempotencyInProgressError) {
-                return {
-                    ctx,
-                    response: errorResponse(httpErrors.IdempotencyInProgress.status, httpErrors.IdempotencyInProgress.code, currentError.message, {
-                        namespace: currentError.namespace,
-                        key: currentError.key,
-                    }),
-                    error: currentError,
-                    owner: "framework",
-                };
-            }
-            if (currentError instanceof GateAuthorizationError) {
-                return {
-                    ctx,
-                    response: errorResponse(currentError.status, currentError.code, currentError.message, currentError.details),
-                    error: currentError,
-                    owner: "framework",
-                };
-            }
-            if (currentError instanceof EntitlementRequiredError) {
-                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;
-            if (preMatchedParams) {
-                matchedParams = preMatchedParams;
-            }
-            else {
-                const compiled = target.compiled;
-                const match = compiled ? compiled.pattern.exec(url.pathname) : null;
-                if (!compiled ||
-                    !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 runNativeBeforeSend = async (initialResult, nativeResponse) => {
-                const originalView = responseForHooks(nativeResponse);
-                const originalHeaders = originalView.headers ?? {};
-                let transformed = originalView;
-                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,
-                        native: true,
-                    });
-                    if (nextResponse) {
-                        if ((nextResponse.status !== nativeResponse.status ||
-                            nextResponse.body !== undefined) &&
-                            !warnedNativeReplacementHooks.has(hook) &&
-                            process.env.NODE_ENV !== "production") {
-                            warnedNativeReplacementHooks.add(hook);
-                            console.warn(`[beignet] beforeSend hook "${hook.name ?? "(anonymous)"}" returned a replacement status or body for a native Response on ${contract.method} ${contract.path}. Native responses are headers-only in beforeSend; status and body changes are ignored.`);
-                        }
-                        transformed = {
-                            status: nativeResponse.status,
-                            headers: nextResponse.headers,
-                        };
-                    }
-                }
-                return mergeNativeResponseHeaders(nativeResponse, originalHeaders, transformed.headers ?? {});
-            };
-            const applyTransformHooks = async (initialResult, allowRetry) => {
-                try {
-                    if (isWebResponse(initialResult.response)) {
-                        return {
-                            ...initialResult,
-                            response: await runNativeBeforeSend(initialResult, initialResult.response),
-                        };
-                    }
-                    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);
-                }
-            };
-            const applyResponseFinalizerHooks = async (initialResult, allowRetry, responseValidation) => {
-                const response = normalizeHttpResponse(initialResult.response);
-                const native = isWebResponse(response);
-                const owner = responseOwnerFor(response, initialResult.owner);
-                try {
-                    for (const hook of hooks) {
-                        const finalizer = getResponseFinalizerHook(hook);
-                        if (!finalizer)
-                            continue;
-                        await finalizer({
-                            req,
-                            ctx: initialResult.ctx,
-                            contract,
-                            path: pathValue,
-                            query: queryValue,
-                            headers: headersValue,
-                            body: bodyValue,
-                            response: responseForHooks(response),
-                            error: initialResult.error,
-                            native: native ? true : undefined,
-                            owner,
-                            responseValidation,
-                        });
-                    }
-                    return {
-                        ...initialResult,
-                        response,
-                    };
-                }
-                catch (error) {
-                    const mapped = await resolveErrorResult(error, initialResult.ctx, pathValue, queryValue, headersValue, bodyValue, { owner: "framework" });
-                    if (!allowRetry) {
-                        return mapped;
-                    }
-                    const transformed = await applyTransformHooks(mapped, true);
-                    return applyResponseFinalizerHooks(transformed, false, "not-applicable");
-                }
-            };
-            let result;
-            const onRequestStartedAt = performance.now();
-            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;
-                }
-            }
-            stages.onRequestMs = performance.now() - onRequestStartedAt;
-            if (!result) {
-                if (optionsOverrides?.skipRoutePreparation) {
-                    let createdCtx;
-                    try {
-                        createdCtx = await timeStage("contextMs", () => contextRuntime.createRequestContext(req, 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 timeStage("handlerMs", () => userHandler({
-                                    req,
-                                    ctx: createdCtx,
-                                    contract,
-                                    path: {},
-                                    query: {},
-                                    headers: rawHeaders,
-                                    body: undefined,
-                                }))),
-                                owner: "framework",
-                            };
-                        }
-                        catch (error) {
-                            result = await resolveErrorResult(error, createdCtx, undefined, undefined, undefined, undefined, { owner: "framework" });
-                        }
-                    }
-                }
-                else {
-                    const parseStartedAt = performance.now();
-                    const rawQuery = {};
-                    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 = rawQuery;
-                    if (contract.query) {
-                        try {
-                            query = await parseStandardSchema(contract.query, query);
-                        }
-                        catch (error) {
-                            result = {
-                                response: requestValidationError(contract, 422, "VALIDATION_ERROR", "Invalid query parameters", "query", error),
-                                owner: "framework",
-                            };
-                        }
-                    }
-                    // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-                    let path = matchedParams;
-                    if (!result && contract.pathParams) {
-                        try {
-                            path = await parseStandardSchema(contract.pathParams, matchedParams);
-                        }
-                        catch (error) {
-                            result = {
-                                response: requestValidationError(contract, 422, "VALIDATION_ERROR", "Invalid path parameters", "path", error),
-                                owner: "framework",
-                            };
-                        }
-                    }
-                    // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-                    let headers = rawHeaders;
-                    const headerSchemas = getContractHeaderSchemas(contract.headers);
-                    if (!result && headerSchemas.length > 0) {
-                        try {
-                            headers = await parseHeaderSchemas(headerSchemas, rawHeaders);
-                        }
-                        catch (error) {
-                            result = {
-                                response: requestValidationError(contract, 422, "VALIDATION_ERROR", "Invalid request headers", "headers", error),
-                                owner: "framework",
-                            };
-                        }
-                    }
-                    // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-                    let body;
-                    // Raw routes own body consumption: the handler reads `req` itself,
-                    // for example to verify a webhook signature over the exact bytes.
-                    if (!result && !optionsOverrides?.rawRoute) {
-                        try {
-                            body = await parseBody(req, maxRequestBodyBytes);
-                        }
-                        catch (error) {
-                            if (error instanceof RequestBodyTooLargeError) {
-                                result = {
-                                    response: requestValidationError(contract, 413, "PAYLOAD_TOO_LARGE", "Request body is too large", "body", error),
-                                    owner: "framework",
-                                };
-                            }
-                            else {
-                                result = {
-                                    response: requestValidationError(contract, 400, "INVALID_BODY", "Malformed JSON", "body", error),
-                                    owner: "framework",
-                                };
-                            }
-                        }
-                    }
-                    if (!result && contract.body) {
-                        try {
-                            body = await parseStandardSchema(contract.body, body);
-                        }
-                        catch (error) {
-                            if (body === undefined &&
-                                error instanceof SchemaValidationError) {
-                                result = {
-                                    response: requestValidationError(contract, 400, "MISSING_BODY", "Request body is required", "body", error),
-                                    owner: "framework",
-                                };
-                            }
-                            else {
-                                result = {
-                                    response: requestValidationError(contract, 422, "VALIDATION_ERROR", "Invalid request body", "body", error),
-                                    owner: "framework",
-                                };
-                            }
-                        }
-                    }
-                    stages.parseMs = performance.now() - parseStartedAt;
-                    if (!result) {
-                        pathValue = path;
-                        queryValue = query;
-                        headersValue = headers;
-                        bodyValue = body;
-                        let createdCtx;
-                        try {
-                            createdCtx = await timeStage("contextMs", () => contextRuntime.createRequestContext(req, contract));
-                            baseCtx = createdCtx;
-                        }
-                        catch (error) {
-                            result = await resolveErrorResult(error, undefined, pathValue, queryValue, headersValue, bodyValue, { owner: "framework" });
-                        }
-                        if (!result) {
-                            const baseArgs = {
-                                req,
-                                ctx: createdCtx,
-                                contract,
-                                path,
-                                query,
-                                headers,
-                                body,
-                            };
-                            let currentCtx = createdCtx;
-                            const beforeHandleStartedAt = performance.now();
-                            for (const hook of routeHooks) {
-                                try {
-                                    const additions = await hook.resolve({
-                                        req,
-                                        ctx: currentCtx,
-                                        contract,
-                                        path,
-                                        query,
-                                        headers,
-                                        body,
-                                    });
-                                    if (additions && typeof additions === "object") {
-                                        currentCtx = contextRuntime.finalizeContext({
-                                            ...currentCtx,
-                                            ...additions,
-                                        });
-                                    }
-                                }
-                                catch (error) {
-                                    result = await resolveErrorResult(error, currentCtx, pathValue, queryValue, headersValue, bodyValue, { owner: "framework" });
-                                    break;
-                                }
-                            }
-                            if (!result) {
-                                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 = contextRuntime.finalizeContext(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;
-                                    }
-                                }
-                            }
-                            stages.beforeHandleMs = performance.now() - beforeHandleStartedAt;
-                            if (!result) {
-                                // Hooks may have elevated the actor or resolved a tenant.
-                                // Refresh the ambient request context so record-time
-                                // consumers such as createAmbientAuditLog see the finalized
-                                // identity.
-                                setActiveRequestIdentity({
-                                    actor: readContextActor(currentCtx),
-                                    tenant: readContextTenant(currentCtx),
-                                });
-                                try {
-                                    result = {
-                                        ctx: currentCtx,
-                                        response: normalizeHttpResponse(await timeStage("handlerMs", () => userHandler({ ...baseArgs, ctx: currentCtx }))),
-                                    };
-                                }
-                                catch (error) {
-                                    result = await resolveErrorResult(error, currentCtx, pathValue, queryValue, headersValue, bodyValue);
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            const sendStartedAt = performance.now();
-            result = await applyTransformHooks(result, true);
-            let finalResponse = normalizeHttpResponse(result.response);
-            let finalError = result.error;
-            let finalOwner = responseOwnerFor(finalResponse, result.owner);
-            let responseValidation = "not-applicable";
-            if (finalOwner === "route" &&
-                !isWebResponse(finalResponse) &&
-                !(options.validateResponses ?? true)) {
-                responseValidation = "disabled";
-            }
-            else if (finalOwner === "route" &&
-                !isWebResponse(finalResponse) &&
-                (options.validateResponses ?? true)) {
-                try {
-                    finalResponse = await finalizeResponse(contract, finalResponse, target.responseValidationExemptStatus);
-                    result = {
-                        ...result,
-                        response: finalResponse,
-                    };
-                    responseValidation = "validated";
-                }
-                catch (error) {
-                    if (error instanceof ResponseContractViolationError) {
-                        result = {
-                            ctx: result.ctx,
-                            response: toContractViolationResponse(error),
-                            error,
-                            owner: "framework",
-                        };
-                        finalResponse = normalizeHttpResponse(result.response);
-                        finalError = result.error;
-                        finalOwner = responseOwnerFor(finalResponse, result.owner);
-                        result = await applyTransformHooks(result, true);
-                        finalResponse = normalizeHttpResponse(result.response);
-                        finalError = result.error;
-                        finalOwner = responseOwnerFor(finalResponse, result.owner);
-                        responseValidation = "not-applicable";
-                    }
-                    else {
-                        throw error;
-                    }
-                }
-            }
-            result = await applyResponseFinalizerHooks(result, true, responseValidation);
-            finalResponse = normalizeHttpResponse(result.response);
-            finalError = result.error;
-            finalOwner = responseOwnerFor(finalResponse, result.owner);
-            if (!isWebResponse(finalResponse)) {
-                finalResponse = withFrameworkErrorOwnerHeader(finalResponse, finalOwner);
-            }
-            stages.sendMs = performance.now() - sendStartedAt;
-            const durationMs = Date.now() - startedAt;
-            const stageTimings = roundStageTimings(stages);
-            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,
-                        stages: stageTimings,
-                    });
-                }
-                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));
-        }
-    };
-    return async (target, req, preMatchedParams) => {
-        const tracing = resolveTracingPort(finalPorts);
-        const instrumentationOptions = options.instrumentation === false ? undefined : options.instrumentation;
-        const pathname = (() => {
-            try {
-                return new URL(req.url).pathname;
-            }
-            catch {
-                return req.url;
-            }
-        })();
-        const ignored = (instrumentationOptions?.ignorePaths ?? ["/api/devtools"]).some((prefix) => {
-            const normalized = prefix.replace(/\/+$/, "");
-            return pathname === normalized || pathname.startsWith(`${normalized}/`);
-        });
-        if (!tracing || ignored) {
-            return executeRequest(target, req, preMatchedParams);
-        }
-        const traceContextHeader = instrumentationOptions?.traceContextHeader ?? "traceparent";
-        const active = tracing.current();
-        const parsedTraceparent = traceContextHeader === false
-            ? undefined
-            : parseTraceparent(req.headers.get(traceContextHeader));
-        const parent = active
-            ? undefined
-            : !parsedTraceparent
-                ? undefined
-                : {
-                    traceparent: parsedTraceparent.traceparent,
-                    tracestate: req.headers.get("tracestate") ?? undefined,
-                };
-        const traceAttributes = {
-            "beignet.contract.name": target.contract.name,
-            "http.request.method": req.method.toUpperCase(),
-            "http.route": target.contract.path,
-        };
-        return await runWithTracing(tracing, {
-            name: `beignet.request ${target.contract.name}`,
-            type: "request",
-            kind: active ? "internal" : "server",
-            parent,
-            attributes: traceAttributes,
-            metricAttributes: traceAttributes,
-        }, async (span) => {
-            const response = await executeRequest(target, req, preMatchedParams);
-            span?.setAttribute("http.response.status_code", response.status);
-            if (response.status >= 500)
-                span?.setStatus("error");
-            return response;
-        });
-    };
-}
-/**
- * Build a memo instrumentation recorder from the app ports, or undefined when
- * no instrumentation sink is wired.
- *
- * Resolved per execution rather than at route-build time because providers
- * contribute `ports.instrumentation`/`ports.devtools` during setup, after
- * routes are registered.
- */
-function createMemoScopeRecorder(ports) {
-    const target = ports;
-    if (!resolveProviderInstrumentationPort(target))
-        return undefined;
-    const instrumentation = createProviderInstrumentation(target, {
-        providerName: "memo",
-        watcher: "memo",
-    });
-    return (event) => {
-        instrumentation.custom({
-            name: `memo.${event.kind}`,
-            label: event.kind === "hit" ? "Memo hit" : "Memo fill",
-            summary: `Memo ${event.kind} for ${event.memo}`,
-            details: {
-                memo: event.memo,
-                key: event.key,
-                ...(event.durationMs !== undefined
-                    ? { durationMs: event.durationMs }
-                    : {}),
-                ...(event.failed ? { failed: true } : {}),
-            },
-        });
-    };
-}
-function buildHandler(
-// biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
-options, finalPorts, contextRuntime, contract, userHandler, hooks, routeHooks = [], optionsOverrides, responseValidationExemptStatus) {
-    const execute = createRequestExecutor(options, finalPorts, contextRuntime, hooks, routeHooks, optionsOverrides);
-    const executionTarget = {
-        contract,
-        compiled: compilePath(contract.path),
-        handler: userHandler,
-        responseValidationExemptStatus,
-    };
-    // Every HTTP execution runs inside a fresh memo scope so createMemo(...)
-    // wrappers dedupe lookups for exactly one request.
-    return (req, preMatchedParams) => runWithMemoScope({ record: createMemoScopeRecorder(finalPorts) }, () => execute(executionTarget, req, preMatchedParams));
-}
+export { contractsFromRoutes, createRoutes, defineRoutes };
 /**
  * Create a Beignet server instance.
  *
@@ -1594,16 +326,33 @@ export async function createServer(options) {
         const url = new URL(req.url);
         const method = req.method.toUpperCase();
         let pathMatchedMethods;
+        let headCandidate;
         for (const entry of registry) {
             if (!entry.compiled.pattern.test(url.pathname))
                 continue;
-            if (entry.method === method) {
+            if (method !== "HEAD" && entry.method === method) {
                 return await entry.handler(req);
             }
             if (!pathMatchedMethods) {
                 pathMatchedMethods = new Set();
             }
             pathMatchedMethods.add(entry.method);
+            if (method === "HEAD" && entry.method === "HEAD") {
+                if (!headCandidate ||
+                    (headCandidate.method === "GET" &&
+                        headCandidate.compiled.shapeKey === entry.compiled.shapeKey)) {
+                    headCandidate = entry;
+                }
+            }
+            if (entry.method === "GET") {
+                pathMatchedMethods.add("HEAD");
+                if (method === "HEAD" && !headCandidate) {
+                    headCandidate = entry;
+                }
+            }
+        }
+        if (headCandidate) {
+            return await headCandidate.handler(req);
         }
         const pathname = url.pathname || "/";
         if (pathMatchedMethods) {
@@ -1648,17 +397,6 @@ export async function createServer(options) {
         ports: finalPorts,
     };
 }
-function roundStageTimings(stages) {
-    const round = (value) => Math.round(value * 100) / 100;
-    return {
-        onRequestMs: round(stages.onRequestMs),
-        parseMs: round(stages.parseMs),
-        contextMs: round(stages.contextMs),
-        beforeHandleMs: round(stages.beforeHandleMs),
-        handlerMs: round(stages.handlerMs),
-        sendMs: round(stages.sendMs),
-    };
-}
 function rawRouteContract(init) {
     return {
         kind: "http",
@@ -1672,63 +410,4 @@ function rawRouteContract(init) {
         metadata: init.metadata ?? {},
     };
 }
-export function defineRoutes(routes) {
-    const flattened = [];
-    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;
-}
-/**
- * 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(routes) {
-    return routes.map((route) => resolveContract(route.contract));
-}
-/**
- * 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 todoRoutes = defineRouteGroup<AppContext>()({
- *   name: "todos",
- *   hooks: [auth.optional()],
- *   routes: [
- *     { contract: listTodos, useCase: listTodosUseCase },
- *   ]
- * });
- * ```
- */
-export function defineRouteGroup() {
-    const createGroup = (input) => ({
-        kind: ROUTE_GROUP_KIND,
-        name: input.name,
-        hooks: input.hooks,
-        routes: input.routes,
-    });
-    return createGroup;
-}
-function isRouteGroup(route) {
-    return (typeof route === "object" &&
-        route !== null &&
-        "kind" in route &&
-        route.kind === ROUTE_GROUP_KIND);
-}
 //# sourceMappingURL=server.js.map