@mupt-ai/dari-gateway 0.2.0 → 0.3.0

package/dist/context/routing_context.js

@@ -0,0 +1,211 @@
+import { prepareCandidates, } from "@mupt-ai/dari-router/policy-engine";
+import { randomUUID } from "node:crypto";
+import { HttpError } from "../http/errors.js";
+import { effectiveContextWindow } from "../models/context_limits.js";
+import { keySourceForModel } from "../models/execution_provider.js";
+import { requiredCapabilitiesFor } from "../interaction/capabilities.js";
+import { providerIdentityFromModel } from "../interaction/provider_continuation_state.js";
+import { isBackgroundRequest } from "../interaction/types.js";
+import { requireCandidateModels } from "../models/ids.js";
+import { modelMetadataLookup } from "../providers/pi.js";
+import { modelSupportsImageInput, modelSupportsHostedWebSearch, modelSupportsReasoningConfigurationUpdate, providerApiCanSerializeResponseFormat, } from "../providers/model_capabilities.js";
+import { selectorMessagesForInteraction, } from "../strategies/selector_projection.js";
+import { interactionPrefixContext, interactionPrefixLookupHashes, } from "./interaction_fingerprint.js";
+import { pricingLookupForRouter } from "./pricing.js";
+import { providerPromptAccounting } from "./provider_prompt_accounting.js";
+import { leaseHistoryFromPrefixHits } from "./lease_history.js";
+import { interactionLeaseFenceDepth } from "./interaction_lease_depth.js";
+// Router resolution only needs lookup hashes. Model-specific chains are
+// derived after resolve, when the enabled providers and APIs are known.
+export function derivePrefixLookupHashes(routerId, interaction) {
+    try {
+        return interactionPrefixLookupHashes(routerId, interaction);
+    }
+    catch (error) {
+        console.error("prefix fingerprinting failed", error);
+        return [];
+    }
+}
+export async function buildRoutingContext(args) {
+    const configuredCandidateModels = requireCandidateModels(args.credentials.enabled_models);
+    // With credits exhausted, route only among models a personal subscription
+    // serves. The credit gate refuses routers with none.
+    const fundedCandidateModels = args.credentials.credit_exhausted
+        ? configuredCandidateModels.filter((model) => keySourceForModel(args.credentials, model) === "subscription")
+        : configuredCandidateModels;
+    const { messages: selectorMessages, images: selectorImages } = selectorMessagesForInteraction(args.interaction, {
+        imageInput: args.credentials.selector_image_input_enabled === true,
+    });
+    const leaseDepth = interactionLeaseFenceDepth(args.interaction);
+    const metadataLookup = modelMetadataLookup(args.credentials.model_configs);
+    const targetsByModel = new Map();
+    for (const model of configuredCandidateModels) {
+        targetsByModel.set(model, providerIdentityFromModel(metadataLookup(model).model));
+    }
+    const capabilityLookup = (modelId) => {
+        const metadata = metadataLookup(modelId);
+        return {
+            provider: typeof metadata.model.provider === "string" ? metadata.model.provider : "",
+            api: typeof metadata.model.api === "string" ? metadata.model.api : "",
+            supportsImageInput: modelSupportsImageInput(metadata),
+            supportsHostedWebSearch: modelSupportsHostedWebSearch(metadata),
+            supportsReasoningConfigurationUpdate: modelSupportsReasoningConfigurationUpdate(metadata),
+            supportsStructuredOutput: providerApiCanSerializeResponseFormat(metadata),
+            supportedThinkingLevels: metadata.supportedThinkingLevels,
+        };
+    };
+    // Image capability filtering (router setting, absent = ON) narrows the
+    // candidate set before strategy resolution — an image-bearing conversation
+    // must not route (or hold a lease) to a text-only model. Prefix chains and
+    // provider accounting still cover every configured model.
+    const imageFilter = resolveImageCapableCandidates({
+        candidateModels: fundedCandidateModels.length > 0 ? fundedCandidateModels : configuredCandidateModels,
+        requiredCapabilities: requiredCapabilitiesFor(args.interaction),
+        enabled: args.credentials.image_capability_filtering !== false,
+        supportsImageInput: (model) => capabilityLookup(model).supportsImageInput,
+    });
+    const prefix = derivePrefixContext({
+        routerId: args.routerId,
+        interaction: args.interaction,
+        targetsByModel,
+    });
+    const promptAccounting = providerPromptAccounting({
+        request: args.interaction,
+        prefix,
+        targetsByModel,
+    });
+    const pricing = pricingLookupForRouter(args.credentials);
+    // A validated harness identity is authoritative. Matching text from another
+    // thread must not contribute cache warmth or selector continuity.
+    const background = isBackgroundRequest(args.interaction);
+    const prefixHits = (background ? [] : args.credentials.prefix_hits ?? []).filter((hit) => args.explicitConversationId === undefined
+        || hit.conversation_id === args.explicitConversationId);
+    const prepared = prepareCandidates({
+        candidateModels: imageFilter.candidateModels,
+        metadataLookup: capabilityLookup,
+        requiredCapabilities: imageFilter.requiredCapabilities,
+        requestedReasoningEffort: args.interaction.reasoning?.effort,
+        thinkingEnabled: args.interaction.reasoning?.enabled === true,
+        toolChoice: args.interaction.toolChoice,
+        modelThinkingLevels: args.credentials.model_thinking_levels,
+        strategy: args.credentials.routing_strategy === "custom" ? "custom" : "dari",
+        customConfig: args.credentials.custom_config,
+        modelPrices: args.credentials.model_prices ?? {},
+        pricing,
+        promptTokenLimitFor: (model) => effectiveContextWindow(args.credentials.model_configs?.[model], args.credentials.allow_long_context === true),
+        requiresPromptEstimateFor: (model) => args.credentials.allow_long_context !== true
+            && args.credentials.model_configs?.[model]?.standard_context_limit != null,
+        averageOutputTokensByModel: Object.fromEntries(Object.entries(args.credentials.model_configs ?? {}).map(([model, config]) => [
+            model,
+            config.average_output_tokens ?? null,
+        ])),
+        promptAccounting,
+        chainsByModel: prefix.chainByModel,
+        // Resolve returns hits up to the platform's conversation lookback;
+        // core narrows them to the warmth window for cost estimation and keeps the
+        // rest for conversation identity and the previous decision.
+        prefixHits,
+        nowMs: (args.receivedAt ?? new Date()).getTime(),
+        looseChain: prefix.looseChain,
+        conversationId: args.explicitConversationId,
+        toolChoiceFp: prefix.fingerprints.tool_choice_fp,
+        responseFormatFp: prefix.fingerprints.response_format_fp,
+        previousDecision: background ? undefined : args.previousDecision,
+    });
+    for (const warning of prepared.warnings) {
+        console.error("cache cost estimation failed", warning.error);
+    }
+    const conversationId = args.explicitConversationId
+        ?? prepared.conversationId
+        ?? randomUUID();
+    // A harness identity always produces an explicit conversation id, so it
+    // cannot distinguish a brand-new session from a recovered one on its own.
+    // Prefix lookup is already scoped to that id; no recovered conversation
+    // therefore means this is its first observed turn.
+    const isNewConversation = prepared.conversationId === null;
+    // Lease context (router setting, absent = ON) feeds the selector the
+    // original task and reconstructed lease history. Disabled routers skip the
+    // reconstruction entirely so their selector inputs stay byte-identical to
+    // the pre-lease-context behavior.
+    const leaseHistory = !background && args.credentials.lease_context_enabled !== false
+        ? leaseHistoryFromPrefixHits({
+            prefixHits,
+            conversationId,
+            candidates: prepared.candidateResolution.candidates,
+            messages: selectorMessages,
+        })
+        : undefined;
+    return {
+        leaseDepth,
+        hits: prepared.hits,
+        reportingCostEstimates: prepared.costEstimates,
+        ...(prepared.previousDecision !== undefined
+            ? { previousDecision: prepared.previousDecision }
+            : {}),
+        ...(prepared.activeLease !== undefined ? { activeLease: prepared.activeLease } : {}),
+        ...(prepared.pendingLease !== undefined ? { pendingLease: prepared.pendingLease } : {}),
+        pricing,
+        conversationId,
+        isNewConversation,
+        identityMatchDepth: prepared.identityMatchDepth,
+        ...(prepared.identityHit !== undefined
+            ? { identityHit: prepared.identityHit }
+            : {}),
+        zdr: args.credentials.zdr === true,
+        candidateResolution: prepared.candidateResolution,
+        ...(imageFilter.prunedModels.length > 0
+            ? { imageCapabilityPrunedModels: imageFilter.prunedModels }
+            : {}),
+        prefix,
+        targetsByModel,
+        selectorMessages,
+        selectorImages,
+        ...(leaseHistory !== undefined ? { leaseHistory } : {}),
+        providerBlockDepthFor: promptAccounting.providerBlockDepthFor,
+    };
+}
+// When the filter is disabled, "image_input" is also dropped from the hard
+// capabilities so core preparation keeps today's pass-through behavior instead
+// of re-applying the same exclusion. When enabled, the capability stays as a
+// core-side invariant over the already-narrowed set.
+function resolveImageCapableCandidates(args) {
+    if (!args.requiredCapabilities.includes("image_input")) {
+        return {
+            candidateModels: args.candidateModels,
+            requiredCapabilities: args.requiredCapabilities,
+            prunedModels: [],
+        };
+    }
+    if (!args.enabled) {
+        return {
+            candidateModels: args.candidateModels,
+            requiredCapabilities: args.requiredCapabilities.filter((capability) => capability !== "image_input"),
+            prunedModels: [],
+        };
+    }
+    const capable = args.candidateModels.filter(args.supportsImageInput);
+    if (capable.length === 0) {
+        throw new HttpError(400, "This conversation contains image input, but no enabled model on this router accepts images.", "no_image_capable_candidates");
+    }
+    return {
+        candidateModels: capable,
+        requiredCapabilities: args.requiredCapabilities,
+        prunedModels: args.candidateModels
+            .filter((model) => !args.supportsImageInput(model))
+            .map((model) => ({ model, reason: "image_input_unsupported" })),
+    };
+}
+function derivePrefixContext(args) {
+    try {
+        return interactionPrefixContext(args.routerId, args.interaction, args.targetsByModel);
+    }
+    catch (error) {
+        console.error("prefix fingerprinting failed", error);
+        return {
+            chainByModel: new Map([...args.targetsByModel].map(([model]) => [model, []])),
+            itemIndexByHashByModel: new Map([...args.targetsByModel].map(([model]) => [model, new Map()])),
+            looseChain: [],
+            fingerprints: { tool_choice_fp: "", response_format_fp: "" },
+        };
+    }
+}

