@oscharko-dev/keiko-model-gateway 0.2.0

package/dist/resilience.js

@@ -0,0 +1,182 @@
+// Resilience primitives: a real-time Clock, a bounded exponential-backoff retry
+// loop, and a per-(model,endpoint) circuit breaker. All time-dependent behaviour
+// flows through the injectable Clock so tests are deterministic and instant.
+import { CancelledError, CircuitOpenError, GatewayError, RateLimitError, } from "@oscharko-dev/keiko-security/errors/gateway";
+const MAX_BACKOFF_MS = 30_000;
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => {
+        if (signal?.aborted === true) {
+            return Promise.reject(new DOMException("cancelled", "AbortError"));
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            function onAbort() {
+                clearTimeout(timeout);
+                reject(new DOMException("cancelled", "AbortError"));
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    },
+};
+function backoffDelayMs(attempt, base) {
+    return Math.min(base * 2 ** (attempt - 1), MAX_BACKOFF_MS);
+}
+// A RateLimitError with an explicit retryAfterMs is honoured; otherwise the error's
+// own `retryable` flag decides. Non-GatewayErrors are never retried.
+function retryDelayMs(error, attempt, base) {
+    if (!(error instanceof GatewayError) || !error.retryable) {
+        return null;
+    }
+    if (error instanceof RateLimitError && error.retryAfterMs !== null && error.retryAfterMs > 0) {
+        return Math.min(error.retryAfterMs, MAX_BACKOFF_MS);
+    }
+    return backoffDelayMs(attempt, base);
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new CancelledError("request cancelled during retry");
+    }
+}
+function remainingBudgetMs(start, timeoutMs, clock) {
+    if (timeoutMs === undefined) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return Math.max(0, timeoutMs - (clock.now() - start));
+}
+function asError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+}
+async function sleepWithCancellation(clock, delayMs, signal) {
+    assertNotAborted(signal);
+    try {
+        await clock.sleep(delayMs, signal);
+    }
+    catch (error) {
+        if (signal?.aborted === true) {
+            throw new CancelledError("request cancelled during retry backoff");
+        }
+        throw error;
+    }
+    assertNotAborted(signal);
+}
+export async function executeWithRetry(operation, config, clock, signal) {
+    let lastError;
+    const start = clock.now();
+    for (let attempt = 1; attempt <= config.maxRetries + 1; attempt += 1) {
+        assertNotAborted(signal);
+        const attemptBudget = remainingBudgetMs(start, config.timeoutMs, clock);
+        if (attemptBudget <= 0) {
+            if (lastError) {
+                throw lastError;
+            }
+            throw new CancelledError("request timeout budget exhausted before provider call");
+        }
+        try {
+            return await operation(Number.isFinite(attemptBudget) ? Math.max(1, Math.floor(attemptBudget)) : undefined);
+        }
+        catch (error) {
+            lastError = asError(error);
+            const delay = attempt <= config.maxRetries
+                ? retryDelayMs(lastError, attempt, config.retryBaseDelayMs)
+                : null;
+            if (delay === null) {
+                throw lastError;
+            }
+            const remaining = remainingBudgetMs(start, config.timeoutMs, clock);
+            if (remaining <= 0) {
+                throw lastError;
+            }
+            await sleepWithCancellation(clock, Math.min(delay, remaining), signal);
+        }
+    }
+    throw lastError ?? new CancelledError("request timeout budget exhausted after retries");
+}
+export class CircuitBreaker {
+    modelId;
+    config;
+    clock;
+    state = "closed";
+    consecutiveFailures = 0;
+    openedAt = null;
+    probesRemaining = 0;
+    // Tracks how many half-open probe slots are currently in-flight.
+    probesInFlight = 0;
+    constructor(modelId, config, clock) {
+        this.modelId = modelId;
+        this.config = config;
+        this.clock = clock;
+    }
+    // Called before forwarding a request. Throws CircuitOpenError when the breaker is
+    // open and the cooldown has not elapsed; otherwise lets the call through (entering
+    // half-open as a side effect when cooldown has passed).
+    // In half-open, at most config.halfOpenProbes concurrent probes are admitted; excess
+    // callers receive CircuitOpenError until a probe slot is freed by recordSuccess/Failure.
+    assertAllowed() {
+        if (this.state === "open") {
+            if (this.openedAt !== null && this.clock.now() - this.openedAt >= this.config.cooldownMs) {
+                this.state = "half-open";
+                this.probesRemaining = this.config.halfOpenProbes;
+                this.probesInFlight = 0;
+            }
+            else {
+                throw new CircuitOpenError(`circuit open for model '${this.modelId}'`);
+            }
+        }
+        if (this.state === "half-open") {
+            if (this.probesInFlight >= this.config.halfOpenProbes) {
+                throw new CircuitOpenError(`circuit half-open for model '${this.modelId}'`);
+            }
+            this.probesInFlight += 1;
+        }
+    }
+    recordSuccess() {
+        if (this.state === "half-open") {
+            this.probesInFlight = Math.max(0, this.probesInFlight - 1);
+            this.probesRemaining -= 1;
+            if (this.probesRemaining <= 0) {
+                this.close();
+            }
+            return;
+        }
+        this.consecutiveFailures = 0;
+    }
+    recordFailure() {
+        if (this.state === "half-open") {
+            this.probesInFlight = Math.max(0, this.probesInFlight - 1);
+            this.open();
+            return;
+        }
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.config.failureThreshold) {
+            this.open();
+        }
+    }
+    status(modelId) {
+        return {
+            modelId,
+            state: this.state,
+            consecutiveFailures: this.consecutiveFailures,
+            openedAt: this.openedAt,
+        };
+    }
+    open() {
+        this.state = "open";
+        this.openedAt = this.clock.now();
+        this.probesRemaining = 0;
+        this.probesInFlight = 0;
+    }
+    close() {
+        this.state = "closed";
+        this.consecutiveFailures = 0;
+        this.openedAt = null;
+        this.probesRemaining = 0;
+        this.probesInFlight = 0;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+import type { ModelCapability, NormalizedResponse, GatewayRequest } from "@oscharko-dev/keiko-contracts";
+import type { GroundingLimits } from "@oscharko-dev/keiko-contracts/bff-wire";
+export type { ModelKind, CostClass, LatencyClass, InfillingAlignment, ModelCapability, CompletionInteractionMode, CompletionDegradeReason, CompletionModelSelection, ChatMessage, ChatMessageContentPart, ChatMessageImageUrlContentPart, ChatMessageTextContentPart, ToolDefinition, ResponseFormat, GatewayRequest, NormalizedToolCall, UsageMetadata, NormalizedResponse, FinishReason, StreamDelta, StreamEvent, } from "@oscharko-dev/keiko-contracts";
+export { CONVERSATION_CAPABILITY_CONTRACT_VERSION } from "@oscharko-dev/keiko-contracts";
+export interface ModelProviderConfig {
+    readonly modelId: string;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly apiKeyHeaderName?: string | undefined;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly egress?: OutboundHttpEgressConfig | undefined;
+}
+export interface OutboundHttpEgressConfig {
+    readonly httpProxy?: string | undefined;
+    readonly httpsProxy?: string | undefined;
+    readonly noProxy?: readonly string[] | undefined;
+    readonly caBundlePath?: string | undefined;
+}
+export interface CircuitBreakerConfig {
+    readonly failureThreshold: number;
+    readonly cooldownMs: number;
+    readonly halfOpenProbes: number;
+}
+export interface FigmaConnectorConfig {
+    readonly accessToken?: string | undefined;
+}
+export interface GatewayConfig {
+    readonly providers: readonly ModelProviderConfig[];
+    readonly circuitBreaker: CircuitBreakerConfig;
+    readonly capabilities?: readonly ModelCapability[] | undefined;
+    readonly grounding?: Partial<GroundingLimits> | undefined;
+    readonly egress?: OutboundHttpEgressConfig | undefined;
+    readonly figma?: FigmaConnectorConfig | undefined;
+}
+export type GatewayStreamChunk = {
+    readonly type: "delta";
+    readonly token: string;
+} | {
+    readonly type: "done";
+    readonly response: NormalizedResponse;
+};
+export interface ProviderAdapter {
+    readonly call: (request: GatewayRequest, config: ModelProviderConfig) => Promise<NormalizedResponse>;
+    readonly callStream?: (request: GatewayRequest, config: ModelProviderConfig) => AsyncIterable<GatewayStreamChunk>;
+}
+export interface Clock {
+    readonly now: () => number;
+    readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerStatus {
+    readonly modelId: string;
+    readonly state: CircuitState;
+    readonly consecutiveFailures: number;
+    readonly openedAt: number | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Re-export shim: wire-safe gateway contract types live in @oscharko-dev/keiko-contracts
+// (issue #158). Credential-bearing / port shapes (ModelProviderConfig, GatewayConfig,
+// CircuitBreakerConfig, ProviderAdapter, Clock, CircuitState, CircuitBreakerStatus) STAY here
+// so contracts never carries an apiKey-shaped surface (ADR-0019 direction 1 contracts-leaf).
+// `verbatimModuleSyntax` is on, so type-only names use `export type`.
+export { CONVERSATION_CAPABILITY_CONTRACT_VERSION } from "@oscharko-dev/keiko-contracts";

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const KEIKO_MODEL_GATEWAY_VERSION: "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Package version constant. Pinned at the workspace package's package.json version. Promoted to
+// a `const` string-literal type so downstream tests/assertions stay byte-exact.
+export const KEIKO_MODEL_GATEWAY_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@oscharko-dev/keiko-model-gateway",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Internal workspace package: Keiko model gateway — provider abstraction, OpenAI-compatible adapter, capability registry, routing, resilience, TLS handling. Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal/http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./internal/normalize": {
+      "types": "./dist/normalize.d.ts",
+      "import": "./dist/normalize.js"
+    },
+    "./internal/openai-adapter": {
+      "types": "./dist/openai-adapter.d.ts",
+      "import": "./dist/openai-adapter.js"
+    },
+    "./internal/resilience": {
+      "types": "./dist/resilience.d.ts",
+      "import": "./dist/resilience.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0"
+  }
+}