@npy/fetch 0.1.2 → 0.1.3

package/src/http-client.ts

@@ -0,0 +1,111 @@
+import { createAgentPool } from "./agent-pool";
+import type { Agent, AgentPool } from "./types/agent";
+
+/**
+ * Advanced HTTP client with per-origin pooling and explicit lifecycle control.
+ *
+ * @remarks
+ * Use this API when you want direct access to the library's richer error model and
+ * transport options instead of the fetch-like compatibility layer.
+ *
+ *
+ * @example
+ * ```ts
+ * const client = new HttpClient();
+ * const response = await client.send({
+ *   url: "https://httpbin.org/anything",
+ *   method: "GET",
+ * });
+ * await client.close();
+ * ```
+ */
+export class HttpClient implements AsyncDisposable {
+    readonly #agentPools = new Map<string, AgentPool>();
+    readonly #agentPoolOptions: Readonly<HttpClient.Options>;
+    #closePromise?: Promise<void>;
+
+    constructor(options: HttpClient.Options = {}) {
+        this.#agentPoolOptions = { ...options };
+    }
+
+    get options(): Readonly<HttpClient.Options> {
+        return this.#agentPoolOptions;
+    }
+
+    async send(options: Agent.SendOptions): Promise<Response> {
+        const agentPool = this.#getOrCreateAgentPool(options.url);
+        return agentPool.send(options);
+    }
+
+    /**
+     * Closes all pooled connections owned by this client.
+     *
+     * @remarks
+     * After closing, future requests may recreate pools as needed.
+     */
+    async close(): Promise<void> {
+        if (this.#closePromise) {
+            return this.#closePromise;
+        }
+
+        const promise = (async () => {
+            const entries = Array.from(this.#agentPools.entries());
+
+            const results = await Promise.allSettled(
+                entries.map(async ([origin, agentPool]) => {
+                    try {
+                        await agentPool.close();
+                    } finally {
+                        this.#agentPools.delete(origin);
+                    }
+                }),
+            );
+
+            const errors = results.flatMap((result) =>
+                result.status === "rejected" ? [result.reason] : [],
+            );
+
+            if (errors.length === 1) throw errors[0];
+
+            if (errors.length > 1) {
+                throw new AggregateError(
+                    errors,
+                    "Failed to close one or more agent pools",
+                );
+            }
+        })();
+
+        this.#closePromise = promise;
+
+        try {
+            await promise;
+        } finally {
+            if (this.#closePromise === promise) {
+                this.#closePromise = undefined;
+            }
+        }
+    }
+
+    async [Symbol.asyncDispose](): Promise<void> {
+        await this.close();
+    }
+
+    #getOrCreateAgentPool(url: string | URL): AgentPool {
+        const origin =
+            typeof url === "string" ? new URL(url).origin : url.origin;
+
+        let agentPool = this.#agentPools.get(origin);
+        if (!agentPool) {
+            agentPool = createAgentPool(origin, this.#agentPoolOptions);
+            this.#agentPools.set(origin, agentPool);
+        }
+
+        return agentPool;
+    }
+}
+
+export namespace HttpClient {
+    export interface Options extends AgentPool.Options {}
+}
+
+export interface HttpClientOptions extends HttpClient.Options {}

package/src/index.ts

@@ -0,0 +1,14 @@
+export type { FormDataPolyfill } from "./_internal/guards";
+export type { WithSignal } from "./_internal/net";
+export { connectTcp, connectTls, upgradeTls } from "./_internal/net";
+export * from "./agent";
+export * from "./agent-pool";
+export * from "./body";
+export * from "./dialers";
+export * from "./encoding";
+export * from "./errors";
+export * from "./fetch";
+export * from "./http-client";
+export type { LineReader, Readers } from "./io/readers";
+export type { Writers } from "./io/writers";
+export * from "./types";

package/src/io/_utils.ts

@@ -0,0 +1,82 @@
+import bytes from "bytes";
+
+type TransferEncodingInfo = {
+    has: boolean;
+    chunked: boolean;
+    codings: string[];
+};
+
+export function parseMaxBytes(value?: number | string): number | null {
+    if (value === undefined) return null;
+
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`invalid max size: ${String(value)}`);
+        }
+        return Math.floor(value);
+    }
+
+    const parsed = bytes.parse(value);
+    if (parsed == null || !Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`invalid max size: ${String(value)}`);
+    }
+
+    return parsed;
+}
+
+export function splitTokens(v: string | null): string[] {
+    if (!v) return [];
+    return v
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+
+export function parseTransferEncoding(headers: Headers): TransferEncodingInfo {
+    const raw = headers.get("transfer-encoding");
+    const tks = splitTokens(raw);
+    if (tks.length === 0) return { has: false, chunked: false, codings: [] };
+
+    const chunkedIdx = tks.lastIndexOf("chunked");
+    const hasChunked = chunkedIdx !== -1;
+
+    if (hasChunked && chunkedIdx !== tks.length - 1) {
+        throw new Error(`Invalid transfer-encoding order: ${raw ?? ""}`);
+    }
+
+    if (hasChunked && tks.indexOf("chunked") !== chunkedIdx) {
+        throw new Error(
+            `Invalid transfer-encoding (duplicate chunked): ${raw ?? ""}`,
+        );
+    }
+
+    const codings = tks.filter((t) => t !== "chunked" && t !== "identity");
+
+    return { has: true, chunked: hasChunked, codings };
+}
+
+export function parseContentLength(headers: Headers): number | null {
+    const raw = headers.get("content-length");
+    if (!raw) return null;
+
+    const parts = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (parts.length === 0) return null;
+
+    let value: number | null = null;
+
+    for (const p of parts) {
+        if (!/^\d+$/.test(p)) throw new Error(`Invalid content-length: ${raw}`);
+        const n = Number.parseInt(p, 10);
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error(`Invalid content-length: ${raw}`);
+
+        if (value === null) value = n;
+        else if (value !== n)
+            throw new Error(`Conflicting content-length values: ${raw}`);
+    }
+
+    return value;
+}

package/src/io/buf-writer.ts

@@ -0,0 +1,183 @@
+import type { ISyncWritable, IWritable } from "@fuman/io";
+import { u8 } from "@fuman/utils";
+
+const DEFAULT_BUF_SIZE = 4096;
+const MIN_BUF_SIZE = 16;
+
+export class BufWriter implements IWritable, ISyncWritable {
+    #buffer: Uint8Array;
+    #writable: IWritable;
+
+    #writePos = 0;
+    #error: Error | null = null;
+
+    #pending: Uint8Array[] = [];
+    #pendingBytes = 0;
+
+    #lastWrite: { buf: Uint8Array; size: number; internal: boolean } | null =
+        null;
+
+    constructor(writable: IWritable, size: number = DEFAULT_BUF_SIZE) {
+        if (size < MIN_BUF_SIZE) size = MIN_BUF_SIZE;
+        this.#buffer = u8.alloc(size);
+        this.#writable = writable;
+    }
+
+    get bufferSize(): number {
+        return this.#buffer.byteLength;
+    }
+
+    get buffered(): number {
+        return this.#pendingBytes + this.#writePos;
+    }
+
+    get available(): number {
+        return this.#buffer.byteLength - this.#writePos;
+    }
+
+    reset(writable: IWritable): void {
+        this.#error = null;
+        this.#writePos = 0;
+        this.#pending.length = 0;
+        this.#pendingBytes = 0;
+        this.#lastWrite = null;
+        this.#writable = writable;
+    }
+
+    writeSync(bytes: number): Uint8Array {
+        if (this.#error) throw this.#error;
+        if (bytes < 0) throw new RangeError("bytes must be >= 0");
+        if (this.#lastWrite)
+            throw new Error(
+                "disposeWriteSync must be called before the next writeSync",
+            );
+
+        if (bytes === 0) {
+            const empty = this.#buffer.subarray(this.#writePos, this.#writePos);
+            this.#lastWrite = { buf: empty, size: 0, internal: true };
+            return empty;
+        }
+
+        if (bytes > this.available && this.#writePos > 0) {
+            const copy = u8.allocWith(this.#buffer.subarray(0, this.#writePos));
+            this.#pending.push(copy);
+            this.#pendingBytes += copy.length;
+            this.#writePos = 0;
+        }
+
+        if (bytes <= this.#buffer.byteLength) {
+            if (bytes > this.available) {
+                const copy = u8.allocWith(
+                    this.#buffer.subarray(0, this.#writePos),
+                );
+                this.#pending.push(copy);
+                this.#pendingBytes += copy.length;
+                this.#writePos = 0;
+            }
+
+            const start = this.#writePos;
+            const end = start + bytes;
+            const slice = this.#buffer.subarray(start, end);
+            this.#writePos = end;
+            this.#lastWrite = { buf: slice, size: bytes, internal: true };
+            return slice;
+        }
+
+        const chunk = u8.alloc(bytes);
+        this.#lastWrite = { buf: chunk, size: bytes, internal: false };
+        return chunk;
+    }
+
+    disposeWriteSync(written?: number): void {
+        const lw = this.#lastWrite;
+        if (!lw) return;
+
+        const w = written ?? lw.size;
+        if (w < 0 || w > lw.size) {
+            throw new RangeError(`written out of bounds: ${w} (0..${lw.size})`);
+        }
+
+        if (lw.internal) {
+            this.#writePos -= lw.size - w;
+        } else {
+            if (w > 0) {
+                const chunk = w === lw.size ? lw.buf : lw.buf.subarray(0, w);
+                this.#pending.push(chunk);
+                this.#pendingBytes += chunk.length;
+            }
+        }
+
+        this.#lastWrite = null;
+    }
+
+    async #flushPending(): Promise<void> {
+        if (this.#error) throw this.#error;
+        if (this.#lastWrite)
+            throw new Error(
+                "disposeWriteSync must be called before flush/write",
+            );
+
+        while (this.#pending.length > 0) {
+            const chunk = this.#pending[0];
+            try {
+                await this.#writable.write(chunk);
+            } catch (e) {
+                this.#error = e as Error;
+                throw e;
+            }
+            this.#pending.shift();
+            this.#pendingBytes -= chunk.length;
+        }
+    }
+
+    async flush(): Promise<void> {
+        await this.#flushPending();
+        if (this.#error) throw this.#error;
+        if (this.#writePos === 0) return;
+
+        try {
+            await this.#writable.write(
+                this.#buffer.subarray(0, this.#writePos),
+            );
+        } catch (e) {
+            this.#error = e as Error;
+            throw e;
+        }
+
+        this.#writePos = 0;
+    }
+
+    async write(bytes: Uint8Array): Promise<void> {
+        if (this.#error) throw this.#error;
+        if (!bytes.length) return;
+
+        await this.#flushPending();
+
+        if (this.#writePos === 0 && bytes.length >= this.#buffer.byteLength) {
+            try {
+                await this.#writable.write(bytes);
+            } catch (e) {
+                this.#error = e as Error;
+                throw e;
+            }
+            return;
+        }
+
+        let off = 0;
+        while (off < bytes.length) {
+            if (this.available === 0) {
+                await this.flush();
+                continue;
+            }
+
+            const toCopy = Math.min(this.available, bytes.length - off);
+            this.#buffer.set(bytes.subarray(off, off + toCopy), this.#writePos);
+            this.#writePos += toCopy;
+            off += toCopy;
+
+            if (this.#writePos === this.#buffer.byteLength) {
+                await this.flush();
+            }
+        }
+    }
+}

package/src/io/io.ts

@@ -0,0 +1,322 @@
+import type { IReadable } from "@fuman/io";
+import type { IConnection } from "@fuman/net";
+import { MaxBytesTransformStream } from "../_internal/streams";
+import { decodeStream } from "../encoding";
+import {
+    parseContentLength,
+    parseMaxBytes,
+    parseTransferEncoding,
+    splitTokens,
+} from "./_utils";
+import {
+    BodyReader,
+    ChunkedBodyReader,
+    LineReader,
+    type Readers,
+} from "./readers";
+import { createRequestWriter, type Writers } from "./writers";
+
+function parseStatusLine(line: string) {
+    const m = /^HTTP\/(\d+)\.(\d+)\s+(\d{3})(?:\s+(.*))?$/.exec(line);
+    if (!m) throw new Error(`Invalid HTTP status line: ${line}`);
+
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const status = Number(m[3]);
+    if (
+        !Number.isFinite(major) ||
+        !Number.isFinite(minor) ||
+        !Number.isFinite(status)
+    ) {
+        throw new Error(`Invalid HTTP status line: ${line}`);
+    }
+
+    return { major, minor, status, statusText: m[4] ?? "" };
+}
+
+function toArrayBufferBytes(
+    bytes: Uint8Array<ArrayBufferLike>,
+): Uint8Array<ArrayBuffer> {
+    if (bytes.buffer instanceof ArrayBuffer) {
+        return bytes as Uint8Array<ArrayBuffer>;
+    }
+    return new Uint8Array(bytes);
+}
+
+function wrapStreamErrors(
+    source: ReadableStream<Uint8Array>,
+    mapError: (err: unknown) => unknown,
+): ReadableStream<Uint8Array> {
+    const reader = source.getReader();
+    let pending: Uint8Array | null = null;
+
+    return new ReadableStream({
+        type: "bytes",
+        async pull(controller) {
+            try {
+                const byob = controller.byobRequest;
+
+                if (byob?.view) {
+                    const target = new Uint8Array(
+                        byob.view.buffer,
+                        byob.view.byteOffset,
+                        byob.view.byteLength,
+                    );
+
+                    if (target.byteLength === 0) {
+                        byob.respond(0);
+                        return;
+                    }
+
+                    let written = 0;
+
+                    if (pending && pending.byteLength > 0) {
+                        const n = Math.min(
+                            target.byteLength,
+                            pending.byteLength,
+                        );
+                        target.set(pending.subarray(0, n), written);
+                        written += n;
+                        pending =
+                            n === pending.byteLength
+                                ? null
+                                : pending.subarray(n);
+                    }
+
+                    while (written === 0) {
+                        const { done, value } = await reader.read();
+
+                        if (done) {
+                            byob.respond(0);
+                            controller.close();
+                            return;
+                        }
+
+                        if (!value || value.byteLength === 0) continue;
+
+                        const n = Math.min(
+                            target.byteLength - written,
+                            value.byteLength,
+                        );
+                        target.set(value.subarray(0, n), written);
+                        written += n;
+
+                        if (n < value.byteLength) {
+                            pending = value.subarray(n);
+                        }
+                    }
+
+                    byob.respond(written);
+                    return;
+                }
+
+                if (pending && pending.byteLength > 0) {
+                    const chunk = pending;
+                    pending = null;
+                    controller.enqueue(toArrayBufferBytes(chunk));
+                    return;
+                }
+
+                const { done, value } = await reader.read();
+
+                if (done) {
+                    controller.close();
+                    return;
+                }
+
+                if (value && value.byteLength > 0) {
+                    controller.enqueue(toArrayBufferBytes(value));
+                }
+            } catch (error) {
+                controller.error(mapError(error));
+            }
+        },
+
+        async cancel(reason) {
+            pending = null;
+            await reader.cancel(reason);
+        },
+    });
+}
+
+export async function readResponse(
+    conn: IConnection<unknown>,
+    options: Readers.Options & LineReader.ReadHeadersOptions = {},
+    shouldIgnoreBody: (status: number) => boolean,
+    onDone?: (reusable: boolean) => void,
+
+    mapBodyError?: (err: unknown) => unknown,
+): Promise<Response> {
+    const lr = new LineReader(conn, options);
+
+    const finalize = (() => {
+        let called = false;
+        return (reusable: boolean) => {
+            if (called) return;
+            called = true;
+            queueMicrotask(() => onDone?.(reusable));
+        };
+    })();
+
+    let statusLine!: {
+        major: number;
+        minor: number;
+        status: number;
+        statusText: string;
+    };
+    let headers!: Headers;
+
+    for (;;) {
+        const line = await lr.readLine();
+        if (line === null)
+            throw new Error("Unexpected EOF while reading status line");
+
+        const parsed = parseStatusLine(line);
+        const hdrs = await lr.readHeaders(options);
+
+        if (parsed.status >= 100 && parsed.status < 200) {
+            if (parsed.status === 101)
+                throw new Error("HTTP/1.1 protocol upgrades not supported");
+            continue;
+        }
+
+        statusLine = parsed;
+        headers = hdrs;
+        break;
+    }
+
+    const { major, minor, status, statusText } = statusLine;
+
+    const connectionTokens = splitTokens(headers.get("connection"));
+    const hasClose = connectionTokens.includes("close");
+    const hasKeepAlive = connectionTokens.includes("keep-alive");
+
+    const isHttp10 = major === 1 && minor === 0;
+    const keepAliveOk = !isHttp10 || hasKeepAlive;
+
+    const ignoreBody = shouldIgnoreBody(status);
+
+    const te = parseTransferEncoding(headers);
+
+    let chunked = false;
+    let contentLength: number | null = null;
+
+    if (!ignoreBody) {
+        if (te.has) {
+            chunked = te.chunked;
+            contentLength = null;
+            headers.delete("content-length");
+        } else {
+            chunked = false;
+            contentLength = parseContentLength(headers);
+        }
+    }
+
+    const bodyDelimited = ignoreBody || chunked || contentLength != null;
+    const reusable = keepAliveOk && !hasClose && bodyDelimited;
+
+    if (ignoreBody) {
+        finalize(reusable);
+        return new Response(null, { status, statusText, headers });
+    }
+
+    if (chunked) headers.delete("content-length");
+
+    const reader: IReadable = chunked
+        ? new ChunkedBodyReader(lr, options)
+        : new BodyReader(lr, contentLength, options);
+
+    const rawBody = new ReadableStream({
+        type: "bytes",
+        async pull(controller: ReadableByteStreamController) {
+            const byob = controller.byobRequest;
+            const view = byob?.view
+                ? new Uint8Array(
+                      byob.view.buffer,
+                      byob.view.byteOffset,
+                      byob.view.byteLength,
+                  )
+                : new Uint8Array(
+                      new ArrayBuffer(options.readChunkSize ?? 16 * 1024),
+                  );
+
+            try {
+                const n = await reader.read(view);
+                if (n === 0) {
+                    byob?.respond(0);
+                    controller.close();
+                    finalize(reusable);
+                    return;
+                }
+
+                if (byob) byob.respond(n);
+                else controller.enqueue(view.subarray(0, n));
+            } catch (err) {
+                controller.error(err);
+                finalize(false);
+            }
+        },
+        cancel() {
+            finalize(false);
+        },
+    });
+
+    let body: ReadableStream<Uint8Array> = rawBody;
+
+    try {
+        if (te.has && te.codings.length > 0) {
+            const decodedTe = decodeStream(
+                body,
+                te.codings,
+            ) as ReadableStream<Uint8Array>;
+            if (decodedTe !== body) {
+                if (te.chunked) headers.set("transfer-encoding", "chunked");
+                else headers.delete("transfer-encoding");
+
+                headers.delete("content-length");
+            }
+            body = decodedTe;
+        }
+
+        const decompress =
+            (options as Readers.DecompressionOptions).decompress !== false;
+        const contentEncoding = headers.get("content-encoding") ?? undefined;
+
+        if (decompress && contentEncoding) {
+            const decodedCe = decodeStream(
+                body,
+                contentEncoding,
+            ) as ReadableStream<Uint8Array>;
+            if (decodedCe !== body) {
+                headers.delete("content-encoding");
+                headers.delete("content-length");
+            }
+            body = decodedCe;
+        }
+
+        const maxDecoded = parseMaxBytes(
+            (options as Readers.SizeLimitOptions).maxDecodedBodySize,
+        );
+        if (maxDecoded != null) {
+            body = body.pipeThrough(new MaxBytesTransformStream(maxDecoded));
+        }
+
+        if (mapBodyError != null) {
+            body = wrapStreamErrors(body, mapBodyError);
+        }
+    } catch (err) {
+        finalize(false);
+        throw err;
+    }
+
+    return new Response(body, { status, statusText, headers });
+}
+
+export async function writeRequest(
+    conn: IConnection<unknown>,
+    req: Writers.Request,
+    options: Writers.Options = {},
+): Promise<void> {
+    const writer = createRequestWriter(conn, options);
+    await writer.write(req);
+}