@npy/fetch 0.1.1 → 0.1.3

package/tests/agent.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { createAgent } from "../src/agent";
+import { AutoDialer } from "../src/dialers";
+import {
+    AgentBusyError,
+    OriginMismatchError,
+    RequestAbortedError,
+    ResponseDecodeError,
+} from "../src/errors";
+import { createTestServer } from "./test-utils";
+
+describe("agent.ts", () => {
+    const testServer = createTestServer();
+    const dialer = new AutoDialer();
+
+    afterAll(async () => {
+        await testServer.stop();
+    });
+
+    test("agent performs sequential requests against the same origin", async () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            const response1 = await agent.send({
+                url: `${testServer.baseUrl}/text`,
+                method: "GET",
+            });
+            expect(response1.status).toBe(200);
+            expect(await response1.text()).toBe("Hello, World!");
+
+            const response2 = await agent.send({
+                url: `${testServer.baseUrl}/json`,
+                method: "GET",
+            });
+            expect(response2.status).toBe(200);
+            expect(await response2.json()).toEqual({
+                message: "Hello, JSON!",
+            });
+
+            expect(agent.isIdle).toBe(true);
+        } finally {
+            agent.close();
+        }
+    });
+
+    test("agent rejects cross-origin requests with OriginMismatchError", async () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            await expect(
+                agent.send({
+                    url: "http://example.com/test",
+                    method: "GET",
+                }),
+            ).rejects.toBeInstanceOf(OriginMismatchError);
+        } finally {
+            agent.close();
+        }
+    });
+
+    test("agent rejects concurrent use while busy with AgentBusyError", async () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            const slowRequest = agent.send({
+                url: `${testServer.baseUrl}/slow`,
+                method: "GET",
+            });
+
+            await expect(
+                agent.send({
+                    url: `${testServer.baseUrl}/text`,
+                    method: "GET",
+                }),
+            ).rejects.toBeInstanceOf(AgentBusyError);
+
+            const response = await slowRequest;
+            expect(await response.text()).toBe("Finally!");
+            expect(agent.isIdle).toBe(true);
+        } finally {
+            agent.close();
+        }
+    });
+
+    test("agent returns to idle after aborted requests", async () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            const controller = new AbortController();
+            const request = agent.send({
+                url: `${testServer.baseUrl}/slow`,
+                method: "GET",
+                signal: controller.signal,
+            });
+
+            setTimeout(() => controller.abort(new Error("abort test")), 50);
+
+            await expect(request).rejects.toBeInstanceOf(RequestAbortedError);
+            await expect(agent.whenIdle()).resolves.toBeUndefined();
+            expect(agent.isIdle).toBe(true);
+        } finally {
+            agent.close();
+        }
+    });
+
+    test("agent maps decoding failures during body consumption", async () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            const response = await agent.send({
+                url: `${testServer.baseUrl}/bad-gzip`,
+                method: "GET",
+            });
+
+            await expect(response.text()).rejects.toBeInstanceOf(
+                ResponseDecodeError,
+            );
+        } finally {
+            agent.close();
+        }
+    });
+
+    test("agent metadata reflects host and port", () => {
+        const agent = createAgent(dialer, testServer.baseUrl);
+
+        try {
+            const baseUrl = new URL(testServer.baseUrl);
+            expect(agent.hostname).toBe(baseUrl.hostname);
+            expect(agent.port).toBe(Number(baseUrl.port));
+        } finally {
+            agent.close();
+        }
+    });
+});

