sneak/quak
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 4 red: ApiClient tests and stub

Browse Source 
19 tests covering ApiClient's full public surface: default and custom
origins, X-Client-Package and X-Auth-Token headers, getJSON with query
params, postJSON with JSON body, ApiError on 4xx/5xx, streaming file
and thumbnail downloads, and self-hosted origin routing.

Tests inject a recording fetch via the constructor, so nothing hits the
network. The test file is documented to serve as canonical usage
reference per the development workflow.
This commit is contained in:
Jeffrey Paul
2026-05-11 01:01:34 -07:00
parent d8466be0a7
commit ef3f10fecc
2 changed files with 442 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
src/api/client.ts Normal file
View File

@@ -0,0 +1,57 @@
// Stub: see the README "Development workflow" section for TDD policy.
export interface ApiClientOptions {
apiOrigin?: string;
filesOrigin?: string;
thumbsOrigin?: string;
authToken?: string;
fetch?: typeof globalThis.fetch;
userAgent?: string;
}
export class ApiError extends Error {
readonly status: number;
readonly code?: string;
readonly requestID?: string;
readonly body?: unknown;
constructor(
_message: string,
_status: number,
_opts?: { code?: string; requestID?: string; body?: unknown },
) {
super(_message);
this.status = _status;
this.code = _opts?.code;
this.requestID = _opts?.requestID;
this.body = _opts?.body;
}
}
export class ApiClient {
constructor(_opts?: ApiClientOptions) {
throw new Error("ApiClient not implemented");
}
setAuthToken(_token: string): void {
throw new Error("not implemented");
}
clearAuthToken(): void {
throw new Error("not implemented");
}
async getJSON<T>(
_path: string,
_query?: Record<string, string | number | undefined>,
): Promise<T> {
throw new Error("not implemented");
}
async postJSON<T>(_path: string, _body: unknown): Promise<T> {
throw new Error("not implemented");
}
async getFileStream(_fileID: number): Promise<ReadableStream<Uint8Array>> {
throw new Error("not implemented");
}
async getThumbnailStream(
_fileID: number,
): Promise<ReadableStream<Uint8Array>> {
throw new Error("not implemented");
}
}

385
test/api/client.test.ts Normal file
View File

