@npy/fetch 0.1.2 → 0.1.3

package/src/dialers/tcp.ts

@@ -0,0 +1,162 @@
+import type { NodeTlsConnectOptions } from "@fuman/node";
+import { connectTcp, connectTls } from "../_internal/net";
+import type { Dialer } from "../types/dialer";
+
+const DEFAULT_TCP_PORT = 80;
+const DEFAULT_TLS_PORT = 443;
+const DEFAULT_HTTP_ALPN_PROTOCOLS = ["http/1.1"] as const;
+
+export type HostPort = {
+    address: string;
+    port: number;
+};
+
+function parsePort(value: string | number): number {
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value <= 0 || value > 65535) {
+            throw new TypeError(`Invalid port: ${String(value)}`);
+        }
+
+        return value;
+    }
+
+    if (!/^\d+$/.test(value)) {
+        throw new TypeError(`Invalid port: ${JSON.stringify(value)}`);
+    }
+
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw new TypeError(`Invalid port: ${JSON.stringify(value)}`);
+    }
+
+    return parsed;
+}
+
+/**
+ * Resolves the effective network address and port for a URL or dial target.
+ *
+ * @remarks
+ * When the input does not include an explicit port, the provided default port is used.
+ */
+export function resolveHostPort(
+    target: URL | Dialer.Target,
+    defaultPort: number,
+): HostPort {
+    const address = target instanceof URL ? target.hostname : target.address;
+
+    if (!address) {
+        throw new TypeError("Target address is required");
+    }
+
+    const port =
+        target instanceof URL
+            ? parsePort(target.port || String(defaultPort))
+            : parsePort(target.port || defaultPort);
+
+    return { address, port };
+}
+
+/**
+ * Dialer for plain TCP targets.
+ *
+ * @remarks
+ * This dialer rejects secure targets and is intended for HTTP over raw TCP.
+ */
+export class TcpDialer implements Dialer {
+    async dial(
+        target: Dialer.Target,
+        options: Dialer.Options = {},
+    ): Promise<Dialer.ConnectionLike> {
+        if (target.secure) {
+            throw new Error("TcpDialer cannot dial a secure target");
+        }
+
+        const endpoint = resolveHostPort(target, DEFAULT_TCP_PORT);
+
+        return connectTcp({
+            ...endpoint,
+            signal: options.signal,
+        });
+    }
+}
+
+/**
+ * Dialer for TLS targets.
+ *
+ * @remarks
+ * This dialer rejects insecure targets and applies TLS-specific options such as
+ * CA certificates, SNI and ALPN.
+ */
+export class TlsDialer implements Dialer {
+    readonly #options: Readonly<TlsDialer.Options>;
+
+    constructor(options: TlsDialer.Options = {}) {
+        this.#options = { ...options };
+    }
+
+    async dial(
+        target: Dialer.Target,
+        options: Dialer.Options = {},
+    ): Promise<Dialer.ConnectionLike> {
+        if (!target.secure) {
+            throw new Error("TlsDialer cannot dial an insecure target");
+        }
+
+        const endpoint = resolveHostPort(target, DEFAULT_TLS_PORT);
+        const extraOptions =
+            this.#options.extraOptions || target.extraOptions
+                ? {
+                      ...this.#options.extraOptions,
+                      ...target.extraOptions,
+                  }
+                : undefined;
+
+        return connectTls({
+            ...endpoint,
+            signal: options.signal,
+            caCerts: this.#options.caCerts,
+            sni: target.sni ?? this.#options.sni ?? endpoint.address,
+            alpnProtocols: target.alpnProtocols ??
+                this.#options.alpnProtocols ?? [...DEFAULT_HTTP_ALPN_PROTOCOLS],
+            extraOptions,
+        });
+    }
+}
+
+export namespace TlsDialer {
+    export interface Options {
+        caCerts?: string[];
+        sni?: string;
+        alpnProtocols?: string[];
+        extraOptions?: NodeTlsConnectOptions["extraOptions"];
+    }
+}
+
+/**
+ * Selects {@link TcpDialer} or {@link TlsDialer} based on the target security mode.
+ */
+export class AutoDialer implements Dialer {
+    readonly tcpDialer: TcpDialer;
+    readonly tlsDialer: TlsDialer;
+
+    constructor(options: AutoDialer.Options = {}) {
+        this.tcpDialer = options.tcp ?? new TcpDialer();
+        this.tlsDialer = options.tls ?? new TlsDialer();
+    }
+
+    dial(
+        target: Dialer.Target,
+        options: Dialer.Options = {},
+    ): Promise<Dialer.ConnectionLike> {
+        return target.secure
+            ? this.tlsDialer.dial(target, options)
+            : this.tcpDialer.dial(target, options);
+    }
+}
+
+export namespace AutoDialer {
+    export interface Options {
+        tcp?: TcpDialer;
+        tls?: TlsDialer;
+    }
+}