package/dist/http/auth.d.ts

@@ -0,0 +1,2 @@
+export declare function bearerToken(headers: Headers): string;
+export declare function anthropicToken(headers: Headers): string;

package/dist/http/auth.js

@@ -0,0 +1,35 @@
+import { timingSafeEqual } from "node:crypto";
+import { HttpError } from "./errors.js";
+export function bearerToken(headers) {
+    const value = headers.get("authorization") ?? "";
+    const [scheme, token] = value.split(/\s+/, 2);
+    if (scheme?.toLowerCase() !== "bearer" || !token) {
+        throw new HttpError(401, "Missing or invalid routing API key.", "authentication_error");
+    }
+    return publicRoutingToken(token);
+}
+export function anthropicToken(headers) {
+    const authorization = headers.get("authorization");
+    if (authorization)
+        return bearerToken(headers);
+    const apiKey = headers.get("x-api-key");
+    if (!apiKey) {
+        throw new HttpError(401, "Missing or invalid routing API key.", "authentication_error");
+    }
+    return publicRoutingToken(apiKey);
+}
+function publicRoutingToken(token) {
+    const internalToken = process.env.DARI_ROUTING_INTERNAL_TOKEN;
+    if (internalToken && matchesInternalToken(token, internalToken)) {
+        throw new HttpError(401, "Internal routing credentials cannot authorize public inference.", "authentication_error");
+    }
+    return token;
+}
+function matchesInternalToken(token, internalToken) {
+    // Compare byte lengths, not character counts: timingSafeEqual throws on
+    // buffers of different sizes, and a multi-byte character can match the
+    // secret's character count without matching its byte length.
+    const candidate = Buffer.from(token);
+    const expected = Buffer.from(internalToken);
+    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,19 @@
+import { RouterCoreError } from "@mupt-ai/dari-router/policy-engine";
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly param?: string;
+    readonly headers?: Record<string, string>;
+    constructor(status: number, message: string, code?: string, param?: string, headers?: Record<string, string>);
+}
+export declare function errorResponseHeaders(error: unknown): Record<string, string>;
+export declare function httpErrorFrom(error: RouterCoreError): HttpError;
+export declare function rethrowFrameworkErrorAsHttp(error: unknown, status: number): never;
+export declare function errorCode(error: unknown, fallback: string): string;
+export declare function errorResponse(error: unknown): Response;
+export declare function normalizeError(error: unknown): {
+    status: number;
+    message: string;
+    code: string;
+    param?: string;
+};

