kinetex 1.3.0 → 1.4.0

package/dist/cjs/socks5.js

@@ -136,6 +136,12 @@ class BufReader {
     }
 }
 function withTimeout(promise, ms, message) {
+    // A non-positive budget means "no timeout", matching `denoTcpConnector`,
+    // which documents and tests exactly that. Passing 0 to `setTimeout` fired on
+    // the next tick, so `connectTimeoutMs: 0` — the conventional way to say
+    // "wait as long as it takes" — failed the connection instantly.
+    if (!Number.isFinite(ms) || ms <= 0)
+        return promise;
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Socks5Error(message, "SOCKS5_TIMEOUT", true)), ms);
         promise.then((v) => {
@@ -179,8 +185,46 @@ function encodeAddress(host, remoteDns) {
     }
     return new Uint8Array([AddrType.Domain, enc.length, ...enc]);
 }
+/**
+ * A single hextet: one to four hex digits.
+ *
+ * `parseInt(g, 16)` is not a validation. It accepts trailing garbage
+ * (`parseInt("12zz", 16)` is 18) and returns `NaN` for anything that is not
+ * hex at all — and `NaN` then sailed through the `g < 0 || g > 0xffff` range
+ * check, because every comparison with `NaN` is false. `NaN >> 8 & 0xff` is
+ * 0, so such a group contributed a zero pair.
+ */
+const HEX_GROUP = /^[0-9a-fA-F]{1,4}$/;
+/**
+ * True when `s` is a syntactically valid IPv6 literal.
+ *
+ * Structural, NOT "contains a colon". The old test accepted any string with a
+ * colon in it, so a hostname like `g:h:i:j:k:l:m:n` was taken for an IPv6
+ * literal: eight groups, every one of them `NaN`, all eight of which passed
+ * the range check, and the result encoded as sixteen zero bytes. The proxy
+ * was then asked to connect to the unspecified address `::` and the tunnel
+ * was established — to the wrong place, with no error anywhere. A name that
+ * is not a valid IPv6 literal is now left to the domain-name encoding, where
+ * the proxy resolves it and reports host-unreachable if it is not real.
+ */
 function isIPv6(s) {
-    return s.includes(":");
+    if (!s.includes(":"))
+        return false;
+    // At most one compressed run ("::"). Two would be ambiguous.
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return false;
+    const groupsOf = (part) => part === undefined || part === "" ? [] : part.split(":");
+    const left = groupsOf(halves[0]);
+    if (halves.length === 2) {
+        const right = groupsOf(halves[1]);
+        // "::" must stand for at least one omitted group.
+        if (left.length + right.length > 7)
+            return false;
+        return [...left, ...right].every((g) => HEX_GROUP.test(g));
+    }
+    // Uncompressed: all eight groups must be present and well formed.
+    return left.length === 8 && left.every((g) => HEX_GROUP.test(g));
 }
 /**
  * Expand a compressed IPv6 address to 8 groups (16 bytes).
@@ -198,7 +242,7 @@ function isIPv6(s) {
 function expandIPv6(addr) {
     // Expand :: and return 16 bytes
     const halves = addr.split("::");
-    const expand = (part) => part ? part.split(":").map((g) => parseInt(g || "0", 16)) : [];
+    const expand = (part) => part ? part.split(":").map((g) => (HEX_GROUP.test(g) ? parseInt(g, 16) : Number.NaN)) : [];
     let groups;
     if (halves.length === 2) {
         const left = expand(halves[0]);
@@ -212,9 +256,11 @@ function expandIPv6(addr) {
     if (groups.length !== 8) {
         throw new Socks5Error(`Invalid IPv6 address: ${addr}`, "SOCKS5_INVALID_ADDR");
     }
-    // Validate each group is within 16-bit range (0-0xFFFF)
+    // Validate each group is a finite 16-bit value. `Number.isFinite` is the
+    // load-bearing half: a bare `g < 0 || g > 0xffff` is false for every NaN,
+    // so an unparseable group passed and then encoded as a zero pair.
     for (const g of groups) {
-        if (g < 0 || g > 0xffff) {
+        if (!Number.isFinite(g) || g < 0 || g > 0xffff) {
             throw new Socks5Error(`Invalid IPv6 group: ${g} out of range (0-65535)`, "SOCKS5_INVALID_ADDR");
         }
     }
@@ -357,6 +403,17 @@ function sleep(ms) {
 // ---------------------------------------------------------------------------
 // 8. CONFIG NORMALISATION
 // ---------------------------------------------------------------------------
+/** TCP-level errors worth another attempt. */
+const TRANSIENT_DIAL_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EAI_AGAIN",
+]);
 function resolveConfig(cfg) {
     return {
         host: cfg.host,
@@ -398,8 +455,33 @@ function resolveConfig(cfg) {
 export async function createSocks5Tunnel(proxyConfig, target, connector) {
     const config = resolveConfig(proxyConfig);
     return await withRetry(async () => {
-        // Open raw TCP to proxy
-        const conn = await withTimeout(connector(config.host, config.port, config.connectTimeoutMs), config.connectTimeoutMs, `TCP connection to SOCKS5 proxy ${config.host}:${config.port} timed out`);
+        // Open raw TCP to proxy.
+        //
+        // A rejection from the connector used to escape UNCHANGED, so a proxy
+        // that was not listening surfaced as a bare
+        // `Error: connect ECONNREFUSED 127.0.0.1:1` rather than a
+        // Socks5Error. Two things broke at once. The documented contract says
+        // this function throws Socks5Error, and a caller switching on `code`
+        // now had to know about two vocabularies — `ECONNREFUSED` from node:net
+        // and `SOCKS5_*` from here. And `withRetry` only retries an error that
+        // is a Socks5Error with `retriable` set, so the one failure most worth
+        // retrying — the proxy not being up yet — was the one failure never
+        // retried, and the exponential backoff this module is built around went
+        // unused for it.
+        const conn = await withTimeout(connector(config.host, config.port, config.connectTimeoutMs), config.connectTimeoutMs, `TCP connection to SOCKS5 proxy ${config.host}:${config.port} timed out`).catch((err) => {
+            // An abort is the caller's own doing and is already an AbortError,
+            // and anything already in this module's vocabulary passes through.
+            if (err instanceof Socks5Error || err instanceof DOMException)
+                throw err;
+            const code = err?.code;
+            const systemCode = typeof code === "string" ? code : "UNKNOWN";
+            throw new Socks5Error(`Cannot reach SOCKS5 proxy ${config.host}:${config.port}: ${err instanceof Error ? err.message : String(err)}`, "SOCKS5_CONNECT_FAILED", 
+            // Transient at the TCP layer: the proxy may come back, or the path
+            // to it may. ENOTFOUND is deliberately excluded — a proxy hostname
+            // that does not resolve is a configuration mistake, and retrying it
+            // only delays saying so.
+            TRANSIENT_DIAL_CODES.has(systemCode));
+        });
         try {
             const { boundAddr, boundPort } = await performHandshake(conn, target, config);
             return { conn, boundAddr, boundPort };
@@ -459,11 +541,23 @@ export function parseSocks5Url(url) {
         port,
         remoteDns,
     };
+    // Percent-decoding can itself fail: `decodeURIComponent("%ZZ")` throws a
+    // `URIError`, which escaped this function as a raw URIError rather than the
+    // documented Socks5Error, so a caller mapping error codes never saw one.
+    // Nothing here includes the URL, so a clean SOCKS5_BAD_URL leaks nothing.
+    const decode = (raw, field) => {
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            throw new Socks5Error(`Invalid SOCKS5 proxy URL: malformed percent-encoding in the ${field}`, "SOCKS5_BAD_URL");
+        }
+    };
     if (parsed.username) {
-        config.username = decodeURIComponent(parsed.username);
+        config.username = decode(parsed.username, "username");
     }
     if (parsed.password) {
-        config.password = decodeURIComponent(parsed.password);
+        config.password = decode(parsed.password, "password");
     }
     return config;
 }
@@ -556,10 +650,20 @@ export const nodeTcpConnector = (host, port, timeoutMs) => {
         import("node:net")
             .then(({ createConnection }) => {
             const socket = createConnection({ host, port });
-            const timer = setTimeout(() => {
-                socket.destroy();
-                reject(new Socks5Error("TCP connect to proxy timed out", "SOCKS5_TIMEOUT", true));
-            }, timeoutMs);
+            // Same rule as the Deno connector: 0 (or any non-positive budget)
+            // disables the timeout rather than firing on the next tick. Every
+            // `clearTimeout(timer)` below is guarded on `timer` being defined.
+            let timer;
+            if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    socket.destroy();
+                    reject(new Socks5Error("TCP connect to proxy timed out", "SOCKS5_TIMEOUT", true));
+                }, timeoutMs);
+            }
+            const clear = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            };
             let buffer = new Uint8Array(0);
             let pendingRead = null;
             let pendingReject = null;
@@ -610,13 +714,13 @@ export const nodeTcpConnector = (host, port, timeoutMs) => {
                 ended = true;
             });
             socket.once("error", (err) => {
-                clearTimeout(timer);
+                clear();
                 lastError = err;
                 rejectPending(err);
                 reject(err);
             });
             socket.once("connect", () => {
-                clearTimeout(timer);
+                clear();
                 socket.on("error", (err) => {
                     lastError = err;
                     rejectPending(err);
@@ -690,7 +794,19 @@ export const nodeTcpConnector = (host, port, timeoutMs) => {
  */
 export function socks5Connector(proxyConfig, baseConnector) {
     return async (host, port, timeoutMs) => {
-        const tunnel = await createSocks5Tunnel({ connectTimeoutMs: timeoutMs, ...proxyConfig }, { host, port }, baseConnector);
+        // The per-call `timeoutMs` is the more specific value, so it must be
+        // spread LAST. It was spread first, so a `connectTimeoutMs` in the proxy
+        // config silently overrode it — a caller asking for 5s was dialled with
+        // the config's 99s, and nothing said so. It also now bounds the
+        // handshake, which is the same "how long may this connection take" budget
+        // the caller expressed and was otherwise ignored entirely.
+        const perCall = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+        const connectTimeoutMs = perCall ?? proxyConfig.connectTimeoutMs;
+        const tunnel = await createSocks5Tunnel({
+            ...proxyConfig,
+            ...(connectTimeoutMs !== undefined ? { connectTimeoutMs } : {}),
+            ...(perCall !== undefined ? { handshakeTimeoutMs: perCall } : {}),
+        }, { host, port }, baseConnector);
         return tunnel.conn;
     };
 }

package/dist/cjs/sse.js

@@ -113,6 +113,12 @@ export class SSEParser {
         }
         switch (field) {
             case "id":
+                // A field value containing U+0000 is ignored per spec. This string is
+                // replayed verbatim in the `Last-Event-ID` request header on every
+                // reconnect, and a NUL is not a legal header value at all — so
+                // storing one turns a reconnection into a thrown TypeError.
+                if (value.includes("\u0000"))
+                    break;
                 // Empty id resets the last event id to null per spec
                 this.id = value || null;
                 break;
@@ -123,9 +129,12 @@ export class SSEParser {
                 this.data.push(value);
                 break;
             case "retry": {
-                const ms = parseInt(value, 10);
-                if (!isNaN(ms) && ms >= 0)
-                    this.retry = ms;
+                // Spec: the field is honoured only when every character is an ASCII
+                // digit. `parseInt` accepted a trailing "abc", a leading "+", and the
+                // "1e3" exponent, so a proxy rewriting the line as
+                // `retry: 3000; path=/` silently set the reconnection back-off.
+                if (/^[0-9]+$/.test(value))
+                    this.retry = Number(value);
                 break;
             }
             // Unknown fields are ignored per spec
@@ -288,13 +297,35 @@ export class SSEClient {
     async collect(options = {}) {
         const events = [];
         let count = 0;
-        for await (const event of this._stream()) {
-            events.push(event);
-            count++;
-            if (options.limit && count >= options.limit)
-                break;
-            if (options.signal?.aborted)
-                break;
+        // The signal has to reach the read loop, not just the check after an
+        // event. Cancelling a collection is for a stream that has gone quiet, and
+        // a quiet stream is precisely the one parked in `reader.read()` with no
+        // event to reach the check — so the abort was only ever observed once
+        // something arrived, which for a stalled endpoint meant never. Aborting
+        // the stream's own controller is what makes the pending read settle, so
+        // the generator unwinds and the socket is released.
+        // An `abort` event never fires on a signal that is already aborted, so a
+        // listener alone would silently ignore the one case that needs no
+        // waiting: a request cancelled before it starts must not connect at all.
+        const signal = options.signal;
+        if (signal?.aborted)
+            return [];
+        const onAbort = () => {
+            this._streamController?.abort();
+        };
+        signal?.addEventListener("abort", onAbort);
+        try {
+            for await (const event of this._stream()) {
+                events.push(event);
+                count++;
+                if (options.limit && count >= options.limit)
+                    break;
+                if (options.signal?.aborted)
+                    break;
+            }
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
         }
         return events;
     }
@@ -334,7 +365,13 @@ export class SSEClient {
         let reconnectAttempt = 0;
         // Create abort controller for this stream
         this._streamController = new AbortController();
-        while (!this._closed && !this._streamController?.signal.aborted) {
+        // `close()` aborts this controller, but the reconnect back-off below used
+        // to sleep on the *caller's* signal only. A `close()` during a back-off
+        // therefore left the generator parked for the full delay — up to
+        // `maxReconnectDelayMs` — so `for await (const e of client.stream())` hung
+        // long after the client was told to shut down. The back-off watches both.
+        const streamSignal = this._streamController.signal;
+        while (!this._closed && !streamSignal.aborted) {
             // Snapshot _closed to avoid race with setter firing during yield
             const closedSnapshot = this._closed;
             if (closedSnapshot || cfg.signal?.aborted || this._streamController?.signal.aborted)
@@ -402,7 +439,17 @@ export class SSEClient {
                     while (!closedSnapshot) {
                         if (cfg.signal?.aborted)
                             break;
-                        const { done, value } = await reader.read();
+                        // `closedSnapshot` is a snapshot, and neither signal is wired into
+                        // the fetch (the request carries the caller's signal, not the
+                        // stream's), so a `close()` — documented as aborting any active
+                        // stream — was simply not observed until the server happened to
+                        // send something. On a long-lived stream, which is the normal
+                        // case, `for await (const e of client.stream())` never returned
+                        // after `client.close()`. The read is raced against both signals.
+                        const result = await readOrAbort(reader.read(), cfg.signal, streamSignal);
+                        if (result === null)
+                            break;
+                        const { done, value } = result;
                         if (done)
                             break;
                         const text = decoder.decode(value, { stream: true });
@@ -426,15 +473,21 @@ export class SSEClient {
                 finally {
                     if (heartbeatTimer)
                         clearTimeout(heartbeatTimer);
+                    // The returned promise is what has to be handled, not the call.
+                    // `cancel()` on a reader whose stream is already errored — which is
+                    // exactly what an abort leaves behind — rejects with that stored
+                    // error, and a rejection nobody awaits terminates a Node process.
                     try {
-                        reader.cancel();
+                        void reader.cancel().catch(() => { });
                     }
                     catch {
                         /* ignore */
                     }
                 }
-                // Flush remaining
-                const final = parser.flush();
+                // Flush remaining — but never after an abort or a close(): a
+                // half-received event belonging to a stream the caller has already
+                // torn down is not something to deliver.
+                const final = streamSignal.aborted || cfg.signal?.aborted ? null : parser.flush();
                 if (final) {
                     this.health.totalEvents++;
                     this.health.lastEventAt = Date.now();
@@ -479,10 +532,11 @@ export class SSEClient {
                     clearTimeout(heartbeatTimer);
                     heartbeatTimer = null;
                 }
-                // Abortable: without the signal an abort() during back-off had to wait
-                // out the full delay (up to maxReconnectDelayMs) before being noticed.
-                await sleep(delay, cfg.signal);
-                if (cfg.signal?.aborted)
+                // Abortable by the caller's signal *and* by close(). Without this, an
+                // abort or a close() during back-off had to wait out the full delay (up
+                // to maxReconnectDelayMs) before being noticed.
+                await sleepOrAbort(delay, cfg.signal, streamSignal);
+                if (cfg.signal?.aborted || streamSignal.aborted)
                     break;
                 parser.reset();
                 continue;
@@ -512,10 +566,11 @@ export class SSEClient {
                 clearTimeout(heartbeatTimer);
                 heartbeatTimer = null;
             }
-            await sleep(delay, cfg.signal);
-            // Same as the error path: without this, a close()/abort() during a
-            // clean-close back-off was not noticed until the full delay elapsed.
-            if (cfg.signal?.aborted)
+            // Same as the error path: without watching the stream signal here too, a
+            // close()/abort() during a clean-close back-off was not noticed until the
+            // full delay elapsed.
+            await sleepOrAbort(delay, cfg.signal, streamSignal);
+            if (cfg.signal?.aborted || streamSignal.aborted)
                 break;
         }
         this.health.connected = false;
@@ -587,13 +642,19 @@ export class SSERouter {
      */
     onJSON(eventType, handler) {
         return this.on(eventType, async (data, evt) => {
+            let parsed;
             try {
-                const parsed = sanitizeParsedJSON(JSON.parse(data));
-                await handler(parsed, evt);
+                parsed = sanitizeParsedJSON(JSON.parse(data));
             }
             catch {
-                /* ignore parse error */
+                // Only the PARSE is swallowed, which is what the method documents. The
+                // handler used to run inside the same `try`, so a handler that threw
+                // was discarded with no trace of why — and `dispatch()` / `consume()`
+                // awaited every handler, so a caller relying on them to surface
+                // failures never saw one.
+                return;
             }
+            await handler(parsed, evt);
         });
     }
     /** Register a handler for "message" events (default event type). */
@@ -634,6 +695,24 @@ export class SSERouter {
 // ============================================================================
 // §7  SSE SERVER BUILDER
 // ============================================================================
+/**
+ * Make a value safe to place after a field name in an SSE stream.
+ *
+ * The event-stream format has no escaping: a CR, LF or NUL inside a field
+ * value ends that line, and whatever follows is parsed as a field of its own.
+ * `id` and `event` are written verbatim, so a caller passing a row id, a
+ * filename or any other user-controlled string could forge `event:` or
+ * `data:` lines into the stream — the receiving parser reads them as
+ * first-class fields, not as a fragment of the value. The characters are
+ * removed rather than escaped, because there is nothing to escape them with.
+ */
+function asFieldValue(value) {
+    // The control characters are the point: CR, LF and NUL are exactly the
+    // bytes that would terminate the SSE field line and let the rest of the
+    // value be read as fields of its own.
+    // deno-lint-ignore no-control-regex
+    return value.replace(/[\r\n\u0000]/g, "");
+}
 /**
  * Builder for creating SSE-compatible server responses.
  * Works with any runtime that supports the WHATWG Streams API.
@@ -661,7 +740,7 @@ export class SSEServerResponse {
     /** Send a comment (heartbeat ping). */
     comment(text = "") {
         if (!this._closed)
-            this.controller.enqueue(`: ${text}\n\n`);
+            this.controller.enqueue(`: ${asFieldValue(text)}\n\n`);
         return this;
     }
     /** Send a "message" event. */
@@ -674,13 +753,15 @@ export class SSEServerResponse {
             return this;
         let msg = "";
         if (options.id !== undefined)
-            msg += `id: ${options.id}\n`;
+            msg += `id: ${asFieldValue(options.id)}\n`;
         if (event !== "message")
-            msg += `event: ${event}\n`;
+            msg += `event: ${asFieldValue(event)}\n`;
         if (options.retry !== undefined)
             msg += `retry: ${options.retry}\n`;
-        // Multi-line data support
-        for (const line of data.split("\n")) {
+        // Multi-line data support. Split on all three SSE line endings, not just
+        // LF: a bare CR ends a line for every conforming reader, so leaving it
+        // inside a `data:` value silently turned one event into two on the way in.
+        for (const line of data.split(/\r\n|\r|\n/)) {
             msg += `data: ${line}\n`;
         }
         msg += "\n";
@@ -847,21 +928,70 @@ export function parseSSEText(text) {
 // ============================================================================
 // §10  UTILITIES
 // ============================================================================
-function sleep(ms, signal) {
-    return new Promise((r) => {
-        if (signal?.aborted) {
-            r();
-            return;
-        }
+/**
+ * Sleep for `ms`, or until any of `signals` aborts.
+ *
+ * `sleep` above only watches one signal, which is not enough for the reconnect
+ * back-off: that sleep has to be interruptible both by the caller's signal and
+ * by `close()`, and those are two different signals.
+ */
+/**
+ * A read that gives up when any of `signals` aborts.
+ *
+ * Resolves `null` on abort, and otherwise passes the read through — including
+ * its rejection, which must still surface (a reset mid-stream is a real
+ * error, not an abort). The pending read is left with a no-op rejection
+ * handler when the race is won by an abort, or it would surface later as an
+ * unhandled rejection and take the host process down.
+ */
+function readOrAbort(read, ...signals) {
+    const live = signals.filter((s) => Boolean(s));
+    if (live.some((s) => s.aborted)) {
+        read.then(undefined, () => { });
+        return Promise.resolve(null);
+    }
+    return new Promise((resolve, reject) => {
         const onAbort = () => {
+            detach();
+            read.then(undefined, () => { });
+            resolve(null);
+        };
+        const detach = () => {
+            for (const s of live)
+                s.removeEventListener("abort", onAbort);
+        };
+        for (const s of live)
+            s.addEventListener("abort", onAbort, { once: true });
+        read.then((v) => {
+            detach();
+            resolve(v);
+        }, (e) => {
+            detach();
+            reject(e);
+        });
+    });
+}
+function sleepOrAbort(ms, ...signals) {
+    const live = signals.filter((s) => Boolean(s));
+    if (live.some((s) => s.aborted))
+        return Promise.resolve();
+    return new Promise((r) => {
+        const handlers = [];
+        const finish = () => {
             clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
+            for (const h of handlers)
+                h();
             r();
         };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            r();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(finish, ms);
+        for (const s of live) {
+            const onAbort = () => {
+                clearTimeout(timer);
+                s.removeEventListener("abort", onAbort);
+                r();
+            };
+            handlers.push(() => s.removeEventListener("abort", onAbort));
+            s.addEventListener("abort", onAbort, { once: true });
+        }
     });
 }