@velum-labs/routekit-gateway 0.9.0

package/dist/test/drain.test.js

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { startGateway } from "../server.js";
+/**
+ * Graceful drain: a draining gateway must report unhealthy and reject new
+ * model calls while letting in-flight requests (long-lived LLM streams)
+ * finish within the grace, and must sever what remains once it expires.
+ */
+/** A backend whose chat stream stays open until the test releases it. */
+function heldStreamBackend() {
+    let controller;
+    return {
+        defaultModel: "mock-model",
+        chat: async () => new Response(new ReadableStream({
+            start(streamController) {
+                controller = streamController;
+                streamController.enqueue(Buffer.from('data: {"choices":[{"delta":{"content":"first"}}]}\n\n'));
+            }
+        }), { 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 }),
+        release: () => {
+            controller?.enqueue(Buffer.from("data: [DONE]\n\n"));
+            controller?.close();
+        }
+    };
+}
+test("drain finishes in-flight streams, rejects new work, and flips /health to 503", async () => {
+    const backend = heldStreamBackend();
+    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",
+                stream: true,
+                messages: [{ role: "user", content: "hi" }]
+            })
+        });
+        const reader = response.body?.getReader();
+        assert.ok(reader !== undefined);
+        await reader.read();
+        // Begin the drain while the stream is in flight.
+        const drained = gateway.drain(5_000);
+        // Health flips to 503 so probes stop routing new work here.
+        const health = await fetch(`${gateway.url()}/health`);
+        assert.equal(health.status, 503);
+        assert.deepEqual(await health.json(), { status: "draining" });
+        // New model calls are rejected while draining.
+        const rejected = 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(rejected.status, 503);
+        const body = (await rejected.json());
+        assert.equal(body.error?.type, "unavailable");
+        // The in-flight stream completes normally once the upstream finishes.
+        backend.release();
+        let text = "";
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            text += Buffer.from(value ?? []).toString("utf8");
+        }
+        assert.match(text, /\[DONE\]/);
+        await drained;
+    }
+    finally {
+        await gateway.close();
+    }
+});
+test("drain grace expiry severs a stream that never finishes", async () => {
+    const backend = heldStreamBackend();
+    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",
+                stream: true,
+                messages: [{ role: "user", content: "hi" }]
+            })
+        });
+        const reader = response.body?.getReader();
+        assert.ok(reader !== undefined);
+        await reader.read();
+        const started = Date.now();
+        await gateway.drain(300);
+        assert.ok(Date.now() - started >= 250, "drain waits out the grace before severing");
+        // The severed client observes an abnormal end, not a silent hang.
+        await assert.rejects(async () => {
+            for (;;) {
+                const { done } = await reader.read();
+                if (done)
+                    break;
+            }
+        });
+    }
+    finally {
+        await gateway.close();
+    }
+});
+test("close without a prior drain remains immediate", async () => {
+    const backend = heldStreamBackend();
+    const gateway = await startGateway({ backend });
+    const health = await fetch(`${gateway.url()}/health`);
+    assert.equal(health.status, 200);
+    const started = Date.now();
+    await gateway.close();
+    assert.ok(Date.now() - started < 1_000, "close() must not wait for a drain grace");
+    await assert.rejects(fetch(`${gateway.url()}/health`));
+});

package/dist/test/dropped.test.d.ts

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

package/dist/test/dropped.test.js

