@velum-labs/routekit-gateway 0.9.0

package/dist/test/routed-backend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/routed-backend.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ModelRoutedBackend } from "../backend.js";
+function stubBackend(id, defaultModel) {
+    const chats = [];
+    return {
+        defaultModel,
+        chats,
+        chat(body) {
+            chats.push(body);
+            return Promise.resolve(new Response(JSON.stringify({ served_by: id }), {
+                status: 200,
+                headers: { "content-type": "application/json" }
+            }));
+        },
+        models: () => Promise.resolve(new Response("{}", { status: 200 })),
+        embeddings: () => Promise.resolve(new Response("{}", { status: 200 }))
+    };
+}
+test("ModelRoutedBackend dispatches by requested model id", async () => {
+    const primary = stubBackend("primary", "qwen3");
+    const routed = stubBackend("front-door");
+    const backend = new ModelRoutedBackend({
+        routedModelIds: ["route-primary", "route-secondary"],
+        routed,
+        primary
+    });
+    const member = (await (await backend.chat({ model: "qwen3", messages: [] })).json());
+    assert.equal(member.served_by, "primary");
+    const routedResponse = (await (await backend.chat({ model: "route-secondary", messages: [] })).json());
+    assert.equal(routedResponse.served_by, "front-door");
+    // No model at all falls back to the primary (its defaultModel applies).
+    const bare = (await (await backend.chat({ messages: [] })).json());
+    assert.equal(bare.served_by, "primary");
+    assert.equal(backend.defaultModel, "qwen3");
+    assert.deepEqual([...backend.listModelIds()], ["qwen3", "route-primary", "route-secondary"]);
+    assert.equal(backend.resolveModel("route-primary"), "route-primary");
+    assert.equal(backend.resolveModel("anything-else"), "qwen3");
+});

package/dist/test/router.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/router.test.js