package/dist/http/errors.js

@@ -0,0 +1,89 @@
+import { RouterFrameworkError } from "@mupt-ai/dari-router";
+import { RouterCoreError } from "@mupt-ai/dari-router/policy-engine";
+export class HttpError extends Error {
+    status;
+    code;
+    param;
+    // Response headers the error carries to the client, such as retry-after.
+    headers;
+    constructor(status, message, code = "invalid_request_error", param, headers) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.param = param;
+        this.headers = headers;
+    }
+}
+export function errorResponseHeaders(error) {
+    return error instanceof HttpError && error.headers ? error.headers : {};
+}
+// @mupt-ai/dari-router is transport-agnostic; its error kinds map onto the HTTP
+// statuses this service always used for the same conditions.
+const CORE_ERROR_STATUS = {
+    invalid_request: 400,
+    selector_output: 502,
+    configuration: 500,
+};
+export function httpErrorFrom(error) {
+    return new HttpError(CORE_ERROR_STATUS[error.kind], error.message, error.code, error.param);
+}
+export function rethrowFrameworkErrorAsHttp(error, status) {
+    throw error instanceof RouterFrameworkError
+        ? new HttpError(status, error.message, error.code, error.param)
+        : error;
+}
+// Error code for logging/telemetry, covering both transport and core errors.
+export function errorCode(error, fallback) {
+    if (error instanceof HttpError
+        || error instanceof RouterCoreError
+        || error instanceof RouterFrameworkError) {
+        return error.code;
+    }
+    return fallback;
+}
+export function errorResponse(error) {
+    const normalized = normalizeError(error);
+    return Response.json({
+        error: {
+            message: normalized.message,
+            type: openAiErrorType(normalized.status),
+            code: normalized.code,
+            ...(normalized.param ? { param: normalized.param } : {}),
+        },
+    }, { status: normalized.status, headers: errorResponseHeaders(error) });
+}
+function openAiErrorType(status) {
+    if (status === 429)
+        return "rate_limit_error";
+    return status >= 500 ? "server_error" : "invalid_request_error";
+}
+export function normalizeError(error) {
+    if (error instanceof HttpError) {
+        return {
+            status: error.status,
+            message: error.message,
+            code: error.code,
+            param: error.param,
+        };
+    }
+    if (error instanceof RouterCoreError) {
+        return {
+            status: CORE_ERROR_STATUS[error.kind],
+            message: error.message,
+            code: error.code,
+            param: error.param,
+        };
+    }
+    if (error instanceof RouterFrameworkError) {
+        return {
+            status: error.status,
+            message: error.message,
+            code: error.code,
+            param: error.param,
+        };
+    }
+    if (error instanceof Error) {
+        return { status: 500, message: error.message, code: "internal_error" };
+    }
+    return { status: 500, message: "Internal server error", code: "internal_error" };
+}