@@ -0,0 +1,80 @@
+/**
+ * Acceptance tests for the dialect drop recorder (WS6.1): every deliberately
+ * untranslated field is observable on the enclosing turn span and warns
+ * exactly once per process.
+ */
+import assert from "node:assert/strict";
+import { beforeEach, test } from "node:test";
+import { DIALECT_DROPPED_ATTRIBUTE, droppedField, resetDroppedFieldWarnings, withDroppedFieldSpan } from "../adapters/dropped.js";
+function captureStderr(run) {
+    const original = process.stderr.write.bind(process.stderr);
+    let captured = "";
+    process.stderr.write = ((chunk) => {
+        captured += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+        return true;
+    });
+    try {
+        run();
+    }
+    finally {
+        process.stderr.write = original;
+    }
+    return captured;
+}
+function recordingSpan() {
+    const attributes = {};
+    return {
+        target: {
+            span: {
+                setAttribute(name, value) {
+                    attributes[name] = value;
+                }
+            }
+        },
+        attributes
+    };
+}
+beforeEach(() => {
+    resetDroppedFieldWarnings();
+});
+test("warns once per distinct dialect.field, not per occurrence", () => {
+    const first = captureStderr(() => droppedField("anthropic", "top_k"));
+    const repeat = captureStderr(() => droppedField("anthropic", "top_k"));
+    const other = captureStderr(() => droppedField("responses", "truncation"));
+    assert.match(first, /anthropic field "top_k" is not translated and was dropped/);
+    assert.equal(repeat, "");
+    assert.match(other, /responses field "truncation"/);
+});
+test("ctx narrows the warning and the span entry", () => {
+    const out = captureStderr(() => droppedField("anthropic", "is_error", "tool_result"));
+    assert.match(out, /anthropic field "tool_result.is_error"/);
+});
+test("appends every occurrence to the ambient span's dropped-list attribute", () => {
+    const span = recordingSpan();
+    captureStderr(() => {
+        withDroppedFieldSpan(span.target, () => {
+            droppedField("anthropic", "top_k");
+            droppedField("anthropic", "metadata");
+            droppedField("anthropic", "top_k");
+        });
+    });
+    assert.deepEqual(span.attributes[DIALECT_DROPPED_ATTRIBUTE], [
+        "anthropic.top_k",
+        "anthropic.metadata",
+        "anthropic.top_k"
+    ]);
+});
+test("survives async boundaries within the wrapped scope", async () => {
+    const span = recordingSpan();
+    await withDroppedFieldSpan(span.target, async () => {
+        await Promise.resolve();
+        captureStderr(() => droppedField("responses", "include"));
+    });
+    assert.deepEqual(span.attributes[DIALECT_DROPPED_ATTRIBUTE], [
+        "responses.include"
+    ]);
+});
+test("is warn-only without an ambient span", () => {
+    const out = captureStderr(() => droppedField("cursor", "reasoning"));
+    assert.match(out, /cursor field "reasoning"/);
+});

package/dist/test/endpoint-health.test.d.ts

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

package/dist/test/endpoint-health.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { endpointHealthProbe, probeEndpointHealth } from "../endpoint-health.js";
+function endpoint(provider, dialect, baseUrl) {
+    return {
+        endpointId: `${provider}-endpoint`,
+        model: `${provider}-model`,
+        provider,
+        dialect,
+        baseUrl
+    };
+}
+test("health probes use registry-native OpenAI, Anthropic, and Google authentication", () => {
+    const openai = endpointHealthProbe(endpoint("openai", "openai", "https://api.openai.com/v1"), "openai-secret");
+    assert.equal(openai.supported, true);
+    if (openai.supported) {
+        assert.equal(new URL(openai.probe.url).pathname, "/v1/models");
+        assert.equal(openai.probe.headers.authorization, "Bearer openai-secret");
+    }
+    const anthropic = endpointHealthProbe(endpoint("anthropic", "anthropic", "https://api.anthropic.com/v1"), "anthropic-secret");
+    assert.equal(anthropic.supported, true);
+    if (anthropic.supported) {
+        assert.equal(new URL(anthropic.probe.url).pathname, "/v1/models");
+        assert.equal(anthropic.probe.headers["x-api-key"], "anthropic-secret");
+        assert.equal(anthropic.probe.headers["anthropic-version"], "2023-06-01");
+        assert.equal(anthropic.probe.headers.authorization, undefined);
+    }
+    const google = endpointHealthProbe(endpoint("google", "google", "https://generativelanguage.googleapis.com/v1beta"), "google-secret");
+    assert.equal(google.supported, true);
+    if (google.supported) {
+        assert.equal(new URL(google.probe.url).pathname, "/v1beta/models");
+        assert.equal(google.probe.headers["x-goog-api-key"], "google-secret");
+        assert.equal(google.probe.headers.authorization, undefined);
+    }
+});
+test("custom endpoints use dialect rules while Codex avoids unsafe generation probes", async () => {
+    const custom = endpointHealthProbe(endpoint("private-provider", "anthropic", "https://private.example/api/v1"), "private-secret");
+    assert.equal(custom.supported, true);
+    if (custom.supported) {
+        assert.equal(new URL(custom.probe.url).pathname, "/api/v1/models");
+        assert.equal(custom.probe.headers["x-api-key"], "private-secret");
+    }
+    let requested = false;
+    const result = await probeEndpointHealth(endpoint("codex", "openai", "https://chatgpt.com/backend-api/codex"), {
+        credential: "codex-secret",
+        fetchImpl: async () => {
+            requested = true;
+            return new Response(null, { status: 200 });
+        }
+    });
+    assert.equal(requested, false);
+    assert.equal(result.kind, "unsupported");
+    if (result.kind === "unsupported")
+        assert.match(result.reason, /Codex responses provider/);
+    assert.equal(JSON.stringify(result).includes("codex-secret"), false);
+    const customCodex = endpointHealthProbe(endpoint("private-provider", "codex", "https://private.example/responses"), "private-secret");
+    assert.equal(customCodex.supported, false);
+    if (!customCodex.supported)
+        assert.match(customCodex.reason, /Codex responses dialect/);
+});
+test("health results classify native auth rejection without returning credentials", async () => {
+    const result = await probeEndpointHealth(endpoint("google", "google", "https://generativelanguage.googleapis.com/v1beta"), {
+        credential: "never-return-this",
+        fetchImpl: async () => new Response(null, { status: 400 })
+    });
+    assert.deepEqual(result, {
+        kind: "response",
+        ok: false,
+        status: 400,
+        authRejected: true
+    });
+    assert.equal(JSON.stringify(result).includes("never-return-this"), false);
+});

