Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

refactor(sdk): route _fetch through rawFetch instead of duplicating it (#3473)

trs-80b2b58474c4a3
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index 9b837ef3b..dbfa71fd6 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -498,6 +498,7 @@ export class HeadroomClient implements HeadroomClientInterface {
/**
* Raw fetch with proxy base URL, auth, and timeout.
+ * A string body is sent as-is; anything else is JSON-serialized.
* @internal
*/
async rawFetch(
@@ -525,7 +526,12 @@ export class HeadroomClient implements HeadroomClientInterface {
response = await fetch(url, {
method: options.method,
headers,
- body: options.body ? JSON.stringify(options.body) : undefined,
+ body:
+ typeof options.body === "string"
+ ? options.body
+ : options.body
+ ? JSON.stringify(options.body)
+ : undefined,
signal: AbortSignal.timeout(this.timeout),
});
} catch (error) {
@@ -551,52 +557,12 @@ export class HeadroomClient implements HeadroomClientInterface {
return response;
}
- /** @internal */
- private async _fetch(
+ /** Proxy-only endpoints, whose bodies are already serialized. @internal */
+ private _fetch(
path: string,
- init: { method: string; body?: string; headers?: Record<string, string> },
+ init: { method: string; body?: string },
): Promise<Response> {
- const url = `${this.baseUrl}${path}`;
- const headers: Record<string, string> = {
- "Content-Type": "application/json",
- ...init.headers,
- };
- if (this.apiKey) {
- headers["Authorization"] = `Bearer ${this.apiKey}`;
- }
- if (this.stack && !headers["X-Headroom-Stack"]) {
- headers["X-Headroom-Stack"] = this.stack;
- }
-
- let response: Response;
- try {
- response = await fetch(url, {
- method: init.method,
- headers,
- body: init.body,
- signal: AbortSignal.timeout(this.timeout),
- });
- } catch (error) {
- throw new HeadroomConnectionError(
- `Failed to connect to Headroom at ${this.baseUrl}: ${error}`,
- );
- }
-
- if (!response.ok) {
- let errorBody: ProxyErrorResponse | undefined;
- try {
- errorBody = (await response.json()) as ProxyErrorResponse;
- } catch {
- // ignore
- }
- throw mapProxyError(
- response.status,
- errorBody?.error?.type ?? "unknown",
- errorBody?.error?.message ?? `HTTP ${response.status}`,
- );
- }
-
- return response;
+ return this.rawFetch(path, init);
}
private async _doCompress(
diff --git a/sdk/typescript/test/client-expanded.test.ts b/sdk/typescript/test/client-expanded.test.ts
index f982470a1..ce6754ced 100644
--- a/sdk/typescript/test/client-expanded.test.ts
+++ b/sdk/typescript/test/client-expanded.test.ts
@@ -4,6 +4,7 @@
*/
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { HeadroomClient } from "../src/client.js";
+import { HeadroomConnectionError } from "../src/types.js";
const mockFetch = vi.fn();
vi.stubGlobal("fetch", mockFetch);
@@ -371,3 +372,79 @@ describe("HeadroomClient config passthrough", () => {
expect(body.config.smart_crusher.min_tokens_to_crush).toBe(100);
});
});
+
+describe("shared HTTP transport", () => {
+ beforeEach(() => {
+ mockFetch.mockReset();
+ });
+
+ it("serializes structured bodies once and sends serialized bodies verbatim", async () => {
+ mockFetch.mockResolvedValue(jsonResponse({ ok: true }));
+ const client = new HeadroomClient({ baseUrl: "http://test:8787" });
+
+ // Structured body (rawFetch) — serialized exactly once.
+ await client.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "hi" }] });
+ expect(JSON.parse(mockFetch.mock.calls[0][1].body).messages[0].content).toBe("hi");
+
+ // Already-serialized body (_fetch) — passed through, not re-stringified.
+ await client.compressRaw({ messages: [{ role: "user", content: "hi" }] } as any);
+ expect(JSON.parse(mockFetch.mock.calls[1][1].body).messages[0].content).toBe("hi");
+
+ // No body — nothing sent.
+ await client.telemetry.getStats();
+ expect(mockFetch.mock.calls[2][1].body).toBeUndefined();
+ });
+
+ it("keeps proxy headers on requests without provider auth", async () => {
+ mockFetch.mockResolvedValue(jsonResponse({ ok: true }));
+ const client = new HeadroomClient({ baseUrl: "http://test:8787", apiKey: "hr_proxykey", stack: "cli" });
+ await client.telemetry.getStats();
+ const headers = mockFetch.mock.calls[0][1].headers;
+ expect(headers["Content-Type"]).toBe("application/json");
+ expect(headers["Authorization"]).toBe("Bearer hr_proxykey");
+ expect(headers["X-Headroom-Stack"]).toBe("cli");
+ });
+
+ it("does not overwrite provider auth headers with the proxy apiKey", async () => {
+ mockFetch.mockResolvedValue(jsonResponse({ choices: [] }));
+ const client = new HeadroomClient({
+ baseUrl: "http://test:8787",
+ apiKey: "hr_proxykey",
+ providerApiKey: "sk-provider",
+ });
+ await client.chat.completions.create({ model: "gpt-4o", messages: [] });
+ expect(mockFetch.mock.calls[0][1].headers["Authorization"]).toBe("Bearer sk-provider");
+
+ await client.messages.create({ model: "claude-3", messages: [] } as any);
+ const anthropicHeaders = mockFetch.mock.calls[1][1].headers;
+ expect(anthropicHeaders["x-api-key"]).toBe("sk-provider");
+ expect(anthropicHeaders["Authorization"]).toBeUndefined();
+ });
+
+ it("does not overwrite an environment provider key either", async () => {
+ mockFetch.mockResolvedValue(jsonResponse({ choices: [] }));
+ vi.stubEnv("OPENAI_API_KEY", "sk-env-provider");
+ const client = new HeadroomClient({ baseUrl: "http://test:8787", apiKey: "hr_proxykey" });
+ await client.chat.completions.create({ model: "gpt-4o", messages: [] });
+ expect(mockFetch.mock.calls[0][1].headers["Authorization"]).toBe("Bearer sk-env-provider");
+ vi.unstubAllEnvs();
+ });
+
+ it("maps non-ok responses with non-JSON bodies", async () => {
+ mockFetch.mockResolvedValue({
+ ok: false,
+ status: 502,
+ json: async () => {
+ throw new Error("not json");
+ },
+ });
+ const client = new HeadroomClient({ baseUrl: "http://test:8787" });
+ await expect(client.telemetry.getStats()).rejects.toThrow("HTTP 502");
+ });
+
+ it("wraps connection failures", async () => {
+ mockFetch.mockRejectedValue(new TypeError("fetch failed"));
+ const client = new HeadroomClient({ baseUrl: "http://test:8787" });
+ await expect(client.telemetry.getStats()).rejects.toThrow(HeadroomConnectionError);
+ });
+});