package/dist/http/handler.d.ts

@@ -0,0 +1,12 @@
+import { type GatewayPlatform } from "../platform/platform.js";
+import type { SelectorBackend } from "../strategies/routing.js";
+export type GatewayHandlerOptions = {
+    platform: GatewayPlatform;
+    selectorBackend: SelectorBackend;
+};
+/**
+ * The gateway's routed HTTP surface: `/v1/{chat/completions,responses,
+ * messages,models}` on the default router and `/{router_id}/v1/...` on a
+ * named one. Binds `options.platform` for every request it serves.
+ */
+export declare function createRequestHandler(options: GatewayHandlerOptions): (request: Request) => Promise<Response>;

package/dist/http/handler.js

@@ -0,0 +1,88 @@
+import { handleResponses, handleResponsesWebSocketFallback, } from "../ingress/codex.js";
+import { handleModels } from "../ingress/models.js";
+import { handleMuseCodeModels } from "../ingress/muse_models.js";
+import { handleChatCompletions } from "../ingress/chat_completions.js";
+import { handleAnthropicMessages } from "../ingress/anthropic_messages.js";
+import { bindGatewayPlatform } from "../platform/platform.js";
+import { DEFAULT_ROUTER_ALIAS } from "../platform/routing_contract.js";
+import { errorResponse, HttpError } from "./errors.js";
+/**
+ * The gateway's routed HTTP surface: `/v1/{chat/completions,responses,
+ * messages,models}` on the default router and `/{router_id}/v1/...` on a
+ * named one. Binds `options.platform` for every request it serves.
+ */
+export function createRequestHandler(options) {
+    const { selectorBackend } = options;
+    bindGatewayPlatform(options.platform);
+    return async function handleRequest(request) {
+        const url = new URL(request.url);
+        if (request.method === "GET" &&
+            (url.pathname === "/healthz" || url.pathname === "/health")) {
+            return Response.json({ status: "ok" });
+        }
+        // Muse Code reads its model list from its base URL's origin; `dari muse`
+        // forwards it to the router's own path.
+        const museModels = url.pathname.match(/^(?:\/([^/]+))?\/muse-code\/models$/);
+        if (request.method === "GET" && museModels !== null) {
+            return await handleMuseCodeModels(request, museModels[1] ?? DEFAULT_ROUTER_ALIAS);
+        }
+        // Claude Code probes this first-party endpoint before its Messages call
+        // when ANTHROPIC_BASE_URL points at a compatible gateway.
+        if (request.method === "HEAD" && url.pathname === "/api/hello") {
+            return new Response(null, { status: 200 });
+        }
+        const endpoint = routedEndpoint(url.pathname);
+        if (endpoint?.protocol === "chat" && request.method === "POST") {
+            return await handleChatCompletions(request, endpoint.routerId, selectorBackend);
+        }
+        if (endpoint?.protocol === "responses") {
+            if (request.method === "GET")
+                return handleResponsesWebSocketFallback();
+            if (request.method === "POST") {
+                return await handleResponses(request, endpoint.routerId, selectorBackend);
+            }
+        }
+        if (endpoint?.protocol === "messages" && request.method === "POST") {
+            return await handleAnthropicMessages(request, endpoint.routerId, selectorBackend);
+        }
+        if (endpoint?.protocol === "models" && request.method === "GET") {
+            return await handleModels(request, endpoint.routerId);
+        }
+        return errorResponse(new HttpError(404, "Not found", "not_found"));
+    };
+}
+function routedEndpoint(pathname) {
+    const defaultProtocol = protocolForSuffix(pathname, "/v1");
+    if (defaultProtocol !== null) {
+        return { routerId: DEFAULT_ROUTER_ALIAS, protocol: defaultProtocol };
+    }
+    const match = pathname.match(/^\/([^/]+)(?:\/v1)?\/(chat\/completions|responses|messages|models)$/);
+    if (match === null)
+        return null;
+    return {
+        routerId: match[1],
+        protocol: protocolForRoute(match[2]),
+    };
+}
+function protocolForSuffix(pathname, prefix) {
+    if (pathname === `${prefix}/chat/completions`)
+        return "chat";
+    if (pathname === `${prefix}/responses`)
+        return "responses";
+    if (pathname === `${prefix}/messages`)
+        return "messages";
+    if (pathname === `${prefix}/models`)
+        return "models";
+    return null;
+}
+function protocolForRoute(route) {
+    if (route === "chat/completions")
+        return "chat";
+    if (route === "responses")
+        return "responses";
+    if (route === "messages")
+        return "messages";
+    if (route === "models")
+        return "models";
+    throw new Error(`Unsupported routed endpoint: ${route}`);
+}