@@ -0,0 +1,385 @@
/**
* Tests for `ApiClient`.
*
* `ApiClient` is the HTTP layer that every other module in quack calls to
* reach the Ente server. It handles:
*
* - Base URL resolution. Production uses `https://api.ente.io` for the
* API, `https://files.ente.io` for file downloads, and
* `https://thumbnails.ente.io` for thumbnail downloads. Self-hosted
* deployments override the API origin via the constructor or via the
* `ENTE_API_ENDPOINT` environment variable. When a custom API origin
* is set, file and thumbnail downloads route through that same origin
* at `/files/download/<id>` and `/files/preview/<id>` instead of the
* dedicated CDN hosts.
*
* - Required headers. Every request carries `X-Client-Package`
* (`berlin.sneak.quack`). Authenticated requests also carry
* `X-Auth-Token` with the token recovered by `unwrapAuth`.
*
* - JSON serialization. `getJSON` and `postJSON` handle Accept /
* Content-Type headers and JSON parsing.
*
* - Error mapping. Non-2xx responses become `ApiError` instances that
* expose `.status`, `.code` (from the server's JSON error body, if
* present), `.requestID` (from the `x-request-id` response header),
* and `.body` (the raw parsed body).
*
* - Streaming downloads. `getFileStream` and `getThumbnailStream`
* return a `ReadableStream<Uint8Array>` from the appropriate CDN
* (or the self-hosted fallback path).
*
* All tests inject a fake `fetch` via the constructor so nothing touches
* the network. The fake records every call for assertion.
*/
import { describe, expect, it } from "vitest";
import { ApiClient, ApiError } from "../../src/api/client.js";
// ---------------------------------------------------------------------------
// Test helpers
// ---------------------------------------------------------------------------
/**
* A minimal fake Response that satisfies the subset of the Response API
* that ApiClient uses. Keeps tests short.
*/
const jsonResponse = (
body: unknown,
status = 200,
headers: Record<string, string> = {},
): Response =>
new Response(JSON.stringify(body), {
status,
headers: { "content-type": "application/json", ...headers },
});
const textResponse = (
body: string,
status = 200,
headers: Record<string, string> = {},
): Response =>
new Response(body, {
status,
headers: { "content-type": "text/plain", ...headers },
});
const streamResponse = (
body: Uint8Array,
status = 200,
headers: Record<string, string> = {},
): Response => new Response(body, { status, headers });
/**
* Build a recording fetch. Returns the fake function and a list of
* captured `{ url, init }` pairs. Each call pops the next canned
* response; if the list runs out, the call rejects.
*/
const recordingFetch = (
...responses: Response[]
): {
fetch: typeof globalThis.fetch;
calls: { url: string; init: RequestInit | undefined }[];
} => {
const calls: { url: string; init: RequestInit | undefined }[] = [];
let i = 0;
const fake = async (
input: RequestInfo | URL,
init?: RequestInit,
): Promise<Response> => {
const url =
typeof input === "string"
? input
: input instanceof URL
? input.href
: input.url;
calls.push({ url, init });
if (i >= responses.length) {
throw new Error(`recordingFetch: no response for call #${i}`);
}
return responses[i++]!;
};
return { fetch: fake as typeof globalThis.fetch, calls };
};
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
describe("ApiClient defaults", () => {
it("uses production origins when no overrides are given", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({ ok: true }));
const client = new ApiClient({ fetch });
await client.getJSON("/health");
expect(calls[0]!.url).toBe("https://api.ente.io/health");
});
it("attaches X-Client-Package to every request", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch });
await client.getJSON("/ping");
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.get("X-Client-Package")).toBe("berlin.sneak.quack");
});
});
describe("ApiClient auth token", () => {
it("does not send X-Auth-Token when no token is set", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch });
await client.getJSON("/public");
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.has("X-Auth-Token")).toBe(false);
});
it("sends X-Auth-Token after setAuthToken", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch });
client.setAuthToken("my-token-123");
await client.getJSON("/private");
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.get("X-Auth-Token")).toBe("my-token-123");
});
it("accepts authToken in constructor options", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch, authToken: "ctor-token" });
await client.getJSON("/private");
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.get("X-Auth-Token")).toBe("ctor-token");
});
it("stops sending X-Auth-Token after clearAuthToken", async () => {
const { fetch, calls } = recordingFetch(
jsonResponse({}),
jsonResponse({}),
);
const client = new ApiClient({ fetch, authToken: "temp" });
await client.getJSON("/a");
client.clearAuthToken();
await client.getJSON("/b");
const h0 = new Headers(calls[0]!.init?.headers as HeadersInit);
const h1 = new Headers(calls[1]!.init?.headers as HeadersInit);
expect(h0.has("X-Auth-Token")).toBe(true);
expect(h1.has("X-Auth-Token")).toBe(false);
});
});
describe("ApiClient.getJSON", () => {
it("sends a GET request and parses JSON", async () => {
const { fetch, calls } = recordingFetch(
jsonResponse({ collections: [1, 2, 3] }),
);
const client = new ApiClient({ fetch });
const result = await client.getJSON<{ collections: number[] }>(
"/collections/v2",
);
expect(calls[0]!.init?.method).toBe("GET");
expect(result.collections).toEqual([1, 2, 3]);
});
it("appends query parameters to the URL", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch });
await client.getJSON("/users/srp/attributes", {
email: "a@b.c",
sinceTime: 12345,
});
const url = new URL(calls[0]!.url);
expect(url.searchParams.get("email")).toBe("a@b.c");
expect(url.searchParams.get("sinceTime")).toBe("12345");
});
it("omits query parameters whose value is undefined", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({ fetch });
await client.getJSON("/x", { keep: "yes", drop: undefined });
const url = new URL(calls[0]!.url);
expect(url.searchParams.has("keep")).toBe(true);
expect(url.searchParams.has("drop")).toBe(false);
});
});
describe("ApiClient.postJSON", () => {
it("sends a POST with JSON body and Content-Type", async () => {
const { fetch, calls } = recordingFetch(
jsonResponse({ sessionID: "abc" }),
);
const client = new ApiClient({ fetch });
const result = await client.postJSON<{ sessionID: string }>(
"/users/srp/create-session",
{ userID: "u1", A: "aaa" },
);
expect(calls[0]!.init?.method).toBe("POST");
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.get("Content-Type")).toBe("application/json");
expect(JSON.parse(calls[0]!.init?.body as string)).toEqual({
userID: "u1",
A: "aaa",
});
expect(result.sessionID).toBe("abc");
});
});
describe("ApiClient custom origins", () => {
it("uses a custom apiOrigin for API calls", async () => {
const { fetch, calls } = recordingFetch(jsonResponse({}));
const client = new ApiClient({
fetch,
apiOrigin: "https://my-ente.example.com",
});
await client.getJSON("/health");
expect(calls[0]!.url).toBe("https://my-ente.example.com/health");
});
it("routes file downloads through apiOrigin when custom", async () => {
// Self-hosted servers don't have dedicated CDN hosts. File
// downloads use the API origin at /files/download/<id>.
const body = new Uint8Array([0xca, 0xfe]);
const { fetch, calls } = recordingFetch(streamResponse(body));
const client = new ApiClient({
fetch,
apiOrigin: "https://my-ente.example.com",
});
await client.getFileStream(99);
expect(calls[0]!.url).toBe(
"https://my-ente.example.com/files/download/99",
);
});
it("routes thumbnail downloads through apiOrigin when custom", async () => {
const body = new Uint8Array([0xde, 0xad]);
const { fetch, calls } = recordingFetch(streamResponse(body));
const client = new ApiClient({
fetch,
apiOrigin: "https://my-ente.example.com",
});
await client.getThumbnailStream(77);
expect(calls[0]!.url).toBe(
"https://my-ente.example.com/files/preview/77",
);
});
it("uses production CDN hosts when apiOrigin is default", async () => {
const body = new Uint8Array([1, 2, 3]);
const { fetch, calls } = recordingFetch(
streamResponse(body),
streamResponse(body),
);
const client = new ApiClient({ fetch });
await client.getFileStream(10);
await client.getThumbnailStream(20);
expect(calls[0]!.url).toBe("https://files.ente.io/?fileID=10");
expect(calls[1]!.url).toBe("https://thumbnails.ente.io/?fileID=20");
});
});
describe("ApiError", () => {
it("throws ApiError on 4xx with status, code, requestID", async () => {
const { fetch } = recordingFetch(
jsonResponse({ code: "INVALID_TOKEN", message: "bad token" }, 401, {
"x-request-id": "req-abc",
}),
);
const client = new ApiClient({ fetch });
try {
await client.getJSON("/protected");
expect.unreachable("should have thrown");
} catch (err) {
expect(err).toBeInstanceOf(ApiError);
const apiErr = err as ApiError;
expect(apiErr.status).toBe(401);
expect(apiErr.code).toBe("INVALID_TOKEN");
expect(apiErr.requestID).toBe("req-abc");
expect(apiErr.body).toEqual({
code: "INVALID_TOKEN",
message: "bad token",
});
}
});
it("throws ApiError on 5xx", async () => {
const { fetch } = recordingFetch(
textResponse("Internal Server Error", 500, {
"x-request-id": "req-xyz",
}),
);
const client = new ApiClient({ fetch });
try {
await client.postJSON("/boom", {});
expect.unreachable("should have thrown");
} catch (err) {
expect(err).toBeInstanceOf(ApiError);
const apiErr = err as ApiError;
expect(apiErr.status).toBe(500);
expect(apiErr.requestID).toBe("req-xyz");
}
});
it("throws ApiError on non-2xx stream downloads", async () => {
const { fetch } = recordingFetch(
textResponse("Not Found", 404, { "x-request-id": "req-404" }),
);
const client = new ApiClient({ fetch });
try {
await client.getFileStream(999);
expect.unreachable("should have thrown");
} catch (err) {
expect(err).toBeInstanceOf(ApiError);
expect((err as ApiError).status).toBe(404);
}
});
});
describe("ApiClient.getFileStream / getThumbnailStream", () => {
it("returns a ReadableStream on success", async () => {
const payload = new Uint8Array([10, 20, 30, 40]);
const { fetch } = recordingFetch(streamResponse(payload));
const client = new ApiClient({ fetch });
const stream = await client.getFileStream(5);
expect(stream).toBeInstanceOf(ReadableStream);
const reader = stream.getReader();
const chunks: Uint8Array[] = [];
for (;;) {
const { done, value } = await reader.read();
if (done) break;
chunks.push(value);
}
const all = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
let offset = 0;
for (const c of chunks) {
all.set(c, offset);
offset += c.length;
}
expect(all).toEqual(payload);
});
it("attaches X-Auth-Token to CDN downloads", async () => {
const { fetch, calls } = recordingFetch(
streamResponse(new Uint8Array(0)),
);
const client = new ApiClient({ fetch, authToken: "tk" });
await client.getFileStream(1);
const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
expect(headers.get("X-Auth-Token")).toBe("tk");
});
});