@mupt-ai/dari-gateway 0.0.0-stage → 0.2.0

package/src/http/errors.ts

@@ -0,0 +1,114 @@
+import { RouterFrameworkError } from "@mupt-ai/dari-router";
+import { RouterCoreError } from "@mupt-ai/dari-router/policy-engine";
+
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly param?: string;
+  // Response headers the error carries to the client, such as retry-after.
+  readonly headers?: Record<string, string>;
+
+  constructor(
+    status: number,
+    message: string,
+    code = "invalid_request_error",
+    param?: string,
+    headers?: Record<string, string>,
+  ) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.param = param;
+    this.headers = headers;
+  }
+}
+
+export function errorResponseHeaders(error: unknown): Record<string, string> {
+  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: Record<RouterCoreError["kind"], number> = {
+  invalid_request: 400,
+  selector_output: 502,
+  configuration: 500,
+};
+
+export function httpErrorFrom(error: RouterCoreError): HttpError {
+  return new HttpError(CORE_ERROR_STATUS[error.kind], error.message, error.code, error.param);
+}
+
+export function rethrowFrameworkErrorAsHttp(error: unknown, status: number): never {
+  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: unknown, fallback: string): string {
+  if (
+    error instanceof HttpError
+    || error instanceof RouterCoreError
+    || error instanceof RouterFrameworkError
+  ) {
+    return error.code;
+  }
+  return fallback;
+}
+
+export function errorResponse(error: unknown): Response {
+  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: number): string {
+  if (status === 429) return "rate_limit_error";
+  return status >= 500 ? "server_error" : "invalid_request_error";
+}
+
+export function normalizeError(error: unknown): {
+  status: number;
+  message: string;
+  code: string;
+  param?: string;
+} {
+  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/src/http/handler.ts

@@ -0,0 +1,110 @@
+import {
+  handleResponses,
+  handleResponsesWebSocketFallback,
+} from "../ingress/codex";
+import { handleModels } from "../ingress/models";
+import { handleChatCompletions } from "../ingress/chat_completions";
+import { handleAnthropicMessages } from "../ingress/anthropic_messages";
+import { bindGatewayPlatform, type GatewayPlatform } from "../platform/platform";
+import { DEFAULT_ROUTER_ALIAS } from "../platform/routing_contract";
+import type { SelectorBackend } from "../strategies/routing";
+import { errorResponse, HttpError } from "./errors";
+
+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 function createRequestHandler(options: GatewayHandlerOptions) {
+  const { selectorBackend } = options;
+  bindGatewayPlatform(options.platform);
+  return async function handleRequest(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    if (
+      request.method === "GET" &&
+      (url.pathname === "/healthz" || url.pathname === "/health")
+    ) {
+      return Response.json({ status: "ok" });
+    }
+    // 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"));
+  };
+}
+
+type RoutedEndpoint = {
+  routerId: string;
+  protocol: "chat" | "responses" | "messages" | "models";
+};
+
+function routedEndpoint(pathname: string): RoutedEndpoint | null {
+  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: string,
+  prefix: string,
+): RoutedEndpoint["protocol"] | null {
+  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: string): RoutedEndpoint["protocol"] {
+  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/src/http/http2_server.ts

@@ -0,0 +1,122 @@
+import {
+  createServer,
+  type Http2ServerRequest,
+  type Http2ServerResponse,
+  type ServerHttp2Session,
+} from "node:http2";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+
+export type Http2RequestHandler = (request: Request) => Response | Promise<Response>;
+
+export type Http2RoutingServer = {
+  readonly port: number;
+  stop(force?: boolean): Promise<void>;
+};
+
+const HTTP2_FORBIDDEN_RESPONSE_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-connection",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+export function startHttp2Server(port: number, handler: Http2RequestHandler): Http2RoutingServer {
+  const sessions = new Set<ServerHttp2Session>();
+  let closePromise: Promise<void> | undefined;
+  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): Promise<void> {
+      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: Http2ServerRequest,
+  outgoing: Http2ServerResponse,
+  handler: Http2RequestHandler,
+): Promise<void> {
+  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 as unknown as NodeReadableStream),
+      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: Http2ServerRequest, signal: AbortSignal): Request {
+  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,
+    } as RequestInit & { duplex?: "half" },
+  );
+}

package/src/http/serve.ts