package/tests/body.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, test } from "bun:test";
+import { Readable } from "node:stream";
+import { extractBody, getFormDataLength } from "../src/body";
+
+async function readAllBytes(readable: Readable): Promise<Uint8Array> {
+    const chunks: Buffer[] = [];
+    for await (const chunk of readable) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+
+function parseBoundary(contentType: string): string {
+    const match = /boundary=([^\s;]+)/.exec(contentType);
+    if (!match) throw new Error(`No boundary in: ${contentType}`);
+    return match[1]!;
+}
+
+describe("extractBody", () => {
+    test("null returns empty body with zero content-length", () => {
+        const state = extractBody(null);
+        expect(state.body).toBeNull();
+        expect(state.contentLength).toBe(0);
+        expect(state.contentType).toBeNull();
+    });
+
+    test("string sets UTF-8 content-type and correct byte length", () => {
+        const state = extractBody("héllo");
+        expect(state.body).toBeInstanceOf(Uint8Array);
+        expect(state.contentType).toBe("text/plain;charset=UTF-8");
+
+        expect(state.contentLength).toBe(6);
+    });
+
+    test("Uint8Array passes through with exact size", () => {
+        const bytes = new Uint8Array([10, 20, 30, 40]);
+        const state = extractBody(bytes);
+        expect(state.body).toBe(bytes);
+        expect(state.contentLength).toBe(4);
+        expect(state.contentType).toBeNull();
+    });
+
+    test("URLSearchParams sets form-urlencoded content-type", () => {
+        const params = new URLSearchParams({ a: "1", b: "2" });
+        const state = extractBody(params);
+        expect(state.contentType).toContain(
+            "application/x-www-form-urlencoded",
+        );
+        expect(state.body).toBeInstanceOf(Uint8Array);
+        const text = new TextDecoder().decode(state.body as Uint8Array);
+        expect(text).toBe("a=1&b=2");
+    });
+
+    test("FormData sets multipart content-type with boundary", () => {
+        const form = new FormData();
+        form.append("key", "value");
+
+        const state = extractBody(form);
+        expect(state.contentType).toContain("multipart/form-data");
+        expect(state.contentType).toContain("boundary=");
+        expect(state.contentLength).toBeGreaterThan(0);
+        expect(state.body).toBeInstanceOf(Readable);
+    });
+
+    test("empty FormData produces a valid (footer-only) body", () => {
+        const state = extractBody(new FormData());
+        expect(state.contentType).toContain("multipart/form-data");
+        expect(state.contentLength).toBeGreaterThan(0);
+
+        expect(state.body).toBeInstanceOf(Readable);
+    });
+
+    test("ReadableStream body is passed through unchanged", () => {
+        const stream = new ReadableStream();
+        const state = extractBody(stream);
+        expect(state.body).toBe(stream);
+        expect(state.contentLength).toBeNull();
+    });
+});
+
+describe("getFormDataLength", () => {
+    test("matches actual serialized byte count — text-only fields", async () => {
+        const form = new FormData();
+        form.append("username", "alice");
+        form.append("email", "alice@example.com");
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const declared = getFormDataLength(form, boundary);
+
+        const actual = await readAllBytes(state.body as Readable);
+        expect(actual.byteLength).toBe(declared);
+    });
+
+    test("matches actual serialized byte count — single Blob field", async () => {
+        const form = new FormData();
+        form.append(
+            "file",
+            new Blob(["binary content"], { type: "application/octet-stream" }),
+            "data.bin",
+        );
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const declared = getFormDataLength(form, boundary);
+
+        const actual = await readAllBytes(state.body as Readable);
+        expect(actual.byteLength).toBe(declared);
+    });
+
+    test("matches actual serialized byte count — mixed text and Blob fields", async () => {
+        const form = new FormData();
+        form.append("description", "a short text");
+        form.append(
+            "attachment",
+            new Blob(["<html></html>"], { type: "text/html" }),
+            "page.html",
+        );
+        form.append("tag", "important");
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const declared = getFormDataLength(form, boundary);
+
+        const actual = await readAllBytes(state.body as Readable);
+        expect(actual.byteLength).toBe(declared);
+    });
+
+    test("matches for empty FormData", async () => {
+        const form = new FormData();
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const declared = getFormDataLength(form, boundary);
+
+        const actual = await readAllBytes(state.body as Readable);
+        expect(actual.byteLength).toBe(declared);
+    });
+
+    test("matches for multibyte UTF-8 field value", async () => {
+        const form = new FormData();
+        form.append("greeting", "こんにちは");
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const declared = getFormDataLength(form, boundary);
+
+        const actual = await readAllBytes(state.body as Readable);
+        expect(actual.byteLength).toBe(declared);
+    });
+});
+
+describe("multipart wire format", () => {
+    test("text field produces valid multipart structure", async () => {
+        const form = new FormData();
+        form.append("name", "bob");
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const bytes = await readAllBytes(state.body as Readable);
+        const text = new TextDecoder().decode(bytes);
+
+        expect(text).toContain(`--${boundary}\r\n`);
+        expect(text).toContain(`Content-Disposition: form-data; name="name"`);
+        expect(text).toContain(`\r\n\r\nbob\r\n`);
+        expect(text).toContain(`--${boundary}--`);
+    });
+
+    test("Blob field includes filename and Content-Type headers", async () => {
+        const form = new FormData();
+        form.append(
+            "upload",
+            new Blob(["data"], { type: "text/plain" }),
+            "notes.txt",
+        );
+
+        const state = extractBody(form);
+        const bytes = await readAllBytes(state.body as Readable);
+        const text = new TextDecoder().decode(bytes);
+
+        expect(text).toContain(`filename="notes.txt"`);
+        expect(text).toContain(`Content-Type: text/plain`);
+        expect(text).toContain(`data`);
+    });
+
+    test("Blob without explicit filename falls back to 'blob'", async () => {
+        const form = new FormData();
+
+        form.append("f", new Blob(["x"]));
+
+        const state = extractBody(form);
+        const bytes = await readAllBytes(state.body as Readable);
+        const text = new TextDecoder().decode(bytes);
+
+        expect(text).toContain(`filename="blob"`);
+    });
+
+    test("Blob without type falls back to application/octet-stream", async () => {
+        const form = new FormData();
+        form.append("f", new Blob(["x"]), "file.dat");
+
+        const state = extractBody(form);
+        const bytes = await readAllBytes(state.body as Readable);
+        const text = new TextDecoder().decode(bytes);
+
+        expect(text).toContain(`Content-Type: application/octet-stream`);
+    });
+
+    test("each field is separated by boundary", async () => {
+        const form = new FormData();
+        form.append("a", "1");
+        form.append("b", "2");
+        form.append("c", "3");
+
+        const state = extractBody(form);
+        const boundary = parseBoundary(state.contentType!);
+        const bytes = await readAllBytes(state.body as Readable);
+        const text = new TextDecoder().decode(bytes);
+
+        const openings = (
+            text.match(new RegExp(`--${boundary}\r\n`, "g")) ?? []
+        ).length;
+        const closing = (text.match(new RegExp(`--${boundary}--`, "g")) ?? [])
+            .length;
+        expect(openings).toBe(3);
+        expect(closing).toBe(1);
+    });
+});

package/tests/errors.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import {
+    AgentBusyError,
+    ConnectionError,
+    ConnectTimeoutError,
+    ErrorType,
+    FetchError,
+    FetchErrorCode,
+    HttpStatusError,
+    OriginMismatchError,
+    RequestAbortedError,
+    ResponseBodyError,
+    ResponseHeaderError,
+    UnsupportedMethodError,
+} from "../src/errors";
+
+describe("errors.ts", () => {
+    test("base FetchError exposes code, phase, retryable and cause", () => {
+        const cause = new Error("boom");
+        const error = new ResponseHeaderError(cause, {
+            url: "http://example.test/resource",
+            method: "GET",
+            origin: "http://example.test",
+        });
+
+        expect(error).toBeInstanceOf(FetchError);
+        expect(error.name).toBe("ResponseHeaderError");
+        expect(error.code).toBe(FetchErrorCode.RESPONSE_HEADERS);
+        expect(error.phase).toBe("response");
+        expect(error.retryable).toBe(true);
+        expect(error.type).toBe(ErrorType.NETWORK);
+        expect(error.cause).toBe(cause);
+        expect(error.context?.url).toBe("http://example.test/resource");
+        expect(error.context?.method).toBe("GET");
+    });
+
+    test("abort/connect/network errors expose the expected classifications", () => {
+        const cause = new Error("boom");
+
+        const aborted = new RequestAbortedError(cause, {
+            url: "http://example.test/abort",
+            method: "GET",
+        });
+
+        const timeout = new ConnectTimeoutError(cause, {
+            host: "example.test",
+            port: 443,
+        });
+
+        const network = new ConnectionError(cause, {
+            host: "example.test",
+            port: 443,
+        });
+
+        expect(aborted.code).toBe(FetchErrorCode.ABORTED);
+        expect(aborted.phase).toBe("request");
+        expect(aborted.retryable).toBe(false);
+        expect(aborted.type).toBe(ErrorType.ABORTED);
+
+        expect(timeout.code).toBe(FetchErrorCode.TIMEOUT);
+        expect(timeout.phase).toBe("connect");
+        expect(timeout.retryable).toBe(true);
+        expect(timeout.type).toBe(ErrorType.TIMEOUT);
+
+        expect(network.code).toBe(FetchErrorCode.CONNECTION);
+        expect(network.phase).toBe("connect");
+        expect(network.retryable).toBe(true);
+        expect(network.type).toBe(ErrorType.NETWORK);
+    });
+
+    test("agent/policy errors expose specific metadata", () => {
+        const busy = new AgentBusyError({
+            origin: "http://example.test",
+            host: "example.test",
+            port: 80,
+        });
+
+        const mismatch = new OriginMismatchError(
+            "http://a.test",
+            "http://b.test",
+            { url: "http://b.test/resource" },
+        );
+
+        const unsupportedMethod = new UnsupportedMethodError("CONNECT", {
+            url: "http://example.test",
+            method: "CONNECT",
+        });
+
+        expect(busy.code).toBe(FetchErrorCode.AGENT_BUSY);
+        expect(busy.phase).toBe("agent");
+        expect(busy.retryable).toBe(true);
+
+        expect(mismatch.code).toBe(FetchErrorCode.ORIGIN_MISMATCH);
+        expect(mismatch.phase).toBe("policy");
+        expect(mismatch.retryable).toBe(false);
+        expect(mismatch.context?.details?.expectedOrigin).toBe("http://a.test");
+        expect(mismatch.context?.details?.actualOrigin).toBe("http://b.test");
+
+        expect(unsupportedMethod.code).toBe(FetchErrorCode.UNSUPPORTED_METHOD);
+        expect(unsupportedMethod.phase).toBe("policy");
+        expect(unsupportedMethod.retryable).toBe(false);
+    });
+
+    test("HTTP status errors classify 4xx and 5xx correctly", () => {
+        const http4xx = new HttpStatusError(404, {
+            url: "http://example.test/not-found",
+            method: "GET",
+        });
+
+        const http5xx = new HttpStatusError(503, {
+            url: "http://example.test/unavailable",
+            method: "GET",
+        });
+
+        expect(http4xx.code).toBe(FetchErrorCode.HTTP_STATUS);
+        expect(http4xx.phase).toBe("response");
+        expect(http4xx.retryable).toBe(false);
+        expect(http4xx.type).toBe(ErrorType.HTTP_CLIENT_ERROR);
+        expect(http4xx.statusCode).toBe(404);
+
+        expect(http5xx.code).toBe(FetchErrorCode.HTTP_STATUS);
+        expect(http5xx.phase).toBe("response");
+        expect(http5xx.retryable).toBe(true);
+        expect(http5xx.type).toBe(ErrorType.HTTP_SERVER_ERROR);
+        expect(http5xx.statusCode).toBe(503);
+    });
+
+    test("toJSON exposes the stable diagnostic payload", () => {
+        const cause = new Error("boom");
+        const error = new ResponseBodyError(cause, {
+            url: "http://example.test/stream",
+            method: "GET",
+        });
+
+        expect(error.toJSON()).toEqual({
+            name: "ResponseBodyError",
+            message: "Failed while reading response body",
+            code: FetchErrorCode.RESPONSE_BODY,
+            phase: "body",
+            retryable: true,
+            type: ErrorType.NETWORK,
+            context: {
+                url: "http://example.test/stream",
+                method: "GET",
+            },
+            cause: {
+                name: "Error",
+                message: "boom",
+            },
+        });
+    });
+});