package/dist/http/http2_server.d.ts

@@ -0,0 +1,6 @@
+export type Http2RequestHandler = (request: Request) => Response | Promise<Response>;
+export type Http2RoutingServer = {
+    readonly port: number;
+    stop(force?: boolean): Promise<void>;
+};
+export declare function startHttp2Server(port: number, handler: Http2RequestHandler): Http2RoutingServer;

package/dist/http/http2_server.js

@@ -0,0 +1,103 @@
+import { createServer, } from "node:http2";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+const HTTP2_FORBIDDEN_RESPONSE_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "upgrade",
+]);
+export function startHttp2Server(port, handler) {
+    const sessions = new Set();
+    let closePromise;
+    const server = createServer((request, response) => {
+        void handleRequest(request, response, handler);
+    });
+    server.on("session", (session) => {
+        sessions.add(session);
+        session.once("close", () => sessions.delete(session));
+    });
+    server.listen(port, "0.0.0.0");
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("HTTP/2 routing server did not bind to a TCP port.");
+    }
+    return {
+        port: address.port,
+        stop(force = false) {
+            for (const session of sessions) {
+                if (force)
+                    session.destroy();
+                else
+                    session.close();
+            }
+            closePromise ??= new Promise((resolve, reject) => {
+                server.close((error) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                });
+            });
+            return closePromise;
+        },
+    };
+}
+async function handleRequest(incoming, outgoing, handler) {
+    const abort = new AbortController();
+    incoming.once("aborted", () => abort.abort());
+    outgoing.once("close", () => {
+        if (!outgoing.writableEnded)
+            abort.abort();
+    });
+    try {
+        const response = await handler(toRequest(incoming, abort.signal));
+        outgoing.statusCode = response.status;
+        for (const [name, value] of response.headers) {
+            if (!HTTP2_FORBIDDEN_RESPONSE_HEADERS.has(name.toLowerCase())) {
+                outgoing.setHeader(name, value);
+            }
+        }
+        if (response.body === null || incoming.method === "HEAD") {
+            outgoing.end();
+            return;
+        }
+        await pipeline(Readable.fromWeb(response.body), outgoing);
+    }
+    catch (error) {
+        if (abort.signal.aborted || outgoing.destroyed)
+            return;
+        console.error("routing HTTP/2 request failed", error);
+        if (outgoing.headersSent) {
+            outgoing.destroy();
+            return;
+        }
+        outgoing.statusCode = 500;
+        outgoing.setHeader("content-type", "application/json");
+        outgoing.end(JSON.stringify({ error: { message: "Internal server error." } }));
+    }
+}
+function toRequest(incoming, signal) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(incoming.headers)) {
+        if (name.startsWith(":"))
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(name, item);
+        }
+        else if (value !== undefined) {
+            headers.set(name, value);
+        }
+    }
+    const method = incoming.method ?? "GET";
+    const hasBody = method !== "GET" && method !== "HEAD";
+    return new Request(`${incoming.scheme ?? "http"}://${incoming.authority ?? "localhost"}${incoming.url}`, {
+        method,
+        headers,
+        body: hasBody ? Readable.toWeb(incoming) : undefined,
+        signal,
+        duplex: hasBody ? "half" : undefined,
+    });
+}