@@ -0,0 +1,119 @@
+import { captureOperationalError } from "../observability/errors";
+import { drainBackgroundTelemetryFor } from "../telemetry/background";
+import { startHttp2Server } from "./http2_server";
+
+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;
+
+type StoppableServer = {
+  stop(force?: boolean): Promise<void>;
+};
+
+export function startServer(
+  listenPort: number,
+  handler: (request: Request) => Promise<Response>,
+  options: { http2?: boolean } = {},
+) {
+  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: StoppableServer,
+  closeClients: () => Promise<unknown>,
+): void {
+  let shuttingDown = false;
+  const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
+    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: StoppableServer,
+  gracefulTimeoutMs: number = GRACEFUL_SERVER_STOP_TIMEOUT_MS,
+  forceStopSettleTimeoutMs: number = FORCE_STOP_SETTLE_TIMEOUT_MS,
+): Promise<void> {
+  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: StoppableServer,
+  force: boolean,
+  timeoutMs: number,
+): Promise<"stopped" | "failed" | "timed_out"> {
+  return Promise.race([
+    new Promise<void>((resolve) => resolve(server.stop(force))).then(
+      () => "stopped" as const,
+      (error: unknown) => {
+        reportServerStopFailure(error);
+        return "failed" as const;
+      },
+    ),
+    Bun.sleep(timeoutMs).then(() => "timed_out" as const),
+  ]);
+}
+
+function reportServerStopFailure(error: unknown): void {
+  console.warn(
+    "routing server shutdown failed",
+    error instanceof Error ? error.name : "UnknownError",
+  );
+  captureOperationalError(error, { code: "server_force_stop_failed" });
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// Public entry points. Every module is also importable by path
+// (`@mupt-ai/dari-gateway/<dir>/<module>`) for deployments that compose the
+// gateway with their own platform. This entry needs no Bun APIs; the Bun
+// server and the SQLite-backed self-hosted gateway live in `./bun`.
+export { createRequestHandler, type GatewayHandlerOptions } from "./http/handler";
+export type {
+  GatewayPlatform,
+  OperationalErrorContext,
+  PendingLeaseWrite,
+  PrefixStateWrite,
+  ProviderCredentialRequest,
+  RequestErrorContext,
+  RequestRecord,
+  RequestSummary,
+  RequestTags,
+  ResolveRouterRequest,
+  SubscriptionHold,
+} from "./platform/platform";
+export { createAutoRoutingSelectorBackend } from "./strategies/auto_routing_selector";
+export { createPrioritySelectorBackend } from "./strategies/priority_selector";
+export { createLlmSelectorBackend, type SelectorBackend } from "./strategies/routing";
+export type { ProviderCredential, ResolvedRouter } from "./types";

package/src/ingress/anthropic_messages.ts

@@ -0,0 +1,162 @@
+import { isRecord } from "@mupt-ai/dari-router/policy-engine";
+import { anthropicMessagesResponse } from "../protocol/output/anthropic_messages";
+import { anthropicMessagesSseStream } from "../protocol/output/anthropic_messages_stream";
+import { anthropicToken } from "../http/auth";
+import { errorResponseHeaders, normalizeError } from "../http/errors";
+import { captureRequestError } from "../observability/errors";
+import { anthropicMessagesToInteraction } from "../protocol/input/anthropic_messages";
+import { handleRoutedCompletion } from "../runtime/routed_completion";
+import type { SelectorBackend } from "../strategies/routing";
+import { claudeCodeRequestContext } from "./claude_code/request_context";
+import {
+  claudeCodeConversationIdentity,
+} from "../runtime/harness_identity";
+import { parseJsonRequest } from "./json";
+import type { AnthropicSafeguards } from "../interaction/types";
+
+type AnthropicErrorType =
+  | "authentication_error"
+  | "permission_error"
+  | "not_found_error"
+  | "rate_limit_error"
+  | "api_error"
+  | "invalid_request_error";
+
+const LEGACY_CLAUDE_CODE_BETA = "claude-code-20250219";
+const SAFEGUARDS_BETA_PREFIX = "dangerous-tool-use-";
+
+export async function handleAnthropicMessages(
+  request: Request,
+  routerId: string,
+  selectorBackend: SelectorBackend,
+): Promise<Response> {
+  try {
+    const apiKey = anthropicToken(request.headers);
+    const rawPayload = await parseJsonRequest<Record<string, unknown>>(request);
+    const interaction = anthropicMessagesToInteraction(rawPayload);
+    const isClaudeCode = isClaudeCodeRequest(request.headers);
+    const anthropicSafeguards = safeguardsFrom(rawPayload, request.headers);
+    const forwarded = anthropicSafeguards === undefined
+      ? interaction
+      : { ...interaction, anthropicSafeguards };
+    const payload = isClaudeCode
+      ? {
+          ...forwarded,
+          agentContext: claudeCodeRequestContext(request.headers),
+          // Native tool results may be followed by harness-injected text.
+          // Preserve their structural continuation semantics, not prompt inference.
+          ...(latestMessageHasToolResult(rawPayload.messages)
+            ? { requestPurpose: "tool_continuation" as const } : {}),
+          claudeCodeUserAgent: request.headers.get("user-agent")!.trim(),
+        }
+      : forwarded;
+    return await handleRoutedCompletion({
+      request,
+      routerId,
+      apiKey,
+      payload,
+      responseBody: anthropicMessagesResponse,
+      streamBody: anthropicMessagesSseStream,
+      errorResponse: anthropicErrorResponse,
+      selectorBackend,
+      clientHarness: isClaudeCode ? "claude_code" : undefined,
+      harnessConversationIdentity: isClaudeCode
+        ? claudeCodeConversationIdentity(
+            request.headers,
+            payload.promptCacheKey,
+          )
+        : undefined,
+    });
+  } catch (error) {
+    const response = anthropicErrorResponse(error);
+    captureRequestError(error, {
+      request,
+      routerId,
+      sourceProtocol: "anthropic_messages",
+      status: response.status,
+    });
+    return response;
+  }
+}
+
+function latestMessageHasToolResult(messages: unknown): boolean {
+  if (!Array.isArray(messages)) return false;
+  const message = messages.at(-1);
+  return isRecord(message) && message.role === "user" && Array.isArray(message.content)
+    && message.content.some((block) => isRecord(block) && block.type === "tool_result");
+}
+
+// A safeguards body field only works with its paired beta, so forward the two
+// together or not at all.
+function safeguardsFrom(
+  payload: Record<string, unknown>,
+  headers: Headers,
+): AnthropicSafeguards | undefined {
+  if (!Array.isArray(payload.safeguards) || payload.safeguards.length === 0) {
+    return undefined;
+  }
+  const betas = [...anthropicBetas(headers)].filter((beta) =>
+    beta.startsWith(SAFEGUARDS_BETA_PREFIX)
+  );
+  return betas.length === 0 ? undefined : { safeguards: payload.safeguards, betas };
+}
+
+function anthropicBetas(headers: Headers): Set<string> {
+  return new Set(
+    (headers.get("anthropic-beta") ?? "")
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  );
+}
+
+function isClaudeCodeRequest(headers: Headers): boolean {
+  const userAgent = headers.get("user-agent")?.trim().toLowerCase() ?? "";
+  const app = headers.get("x-app")?.trim().toLowerCase();
+  const betas = anthropicBetas(headers);
+  return (
+    userAgent.startsWith("claude-cli/") &&
+    (app === "cli" || app === "cli-bg") &&
+    (
+      Boolean(headers.get("x-claude-code-session-id")?.trim()) ||
+      betas.has(LEGACY_CLAUDE_CODE_BETA)
+    )
+  );
+}
+
+// Dari-specific codes clients act on; every other code stays internal.
+const CLIENT_VISIBLE_ERROR_CODES = new Set([
+  "personal_subscription_unavailable",
+  "subscription_switched",
+  "subscription_usage_limit",
+]);
+
+export function anthropicErrorResponse(error: unknown): Response {
+  const { status, message, code } = normalizeError(error);
+  return Response.json(
+    {
+      type: "error",
+      error: {
+        type: anthropicErrorType(status),
+        message,
+        ...(CLIENT_VISIBLE_ERROR_CODES.has(code) ? { code } : {}),
+      },
+    },
+    { status, headers: errorResponseHeaders(error) },
+  );
+}
+
+function anthropicErrorType(status: number): AnthropicErrorType {
+  switch (status) {
+    case 401:
+      return "authentication_error";
+    case 403:
+      return "permission_error";
+    case 404:
+      return "not_found_error";
+    case 429:
+      return "rate_limit_error";
+    default:
+      return status >= 500 ? "api_error" : "invalid_request_error";
+  }
+}

package/src/ingress/anthropic_models.ts

@@ -0,0 +1,28 @@
+/* Anthropic-compatible model discovery. Claude Desktop, Cowork, and other
+   Anthropic-SDK gateway clients list models before first use and parse the
+   Anthropic list shape ({data: [{type: "model", ...}]}), not the Codex
+   catalog shape. Discovery advertises the tier synonyms from router_model.ts —
+   the only ids such clients accept as usable (verified in-app: `dari/routing`
+   is rejected, bare tier names classify). Fixed created_at keeps the response
+   byte-stable. */
+
+import { ANTHROPIC_ROUTER_MODEL_TIERS } from "../protocol/input/router_model";
+
+const ROUTER_MODEL_CREATED_AT = "2026-01-01T00:00:00Z";
+
+const tierLabel = (tier: string) =>
+  `Dari Routing (${tier[0].toUpperCase()}${tier.slice(1)} tier)`;
+
+export function anthropicModelsResponse(): Record<string, unknown> {
+  return {
+    data: ANTHROPIC_ROUTER_MODEL_TIERS.map((tier) => ({
+      type: "model",
+      id: tier,
+      display_name: tierLabel(tier),
+      created_at: ROUTER_MODEL_CREATED_AT,
+    })),
+    first_id: ANTHROPIC_ROUTER_MODEL_TIERS[0],
+    last_id: ANTHROPIC_ROUTER_MODEL_TIERS[ANTHROPIC_ROUTER_MODEL_TIERS.length - 1],
+    has_more: false,
+  };
+}