socket-function 1.2.16 → 1.2.17

package/.claude/settings.local.json

@@ -2,7 +2,9 @@
   "permissions": {
     "allow": [
       "Bash(mkdir -p C:/Users/quent/AppData/Local/Temp/claude/D--repos-socket-function/117d10bd-31c6-4c68-938d-1fff47788fa6/scratchpad/tm-recover)",
-      "Bash(cp -r 'C:/Users/quent/AppData/Local/BraveSoftware/Brave-Browser/User Data/Default/Local Extension Settings/dhdgffkkebhmkfjojejmpbldmpobfkfo' C:/Users/quent/AppData/Local/Temp/claude/D--repos-socket-function/117d10bd-31c6-4c68-938d-1fff47788fa6/scratchpad/tm-recover/LocalExtSettings)"
+      "Bash(cp -r 'C:/Users/quent/AppData/Local/BraveSoftware/Brave-Browser/User Data/Default/Local Extension Settings/dhdgffkkebhmkfjojejmpbldmpobfkfo' C:/Users/quent/AppData/Local/Temp/claude/D--repos-socket-function/117d10bd-31c6-4c68-938d-1fff47788fa6/scratchpad/tm-recover/LocalExtSettings)",
+      "Bash(yarn test-dns-claude *)",
+      "Bash(yarn type *)"
     ]
   }
 }

package/index.d.ts

@@ -852,6 +852,25 @@ declare module "socket-function/src/createSingleton" {
 
 }
 