@@ -0,0 +1,297 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { CatalogBackend, NoModelAvailableError, parseDiscoveredModels, parseRouterConfig, UnknownModelError } from "../index.js";
+function fakeSource(sourceId, models, calls = []) {
+    return {
+        sourceId,
+        async discoverModels() {
+            return models;
+        },
+        async chat(body, _signal, _options) {
+            const model = typeof body === "object" &&
+                body !== null &&
+                "model" in body &&
+                typeof body.model === "string"
+                ? body.model
+                : undefined;
+            calls.push({ source: sourceId, ...(model !== undefined ? { model } : {}) });
+            return Response.json({ source: sourceId, model });
+        },
+        async embeddings() {
+            return Response.json({});
+        }
+    };
+}
+test("RouterConfig accepts explicit provider maps and namespaced defaults", () => {
+    assert.deepEqual(parseRouterConfig({ providers: {} }).providers, {});
+    const config = parseRouterConfig({
+        providers: {
+            openai: {},
+            codex: { strategy: "round_robin", switchThreshold: 0.8 }
+        },
+        defaultModel: "codex/gpt-5.5"
+    });
+    assert.equal(config.providers.openai?.strategy, "capacity_weighted");
+    assert.equal(config.providers.codex?.strategy, "round_robin");
+    assert.throws(() => parseRouterConfig({
+        providers: { openai: {} },
+        defaultModel: "gpt-5.5"
+    }), /provider\/model namespace/);
+    assert.throws(() => parseRouterConfig({
+        providers: { openai: {} },
+        defaultModel: "codex/gpt-5.5"
+    }), /provider "codex" is not configured/);
+    assert.throws(() => parseRouterConfig({ endpoints: [] }), /invalid input|unrecognized key/i);
+    assert.throws(() => parseRouterConfig({
+        providers: { openai: {} },
+        reasoningCapabilities: {
+            "openai/opaque": {
+                efforts: [{ id: "quick" }],
+                defaultEffort: "missing"
+            }
+        }
+    }), /default reasoning effort/);
+});
+test("empty provider configuration creates a credential-independent empty catalog", async () => {
+    const backend = await CatalogBackend.create({
+        config: { providers: {} },
+        env: {}
+    });
+    assert.equal(backend.defaultModel, undefined);
+    assert.deepEqual(backend.listModelIds(), []);
+    assert.deepEqual(await backend.providerStatuses(), []);
+    assert.deepEqual(await (await backend.models()).json(), {
+        object: "list",
+        data: []
+    });
+    assert.throws(() => backend.chat({ messages: [] }), (error) => error instanceof NoModelAvailableError);
+    assert.throws(() => backend.chat({ model: "openai/not-configured", messages: [] }), (error) => error instanceof UnknownModelError &&
+        error.model === "openai/not-configured");
+    assert.throws(() => backend.embeddings({ input: "hello" }), (error) => error instanceof NoModelAvailableError);
+});
+test("discovery normalizes native response shapes", () => {
+    assert.deepEqual(parseDiscoveredModels("openai", {
+        data: [{ id: "gpt-5.5" }, { id: "gpt-5.5" }, { nope: true }]
+    }).map((model) => model.id), ["gpt-5.5"]);
+    assert.deepEqual(parseDiscoveredModels("anthropic", {
+        data: [{ id: "claude-opus-4-1" }]
+    }).map((model) => model.id), ["claude-opus-4-1"]);
+    assert.deepEqual(parseDiscoveredModels("google", {
+        models: [{ name: "models/gemini-2.5-pro" }]
+    }).map((model) => model.id), ["gemini-2.5-pro"]);
+    assert.deepEqual(parseDiscoveredModels("codex", {
+        models: [
+            {
+                slug: "gpt-5.5",
+                default_reasoning_level: "balanced",
+                supported_reasoning_levels: [
+                    { effort: "quick", description: "Quick" },
+                    { effort: "balanced", description: "Balanced" }
+                ]
+            }
+        ]
+    }, "codex").map((model) => model.id), ["gpt-5.5"]);
+    const reasoning = parseDiscoveredModels("codex", {
+        models: [
+            {
+                slug: "opaque",
+                default_reasoning_level: "balanced",
+                supported_reasoning_levels: ["quick", "balanced"]
+            }
+        ]
+    }, "codex")[0]?.reasoning;
+    assert.deepEqual(reasoning?.efforts, [{ id: "quick" }, { id: "balanced" }]);
+    assert.equal(reasoning?.defaultEffort, "balanced");
+    assert.equal(reasoning?.wireShape, "openai-responses");
+    assert.equal(reasoning?.provenance, "provider");
+    assert.throws(() => parseDiscoveredModels("openai", { data: [] }), /no usable openai models/);
+});
+test("catalog namespaces live models and strips the source before dispatch", async () => {
+    const calls = [];
+    const backend = await CatalogBackend.create({
+        config: {
+            providers: { openai: {}, openrouter: {} },
+            defaultModel: "openrouter/moonshotai/kimi-k2-thinking"
+        },
+        sources: {
+            openai: fakeSource("openai", [{ id: "gpt-5.5" }], calls),
+            openrouter: fakeSource("openrouter", [{ id: "moonshotai/kimi-k2-thinking" }], calls)
+        }
+    });
+    assert.deepEqual(backend.listModelIds(), [
+        "openai/gpt-5.5",
+        "openrouter/moonshotai/kimi-k2-thinking"
+    ]);
+    assert.deepEqual(backend.resolveModelRoute("gpt-5.5", "openai"), {
+        publicId: "openai/gpt-5.5",
+        nativeId: "gpt-5.5",
+        provider: "openai"
+    });
+    assert.equal(backend.resolveModelRoute("gpt-5.5"), undefined, "bare ids remain invalid without a native-provider scope");
+    assert.deepEqual(backend.resolveModelRoute("openrouter/moonshotai/kimi-k2-thinking", "openai"), {
+        publicId: "openrouter/moonshotai/kimi-k2-thinking",
+        nativeId: "moonshotai/kimi-k2-thinking",
+        provider: "openrouter"
+    }, "an exact canonical id wins even on a native client door");
+    await backend.chat({ messages: [] });
+    await backend.chat({ model: "openai/gpt-5.5", messages: [] });
+    assert.deepEqual(calls, [
+        { source: "openrouter", model: "moonshotai/kimi-k2-thinking" },
+        { source: "openai", model: "gpt-5.5" }
+    ]);
+    const models = (await (await backend.models()).json());
+    assert.deepEqual(models.data.map((model) => [model.id, model.owned_by]), [
+        ["openai/gpt-5.5", "openai"],
+        ["openrouter/moonshotai/kimi-k2-thinking", "openrouter"]
+    ]);
+    assert.deepEqual(backend.modelInfo("openai/gpt-5.5"), {
+        id: "openai/gpt-5.5",
+        provider: "openai",
+        nativeModel: "gpt-5.5",
+        accountClass: "api-key",
+        billingMode: "metered-api",
+        default: false,
+        capabilities: {},
+        reasoning: null
+    });
+    assert.equal(backend.modelInfo("openai/not-real"), undefined);
+});
+test("model info exhaustively classifies subscription and proxy billing", async () => {
+    const backend = await CatalogBackend.create({
+        config: {
+            providers: { codex: {}, "claude-code": {}, cliproxy: {} },
+            defaultModel: "codex/gpt-5.5"
+        },
+        sources: {
+            codex: fakeSource("codex", [
+                {
+                    id: "gpt-5.5",
+                    capabilities: { tools: "supported" },
+                    reasoning: {
+                        status: "supported",
+                        efforts: [{ id: "high" }],
+                        provenance: "provider",
+                        refreshedAt: "2026-07-22T00:00:00.000Z"
+                    }
+                }
+            ]),
+            "claude-code": fakeSource("claude-code", [{ id: "claude-opus-4-1" }]),
+            cliproxy: fakeSource("cliproxy", [{ id: "local-route" }])
+        }
+    });
+    assert.deepEqual(backend.modelInfo("codex/gpt-5.5"), {
+        id: "codex/gpt-5.5",
+        provider: "codex",
+        nativeModel: "gpt-5.5",
+        accountClass: "subscription",
+        billingMode: "subscription",
+        default: true,
+        capabilities: { tools: "supported" },
+        reasoning: {
+            status: "supported",
+            efforts: [{ id: "high" }],
+            provenance: "provider",
+            refreshedAt: "2026-07-22T00:00:00.000Z"
+        }
+    });
+    assert.deepEqual({
+        accountClass: backend.modelInfo("claude-code/claude-opus-4-1")?.accountClass,
+        billingMode: backend.modelInfo("claude-code/claude-opus-4-1")?.billingMode
+    }, { accountClass: "subscription", billingMode: "subscription" });
+    assert.deepEqual({
+        accountClass: backend.modelInfo("cliproxy/local-route")?.accountClass,
+        billingMode: backend.modelInfo("cliproxy/local-route")?.billingMode
+    }, { accountClass: "proxy", billingMode: "upstream-managed" });
+    await backend.close();
+});
+test("cliproxy routes are attributed as subscription billing", async () => {
+    const backend = await CatalogBackend.create({
+        config: {
+            providers: { cliproxy: {} },
+            defaultModel: "cliproxy/gpt-test"
+        },
+        sources: {
+            cliproxy: fakeSource("cliproxy", [{ id: "gpt-test" }])
+        }
+    });
+    const updates = [];
+    const response = await backend.chat({ model: "cliproxy/gpt-test", messages: [] }, undefined, { onAttribution: (update) => updates.push(update) });
+    assert.equal(response.status, 200);
+    assert.deepEqual(updates, [
+        {
+            effective_model: "cliproxy/gpt-test",
+            native_model: "gpt-test",
+            provider: "cliproxy",
+            billing_mode: "subscription"
+        }
+    ]);
+});
+test("catalog applies configured opaque efforts and rejects unavailable values before egress", async () => {
+    const calls = [];
+    const backend = await CatalogBackend.create({
+        config: {
+            providers: { openai: {} },
+            defaultModel: "openai/opaque",
+            reasoningCapabilities: {
+                "openai/opaque": {
+                    efforts: [
+                        { id: "balanced", aliases: ["cursor-balanced"] },
+                        { id: "deep" }
+                    ],
+                    defaultEffort: "balanced",
+                    wireShape: "openai-chat"
+                }
+            }
+        },
+        sources: {
+            openai: fakeSource("openai", [{ id: "opaque" }], calls)
+        }
+    });
+    const accepted = await backend.chat({
+        model: "openai/opaque",
+        reasoning_effort: "cursor-balanced",
+        messages: []
+    });
+    assert.equal(accepted.status, 200);
+    const rejected = await backend.chat({
+        model: "openai/opaque",
+        reasoning_effort: "maximum",
+        messages: []
+    });
+    assert.equal(rejected.status, 400);
+    const malformed = await backend.chat({
+        model: "openai/opaque",
+        reasoning_effort: 7,
+        messages: []
+    });
+    assert.equal(malformed.status, 400);
+    assert.equal(calls.length, 1);
+    assert.equal(backend.reasoningCapabilities("openai/opaque")?.provenance, "config");
+});
+test("unknown models never fall through to the default source", async () => {
+    const backend = await CatalogBackend.create({
+        config: { providers: { openai: {} } },
+        sources: { openai: fakeSource("openai", [{ id: "gpt-5.5" }]) }
+    });
+    assert.throws(() => backend.chat({ model: "openai/not-real", messages: [] }), (error) => error instanceof UnknownModelError && error.model === "openai/not-real");
+});
+test("startup reports provider-specific discovery and credential failures", async () => {
+    await assert.rejects(CatalogBackend.create({
+        config: { providers: { openai: {} } },
+        sources: {
+            openai: {
+                ...fakeSource("openai", []),
+                async discoverModels() {
+                    throw new Error("bad token");
+                }
+            }
+        }
+    }), /provider "openai" discovery failed: bad token/);
+    await assert.rejects(CatalogBackend.create({
+        config: { providers: { openai: {} } },
+        env: {}
+    }), /provider "openai" is missing credential environment variable OPENAI_API_KEY/);
+    await assert.rejects(CatalogBackend.create({
+        config: { providers: { codex: {} } }
+    }), /provider "codex" requires enrolled subscription accounts/);
+});

