zapo-js 1.8.2 → 1.10.0

package/dist/transport/proxy.js

@@ -5,6 +5,9 @@ exports.isProxyAgent = isProxyAgent;
 exports.isProxyTransport = isProxyTransport;
 exports.toProxyDispatcher = toProxyDispatcher;
 exports.toProxyAgent = toProxyAgent;
+exports.toTcpProxyEndpoint = toTcpProxyEndpoint;
+exports.assertTcpProxySupported = assertTcpProxySupported;
+const bytes_1 = require("../util/bytes");
 /** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
@@ -37,3 +40,85 @@ function toProxyAgent(proxy) {
     }
     return proxy;
 }
+const TCP_PROXY_HINT = 'socketOptions.proxy.ws must hold an http.Agent-style proxy pointing at an http: url (e.g. new HttpProxyAgent("http://host:port")) to tunnel raw TCP';
+/**
+ * Resolves the proxy endpoint a raw TCP transport tunnels through with HTTP
+ * CONNECT.
+ *
+ * Returns `undefined` only when no proxy is configured. Proxy shapes the tunnel
+ * cannot honour throw instead of resolving to `undefined`, because dropping one
+ * silently would dial the destination directly – the opposite of what a
+ * deployment that pins its egress to a proxy asked for.
+ */
+function toTcpProxyEndpoint(proxy) {
+    if (!proxy) {
+        return undefined;
+    }
+    if (!isProxyAgent(proxy)) {
+        if (isProxyDispatcher(proxy)) {
+            throw new Error(`undici-style proxy dispatchers cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+        }
+        throw new Error(`unsupported proxy transport – ${TCP_PROXY_HINT}`);
+    }
+    const url = readAgentProxyUrl(proxy);
+    if (url.protocol !== 'http:') {
+        throw new Error(`proxy protocol ${url.protocol} is not supported by the raw TCP tunnel – ${TCP_PROXY_HINT}`);
+    }
+    const username = decodeProxyUserInfo(url.username, 'username');
+    const password = decodeProxyUserInfo(url.password, 'password');
+    return {
+        hostname: url.hostname,
+        port: url.port ? Number(url.port) : 80,
+        authorization: username || password
+            ? `Basic ${(0, bytes_1.bytesToBase64)(bytes_1.TEXT_ENCODER.encode(`${username}:${password}`))}`
+            : undefined
+    };
+}
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+function assertTcpProxySupported(proxy) {
+    toTcpProxyEndpoint(proxy);
+}
+/**
+ * Decodes one userinfo component of a proxy url. `new URL()` keeps invalid
+ * percent escapes verbatim, so a credential holding a literal `%` would reach
+ * `decodeURIComponent` and throw a bare `URIError`. The value never reaches the
+ * message – only the field name does.
+ */
+function decodeProxyUserInfo(value, field) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`proxy url ${field} contains a malformed percent escape`);
+    }
+}
+/**
+ * Reads the proxy url an `http.Agent`-style proxy exposes. Every `*-proxy-agent`
+ * package keeps it on `.proxy`, but only the http/https ones store a `URL`
+ * there – `socks-proxy-agent` stores a parsed `{ host, port, type }` endpoint.
+ */
+function readAgentProxyUrl(agent) {
+    const value = agent.proxy;
+    if (value instanceof URL) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            return new URL(value);
+        }
+        catch {
+            throw new Error(`proxy agent exposes an unparseable proxy url ${JSON.stringify(value)}`);
+        }
+    }
+    if (isSocksProxyEndpoint(value)) {
+        throw new Error(`socks proxy agents cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+    }
+    throw new Error(`proxy agent exposes no proxy url – ${TCP_PROXY_HINT}`);
+}
+/** Matches the `{ host, port, type }` endpoint `socks-proxy-agent` keeps on `.proxy`. */
+function isSocksProxyEndpoint(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.host === 'string' &&
+        typeof value.port === 'number');
+}

package/dist/util/collections.d.ts

@@ -8,4 +8,50 @@ export declare function createPeriodicCleanup(ttlMs: number, run: () => void): P
  * `defaultLimit` when `limit` is undefined. Throws on invalid input.
  */
 export declare function normalizeQueryLimit(limit: number | undefined, defaultLimit: number): number;
+/**
+ * Sweep period shared by a set of idle TTLs: the smallest `ttlMs / 2`,
+ * clamped to [1 s, 60 s].
+ */
+export declare function resolveIdleSweepPeriodMs(ttlsMs: readonly number[]): number;
+/**
+ * Coarse clock for idle expiry: one `unref`'d interval bumps `tick` and runs
+ * every registered sweep, and only while a sweep is registered. Wall-clock
+ * steps never move `tick`.
+ */
+export declare class IdleSweepClock {
+    readonly periodMs: number;
+    private currentTick;
+    private readonly sweeps;
+    private timer;
+    constructor(periodMs: number);
+    get tick(): number;
+    /** Runs `sweep` on every tick until the returned function is called. */
+    register(sweep: (tick: number) => void): () => void;
+    private readonly advance;
+}
+export interface IdleExpiry {
+    readonly clock: IdleSweepClock;
+    readonly ttlMs: number;
+}
+/**
+ * Idle expiry and LRU order for the entries of `data`. A touch moves the key
+ * to the young end of the index and of `data`, at most once per tick, so the
+ * sweep stops at the first live key and `data` iterates least recently used
+ * first. A key expires after `ceil(ttlMs / periodMs) + 1` untouched ticks:
+ * idle for at least `ttlMs` and, timer lateness aside, under `ttlMs + 2 * periodMs`.
+ */
+export declare class IdleExpiryIndex<K, V> {
+    private readonly data;
+    private readonly clock;
+    private readonly idleTicks;
+    private readonly touchedAt;
+    private readonly unregister;
+    constructor(data: Map<K, V>, expiry: IdleExpiry);
+    touch(key: K): void;
+    delete(key: K): void;
+    clear(): void;
+    /** Stops sweeping; the entries stay until the owner clears them. */
+    detach(): void;
+    private readonly sweep;
+}
 export declare function setBoundedMapEntry<K, V>(map: Map<K, V>, key: K, value: V, maxEntries: number, onEvict?: (key: K, value: V) => void): void;

package/dist/util/collections.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdleExpiryIndex = exports.IdleSweepClock = void 0;
 exports.resolveCleanupIntervalMs = resolveCleanupIntervalMs;
 exports.createPeriodicCleanup = createPeriodicCleanup;
 exports.normalizeQueryLimit = normalizeQueryLimit;
+exports.resolveIdleSweepPeriodMs = resolveIdleSweepPeriodMs;
 exports.setBoundedMapEntry = setBoundedMapEntry;
 function resolveCleanupIntervalMs(ttlMs, maxIntervalMs = 60000) {
     if (ttlMs <= 1000) {
@@ -30,6 +32,102 @@ function normalizeQueryLimit(limit, defaultLimit) {
     }
     return limit;
 }
+/**
+ * Sweep period shared by a set of idle TTLs: the smallest `ttlMs / 2`,
+ * clamped to [1 s, 60 s].
+ */
+function resolveIdleSweepPeriodMs(ttlsMs) {
+    let periodMs = 60000;
+    for (let i = 0; i < ttlsMs.length; i += 1) {
+        periodMs = Math.min(periodMs, Math.max(1000, Math.floor(ttlsMs[i] / 2)));
+    }
+    return periodMs;
+}
+/**
+ * Coarse clock for idle expiry: one `unref`'d interval bumps `tick` and runs
+ * every registered sweep, and only while a sweep is registered. Wall-clock
+ * steps never move `tick`.
+ */
+class IdleSweepClock {
+    constructor(periodMs) {
+        this.advance = () => {
+            this.currentTick += 1;
+            for (const sweep of this.sweeps)
+                sweep(this.currentTick);
+        };
+        this.periodMs = periodMs;
+        this.currentTick = 0;
+        this.sweeps = new Set();
+        this.timer = null;
+    }
+    get tick() {
+        return this.currentTick;
+    }
+    /** Runs `sweep` on every tick until the returned function is called. */
+    register(sweep) {
+        this.sweeps.add(sweep);
+        if (this.timer === null) {
+            this.timer = setInterval(this.advance, this.periodMs);
+            this.timer.unref?.();
+        }
+        return () => {
+            this.sweeps.delete(sweep);
+            if (this.sweeps.size > 0 || this.timer === null)
+                return;
+            clearInterval(this.timer);
+            this.timer = null;
+        };
+    }
+}
+exports.IdleSweepClock = IdleSweepClock;
+/**
+ * Idle expiry and LRU order for the entries of `data`. A touch moves the key
+ * to the young end of the index and of `data`, at most once per tick, so the
+ * sweep stops at the first live key and `data` iterates least recently used
+ * first. A key expires after `ceil(ttlMs / periodMs) + 1` untouched ticks:
+ * idle for at least `ttlMs` and, timer lateness aside, under `ttlMs + 2 * periodMs`.
+ */
+class IdleExpiryIndex {
+    constructor(data, expiry) {
+        this.sweep = (tick) => {
+            const cutoff = tick - this.idleTicks;
+            for (const [key, touchedAt] of this.touchedAt) {
+                if (touchedAt > cutoff)
+                    return;
+                this.touchedAt.delete(key);
+                this.data.delete(key);
+            }
+        };
+        this.data = data;
+        this.clock = expiry.clock;
+        this.idleTicks = Math.ceil(expiry.ttlMs / expiry.clock.periodMs) + 1;
+        this.touchedAt = new Map();
+        this.unregister = expiry.clock.register(this.sweep);
+    }
+    touch(key) {
+        const tick = this.clock.tick;
+        if (this.touchedAt.get(key) === tick)
+            return;
+        this.touchedAt.delete(key);
+        this.touchedAt.set(key, tick);
+        const value = this.data.get(key);
+        if (value === undefined)
+            return;
+        this.data.delete(key);
+        this.data.set(key, value);
+    }
+    delete(key) {
+        this.touchedAt.delete(key);
+    }
+    clear() {
+        this.touchedAt.clear();
+    }
+    /** Stops sweeping; the entries stay until the owner clears them. */
+    detach() {
+        this.unregister();
+    }
+}
+exports.IdleExpiryIndex = IdleExpiryIndex;
 function setBoundedMapEntry(map, key, value, maxEntries, onEvict) {
     map.delete(key);
     map.set(key, value);

package/dist/util/index.d.ts

@@ -1,6 +1,6 @@
 export { delay } from './async';
 export { base64ToBytes, bytesToBase64, bytesToBase64UrlSafe, bytesToHex, concatBytes, decodeBase64Url, EMPTY_BYTES, hexToBytes, TEXT_DECODER, TEXT_ENCODER, toBytesView, uint8Equal, uint8TimingSafeEqual } from './bytes';
-export { asBytes, asNumber, asOptionalBytes, asOptionalNumber, asOptionalString, asString, resolveOptionalPositive, resolvePositive, toBoolOrUndef } from './coercion';
-export { normalizeQueryLimit } from './collections';
+export { asBytes, asNumber, asOptionalBytes, asOptionalNumber, asOptionalString, asString, resolveOptionalPositive, resolvePositive, toBoolOrUndef, tryAsNumber } from './coercion';
+export { normalizeQueryLimit, setBoundedMapEntry } from './collections';
 export { toError, toSafeNumber } from './primitives';
 export { isBunRuntime } from './runtime';

package/dist/util/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isBunRuntime = exports.toSafeNumber = exports.toError = exports.normalizeQueryLimit = exports.toBoolOrUndef = exports.resolvePositive = exports.resolveOptionalPositive = exports.asString = exports.asOptionalString = exports.asOptionalNumber = exports.asOptionalBytes = exports.asNumber = exports.asBytes = exports.uint8TimingSafeEqual = exports.uint8Equal = exports.toBytesView = exports.TEXT_ENCODER = exports.TEXT_DECODER = exports.hexToBytes = exports.EMPTY_BYTES = exports.decodeBase64Url = exports.concatBytes = exports.bytesToHex = exports.bytesToBase64UrlSafe = exports.bytesToBase64 = exports.base64ToBytes = exports.delay = void 0;
+exports.isBunRuntime = exports.toSafeNumber = exports.toError = exports.setBoundedMapEntry = exports.normalizeQueryLimit = exports.tryAsNumber = exports.toBoolOrUndef = exports.resolvePositive = exports.resolveOptionalPositive = exports.asString = exports.asOptionalString = exports.asOptionalNumber = exports.asOptionalBytes = exports.asNumber = exports.asBytes = exports.uint8TimingSafeEqual = exports.uint8Equal = exports.toBytesView = exports.TEXT_ENCODER = exports.TEXT_DECODER = exports.hexToBytes = exports.EMPTY_BYTES = exports.decodeBase64Url = exports.concatBytes = exports.bytesToHex = exports.bytesToBase64UrlSafe = exports.bytesToBase64 = exports.base64ToBytes = exports.delay = void 0;
 var async_1 = require("./async");
 Object.defineProperty(exports, "delay", { enumerable: true, get: function () { return async_1.delay; } });
 var bytes_1 = require("./bytes");
@@ -27,8 +27,10 @@ Object.defineProperty(exports, "asString", { enumerable: true, get: function ()
 Object.defineProperty(exports, "resolveOptionalPositive", { enumerable: true, get: function () { return coercion_1.resolveOptionalPositive; } });
 Object.defineProperty(exports, "resolvePositive", { enumerable: true, get: function () { return coercion_1.resolvePositive; } });
 Object.defineProperty(exports, "toBoolOrUndef", { enumerable: true, get: function () { return coercion_1.toBoolOrUndef; } });
+Object.defineProperty(exports, "tryAsNumber", { enumerable: true, get: function () { return coercion_1.tryAsNumber; } });
 var collections_1 = require("./collections");
 Object.defineProperty(exports, "normalizeQueryLimit", { enumerable: true, get: function () { return collections_1.normalizeQueryLimit; } });
+Object.defineProperty(exports, "setBoundedMapEntry", { enumerable: true, get: function () { return collections_1.setBoundedMapEntry; } });
 var primitives_1 = require("./primitives");
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return primitives_1.toError; } });
 Object.defineProperty(exports, "toSafeNumber", { enumerable: true, get: function () { return primitives_1.toSafeNumber; } });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapo-js",
-    "version": "1.8.2",
+    "version": "1.10.0",
     "description": "High-performance WhatsApp Web TypeScript library",
     "license": "MIT",
     "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",