@beignet/core 0.0.1

package/dist/server/server.js

@@ -0,0 +1,1031 @@
+import { BEIGNET_ERROR_OWNER_HEADER, getContractHeaderSchemas, methodSupportsRequestBody, parsePathTemplate, } from "../contracts";
+import { createErrorResponseBody, isAppError, isErrorResponseBody, toErrorResponseBody, } from "../errors";
+import { AuthUnauthorizedError, GateAuthorizationError } from "../ports";
+import { resolveContract } from "./contract-like";
+import { getRequestIdFromContext } from "./hooks/utils";
+import { loadProviderConfig, parseStandardSchema, SchemaValidationError, } from "./providers";
+const ROUTE_GROUP_KIND = "beignet.route-group";
+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 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),
+    };
+}
+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 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: `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(contract, res) {
+    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(contract, res) {
+    const normalized = normalizeResponse(res);
+    await validateResponseAgainstContract(contract, normalized);
+    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,
+        }),
+    };
+}
+async function parseBody(req) {
+    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 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(
+// biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
+options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
+    const compiled = compilePath(contract.path);
+    return async (req, preMatchedParams) => {
+        let baseCtx;
+        let pathValue;
+        let queryValue;
+        let headersValue;
+        let bodyValue;
+        const startedAt = Date.now();
+        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,
+                        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;
+            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, allowRetry) => {
+                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;
+            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;
+                    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: {},
+                                    query: {},
+                                    headers: rawHeaders,
+                                    body: undefined,
+                                })),
+                                owner: "framework",
+                            };
+                        }
+                        catch (error) {
+                            result = await resolveErrorResult(error, createdCtx, undefined, undefined, undefined, undefined, { owner: "framework" });
+                        }
+                    }
+                }
+                else {
+                    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 =
+                                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.message),
+                                        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 =
+                                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.message),
+                                        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 =
+                                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.message),
+                                        owner: "framework",
+                                    };
+                        }
+                    }
+                    // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
+                    let body;
+                    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.message),
+                                            owner: "framework",
+                                        };
+                            }
+                        }
+                    }
+                    if (!result) {
+                        pathValue = path;
+                        queryValue = query;
+                        headersValue = headers;
+                        bodyValue = body;
+                        let createdCtx;
+                        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 = {
+                                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(options) {
+    const registry = [];
+    const providers = (options.providers ?? []);
+    const env = options.providerEnv ?? process.env;
+    const overrides = options.providerConfig ?? {};
+    const providerResults = [];
+    const finalPorts = { ...options.ports };
+    const hooks = [...(options.hooks ?? [])];
+    const contracts = options.routes ? contractsFromRoutes(options.routes) : [];
+    let stopped = false;
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        const errors = [];
+        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();
+    const registeredShapes = new Map();
+    const registerRoute = (contract, handler) => {
+        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 };
+                }
+                const match = compiled.pattern.exec(pathname);
+                if (!match)
+                    return { matched: false };
+                return { matched: true };
+            },
+        });
+        registry.sort((a, b) => compareRouteSpecificity(a.compiled, b.compiled));
+    };
+    const createBuilder = (contract, shouldRegister) => ({
+        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) => {
+        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 = {
+            kind: "http",
+            name: "notFound",
+            method: req.method.toUpperCase(),
+            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(routes) {
+    const flattened = [];
+    for (const route of routes) {
+        if (isRouteGroup(route)) {
+            flattened.push(...route.routes);
+        }
+        else {
+            flattened.push(route);
+        }
+    }
+    return flattened;
+}
+/**
+ * Extract contract configs from a route list. Use this to drive OpenAPI from
+ * the same route registration list that createServer receives.
+ */
+export function contractsFromRoutes(routes) {
+    return routes.map((route) => resolveContract(route.contract));
+}
+/**
+ * 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(group) {
+    return {
+        kind: ROUTE_GROUP_KIND,
+        name: group.name,
+        routes: group.routes,
+    };
+}
+function isRouteGroup(route) {
+    return (typeof route === "object" &&
+        route !== null &&
+        "kind" in route &&
+        route.kind === ROUTE_GROUP_KIND);
+}
+//# sourceMappingURL=server.js.map