package/dist/test/server-resilience.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/server-resilience.test.js

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { startGateway } from "../server.js";
+/**
+ * Crash resilience: an upstream stream that dies mid-response (the shape of a
+ * local model server being OOM-killed during a turn) must fail only that one
+ * request. Historically the error path wrote JSON onto a response whose
+ * headers were already sent, which threw inside the catch handler and killed
+ * the whole process hosting the gateway, leaving the client with a bare
+ * "stream disconnected" error.
+ */
+/** A backend whose chat stream emits one SSE chunk, then errors mid-stream. */
+function midStreamFailureBackend() {
+    return {
+        defaultModel: "mock-model",
+        chat: async () => {
+            const body = new ReadableStream({
+                start(controller) {
+                    controller.enqueue(Buffer.from('data: {"choices":[{"delta":{"content":"hi"}}]}\n\n', "utf8"));
+                    controller.error(new Error("upstream server crashed (simulated OOM kill)"));
+                }
+            });
+            return new Response(body, {
+                status: 200,
+                headers: { "content-type": "text/event-stream" }
+            });
+        },
+        models: async () => new Response(JSON.stringify({ object: "list", data: [{ id: "mock-model" }] }), {
+            status: 200,
+            headers: { "content-type": "application/json" }
+        }),
+        embeddings: async () => new Response(JSON.stringify({}), { status: 200 })
+    };
+}
+test("a mid-stream upstream failure does not kill the gateway process", async () => {
+    const unhandled = [];
+    const onUnhandled = (reason) => {
+        unhandled.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandled);
+    const gateway = await startGateway({ backend: midStreamFailureBackend() });
+    try {
+        // The streaming request fails abnormally (destroyed socket), not silently.
+        await assert.rejects(async () => {
+            const response = await fetch(`${gateway.url()}/v1/chat/completions`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ model: "mock-model", stream: true, messages: [{ role: "user", content: "hi" }] })
+            });
+            await response.text();
+        });
+        // Give any would-be unhandled rejection a macrotask to surface.
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        assert.deepEqual(unhandled, [], "no unhandled rejection escaped the error path");
+        // The gateway (and its hosting process) is still alive and serving.
+        const health = await fetch(`${gateway.url()}/health`);
+        assert.equal(health.status, 200);
+        const models = await fetch(`${gateway.url()}/v1/models`);
+        assert.equal(models.status, 200);
+    }
+    finally {
+        process.off("unhandledRejection", onUnhandled);
+        await gateway.close();
+    }
+});
+test("an error before headers are sent still yields a 502 JSON body", async () => {
+    const backend = {
+        ...midStreamFailureBackend(),
+        chat: async () => {
+            throw new Error("backend exploded before responding");
+        }
+    };
+    const gateway = await startGateway({ backend });
+    try {
+        const response = await fetch(`${gateway.url()}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ model: "mock-model", messages: [{ role: "user", content: "hi" }] })
+        });
+        assert.equal(response.status, 502);
+        const body = (await response.json());
+        assert.equal(body.error?.type, "upstream_error");
+        assert.equal(body.error?.message, "upstream request failed");
+    }
+    finally {
+        await gateway.close();
+    }
+});
+test("client disconnect cancels the upstream response body", async () => {
+    let cancelled = false;
+    let upstreamController;
+    const backend = {
+        defaultModel: "mock-model",
+        chat: async () => new Response(new ReadableStream({
+            start(controller) {
+                upstreamController = controller;
+                controller.enqueue(Buffer.from('data: {"choices":[{"delta":{"content":"first"}}]}\n\n'));
+            },
+            cancel() {
+                cancelled = true;
+            }
+        }), { status: 200, headers: { "content-type": "text/event-stream" } }),
+        models: async () => new Response(JSON.stringify({ data: [] }), { status: 200 }),
+        embeddings: async () => new Response(JSON.stringify({}), { status: 200 })
+    };
+    const gateway = await startGateway({ backend });
+    const aborter = new AbortController();
+    try {
+        const response = await fetch(`${gateway.url()}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model: "mock-model",
+                stream: true,
+                messages: [{ role: "user", content: "hi" }]
+            }),
+            signal: aborter.signal
+        });
+        const reader = response.body?.getReader();
+        assert.ok(reader !== undefined);
+        await reader.read();
+        aborter.abort();
+        const deadline = Date.now() + 1_000;
+        while (!cancelled && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        if (!cancelled)
+            upstreamController?.close();
+        assert.equal(cancelled, true, "the gateway must cancel a body it can no longer deliver");
+    }
+    finally {
+        try {
+            upstreamController?.close();
+        }
+        catch {
+            // already cancelled
+        }
+        await gateway.close();
+    }
+});
+test("oversized request bodies are rejected before the backend is called", async () => {
+    let chatCalls = 0;
+    const backend = {
+        defaultModel: "mock-model",
+        chat: async () => {
+            chatCalls += 1;
+            return new Response(JSON.stringify({ choices: [] }), { status: 200 });
+        },
+        models: async () => new Response(JSON.stringify({ data: [] }), { status: 200 }),
+        embeddings: async () => new Response(JSON.stringify({}), { status: 200 })
+    };
+    const gateway = await startGateway({ backend });
+    try {
+        const response = await fetch(`${gateway.url()}/v1/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                model: "mock-model",
+                messages: [{ role: "user", content: "hi" }],
+                padding: "x".repeat(17 * 1024 * 1024)
+            })
+        });
+        assert.equal(response.status, 413);
+        assert.equal(chatCalls, 0);
+    }
+    finally {
+        await gateway.close();
+    }
+});

package/dist/test/sse-codec.test.d.ts

@@ -0,0 +1 @@
+export {};