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

## Description

`HeadroomClient.rawFetch()` and `HeadroomClient._fetch()` in
`sdk/typescript/src/client.ts` each carried their own copy of the same
transport: URL construction, the `Content-Type` default and
caller-header merge, proxy auth, the `X-Headroom-Stack` guard, `fetch`
with `AbortSignal.timeout`, `HeadroomConnectionError` wrapping, and
non-ok response parsing into `mapProxyError`. The two differed only in
body handling — `rawFetch()` serializes a structured body, `_fetch()`
takes an already-serialized string — and in auth, where `rawFetch()`
refuses to override a provider credential.

`rawFetch()` now sends a `string` body as-is and JSON-serializes
anything else, so `_fetch()` collapses to a typed delegate and the
transport exists once. `client.ts` goes from 632 to 598 lines. This is a
maintenance-only cleanup flagged in the repository efficiency audit;
there is no performance claim.

Nothing observable changes. `_fetch()` is `private` with 25 call sites,
all in `client.ts`, and none passes `headers`, so `rawFetch()`'s "don't
override provider auth" guard resolves exactly the way `_fetch()`'s
unconditional `Authorization` assignment did. Provider-credential
handling itself is untouched.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- `sdk/typescript/src/client.ts`: `rawFetch()` keeps the single
transport implementation; its body argument is now `typeof options.body
=== "string" ? options.body : options.body ?
JSON.stringify(options.body) : undefined`, still evaluated inside the
existing `try`, so an unserializable body keeps throwing
`HeadroomConnectionError`.
- `sdk/typescript/src/client.ts`: `_fetch()` drops from 47 duplicated
lines to `return this.rawFetch(path, init)`. Its `headers` field — dead
across all 25 call sites — is removed from the init type, so a future
caller that needs headers gets a compile error instead of silently
different auth behavior.
- `sdk/typescript/test/client-expanded.test.ts`: six regression cases in
a new `shared HTTP transport` block, covering body encoding, header
precedence, both provider-auth paths, and the error paths.
- No public signature changes, no new class/helper/options object, no
new dependency. `rawFetch()`'s unused `stream` option is left alone; its
callers read `params.stream` themselves.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

TypeScript-only change, so the Python gates do not apply; the SDK's own
suite, `tsc --noEmit` and `tsup` build are the equivalents and all pass.

### Test Output

```text
$ npm test          # sdk/typescript
 Test Files  18 passed | 5 skipped (23)
      Tests  300 passed | 33 skipped (333)
# base e67b3c8a on the same worktree: 294 passed | 33 skipped (327)

$ npm run typecheck
> tsc --noEmit
# clean, exit 0

$ npm run build
DTS dist/index.d.cts              27.79 KB
DTS dist/adapters/vercel-ai.d.cts 1.95 KB
# clean, exit 0

$ gh pr diff 3450 | git apply --check --3way
Applied patch to 'sdk/typescript/src/client.ts' cleanly.
Applied patch to 'sdk/typescript/test/client-expanded.test.ts' cleanly.
```

## Real Behavior Proof

- Environment: macOS 25.6, Node 22 / npm, fresh worktree of `main` @
`e67b3c8a`, `npm ci` in `sdk/typescript`.
- Exact command / steps: enumerated every caller (`rawFetch()` — 2
sites, both in `client.ts`; `_fetch()` — 25 sites, all in `client.ts`,
none passing `headers`); ran `npm test`, `npm run typecheck`, `npm run
build`; then mutation-tested each new assertion by editing `client.ts`
and re-running `npx vitest run test/client-expanded.test.ts`, restoring
the file after each mutation. Mutations: always-stringify
(double-encodes serialized bodies), never-stringify, drop the
`!headers["Authorization"] && !headers["x-api-key"]` guard, drop the
`Content-Type` default, drop the `X-Headroom-Stack` block, send `{}`
instead of no body.
- Observed result: 294 → 300 passing tests with zero regressions;
typecheck and build clean; every one of the six mutations fails 1–2 of
the new tests, so none of them is decorative. The pre-existing
authentication regressions in `client.test.ts` and `compress.test.ts`
still pass unchanged.
- Not tested: no live proxy or provider traffic — the change is a pure
refactor of client-side request assembly, and every assertion is made on
the exact object handed to `fetch`. Streaming was not re-exercised
beyond the existing suite: `parseSSE` consumes the `Response` that
`rawFetch()` already returned unread, and that path is not touched by
this diff.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — this is TypeScript SDK client code
with no rollout gate.
- Minimum rollout channel: n/a; no channel-gated behavior is introduced.
- Stable/default behavior changed: no. Same URL, method, headers, body
bytes, timeout and thrown error types for every existing caller.
- Kill switch / disable path: n/a — revert the commit; there is no
runtime flag to flip.
- Unsafe override required: no.
- Qualification impact: none. No proxy, compression or cache behavior is
involved.
- Rollback path: `git revert` of this single commit; it touches two
files and no persisted state or schema.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Overlap with open PR #3450 (`fix(sdk): preserve proxy authentication
alongside provider credentials`): that PR adds one line inside
`rawFetch()`'s `if (this.apiKey)` block, which this PR does not touch,
and its tests land at the top of `client-expanded.test.ts` while these
land at the bottom. `gh pr diff 3450 | git apply --check --3way` against
this branch reports both files applying cleanly, in either merge order.

One combined effect is worth naming: once both land,
`X-Headroom-Proxy-Token` will also be sent on the proxy-only endpoints
that previously went through `_fetch()`. That is harmless —
`read_proxy_token()` (`headroom/proxy/server.py:2618`) prefers that
header and otherwise falls back to the `Authorization: Bearer` token
those same requests already carry, so the proxy reads an identical
credential either way.

Documentation checkbox is unticked because no documented behavior or
public signature changed; `rawFetch()` is `@internal` and `_fetch()` is
private.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
trs-80
2026-09-24 16:52:47 -05:00
committed by GitHub
co-authored by Claude Opus 5
parent ca4b47a3fc
commit b2b58474c4
2 changed files with 88 additions and 45 deletions
+11 -45
View File
@@ -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(
@@ -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);
});
});