babelgate 1.1.2 → 1.2.0

package/dist/config/yaml-config.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfigPath = resolveConfigPath;
+exports.ignoredEnvKeys = ignoredEnvKeys;
+exports.loadYamlConfig = loadYamlConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const registry_1 = require("../routing/registry");
+const rules_1 = require("../routing/rules");
+const errors_1 = require("../utils/errors");
+const gateway_schema_1 = require("./gateway.schema");
+/**
+ * Discovery order (spec §3.5): explicit --config path, then
+ * BABELGATE_CONFIG, then ./babelgate.yaml, then env-only mode. A named
+ * path that does not exist is a startup error; a missing
+ * ./babelgate.yaml just means env mode.
+ */
+function resolveConfigPath(explicit, env, cwd) {
+    const named = explicit ?? env.BABELGATE_CONFIG;
+    if (named !== undefined) {
+        const resolved = (0, node_path_1.resolve)(cwd, named);
+        if (!(0, node_fs_1.existsSync)(resolved)) {
+            throw new errors_1.ConfigurationError(`Config file not found: ${resolved}`);
+        }
+        return resolved;
+    }
+    const local = (0, node_path_1.join)(cwd, "babelgate.yaml");
+    return (0, node_fs_1.existsSync)(local) ? local : undefined;
+}
+/**
+ * Env vars that apply in env-only mode and are ignored when a YAML
+ * file is loaded (spec §3.5): TARGET_API, every *_API_BASE_URL,
+ * MODEL_MAP, TARGET_CONTEXT_WINDOW and SOURCE_API — the ones that are
+ * set, in that order. Names only, never values.
+ */
+function ignoredEnvKeys(env) {
+    const baseUrlKeys = Object.keys(env)
+        .filter((key) => key.endsWith("_API_BASE_URL"))
+        .sort();
+    return [
+        ...(env.TARGET_API !== undefined ? ["TARGET_API"] : []),
+        ...baseUrlKeys,
+        ...(env.MODEL_MAP !== undefined ? ["MODEL_MAP"] : []),
+        ...(env.TARGET_CONTEXT_WINDOW !== undefined
+            ? ["TARGET_CONTEXT_WINDOW"]
+            : []),
+        ...(env.SOURCE_API !== undefined ? ["SOURCE_API"] : []),
+    ];
+}
+/** ["routes", 1, "to"] → "routes[1].to"; the root is "". */
+function formatIssuePath(segments) {
+    let out = "";
+    for (const segment of segments) {
+        if (typeof segment === "number") {
+            out += `[${segment}]`;
+        }
+        else {
+            out += out === "" ? String(segment) : `.${String(segment)}`;
+        }
+    }
+    return out;
+}
+function requireTarget(text, providerNames, file, at) {
+    const target = (0, rules_1.parseTarget)(text, providerNames);
+    if (target === undefined) {
+        throw new errors_1.ConfigurationError(`${file}: ${at} "${text}" is not <provider>/<model> for a configured provider`);
+    }
+    return target;
+}
+/**
+ * Loads a babelgate.yaml into a GatewayConfig (spec §3.5). Scalars
+ * (PORT, PROXY_API_KEY, UPSTREAM_*) come from `env` exactly as in env
+ * mode; `api_key_env` names are resolved against `env` and the values
+ * become `apiKey` — only the env var names may appear in errors.
+ */
+function loadYamlConfig(path, env) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        throw new errors_1.ConfigurationError(`Config file not found: ${path}`);
+    }
+    const doc = (0, yaml_1.parseDocument)(text, { uniqueKeys: true });
+    const parseError = doc.errors[0];
+    if (parseError !== undefined) {
+        throw new errors_1.ConfigurationError(`${path}: ${parseError.message}`);
+    }
+    const raw = doc.toJS();
+    if (raw === null || raw === undefined) {
+        throw new errors_1.ConfigurationError(`${path}: the config file is empty — 'providers' is required`);
+    }
+    const parsed = gateway_schema_1.gatewayFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues
+            .map((issue) => {
+            const at = formatIssuePath(issue.path);
+            return at === "" ? issue.message : `${at}: ${issue.message}`;
+        })
+            .join("; ");
+        throw new errors_1.ConfigurationError(`${path}: ${detail}`);
+    }
+    const file = parsed.data;
+    const providerNames = new Set(Object.keys(file.providers));
+    if (!providerNames.has(file.default)) {
+        throw new errors_1.ConfigurationError(`${path}: default "${file.default}" is not a configured provider`);
+    }
+    const entries = Object.entries(file.providers).map(([name, provider]) => {
+        let apiKey;
+        if (provider.api_key_env !== undefined) {
+            const value = env[provider.api_key_env];
+            if (value === undefined || value === "") {
+                throw new errors_1.ConfigurationError(`${path}: providers.${name}.api_key_env names ${provider.api_key_env}, which is unset or empty`);
+            }
+            apiKey = value;
+        }
+        return {
+            name,
+            type: provider.type,
+            baseUrl: provider.base_url.replace(/\/$/, ""),
+            apiKey,
+            apiKeyEnv: provider.api_key_env,
+            contextWindow: provider.context_window,
+            timeoutMs: provider.timeout_ms,
+            streamIdleMs: provider.stream_idle_ms,
+        };
+    });
+    const aliases = {};
+    for (const [name, text] of Object.entries(file.aliases ?? {})) {
+        if (providerNames.has(name)) {
+            throw new errors_1.ConfigurationError(`${path}: aliases.${name} — "${name}" is also a provider name`);
+        }
+        aliases[name] = requireTarget(text, providerNames, path, `aliases.${name}`);
+    }
+    const rules = (file.routes ?? []).map((route, index) => ({
+        match: route.match,
+        when: route.when !== undefined
+            ? { minInputTokens: route.when.min_input_tokens }
+            : undefined,
+        to: requireTarget(route.to, providerNames, path, `routes[${index}].to`),
+        fallback: (route.fallback ?? []).map((text, i) => requireTarget(text, providerNames, path, `routes[${index}].fallback[${i}]`)),
+    }));
+    const routing = {
+        defaultProvider: file.default,
+        aliases,
+        rules,
+    };
+    return {
+        port: env.PORT ? parseInt(env.PORT, 10) : 3000,
+        proxyApiKey: env.PROXY_API_KEY || undefined,
+        upstreamTimeoutMs: env.UPSTREAM_TIMEOUT_MS
+            ? parseInt(env.UPSTREAM_TIMEOUT_MS, 10)
+            : 30_000,
+        upstreamRetries: env.UPSTREAM_RETRIES
+            ? parseInt(env.UPSTREAM_RETRIES, 10)
+            : 1,
+        upstreamStreamIdleMs: env.UPSTREAM_STREAM_IDLE_MS
+            ? parseInt(env.UPSTREAM_STREAM_IDLE_MS, 10)
+            : 300_000,
+        registry: (0, registry_1.createRegistry)(entries),
+        routing,
+    };
+}

