proxitor 0.8.0 → 0.9.0-beta.0

package/README.md

@@ -250,6 +250,41 @@ provider:
     p90: 3                    # seconds (soft threshold)
 ```
 
+### Prompt caching
+
+By default, OpenRouter doesn't enable prompt caching — every request pays full token price. Proxitor can inject `cache_control` and `session_id` to make caching work automatically.
+
+**`cacheControl`** — injects `cache_control: { "type": "ephemeral" }` into the request body. OpenRouter uses this to set cache breakpoints and advance them as conversations grow.
+
+**`sessionId`** — injects `session_id` for provider sticky routing. Without it, OpenRouter only pins to a provider after detecting a cache hit. With it, routing sticks from the **first request** — critical for OpenAI models where delayed caching means 0 cached tokens on the first 1-2 requests.
+
+Both support `auto` / `always` / `never` modes:
+
+| Mode | `cacheControl` | `sessionId` |
+|---|---|---|
+| `auto` (default) | Anthropic models on `/v1/chat/completions`; all models on `/v1/messages` and `/v1/responses` | Use `X-Claude-Code-Session-Id` header if present; otherwise generate proxy UUID |
+| `always` | All models, all endpoints | Generate a proxy UUID for sticky routing |
+| `never` | Disabled | Disabled |
+
+```yaml
+cacheControl: auto    # safe default — Anthropic and safe endpoints only
+sessionId: auto       # always ensures sticky routing (client header or proxy UUID)
+
+# Force caching for all models (may cause 400 on non-Anthropic /v1/chat/completions)
+# cacheControl: always
+
+# Per-model overrides
+modelOverrides:
+  "gpt-*":
+    cacheControl: never   # OpenAI caches automatically, no injection needed
+    sessionId: always      # but sticky routing still helps
+```
+
+**Why both matter:**
+- **Anthropic models** — `cache_control` activates caching, `session_id` prevents provider flip-flopping that would invalidate it
+- **OpenAI models** — caching is automatic (no `cache_control` needed), but `session_id` ensures sticky routing from request #1 instead of waiting for a cache hit
+- **All models** — `session_id` prevents the provider switch that silently resets cache
+
 ### Health check
 
 ```sh

package/dist/cli.mjs

@@ -10580,9 +10580,16 @@ const providerConfigSchema = object({
 	preferredMinThroughput: union([number$1().positive(), percentileCutoffsSchema]).optional(),
 	preferredMaxLatency: union([number$1().positive(), percentileCutoffsSchema]).optional()
 }).strict();
