mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
@@ -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);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user