package/dist/test/provenance.test.d.ts

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

package/dist/test/provenance.test.js

@@ -0,0 +1,176 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { buildModelCallRecord } from "../provenance.js";
+import { readProducerVersion, resolveProducerGitSha, UNKNOWN_GIT_SHA } from "../provenance.js";
+const GIT_SHA = /^[a-f0-9]{40}$/;
+test("WS7: resolveProducerGitSha returns a real 40-hex SHA from a source checkout", () => {
+    const previous = process.env.ROUTEKIT_BUILD_GIT_SHA;
+    delete process.env.ROUTEKIT_BUILD_GIT_SHA;
+    try {
+        // The test runs from the handoffkit checkout (not node_modules), so the
+        // runtime `git rev-parse HEAD` fallback resolves the real producer SHA.
+        const sha = resolveProducerGitSha();
+        assert.match(sha, GIT_SHA, "a checkout resolves a real git SHA");
+        assert.notEqual(sha, "0".repeat(40), "never the all-zero faked-provenance placeholder");
+    }
+    finally {
+        if (previous !== undefined)
+            process.env.ROUTEKIT_BUILD_GIT_SHA = previous;
+    }
+});
+test("WS7: a build-time stamp wins over the checkout git lookup", () => {
+    const previous = process.env.ROUTEKIT_BUILD_GIT_SHA;
+    const stamped = "a".repeat(40);
+    process.env.ROUTEKIT_BUILD_GIT_SHA = stamped;
+    try {
+        assert.equal(resolveProducerGitSha(), stamped);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.ROUTEKIT_BUILD_GIT_SHA;
+        else
+            process.env.ROUTEKIT_BUILD_GIT_SHA = previous;
+    }
+});
+test("WS7: an installed copy (node_modules, no stamp) falls back to the 'unknown' sentinel", () => {
+    const previous = process.env.ROUTEKIT_BUILD_GIT_SHA;
+    delete process.env.ROUTEKIT_BUILD_GIT_SHA;
+    try {
+        // A node_modules path is treated as an installed artifact: no git lookup
+        // (so we never mis-report the consumer's repo) → the clearly-marked sentinel.
+        const sha = resolveProducerGitSha("/tmp/project/node_modules/@velum-labs/routekit-gateway/dist");
+        assert.equal(sha, UNKNOWN_GIT_SHA);
+        assert.equal(sha, "unknown");
+        assert.notEqual(sha, "0".repeat(40), "the sentinel is never 40 zeros");
+    }
+    finally {
+        if (previous !== undefined)
+            process.env.ROUTEKIT_BUILD_GIT_SHA = previous;
+    }
+});
+test("WS7: readProducerVersion reads this package's real version", () => {
+    const version = readProducerVersion();
+    assert.match(version, /^\d+\.\d+\.\d+/, "a real semver, not the 0.1.0 stub");
+});
+test("WS7: a built model-call record carries normalized provenance", () => {
+    const record = buildModelCallRecord({
+        callId: "call_test_1",
+        dialect: "openai-chat",
+        requestedModel: "gpt-5.5",
+        model: "gpt-5.5",
+        stream: false,
+        requestBody: { messages: [{ role: "user", content: "hi" }] },
+        startedAt: "2026-06-27T00:00:00.000Z",
+        attribution: {
+            effective_model: "openai/gpt-5.5",
+            native_model: "gpt-5.5",
+            provider: "openai",
+            billing_mode: "api_key",
+            attempts: 1,
+            retries: 0,
+            account_failovers: 0
+        }
+    }, { statusCode: 200, durationMs: 12, responseBody: Buffer.from(JSON.stringify({ id: "x" })) });
+    assert.equal(record.call_id, "call_test_1");
+    assert.equal(record.endpoint_id, "openai-chat");
+    assert.equal(record.status, "succeeded");
+    assert.equal(record.metadata?.unknown_cost, true);
+    assert.deepEqual(record.metadata?.attribution, {
+        effective_model: "openai/gpt-5.5",
+        native_model: "gpt-5.5",
+        provider: "openai",
+        billing_mode: "api_key",
+        attempts: 1,
+        retries: 0,
+        account_failovers: 0
+    });
+});
+test("model-call provenance replaces raw upstream errors with a safe summary", () => {
+    const secret = "sk-secret-must-not-survive";
+    const record = buildModelCallRecord({
+        callId: "call_redacted",
+        dialect: "openai-chat",
+        requestedModel: "openai/gpt-5.5",
+        model: "openai/gpt-5.5",
+        stream: false,
+        requestBody: { messages: [{ role: "user", content: "hi" }] },
+        startedAt: "2026-06-27T00:00:00.000Z"
+    }, {
+        statusCode: 502,
+        durationMs: 2,
+        error: new Error(`authorization Bearer ${secret}`)
+    });
+    assert.equal(record.error?.message, "provider request failed");
+    assert.doesNotMatch(JSON.stringify(record), new RegExp(secret));
+    assert.doesNotMatch(JSON.stringify(record), /authorization/i);
+});
+test("an unconfigured router is not attributed to a provider or marked retryable", () => {
+    const record = buildModelCallRecord({
+        callId: "call_no_route",
+        dialect: "anthropic-messages",
+        requestedModel: undefined,
+        model: undefined,
+        stream: false,
+        requestBody: { messages: [{ role: "user", content: "hi" }] },
+        startedAt: "2026-07-22T00:00:00.000Z"
+    }, {
+        statusCode: 503,
+        durationMs: 1,
+        responseBody: Buffer.from(JSON.stringify({
+            error: {
+                type: "unavailable",
+                message: "no model is available; configure a provider"
+            }
+        }))
+    });
+    assert.equal(record.metadata?.attribution, undefined);
+    assert.deepEqual(record.error, {
+        kind: "capability_missing",
+        message: "no model route is configured",
+        retryable: false
+    });
+});
+test("model-call provenance meters aggregate buffered and Responses SSE usage", () => {
+    const context = {
+        callId: "call_aggregate",
+        dialect: "openai-responses",
+        requestedModel: "gpt-5.5",
+        model: "gpt-5.5",
+        stream: false,
+        requestBody: { input: "research" },
+        startedAt: "2026-06-27T00:00:00.000Z"
+    };
+    const buffered = buildModelCallRecord(context, {
+        statusCode: 200,
+        durationMs: 3,
+        responseBody: Buffer.from(JSON.stringify({
+            usage: {
+                input_tokens: 30,
+                output_tokens: 12,
+                total_tokens: 42
+            }
+        }))
+    });
+    assert.deepEqual(buffered.usage, {
+        prompt_tokens: 30,
+        completion_tokens: 12,
+        total_tokens: 42
+    });
+    assert.equal(buffered.metadata?.cost_estimate_usd, 0.0001575);
+    const streamed = buildModelCallRecord({ ...context, callId: "call_aggregate_stream", stream: true }, {
+        statusCode: 200,
+        durationMs: 3,
+        responseBody: Buffer.from(`data: ${JSON.stringify({
+            type: "response.completed",
+            response: {
+                usage: {
+                    input_tokens: 30,
+                    output_tokens: 12,
+                    total_tokens: 42
+                }
+            }
+        })}\n\n`)
+    });
+    assert.deepEqual(streamed.usage, buffered.usage);
+    assert.equal(streamed.metadata?.cost_estimate_usd, 0.0001575);
+});

package/dist/test/provider-backends.test.d.ts

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