@dbx-tools/cli-model-proxy 0.3.44 → 0.4.0

package/lib/src/server.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OpenAI-compatible HTTP proxy in front of Databricks Model Serving.
+ *
+ * Databricks serving endpoints speak OpenAI wire formats, so this server is a
+ * thin pass-through: it resolves the request's (possibly fuzzy) `model` to a
+ * real endpoint id via the {@link DatabricksBackend}, stamps a fresh auth
+ * header, and forwards to the right Databricks URL:
+ *
+ *   - Chat Completions → `/serving-endpoints/<name>/invocations`, except for
+ *     Responses-only models (Codex) which are translated and sent to
+ *     `/serving-endpoints/responses`.
+ *   - Responses → native `/serving-endpoints/responses` (OpenAI-family) or
+ *     `/serving-endpoints/open-responses` (Claude/Gemini/…), body forwarded
+ *     as-is. No chat round-trip.
+ *
+ * Any OpenAI-compatible tool (iTerm, editors, the `openai` SDK, Codex CLI) can
+ * point its base URL at this server and use loose model names.
+ *
+ * Routes:
+ *   - `GET  /health`, `GET /`            liveness
+ *   - `GET  /v1/models`, `GET /models`   list resolvable endpoints. Emits the
+ *     OpenAI `{object:"list",data:[…]}` shape by default; when the request
+ *     looks like the Codex CLI (a `client_version` query param, which Codex
+ *     always sends) it emits Codex's `{models:[{slug,…}]}` shape instead, so
+ *     both standard OpenAI clients and Codex can enumerate the catalogue.
+ *   - `POST /v1/chat/completions`        proxy (also `/completions`,
+ *     `/v1/completions`, `/v1/embeddings`, and the un-prefixed variants)
+ *   - `POST /v1/responses`               OpenAI Responses API, forwarded to
+ *     Databricks' native Responses / Open Responses surface.
+ *
+ * @module
+ */
+import { type Server } from "node:http";
+import type { DatabricksBackend } from "./backend.js";
+import { type RetryConfig } from "./defaults.js";
+/** Options shared by {@link createProxyServer} and {@link startProxyServer}. */
+export interface ProxyServerOptions {
+    /**
+     * When set, local clients must present this value as a bearer token
+     * (`Authorization: Bearer <key>`). Unset leaves the proxy open, which is fine
+     * for a loopback bind but should be paired with a key on a wider one.
+     */
+    apiKey?: string;
+    /**
+     * Policy for absorbing upstream 429s. Omitted defaults to {@link
+     * DEFAULT_RETRY} (retry on). See {@link RetryConfig}.
+     */
+    retry?: RetryConfig;
+}
+/** Options for {@link startProxyServer}, adding the listen address. */
+export interface StartProxyOptions extends ProxyServerOptions {
+    host?: string;
+    port?: number;
+}
+/** Build (but do not start) the proxy HTTP server. */
+export declare function createProxyServer(backend: DatabricksBackend, options?: ProxyServerOptions): Server;
+/**
+ * Delay (ms) a `429` response asks us to wait, from its `Retry-After` header,
+ * or `undefined` when absent/unparseable. Handles both header forms: an integer
+ * count of seconds, and an HTTP date to wait until (clamped to `>= 0`).
+ */
+export declare function parseRetryAfterMs(header: string | null, nowMs: number): number | undefined;
+/**
+ * Backoff (ms) before retry `attempt` (0-based): exponential from
+ * `baseDelayMs`, capped at `maxDelayMs`, with up to +50% jitter so concurrent
+ * retries from one agent don't resynchronize into the next burst. A server-sent
+ * `Retry-After` wins outright (still capped), since the server knows better
+ * than our schedule when it will accept traffic again.
+ */
+export declare function backoffDelayMs(attempt: number, retry: RetryConfig, retryAfterMs: number | undefined, jitter: number): number;
+/**
+ * Build and start the proxy, resolving once it is accepting connections.
+ * Returns the server and its base URL (with the actually-bound port, so a
+ * `port: 0` request surfaces the OS-assigned port).
+ */
+export declare function startProxyServer(backend: DatabricksBackend, options?: StartProxyOptions): Promise<{
+    server: Server;
+    url: string;
+}>;