package/src/encoding.ts

@@ -0,0 +1,222 @@
+import { Readable } from "node:stream";
+import { nodeReadableToWeb } from "@fuman/node";
+import { DecodeStreamError } from "./_internal/decode-stream-error";
+
+export type ByteStream = ReadableStream<Uint8Array>;
+type ByteSource = ByteStream | AsyncIterable<Uint8Array>;
+export type ByteTransform = TransformStream<Uint8Array, Uint8Array>;
+
+function applyTransforms(
+    stream: ByteSource,
+    contentEncoding: string | string[] | undefined,
+    factory: (contentEncoding?: string | string[]) => ByteTransform[],
+): ByteSource {
+    const transforms = factory(contentEncoding);
+    if (transforms.length === 0) return stream;
+
+    let result: ByteStream;
+
+    if (stream instanceof ReadableStream) {
+        result = stream;
+    } else {
+        result = nodeReadableToWeb(Readable.from(stream));
+    }
+
+    for (const t of transforms) {
+        result = result.pipeThrough(t);
+    }
+
+    return result;
+}
+
+/**
+ * Applies decoding transforms for the given content-encoding list.
+ *
+ * @remarks
+ * If no supported encodings are provided, the original source is returned unchanged.
+ * Async iterables are converted to Web Streams only when transforms are required.
+ */
+export function decodeStream(
+    stream: ByteStream,
+    contentEncoding?: string | string[],
+): ByteStream;
+export function decodeStream(
+    stream: AsyncIterable<Uint8Array>,
+    contentEncoding?: string | string[],
+): AsyncIterable<Uint8Array> | ByteStream;
+export function decodeStream(
+    stream: ByteSource,
+    contentEncoding?: string | string[],
+): ByteSource {
+    return applyTransforms(stream, contentEncoding, createDecoders);
+}
+
+/**
+ * Applies encoding transforms for the given content-encoding list.
+ *
+ * @remarks
+ * If no supported encodings are provided, the original source is returned unchanged.
+ * Async iterables are converted to Web Streams only when transforms are required.
+ */
+export function encodeStream(
+    stream: ByteStream,
+    contentEncoding?: string | string[],
+): ByteStream;
+export function encodeStream(
+    stream: AsyncIterable<Uint8Array>,
+    contentEncoding?: string | string[],
+): AsyncIterable<Uint8Array> | ByteStream;
+export function encodeStream(
+    stream: ByteSource,
+    contentEncoding?: string | string[],
+): ByteSource {
+    return applyTransforms(stream, contentEncoding, createEncoders);
+}
+
+/**
+ * Creates the decoder pipeline for a Content-Encoding or transfer-coding list.
+ *
+ * @remarks
+ * Decoding is applied in reverse order of encoding, as required by HTTP semantics.
+ * The special value `identity` is ignored.
+ */
+export function createDecoders(
+    contentEncoding?: string | string[],
+): ByteTransform[] {
+    const decoders: ByteTransform[] = [];
+
+    if (contentEncoding?.length) {
+        const encodings: string[] = Array.isArray(contentEncoding)
+            ? contentEncoding.flatMap(commaSplit)
+            : contentEncoding.split(",");
+
+        for (const encoding of encodings) {
+            const normalizedEncoding = normalizeEncoding(encoding);
+
+            if (normalizedEncoding === "identity") continue;
+
+            decoders.push(createDecoder(normalizedEncoding));
+        }
+    }
+
+    return decoders.reverse();
+}
+
+/**
+ * Creates the encoder pipeline for a Content-Encoding or transfer-coding list.
+ *
+ * @remarks
+ * Encoders are returned in the declared order. The special value `identity` is ignored.
+ */
+export function createEncoders(
+    contentEncoding?: string | string[],
+): ByteTransform[] {
+    const encoders: ByteTransform[] = [];
+
+    if (contentEncoding?.length) {
+        const encodings: string[] = Array.isArray(contentEncoding)
+            ? contentEncoding.flatMap(commaSplit)
+            : contentEncoding.split(",");
+
+        for (const encoding of encodings) {
+            const normalizedEncoding = normalizeEncoding(encoding);
+
+            if (normalizedEncoding === "identity") continue;
+
+            encoders.push(createEncoder(normalizedEncoding));
+        }
+    }
+
+    return encoders;
+}
+
+function commaSplit(header: string): string[] {
+    return header.split(",");
+}
+
+function normalizeEncoding(encoding: string): string {
+    return encoding.trim().toLowerCase();
+}
+
+function tagDecodeErrors(native: ByteTransform): ByteTransform {
+    const reader = native.readable.getReader();
+
+    const tagged = new ReadableStream<Uint8Array>({
+        pull(controller) {
+            return reader.read().then(
+                ({ done, value }) => {
+                    if (done) {
+                        controller.close();
+                    } else if (value) {
+                        controller.enqueue(
+                            value as unknown as Uint8Array<ArrayBuffer>,
+                        );
+                    }
+                },
+                (err) => {
+                    controller.error(new DecodeStreamError(err));
+                },
+            );
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
+
+    return {
+        writable: native.writable,
+        readable: tagged,
+    } as ByteTransform;
+}
+
+function createDecoder(normalizedEncoding: string): ByteTransform {
+    switch (normalizedEncoding) {
+        case "gzip":
+        case "x-gzip":
+            return tagDecodeErrors(
+                new DecompressionStream("gzip") as ByteTransform,
+            );
+        case "deflate":
+        case "x-deflate":
+            return tagDecodeErrors(
+                new DecompressionStream("deflate") as ByteTransform,
+            );
+        case "zstd":
+        case "x-zstd":
+            return tagDecodeErrors(
+                new DecompressionStream("zstd" as any) as ByteTransform,
+            );
+        case "br":
+            return tagDecodeErrors(
+                new DecompressionStream("brotli" as any) as ByteTransform,
+            );
+        case "identity":
+            return new TransformStream();
+        default:
+            throw new TypeError(
+                `Unsupported content-encoding: "${normalizedEncoding}"`,
+            );
+    }
+}
+
+function createEncoder(normalizedEncoding: string): ByteTransform {
+    switch (normalizedEncoding) {
+        case "gzip":
+        case "x-gzip":
+            return new CompressionStream("gzip") as ByteTransform;
+        case "deflate":
+        case "x-deflate":
+            return new CompressionStream("deflate") as ByteTransform;
+        case "zstd":
+        case "x-zstd":
+            return new CompressionStream("zstd" as any) as ByteTransform;
+        case "br":
+            return new CompressionStream("brotli" as any) as ByteTransform;
+        case "identity":
+            return new TransformStream();
+        default:
+            throw new TypeError(
+                `Unsupported content-encoding: "${normalizedEncoding}"`,
+            );
+    }
+}