+const triStateSchema = _enum([
+	"auto",
+	"always",
+	"never"
+]);
 const modelOverrideSchema = object({
 	provider: providerConfigSchema.optional(),
-	headers: record(string$1(), string$1()).optional()
+	headers: record(string$1(), string$1()).optional(),
+	cacheControl: triStateSchema.optional(),
+	sessionId: triStateSchema.optional()
 }).strict();
 const proxyConfigSchema = object({
 	host: string$1().min(1).default("0.0.0.0"),
@@ -10597,6 +10604,8 @@ const proxyConfigSchema = object({
 	attributionReferer: string$1().min(1).default("https://github.com/neiromaster/proxitor"),
 	attributionTitle: string$1().min(1).default("proxitor"),
 	headers: record(string$1(), string$1()).optional(),
+	cacheControl: triStateSchema.default("auto"),
+	sessionId: triStateSchema.default("auto"),
 	modelOverrides: record(string$1().min(1), modelOverrideSchema).optional()
 }).strict();
 const DEFAULTS = proxyConfigSchema.parse({});
@@ -10716,27 +10725,36 @@ function matchScore(pattern, modelName) {
 function resolveModelConfig(config, modelName) {
 	const result = {
 		provider: config.provider,
-		headers: config.headers ? { ...config.headers } : void 0
+		headers: config.headers ? { ...config.headers } : void 0,
+		cacheControl: config.cacheControl,
+		sessionId: config.sessionId
 	};
 	if (!modelName || !config.modelOverrides) return result;
+	const bestPattern = findBestMatch(Object.keys(config.modelOverrides), modelName);
+	if (bestPattern) applyOverride(result, config.modelOverrides[bestPattern]);
+	return result;
+}
+function findBestMatch(patterns, modelName) {
 	let bestPattern = null;
 	let bestScore = -1;
-	for (const pattern of Object.keys(config.modelOverrides)) {
+	for (const pattern of patterns) {
 		const score = matchScore(pattern, modelName);
 		if (score > bestScore) {
 			bestScore = score;
 			bestPattern = pattern;
 		}
 	}
-	if (bestPattern) {
-		const override = config.modelOverrides[bestPattern];
-		if (override?.provider !== void 0) result.provider = override.provider;
-		if (override?.headers) result.headers = {
-			...result.headers ?? {},
-			...override.headers
-		};
-	}
-	return result;
+	return bestPattern;
+}
+function applyOverride(result, override) {
+	if (!override) return;
+	if (override.provider !== void 0) result.provider = override.provider;
+	if (override.headers) result.headers = {
+		...result.headers ?? {},
+		...override.headers
+	};
+	if (override.cacheControl !== void 0) result.cacheControl = override.cacheControl;
+	if (override.sessionId !== void 0) result.sessionId = override.sessionId;
 }
 async function loadConfig(options) {
 	let fileConfig = {};
@@ -14606,7 +14624,9 @@ const STRIP_REQUEST = new Set([
 	"authorization",
 	"x-api-key",
 	"host",
-	"content-length"
+	"content-length",
+	"x-claude-code-session-id",
+	"x-session-id"
 ]);
 /** Headers to strip from upstream response before forwarding */
 const STRIP_RESPONSE = new Set(["content-length", "content-encoding"]);
@@ -14755,25 +14775,34 @@ function buildUpstreamResponseWithLogging(upstream, method, reqId) {
 }
 //#endregion
 //#region src/proxy/inject.ts
-/** Extract the model name from a raw request body. Returns undefined if not parseable or absent. */
+function isAnthropicModel(modelName) {
+	const lower = modelName.toLowerCase();
+	return lower.startsWith("anthropic/claude") || lower.startsWith("claude-") || lower.includes("claude");
+}
 function extractModel(rawBody) {
 	const json = tryParseBody(rawBody);
 	return typeof json?.model === "string" ? json.model : void 0;
 }
-/** Inject provider routing into request body, always overwriting existing value */
-function injectProvider(rawBody, providerRouting) {
-	if (rawBody.byteLength === 0) throw new Error("Request body is empty; cannot inject provider");
+function injectBodyFields(rawBody, params) {
+	if (rawBody.byteLength === 0) throw new Error("Request body is empty; cannot inject");
 	let json;
 	try {
 		json = JSON.parse(new TextDecoder().decode(rawBody));
 	} catch (parseError) {
-		throw new Error("Request body is not valid JSON; cannot inject provider", { cause: parseError });
+		throw new Error("Request body is not valid JSON; cannot inject", { cause: parseError });
+	}
+	if (params.providerRouting !== void 0) json.provider = params.providerRouting;
+	if (params.cacheControl && !("cache_control" in json)) json.cache_control = { type: "ephemeral" };
+	let effectiveSessionId;
+	if (params.sessionId) if ("session_id" in json) effectiveSessionId = String(json.session_id);
+	else {
+		json.session_id = params.sessionId;
+		effectiveSessionId = params.sessionId;
 	}
-	const modified = {
-		...json,
-		provider: providerRouting
+	return {
+		body: new TextEncoder().encode(JSON.stringify(json)).buffer,
+		effectiveSessionId
 	};
-	return new TextEncoder().encode(JSON.stringify(modified)).buffer;
 }
 //#endregion
 //#region src/proxy/paths.ts
@@ -14805,10 +14834,18 @@ function buildUpstreamUrl(requestUrl, config) {
 }
 //#endregion
 //#region src/proxy.ts
-function readRequestBody(method, raw, inject, providerRouting) {
-	if (["GET", "HEAD"].includes(method)) return void 0;
-	if (inject) return injectProvider(raw, providerRouting);
-	return raw.byteLength > 0 ? raw : void 0;
+const PROXY_SESSION_ID = crypto.randomUUID();
+function deriveSessionId(incomingHeaders, mode) {
+	if (mode === "never") return void 0;
+	const fromClient = incomingHeaders.get("x-claude-code-session-id");
+	if (fromClient) return fromClient.slice(0, 256);
+	return PROXY_SESSION_ID;
+}
+function shouldInjectCacheControl(mode, modelName, path) {
+	if (mode === "never") return false;
+	if (mode === "always") return true;
+	if (path === "/v1/chat/completions" && !isAnthropicModel(modelName ?? "")) return false;
+	return true;
 }
 async function fetchUpstream(url, method, headers, body, signal) {
 	return fetch(url, {
@@ -14837,36 +14874,68 @@ async function readRawBody(request, reqId) {
 		};
 	}
 }
-function resolveRequest(rawBody, config, method, path, reqId) {
+function isReadonlyMethod(method) {
+	return method === "GET" || method === "HEAD";
+}
+function computeInjection(rawBody, config, path, incomingHeaders) {
 	const modelName = extractModel(rawBody);
 	const resolved = resolveModelConfig(config, modelName);
 	const providerRouting = buildProviderRouting(resolved.provider);
-	const inject = shouldInject(method, path) && providerRouting !== void 0;
+	if (!shouldInject("POST", path)) return {
+		modelName,
+		resolved,
+		inject: false
+	};
+	const cacheControlMode = resolved.cacheControl ?? "auto";
+	const sessionIdMode = resolved.sessionId ?? "auto";
+	const injectCacheControl = shouldInjectCacheControl(cacheControlMode, modelName, path);
+	const sessionId = deriveSessionId(incomingHeaders, sessionIdMode);
+	if (providerRouting === void 0 && !injectCacheControl && sessionId === void 0) return {
+		modelName,
+		resolved,
+		inject: false
+	};
+	return {
+		modelName,
+		resolved,
+		inject: true,
+		params: {
+			providerRouting,
+			cacheControl: injectCacheControl,
+			sessionId
+		},
+		sessionId
+	};
+}
+function resolveRequest(rawBody, config, method, path, reqId, incomingHeaders) {
+	const decision = computeInjection(rawBody, config, path, incomingHeaders);
 	let body;
+	let bodyModified = false;
+	let effectiveSessionId;
 	try {
-		body = readRequestBody(method, rawBody, inject, providerRouting);
+		if (decision.inject) {
+			const result = injectBodyFields(rawBody, decision.params);
+			body = result.body;
+			bodyModified = true;
+			effectiveSessionId = result.effectiveSessionId;
+		} else if (!isReadonlyMethod(method)) body = rawBody.byteLength > 0 ? rawBody : void 0;
 	} catch (err) {
 		const message = err instanceof Error ? err.message : "Failed to process request body";
-		logger.error(withReq(reqId, message));
-		return {
-			inject,
-			body: void 0,
-			modelName,
-			headers: resolved.headers,
-			error: new Response(JSON.stringify({ error: {
-				message,
-				type: "proxy_request_error"
-			} }), {
-				status: 400,
-				headers: { "Content-Type": "application/json" }
-			})
-		};
+		if (!isReadonlyMethod(method) && rawBody.byteLength > 0) {
+			body = rawBody;
+			logger.warn(withReq(reqId, `${message}; forwarding body as-is`));
+		} else {
+			body = void 0;
+			logger.warn(withReq(reqId, message));
+		}
 	}
+	const finalHeaders = { ...decision.resolved.headers ?? {} };
+	if (effectiveSessionId !== void 0) finalHeaders["x-session-id"] = effectiveSessionId;
 	return {
-		inject,
+		inject: bodyModified,
 		body,
-		modelName,
-		headers: resolved.headers
+		modelName: decision.modelName,
+		headers: finalHeaders
 	};
 }
 /**
@@ -14956,7 +15025,7 @@ function createProxyServer(config, onReady) {
 		const reqId = requestId();
 		const raw = await readRawBody(c.req.raw, reqId);
 		if (!raw.ok) return raw.response;
-		const resolved = resolveRequest(raw.body, config, method, path, reqId);
+		const resolved = resolveRequest(raw.body, config, method, path, reqId, c.req.raw.headers);
 		if (resolved.error) return resolved.error;
 		const headers = buildRequestHeaders(c.req.raw.headers, config, resolved.inject, resolved.headers);
 		const controller = new AbortController();
@@ -14996,7 +15065,7 @@ function startProxyServer(config, onReady) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.8.0";
+const version = "0.9.0-beta.0";
 //#endregion
 //#region src/cli.ts
 const argv = process.argv.slice(2);