+declare module "socket-function/src/dnsCache" {
+    /// <reference types="node" />
+    import * as net from "net";
+    interface DNSRecord {
+        address: string;
+        family: number;
+    }
+    export declare function resolveHost(hostname: string, family?: number): Promise<DNSRecord[]>;
+    export declare const dnsCacheLookup: net.LookupFunction;
+    export declare function reportConnectionFailure(hostname: string): Promise<boolean>;
+    export {};
+
+}
+
+declare module "socket-function/src/dnsCacheTest" {
+    export {};
+
+}
+
 declare module "socket-function/src/fixLargeNetworkCalls" {
     export declare function markArrayAsSplitable<T>(data: T[]): T[];
     export declare function isSplitableArray<T>(data: T): data is T & (unknown[]);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "socket-function",
-	"version": "1.2.16",
+	"version": "1.2.17",
 	"main": "index.js",
 	"license": "MIT",
 	"dependencies": {
@@ -30,7 +30,8 @@
 		"generate-index-dts": "node ./generateIndexDts.js",
 		"update-types": "yarn emit-dts && yarn generate-index-dts",
 		"prepublishOnly": "yarn update-types",
-		"testsni": "yarn typenode ./src/sniTest.ts"
+		"testsni": "yarn typenode ./src/sniTest.ts",
+		"test-dns-claude": "yarn typenode ./src/dnsCacheTest.ts"
 	},
 	"devDependencies": {
 		"@types/cookie": "^0.5.1",

package/src/dnsCache.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import * as net from "net";
+interface DNSRecord {
+    address: string;
+    family: number;
+}
+export declare function resolveHost(hostname: string, family?: number): Promise<DNSRecord[]>;
+export declare const dnsCacheLookup: net.LookupFunction;
+export declare function reportConnectionFailure(hostname: string): Promise<boolean>;
+export {};

package/src/dnsCache.ts

@@ -0,0 +1,203 @@
+import * as dns from "dns";
+import * as net from "net";
+import { delay } from "./batching";
+
+// Node's default `dns.lookup` (getaddrinfo) delegates to glibc on Linux, which caches certain
+//  failures (notably EAI_AGAIN from a temporarily unreachable resolver) effectively forever within
+//  the process. Once poisoned, every subsequent connection to that host keeps failing even after the
+//  network recovers. To avoid this we resolve names ourselves via `dns.resolve*` (which talks to the
+//  resolver directly and keeps no such sticky failure cache) and maintain our own cache that we can
+//  invalidate on demand. httpsRequest drives that invalidation: on a connection-establishment error it
+//  asks us to re-resolve, then retries against the fresh address.
+
+// How long a successful resolution is trusted before we resolve again. Node by default does no positive
+//  caching at all — it calls getaddrinfo for every single connection — so any cache we add is strictly
+//  better than the baseline; even a 1s TTL would be an improvement. (The failure case is the exception:
+//  glibc caches certain resolution failures process-forever, which is the whole reason this module exists.)
+const CACHE_TTL = 60 * 1000;
+// A single resolution keeps retrying for up to this long / this many attempts before giving up. We very
+//  rarely hit genuinely invalid domains, so we happily trade latency for riding out flaky resolvers.
+const RESOLVE_MAX_TRIES = 10;
+const RESOLVE_MAX_DURATION = 5 * 1000;
+const RESOLVE_RETRY_INTERVAL = 500;
+// Minimum spacing between forced re-resolutions of the same host. This both protects the resolver from a
+//  retry storm and defines when a re-resolution is pointless: if we re-resolved this recently, retrying
+//  the request would just reuse the same fresh answer, so httpsRequest is told not to bother.
+const RERESOLVE_THROTTLE = 5 * 1000;
+// How long a failed resolution is remembered. Without this, a genuinely unresolvable host would re-run the
+//  full (already-exhaustive) 5s resolve loop on every retry and every parallel caller — the resolve loop
+//  takes as long as the throttle window, so the throttle alone never engages. A failure that just survived
+//  RESOLVE_MAX_TRIES won't differ if we immediately try again, so we serve it from cache instead.
+const NEGATIVE_CACHE_TTL = 5 * 1000;
+
+interface DNSRecord {
+    address: string;
+    // 4 or 6
+    family: number;
+}
+
+interface DNSEntry {
+    hostname: string;
+    records?: DNSRecord[];
+    resolvedAt: number;
+    // Shared by all callers that arrive while a resolution is in flight, so parallel requests to the
+    //  same host block on a single resolution rather than each firing their own.
+    resolving?: Promise<DNSRecord[]>;
+    lastReresolve: number;
+    // Negative cache: the last resolution failure and when it completed, so recent failures short-circuit
+    //  rather than re-running the resolve loop. Kept as the real Error so we rethrow it with its code intact.
+    lastError?: Error;
+    failedAt?: number;
+}
+
+const entries = new Map<string, DNSEntry>();
+function getEntry(hostname: string): DNSEntry {
+    let entry = entries.get(hostname);
+    if (!entry) {
+        entry = { hostname, resolvedAt: 0, lastReresolve: 0 };
+        entries.set(hostname, entry);
+    }
+    return entry;
+}
+
+function filterFamily(records: DNSRecord[], family: number): DNSRecord[] {
+    if (!family) return records;
+    return records.filter(r => r.family === family);
+}
+
+// Resolves both address families directly (ignoring the requested family so the cache is family-agnostic;
+//  callers filter afterwards). Falls back to getaddrinfo for names dns.resolve can't see — IP literals,
+//  localhost, and anything in /etc/hosts.
+async function resolveOnce(hostname: string): Promise<DNSRecord[]> {
+    let ipFamily = net.isIP(hostname);
+    if (ipFamily) {
+        return [{ address: hostname, family: ipFamily }];
+    }
+
+    let records: DNSRecord[] = [];
+    await Promise.all([
+        dns.promises.resolve4(hostname).then(
+            addresses => { for (let address of addresses) records.push({ address, family: 4 }); },
+            // A host having no A (or no AAAA) record is normal, not a failure of the whole resolution.
+            () => { }
+        ),
+        dns.promises.resolve6(hostname).then(
+            addresses => { for (let address of addresses) records.push({ address, family: 6 }); },
+            () => { }
+        ),
+    ]);
+    if (records.length > 0) {
+        return records;
+    }
+
+    // dns.resolve* ignores /etc/hosts and the `localhost` entry, so fall back to getaddrinfo. We only
+    //  reach the sticky-failure-caching path when our own resolution found nothing, which is exactly the
+    //  case where /etc/hosts is the likely source of truth.
+    let fallback = await dns.promises.lookup(hostname, { all: true });
+    return fallback.map(r => ({ address: r.address, family: r.family }));
+}
+
+async function resolveFresh(hostname: string): Promise<DNSRecord[]> {
+    let start = Date.now();
+    let attempt = 0;
+    let lastError: unknown;
+    while (true) {
+        attempt++;
+        try {
+            let records = await resolveOnce(hostname);
+            if (records.length > 0) {
+                return records;
+            }
+            lastError = new Error(`No DNS records found for ${hostname}`);
+        } catch (e) {
+            lastError = e;
+        }
+        if (attempt >= RESOLVE_MAX_TRIES) break;
+        if (Date.now() - start >= RESOLVE_MAX_DURATION) break;
+        await delay(RESOLVE_RETRY_INTERVAL);
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+function startResolve(entry: DNSEntry): Promise<DNSRecord[]> {
+    let resolving = (async () => {
+        try {
+            let records = await resolveFresh(entry.hostname);
+            entry.records = records;
+            entry.resolvedAt = Date.now();
+            entry.lastError = undefined;
+            entry.failedAt = undefined;
+            return records;
+        } catch (e) {
+            entry.records = undefined;
+            entry.lastError = e instanceof Error ? e : new Error(String(e));
+            entry.failedAt = Date.now();
+            throw entry.lastError;
+        } finally {
+            entry.resolving = undefined;
+        }
+    })();
+    entry.resolving = resolving;
+    return resolving;
+}
+
+export async function resolveHost(hostname: string, family = 0): Promise<DNSRecord[]> {
+    let entry = getEntry(hostname);
+    if (entry.records && Date.now() - entry.resolvedAt < CACHE_TTL) {
+        return filterFamily(entry.records, family);
+    }
+    // Serve a recent failure from the negative cache rather than re-running the exhaustive resolve loop.
+    if (entry.lastError && entry.failedAt !== undefined && Date.now() - entry.failedAt < NEGATIVE_CACHE_TTL) {
+        throw entry.lastError;
+    }
+    let resolving = entry.resolving ?? startResolve(entry);
+    return filterFamily(await resolving, family);
+}
+
+// A `lookup` function matching Node's net/http contract, so we can hand it to http(s).request and have
+//  the socket use our cache instead of getaddrinfo. Always resolves via our cache; happy eyeballs
+//  (autoSelectFamily) then races the returned addresses.
+export const dnsCacheLookup: net.LookupFunction = function dnsCacheLookup(hostname, options, callback) {
+    let rawFamily = typeof options === "number" ? options : options.family ?? 0;
+    let family = rawFamily === "IPv4" ? 4 : rawFamily === "IPv6" ? 6 : rawFamily;
+    let all = typeof options === "object" && options.all;
+    resolveHost(hostname, family).then(
+        records => {
+            if (all) {
+                callback(null, records.map(r => ({ address: r.address, family: r.family })));
+            } else {
+                let record = records[0];
+                callback(null, record.address, record.family);
+            }
+        },
+        (err: NodeJS.ErrnoException) => callback(err, "", undefined)
+    );
+};
+
+// Called by httpsRequest when a connection could not be established. Forces a throttled re-resolution and
+//  reports whether retrying is worthwhile. Returns false when we re-resolved too recently — in that case
+//  the cache already holds the freshest answer we can get, so retrying would hit the same address.
+export async function reportConnectionFailure(hostname: string): Promise<boolean> {
+    let entry = getEntry(hostname);
+
+    // Another failure already kicked off a re-resolution; block on it and then retry, so parallel
+    //  failures for the same host share a single resolution.
+    if (entry.resolving) {
+        await entry.resolving.catch(() => { });
+        return true;
+    }
+
+    // The resolver itself just failed exhaustively; re-resolving now would only reproduce that failure, so
+    //  there's no point making httpsRequest wait and retry.
+    if (entry.lastError && entry.failedAt !== undefined && Date.now() - entry.failedAt < NEGATIVE_CACHE_TTL) {
+        return false;
+    }
+
+    if (Date.now() - entry.lastReresolve < RERESOLVE_THROTTLE) {
+        return false;
+    }
+    entry.lastReresolve = Date.now();
+    entry.records = undefined;
+    await startResolve(entry).catch(() => { });
+    return true;
+}

package/src/dnsCacheTest.d.ts

@@ -0,0 +1 @@
+export {};

package/src/dnsCacheTest.ts

@@ -0,0 +1,76 @@
+import * as net from "net";
+import * as tls from "tls";
+import * as dns from "dns";
+import { httpsRequest } from "./https";
+
+const HOST = "a.querysubtest.com";
+// 443 is expected to serve HTTPS; the rest are expected to have nothing listening.
+const OPEN_PORT = 443;
+const CLOSED_PORTS = [444, 8443, 12345];
+// Hostnames that cannot resolve: an NXDOMAIN subdomain of a real zone, and the reserved .invalid TLD.
+const BAD_HOSTS = ["nonexistent-abc123.querysubtest.com", "this-cannot-resolve.invalid"];
+
+// Probe the raw socket layer directly, so we can see exactly which errno a not-listening port produces
+//  (the specific concern: ECONNRESET vs ECONNREFUSED/ETIMEDOUT). This bypasses our retry/DNS logic.
+async function probeRaw(host: string, port: number, useTls: boolean): Promise<string> {
+    return new Promise(resolve => {
+        let start = Date.now();
+        let socket = useTls
+            ? tls.connect({ host, port, servername: host, rejectUnauthorized: false })
+            : net.connect({ host, port });
+        let done = (result: string) => {
+            let elapsed = Date.now() - start;
+            socket.destroy();
+            resolve(`${result} (${elapsed}ms)`);
+        };
+        socket.once(useTls ? "secureConnect" : "connect", () => done("CONNECTED"));
+        socket.once("error", (e: NodeJS.ErrnoException) => done(`error code=${e.code} message=${e.message}`));
+        setTimeout(() => done("TIMED OUT after 10s"), 10_000);
+    });
+}
+
+async function tryHttps(url: string): Promise<string> {
+    let start = Date.now();
+    try {
+        let result = await httpsRequest(url);
+        return `OK ${result.length} bytes (${Date.now() - start}ms)`;
+    } catch (e) {
+        let err = e as NodeJS.ErrnoException;
+        return `FAILED code=${err.code} (${Date.now() - start}ms)\n    ${(err.stack ?? String(err)).split("\n").slice(0, 3).join("\n    ")}`;
+    }
+}
+
+// Show what dns.resolve4 does with a bad name directly, so we can see the errno our resolve loop retries on.
+async function probeResolve(host: string): Promise<string> {
+    let start = Date.now();
+    try {
+        let addrs = await dns.promises.resolve4(host);
+        return `resolved ${JSON.stringify(addrs)} (${Date.now() - start}ms)`;
+    } catch (e) {
+        let err = e as NodeJS.ErrnoException;
+        return `error code=${err.code} (${Date.now() - start}ms)`;
+    }
+}
+
+async function main() {
+    console.log(`=== Raw socket probes (which errno does a closed port give?) ===`);
+    console.log(`  ${HOST}:${OPEN_PORT} (tls)   -> ${await probeRaw(HOST, OPEN_PORT, true)}`);
+    for (let port of CLOSED_PORTS) {
+        console.log(`  ${HOST}:${port} (tcp) -> ${await probeRaw(HOST, port, false)}`);
+        console.log(`  ${HOST}:${port} (tls) -> ${await probeRaw(HOST, port, true)}`);
+    }
+
+    console.log(`\n=== httpsRequest (full path: DNS cache + retry) ===`);
+    console.log(`  https://${HOST}:${OPEN_PORT}/   -> ${await tryHttps(`https://${HOST}:${OPEN_PORT}/`)}`);
+    for (let port of CLOSED_PORTS) {
+        console.log(`  https://${HOST}:${port}/ -> ${await tryHttps(`https://${HOST}:${port}/`)}`);
+    }
+
+    console.log(`\n=== Bad hostnames (resolve loop + ENOTFOUND retry path) ===`);
+    for (let host of BAD_HOSTS) {
+        console.log(`  dns.resolve4(${host}) -> ${await probeResolve(host)}`);
+        console.log(`  https://${host}/ -> ${await tryHttps(`https://${host}/`)}`);
+    }
+}
+
+main().then(() => process.exit(0), e => { console.error(e.stack ?? e); process.exit(1); });

package/src/https.ts

@@ -1,10 +1,44 @@
 import * as https from "https";
 import * as http from "http";
 import { isNode } from "./misc";
+import { delay } from "./batching";
+import { dnsCacheLookup, reportConnectionFailure } from "./dnsCache";
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 
+// Error codes that mean the TCP connection was never established (so no request bytes reached the server
+//  and a full retry — even of a non-idempotent method — is safe). These are the failures a stale DNS
+//  answer produces, and the only ones we re-resolve + retry on.
+const CONNECTION_ERROR_CODES = new Set([
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EHOSTDOWN",
+    "EADDRNOTAVAIL",
+]);
+// Upper bound on retries; the real limiter is the DNS re-resolve throttle, which stops us once a fresh
+//  answer can't differ from what we already tried.
+const CONNECTION_RETRY_COUNT = 3;
+// A short pause before retrying, giving a transient network/resolver blip time to clear.
+const CONNECTION_RETRY_WAIT = 500;
+
+function isConnectionError(error: unknown): boolean {
+    if (!error || typeof error !== "object") return false;
+    let code = (error as NodeJS.ErrnoException).code;
+    if (code && CONNECTION_ERROR_CODES.has(code)) return true;
+    // autoSelectFamily surfaces all-candidates-failed as an AggregateError; treat it as connection-level
+    //  if any underlying attempt was.
+    let aggregate = (error as AggregateError).errors;
+    if (Array.isArray(aggregate) && aggregate.some(isConnectionError)) return true;
+    let cause = (error as { cause?: unknown }).cause;
+    if (cause && cause !== error) return isConnectionError(cause);
+    return false;
+}
+
 export function httpsRequest(
     url: string,
     payload?: Buffer | Buffer[],
@@ -24,50 +58,78 @@ export function httpsRequest(
             if (urlObj.port) {
                 port = +urlObj.port;
             }
-            return new Promise<Buffer>((resolve, reject) => {
-                let httpRequest = requestor.request(
-                    urlObj + "",
-                    {
-                        method,
-                        headers: config?.headers,
-                        // NOTE: We get a lot of backblaze errors when we try to re-use connections. It might be faster,
-                        //  but... anything that cares about speed should use websockets anyways...
-                        agent: new requestor.Agent({ keepAlive: false }),
-                    },
-                    async httpResponse => {
-                        let data: Buffer[] = [];
-                        httpResponse.on("data", chunk => {
-                            data.push(chunk);
-                        });
 
-                        await new Promise<void>(resolve => {
-                            httpResponse.on("end", () => {
-                                resolve();
+            let attempt = 0;
+            while (true) {
+                try {
+                    return await sendOnce();
+                } catch (e) {
+                    if (attempt >= CONNECTION_RETRY_COUNT || !isConnectionError(e)) {
+                        throw e;
+                    }
+                    attempt++;
+                    // A brief pause lets a transient blip settle, then we ask the DNS cache to re-resolve.
+                    //  If it declines (throttled — a fresh answer would match what just failed), retrying
+                    //  is pointless, so we surface the original error instead of looping.
+                    await delay(CONNECTION_RETRY_WAIT);
+                    let willReresolve = await reportConnectionFailure(urlObj.hostname);
+                    if (!willReresolve) {
+                        throw e;
+                    }
+                }
+            }
+
+            function sendOnce() {
+                return new Promise<Buffer>((resolve, reject) => {
+                    let httpRequest = requestor.request(
+                        urlObj + "",
+                        {
+                            method,
+                            headers: config?.headers,
+                            // NOTE: We get a lot of backblaze errors when we try to re-use connections. It might be faster,
+                            //  but... anything that cares about speed should use websockets anyways...
+                            agent: new requestor.Agent({ keepAlive: false }),
+                            // Resolve via our own DNS cache so we can bypass glibc's sticky failure caching and
+                            //  re-resolve on demand. autoSelectFamily forces happy eyeballs across the returned
+                            //  addresses even on older Node.
+                            lookup: dnsCacheLookup,
+                            autoSelectFamily: true,
+                        } as https.RequestOptions,
+                        async httpResponse => {
+                            let data: Buffer[] = [];
+                            httpResponse.on("data", chunk => {
+                                data.push(chunk);
                             });
-                        });
 
-                        if (!httpResponse.statusCode?.toString().startsWith("2")) {
-                            reject(new Error(`Error for ${url}, ${httpResponse.statusCode} ${httpResponse.statusMessage}\n` + Buffer.concat(data).toString()));
-                        } else {
-                            resolve(Buffer.concat(data));
+                            await new Promise<void>(resolve => {
+                                httpResponse.on("end", () => {
+                                    resolve();
+                                });
+                            });
+
+                            if (!httpResponse.statusCode?.toString().startsWith("2")) {
+                                reject(new Error(`Error for ${url}, ${httpResponse.statusCode} ${httpResponse.statusMessage}\n` + Buffer.concat(data).toString()));
+                            } else {
+                                resolve(Buffer.concat(data));
+                            }
                         }
+                    );
+                    if (config?.cancel) {
+                        void config.cancel.finally(() => {
+                            httpRequest.destroy();
+                        });
                     }
-                );
-                if (config?.cancel) {
-                    void config.cancel.finally(() => {
-                        httpRequest.destroy();
-                    });
-                }
-                httpRequest.on("error", reject);
+                    httpRequest.on("error", reject);
 
-                if (payload) {
-                    if (Array.isArray(payload)) {
-                        payload = Buffer.concat(payload);
+                    if (payload) {
+                        if (Array.isArray(payload)) {
+                            payload = Buffer.concat(payload);
+                        }
+                        httpRequest.write(payload);
                     }
-                    httpRequest.write(payload);
-                }
-                httpRequest.end();
-            });
+                    httpRequest.end();
+                });
+            }
         })();
 
     } else {