package/dist/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.startServer = startServer;
 const app_1 = require("./app");
 const env_config_1 = require("./config/env-config");
+const table_1 = require("./routing/table");
 const logger_1 = require("./utils/logger");
 /**
  * Starts the proxy and resolves once it is listening. Importing this module
@@ -33,11 +34,12 @@ function startServer() {
         server.once("listening", () => {
             logger_1.logger.info({
                 port,
-                sourceApi: config.sourceApi,
-                targetApi: config.targetApi,
-                targetBaseUrl: config.targetBaseUrl,
-                targetApiKey: config.targetApiKey ? "****" : "Not configured",
+                defaultProvider: config.routing.defaultProvider,
+                providers: config.registry.names(),
             }, "Server started");
+            for (const line of (0, table_1.formatRoutingTable)(config)) {
+                logger_1.logger.info(line);
+            }
             process.on("SIGTERM", () => shutdown("SIGTERM"));
             process.on("SIGINT", () => shutdown("SIGINT"));
             resolve(server);

package/dist/middleware/detect-source.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSourceMiddleware = detectSourceMiddleware;
+const detect_source_1 = require("../routing/detect-source");
+/**
+ * Records the detected client format on `res.locals.sourceApi` so the
+ * proxy route and the error handler use the request's own dialect
+ * (spec §3.2). Mounted before the body parser and auth so their errors
+ * render in the detected dialect too. Reads no config — detection is
+ * pure method + path + headers.
+ */
+function detectSourceMiddleware() {
+    return (req, res, next) => {
+        const sourceApi = (0, detect_source_1.detectSource)(req.method, req.path, req.headers);
+        if (sourceApi) {
+            res.locals.sourceApi = sourceApi;
+        }
+        next();
+    };
+}

package/dist/middleware/error-handler.js