package/dist/http/serve.d.ts

@@ -0,0 +1,20 @@
+type StoppableServer = {
+    stop(force?: boolean): Promise<void>;
+};
+export declare function startServer(listenPort: number, handler: (request: Request) => Promise<Response>, options?: {
+    http2?: boolean;
+}): import("./http2_server.js").Http2RoutingServer | Bun.Server<undefined>;
+/**
+ * On SIGTERM/SIGINT: stop accepting work, let active requests finish, drain
+ * background reporting within the shutdown budget, run `closeClients`, exit.
+ */
+export declare function installShutdownHandlers(server: StoppableServer, closeClients: () => Promise<unknown>): void;
+/**
+ * stop(false) refuses new work and lets active requests finish; if that does
+ * not settle in time, one stop(true) destroys what is left so stream
+ * cancellation registers its finalizers before the background drain starts.
+ * Both calls are bounded: a hung stop promise must not consume the shutdown
+ * budget.
+ */
+export declare function stopServerForShutdown(server: StoppableServer, gracefulTimeoutMs?: number, forceStopSettleTimeoutMs?: number): Promise<void>;
+export {};

package/dist/http/serve.js

@@ -0,0 +1,78 @@
+import { captureOperationalError } from "../observability/errors.js";
+import { drainBackgroundTelemetryFor } from "../telemetry/background.js";
+import { startHttp2Server } from "./http2_server.js";
+const GRACEFUL_SERVER_STOP_TIMEOUT_MS = 5_000;
+const FORCE_STOP_SETTLE_TIMEOUT_MS = 250;
+// Container platforms commonly send SIGKILL 10 seconds after SIGTERM. Reserve
+// the final 2 seconds for closing telemetry clients and 500ms for process
+// scheduling.
+const SHUTDOWN_WORK_TIMEOUT_MS = 7_500;
+export function startServer(listenPort, handler, options = {}) {
+    if (options.http2) {
+        return startHttp2Server(listenPort, handler);
+    }
+    // The selector runs before the first response byte, and routed models can
+    // remain silent while reasoning. Disable Bun's default 10s idle timeout;
+    // clients and infrastructure still bound total request lifetime.
+    return Bun.serve({
+        port: listenPort,
+        fetch: handler,
+        idleTimeout: 0,
+    });
+}
+/**
+ * On SIGTERM/SIGINT: stop accepting work, let active requests finish, drain
+ * background reporting within the shutdown budget, run `closeClients`, exit.
+ */
+export function installShutdownHandlers(server, closeClients) {
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        const workDeadlineAtMs = performance.now() + SHUTDOWN_WORK_TIMEOUT_MS;
+        console.info("routing server shutting down", JSON.stringify({ signal }));
+        try {
+            await stopServerForShutdown(server);
+        }
+        finally {
+            const remaining = await drainBackgroundTelemetryFor(Math.max(0, workDeadlineAtMs - performance.now()));
+            if (remaining > 0) {
+                console.warn("routing server background drain timed out", JSON.stringify({ remaining_task_count: remaining }));
+                captureOperationalError(new Error(`Routing shutdown abandoned ${remaining} background task(s).`), { code: "background_drain_timeout" });
+            }
+            await closeClients();
+            process.exit(0);
+        }
+    };
+    process.once("SIGTERM", () => void shutdown("SIGTERM"));
+    process.once("SIGINT", () => void shutdown("SIGINT"));
+}
+/**
+ * stop(false) refuses new work and lets active requests finish; if that does
+ * not settle in time, one stop(true) destroys what is left so stream
+ * cancellation registers its finalizers before the background drain starts.
+ * Both calls are bounded: a hung stop promise must not consume the shutdown
+ * budget.
+ */
+export async function stopServerForShutdown(server, gracefulTimeoutMs = GRACEFUL_SERVER_STOP_TIMEOUT_MS, forceStopSettleTimeoutMs = FORCE_STOP_SETTLE_TIMEOUT_MS) {
+    if ((await stopWithin(server, false, gracefulTimeoutMs)) !== "timed_out") {
+        return;
+    }
+    if ((await stopWithin(server, true, forceStopSettleTimeoutMs)) === "timed_out") {
+        reportServerStopFailure(new Error("Routing server force-stop settlement timed out."));
+    }
+}
+function stopWithin(server, force, timeoutMs) {
+    return Promise.race([
+        new Promise((resolve) => resolve(server.stop(force))).then(() => "stopped", (error) => {
+            reportServerStopFailure(error);
+            return "failed";
+        }),
+        Bun.sleep(timeoutMs).then(() => "timed_out"),
+    ]);
+}
+function reportServerStopFailure(error) {
+    console.warn("routing server shutdown failed", error instanceof Error ? error.name : "UnknownError");
+    captureOperationalError(error, { code: "server_force_stop_failed" });
+}