@@ -83,6 +83,14 @@ const errorHandler = (err, req, res, _next) => {
     const isProduction = process.env.NODE_ENV === "production";
     const requestId = req.id;
     const sourceApi = res.locals.sourceApi;
+    // §3.4: errors after upstream attempts carry x-babelgate-attempts
+    // (and any other responseHeaders the pipeline attached) — set them
+    // before the dialect rendering below writes the body.
+    if (err instanceof errors_1.ProxyError && err.responseHeaders !== undefined) {
+        for (const [name, value] of Object.entries(err.responseHeaders)) {
+            res.setHeader(name, value);
+        }
+    }
     if (err instanceof errors_1.UpstreamError) {
         logUpstreamError(err, requestId);
     }

package/dist/routes/proxy.js

@@ -21,6 +21,9 @@ exports.proxyRouter.use(async (req, res, next) => {
     });
     try {
         const result = await (0, proxy_service_1.proxyRequest)(req.path, req.method, req.body, String(req.id), {
+            // Client format detected by the middleware; undefined → the
+            // service returns null → 404.
+            source: res.locals.sourceApi,
             query: Object.fromEntries(Object.entries(req.query).map(([k, v]) => [k, String(v)])),
             signal: ac.signal,
         });

package/dist/routing/detect-source.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSource = detectSource;
+const adapters_1 = require("../transformers/adapters");
+/**
+ * Pure request → client-format detection (spec §3.2): the request's
+ * method + path prefix selects the provider whose dialect the client
+ * speaks, over the same PROVIDER_ROUTES table the services match on.
+ *
+ * The only ambiguous route is `GET /v1/models`, shared by openai and
+ * anthropic. Anthropic SDKs always send `anthropic-version`
+ * (@anthropic-ai/sdk client.js:842 — unconditional default header).
+ * Claude Code model discovery does not: its gateway docs ("Model
+ * discovery → Request and response",
+ * https://code.claude.com/docs/en/llm-gateway-protocol) show
+ * `GET /v1/models?limit=1000` carrying `Authorization`, `x-api-key` and
+ * `ANTHROPIC_CUSTOM_HEADERS` — Claude Code ≥ 2.1.248 sends both
+ * credential headers. Either `anthropic-version` or `x-api-key` marks
+ * the client as anthropic; OpenAI SDKs authenticate with
+ * `Authorization: Bearer` alone, so neither header → openai.
+ * `headers` are the request's own (Node lowercases the names).
+ */
+function detectSource(method, path, headers) {
+    const matches = Object.keys(adapters_1.PROVIDER_ROUTES).filter((provider) => adapters_1.PROVIDER_ROUTES[provider].some((r) => r.method === method && path.startsWith(r.pathPrefix)));
+    if (matches.length === 0)
+        return undefined;
+    const headerNames = new Set(Object.keys(headers).map((name) => name.toLowerCase()));
+    const anthropicClient = headerNames.has("anthropic-version") || headerNames.has("x-api-key");
+    if (anthropicClient && matches.includes("anthropic")) {
+        return "anthropic";
+    }
+    return matches[0];
+}

package/dist/routing/fallback.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hopOutcome = hopOutcome;
+exports.isFallbackEligible = isFallbackEligible;
+const errors_1 = require("../utils/errors");
+/** Upstream statuses that move the request to the next route target. */
+const FALLBACK_STATUSES = new Set([429, 500, 502, 503, 504, 529]);
+/**
+ * The hop's outcome for the spec §3.4 route log line, classified from
+ * the UpstreamError shapes http-client produces: `upstreamStatus` set →
+ * "http_error"; no status with a 504 client code → "timeout"; no status
+ * with a 502 client code → "transport". Anything that isn't an
+ * UpstreamError never reached the upstream — undefined, not a hop
+ * outcome.
+ */
+function hopOutcome(err) {
+    if (!(err instanceof errors_1.UpstreamError))
+        return undefined;
+    if (err.upstreamStatus !== undefined)
+        return "http_error";
+    return err.statusCode === 504 ? "timeout" : "transport";
+}
+/**
+ * Fallback-eligible failures, exactly the spec §3.4 list: transport
+ * failure; header/connect timeout; upstream 429, 500, 502, 503, 504,
+ * 529. Everything else — client-facing 4xx, a non-JSON 2xx body, errors
+ * raised before the upstream call (validation, transform) — fails
+ * immediately.
+ */
+function isFallbackEligible(err) {
+    if (!(err instanceof errors_1.UpstreamError))
+        return false;
+    if (err.upstreamStatus === undefined) {
+        return err.statusCode === 502 || err.statusCode === 504;
+    }
+    return FALLBACK_STATUSES.has(err.upstreamStatus);
+}

package/dist/routing/plan-route.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planRoute = planRoute;
+const rules_1 = require("./rules");
+/**
+ * Pure model → route resolution (spec §3.3): no I/O, clock or
+ * randomness. Resolution order:
+ *   1. explicit `provider/model` (first-`/` prefix is a registered
+ *      provider) — rules are skipped;
+ *   2. alias — exact, case-sensitive name;
+ *   3. routes in order — first `match` glob whose `when` also holds;
+ *   4. the default provider, model unchanged.
+ * `targets` is the matched target followed by its fallback list;
+ * explicit, alias and default plans carry no fallbacks.
+ */
+function planRoute(input) {
+    const explicit = (0, rules_1.parseTarget)(input.requestedModel, input.providerNames);
+    if (explicit !== undefined) {
+        return { targets: [explicit], reason: "explicit" };
+    }
+    const alias = Object.hasOwn(input.routing.aliases, input.requestedModel)
+        ? input.routing.aliases[input.requestedModel]
+        : undefined;
+    if (alias !== undefined) {
+        return { targets: [alias], reason: `alias:${input.requestedModel}` };
+    }
+    for (const [index, rule] of input.routing.rules.entries()) {
+        if (!(0, rules_1.globMatch)(rule.match, input.requestedModel))
+            continue;
+        const min = rule.when?.minInputTokens;
+        if (min !== undefined && input.estimatedInputTokens < min)
+            continue;
+        return {
+            targets: [rule.to, ...rule.fallback],
+            reason: `rule:${index}`,
+        };
+    }
+    return {
+        targets: [
+            {
+                provider: input.routing.defaultProvider,
+                model: input.requestedModel,
+            },
+        ],
+        reason: "default",
+    };
+}

package/dist/routing/registry.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRegistry = createRegistry;
+exports.authHeaders = authHeaders;
+const errors_1 = require("../utils/errors");
+/** A duplicate provider name is a startup error, never a silent win. */
+function createRegistry(entries) {
+    const byName = new Map();
+    for (const entry of entries) {
+        if (byName.has(entry.name)) {
+            throw new errors_1.ConfigurationError(`Duplicate provider name: ${entry.name}`);
+        }
+        byName.set(entry.name, entry);
+    }
+    return {
+        get(name) {
+            const entry = byName.get(name);
+            if (entry === undefined) {
+                throw new errors_1.ConfigurationError(`Unknown provider: ${name}`);
+            }
+            return entry;
+        },
+        has: (name) => byName.has(name),
+        names: () => [...byName.keys()],
+    };
+}
+/**
+ * Provider-specific auth headers — the body of proxy.service's former
+ * buildAuthHeaders, now keyed on the provider entry.
+ */
+function authHeaders(entry) {
+    if (!entry.apiKey)
+        return {};
+    switch (entry.type) {
+        case "openai":
+            return { Authorization: `Bearer ${entry.apiKey}` };
+        case "anthropic":
+            return {
+                "x-api-key": entry.apiKey,
+                "anthropic-version": "2023-06-01",
+            };
+        case "gemini":
+            return { "x-goog-api-key": entry.apiKey };
+        case "ollama":
+            return {};
+    }
+}

package/dist/routing/route-log.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logRoute = logRoute;
+const logger_1 = require("../utils/logger");
+/** One info line per chat request, replacing "Request completed". */
+function logRoute(record) {
+    logger_1.logger.info(record, "Request completed");
+}

package/dist/routing/rules.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globMatch = globMatch;
+exports.parseTarget = parseTarget;
+/** `*` matches any run of characters; every other character is literal. */
+function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+/**
+ * Glob test used by routing rules — the matcher moved here unchanged
+ * from utils/model-map.ts (spec §3.3: `*` matches any run of
+ * characters; everything else is literal).
+ */
+function globMatch(pattern, value) {
+    return globToRegExp(pattern).test(value);
+}
+/**
+ * `provider/model` → {provider, model} (spec §3.3): splits on the
+ * first `/` only, and only when the prefix is a registered provider
+ * name (case-sensitive) and the rest is non-empty — model names may
+ * contain `/` and `:`. Anything else is not a target.
+ */
+function parseTarget(text, providerNames) {
+    const slash = text.indexOf("/");
+    if (slash === -1)
+        return undefined;
+    const provider = text.slice(0, slash);
+    const model = text.slice(slash + 1);
+    if (model === "" || !providerNames.has(provider))
+        return undefined;
+    return { provider, model };
+}

package/dist/routing/table.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRoutingTable = formatRoutingTable;
+/**
+ * The startup routing table (spec §3.5): one line per provider, one per
+ * alias, one per route in order, then the default. Key env var names
+ * may be shown; key values never are.
+ */
+function formatRoutingTable(config) {
+    const lines = [];
+    for (const name of config.registry.names()) {
+        const entry = config.registry.get(name);
+        const key = entry.apiKeyEnv !== undefined ? `env ${entry.apiKeyEnv}` : "none";
+        lines.push(`provider ${name} (type ${entry.type}, ${entry.baseUrl}, key ${key})`);
+    }
+    for (const [name, target] of Object.entries(config.routing.aliases)) {
+        lines.push(`alias ${name} -> ${target.provider}/${target.model}`);
+    }
+    for (const [index, rule] of config.routing.rules.entries()) {
+        const when = rule.when?.minInputTokens !== undefined
+            ? ` when min_input_tokens>=${rule.when.minInputTokens}`
+            : "";
+        const fallback = rule.fallback.length > 0
+            ? ` fallback ${rule.fallback
+                .map((target) => `${target.provider}/${target.model}`)
+                .join(", ")}`
+            : "";
+        lines.push(`route ${index} ${rule.match}${when} -> ${rule.to.provider}/${rule.to.model}${fallback}`);
+    }
+    lines.push(`default -> ${config.routing.defaultProvider}`);
+    return lines;
+}

package/dist/services/attempt-targets.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toClientFacing = toClientFacing;
+exports.canonicalForTarget = canonicalForTarget;
+exports.attemptTargets = attemptTargets;
+const fallback_1 = require("../routing/fallback");
+const errors_1 = require("../utils/errors");
+const upstream_errors_1 = require("./upstream-errors");
+/**
+ * Attach the spec §3.3 client-facing rendering to an upstream failure
+ * (moved from proxy.service). Only real upstream error statuses (≥ 400)
+ * go through the mapping table — timeouts, transport failures and
+ * non-JSON 2xx replies already carry their final client-facing message.
+ */
+function toClientFacing(err, target) {
+    if (err.upstreamStatus !== undefined && err.upstreamStatus >= 400) {
+        err.clientError = (0, upstream_errors_1.toClientError)(target, err.upstreamStatus, err.upstreamBody, err.retryAfterSeconds);
+    }
+    return err;
+}
+/**
+ * The canonical request this attempt sends upstream: the routed model
+ * and the target provider's contextWindow (unset → config untouched,
+ * spec §3.1), set on a COPY — the decoded request is never mutated.
+ */
+function canonicalForTarget(canonical, entry, target) {
+    const out = { ...canonical, model: target.model };
+    if (entry.contextWindow !== undefined) {
+        out.config = { ...canonical.config, contextWindow: entry.contextWindow };
+    }
+    return out;
+}
+/**
+ * The fallback loop shared by both chat services (spec §3.4): try each
+ * of plan's targets in order. A client abort rethrows immediately —
+ * no further target is tried. A fallback-eligible failure with targets
+ * remaining records its hop and continues; anything else, and the last
+ * target's error, carries `x-babelgate-attempts` in responseHeaders and
+ * is rethrown. `ctx.hops`, when given, is filled with every upstream
+ * hop (ok and failed) so the caller can emit the route log line even on
+ * failure; the same array is returned on success.
+ */
+async function attemptTargets(plan, registry, attempt, ctx) {
+    const hops = ctx.hops ?? [];
+    for (const [index, target] of plan.targets.entries()) {
+        const entry = registry.get(target.provider);
+        const start = Date.now();
+        try {
+            const value = await attempt(entry, target);
+            hops.push({
+                provider: target.provider,
+                model: target.model,
+                outcome: "ok",
+                ms: Date.now() - start,
+            });
+            return { value, target, entry, hops };
+        }
+        catch (err) {
+            // Client went away — stop; try no further target.
+            if (ctx.signal?.aborted)
+                throw err;
+            // Only upstream failures are hops: an error raised before the
+            // request left (validation, transform) is no route outcome.
+            const outcome = (0, fallback_1.hopOutcome)(err);
+            if (outcome !== undefined) {
+                hops.push({
+                    provider: target.provider,
+                    model: target.model,
+                    outcome,
+                    ...(outcome === "http_error"
+                        ? { status: err.upstreamStatus }
+                        : {}),
+                    ms: Date.now() - start,
+                });
+            }
+            if (index < plan.targets.length - 1 &&
+                (0, fallback_1.isFallbackEligible)(err)) {
+                continue;
+            }
+            if (err instanceof errors_1.ProxyError) {
+                err.responseHeaders = {
+                    ...err.responseHeaders,
+                    "x-babelgate-attempts": String(index + 1),
+                };
+            }
+            throw err;
+        }
+    }
+    // plan.targets is never empty (planRoute always returns ≥ 1 target).
+    throw new Error("attemptTargets: plan has no targets");
+}