@promigence/sdk 0.1.0-beta.13 → 0.1.0-beta.14

package/dist/cjs/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.13";
+export declare const VERSION = "0.1.0-beta.14";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";

package/dist/cjs/core.js

@@ -7,7 +7,7 @@ exports.fixBeyondMessage = fixBeyondMessage;
 exports.previewsOff = previewsOff;
 exports.exitForCode = exitForCode;
 const hint_js_1 = require("./hint.js");
-exports.VERSION = "0.1.0-beta.13";
+exports.VERSION = "0.1.0-beta.14";
 exports.DOCS_URL = "https://promigence.ai";
 exports.ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 exports.DEFAULT_API_URL = "https://api.promigence.ai/v1";

package/dist/cjs/http2.d.ts

@@ -189,6 +189,7 @@ export declare const __http2Internals: {
         closedReason: string;
         messages: number;
         posts: number;
+        startedAt: number;
     } | undefined;
     /** The transport thread's number of connections and spacing between new requests on one, for an environment (`threadKnobs`). */
     threadKnobs(env: NodeJS.ProcessEnv): {

package/dist/cjs/http2.js

@@ -21,6 +21,7 @@ const MAX_SESSIONS = 4;
 const FIRST_SESSIONS = 2;
 const BURST_MIN = 8;
 const HOLD_MS = 10;
+const STANDBY_AFTER_MS = 300;
 const LOAD_FIRST_USE_MS = 120_000;
 const CONNECT_TIMEOUT_MS = 10_000;
 const IDLE_CLOSE_MS = 10_000;
@@ -572,6 +573,7 @@ exports.tuning = {
     holdMs: HOLD_MS,
     burstMin: BURST_MIN,
     loadFirstUseMs: LOAD_FIRST_USE_MS,
+    standbyAfterMs: STANDBY_AFTER_MS,
     earlyPlatform: undefined,
     earlyServers: undefined,
     earlyHostsFile: undefined,
@@ -855,7 +857,9 @@ function apiLookup(asked, observe, ipv4First = v4First(), earlyOk = true) {
 const earlies = new Map();
 const MAX_EARLIES = 4;
 const EARLY_MAX_AGE_MS = 60_000;
-const EARLY_TIMEOUT_MS = 2_000;
+const LOOKUP_FIRST_MS = 150;
+const LOOKUP_TRIES = 3;
+const LOOKUP_AT_MS = [0, 100, 250];
 const DNS_AT_LOAD = (() => {
     try {
         return nodeDns();
@@ -876,8 +880,8 @@ function lookupReplaced() {
 const EARLY_WORKER = `
 const { workerData } = require("node:worker_threads");
 const { isIPv4 } = require("node:net");
-const { port, host, timeoutMs, servers, hostsFile } = workerData;
-const done = (m) => { try { port.postMessage(m); } catch {} try { port.close(); } catch {} };
+const { port, host, timeoutMs, tries, atMs, servers, hostsFile } = workerData;
+const done = (m) => { m.hr = Number(process.hrtime.bigint()) / 1e6; try { port.postMessage(m); } catch {} try { port.close(); } catch {} };
 try {
   let named = false;
   const v4 = [];
@@ -891,12 +895,28 @@ try {
   } catch {}
   if (named) done(v4.length > 0 ? { host, addrs: v4, ttl: 60, at: Date.now() } : { host, none: "hosts" });
   else {
-    const r = new (require("node:dns").Resolver)({ timeout: timeoutMs, tries: 1 });
-    if (Array.isArray(servers) && servers.length > 0) r.setServers(servers);
-    r.resolve4(host, { ttl: true }, (err, recs) => {
-      if (err || !Array.isArray(recs) || recs.length === 0) return done({ host, none: (err && err.code) || "empty" });
-      done({ host, addrs: recs.map((x) => x.address), ttl: Math.min(...recs.map((x) => x.ttl)), at: Date.now() });
-    });
+    const { Resolver } = require("node:dns");
+    const rs = [];
+    const timers = [];
+    let fin = false, asked = 0, failed = 0;
+    const finish = (m) => { if (fin) return; fin = true; for (const t of timers) clearTimeout(t); for (const r of rs) { try { r.cancel(); } catch {} } done(m); };
+    const gaveUp = (why) => { if (++failed < asked) return; if (asked < atMs.length) ask(); else finish({ host, none: why }); };
+    const ask = () => {
+      if (fin || asked >= atMs.length) return;
+      const k = asked++;
+      try {
+        const r = new Resolver({ timeout: timeoutMs, tries });
+        const list = Array.isArray(servers) && servers.length > 0 ? servers : r.getServers();
+        if (list.length > 0) r.setServers(list.map((_, i) => list[(i + k) % list.length]));
+        rs.push(r);
+        r.resolve4(host, { ttl: true }, (err, recs) => {
+          if (fin) return;
+          if (!err && Array.isArray(recs) && recs.length > 0) return finish({ host, addrs: recs.map((x) => x.address), ttl: Math.min(...recs.map((x) => x.ttl)), at: Date.now() });
+          gaveUp((err && err.code) || "empty");
+        });
+      } catch { gaveUp("error"); }
+    };
+    for (const ms of atMs) { if (ms <= 0) ask(); else timers.push(setTimeout(ask, ms)); }
   }
 } catch { done({ host, none: "error" }); }
 `;
@@ -927,7 +947,7 @@ function earlyLookupFor(host) {
         const worker = new node_worker_threads_1.Worker(EARLY_WORKER, {
             eval: true,
             workerData: {
-                port: port2, host, timeoutMs: EARLY_TIMEOUT_MS,
+                port: port2, host, timeoutMs: LOOKUP_FIRST_MS, tries: LOOKUP_TRIES, atMs: LOOKUP_AT_MS,
                 servers: exports.tuning.earlyServers ?? (Array.isArray(earlySeam().servers) ? earlySeam().servers : undefined),
                 hostsFile: exports.tuning.earlyHostsFile ?? (typeof earlySeam().hostsFile === "string" ? earlySeam().hostsFile : undefined),
             },
@@ -975,6 +995,10 @@ function settleEarly(e, message) {
     else {
         e.state = "none";
     }
+    if (trace_js_1.TRACE_ON) {
+        const at = typeof m?.hr === "number" ? m.hr - (Number(process.hrtime.bigint()) / 1e6 - performance.now()) : performance.now();
+        (0, trace_js_1.traceEventAt)(e.state === "answered" ? `dns:early-answer ${addrs.length}` : `dns:early-none ${typeof m?.none === "string" ? m.none : "gone"}`, at);
+    }
     safely(() => { e.port.close(); });
     const waiters = e.waiters.splice(0);
     for (const w of waiters)
@@ -1338,6 +1362,8 @@ class TransportThread {
     everReady = false;
     closedReason = "";
     onFail;
+    startedAt = performance.now();
+    startWaiters = [];
     inflight = new Map();
     nextId = 1;
     listening = false;
@@ -1377,10 +1403,41 @@ class TransportThread {
         }
     }
     ready() {
-        if (!this.listening && this.state !== "closed")
+        if ((!this.listening || this.state === "starting") && this.state !== "closed")
             this.poll();
         return this.state === "ready" && this.sessions > 0 && this.inflight.size < this.sessions * this.limit && this.freeMarks.length > 0;
     }
+    starting() {
+        if (this.state === "starting")
+            this.poll();
+        return this.state === "starting";
+    }
+    whenStarted(cb) {
+        if (!this.starting()) {
+            queueMicrotask(cb);
+            return () => { };
+        }
+        this.startWaiters.push(cb);
+        this.listen();
+        return () => {
+            const i = this.startWaiters.indexOf(cb);
+            if (i >= 0)
+                this.startWaiters.splice(i, 1);
+        };
+    }
+    started() {
+        for (const cb of this.startWaiters.splice(0))
+            safely(cb);
+    }
+    listen() {
+        if (this.listening)
+            return;
+        this.listening = true;
+        this.poll();
+        this.port.on("message", (m) => { this.onMessage(m); });
+        if (!this.refd)
+            safely(() => { this.port.unref(); });
+    }
     onMessage(m) {
         const msg = m;
         this.messages++;
@@ -1403,8 +1460,16 @@ class TransportThread {
                         if (typeof c.index === "number" && typeof c.addr === "string" && typeof c.localPort === "number")
                             (0, trace_js_1.traceEventAt)(`thread:conn${c.index} ${c.addr} ${c.localPort}`, t);
                     }
+                    if (first)
+                        this.started();
                 }
                 return;
+            case "ev": {
+                const e = msg;
+                if (typeof e.n === "string" && typeof e.hr === "number")
+                    (0, trace_js_1.traceEventAt)(`thread:w-${e.n}`, e.hr - this.hrOffset);
+                return;
+            }
             case "sessions":
                 if (typeof msg.sessions === "number")
                     this.sessions = msg.sessions;
@@ -1415,6 +1480,7 @@ class TransportThread {
                     if (this.closedReason === "")
                         this.closedReason = msg.reason ?? "draining";
                     (0, trace_js_1.traceEvent)("thread:draining");
+                    this.started();
                 }
                 return;
             case "closed":
@@ -1495,6 +1561,7 @@ class TransportThread {
             this.port.postMessage({ t: "drain" });
         }
         catch { }
+        this.started();
     }
     close(reason) {
         if (this.state === "closed")
@@ -1503,6 +1570,7 @@ class TransportThread {
         if (this.closedReason === "")
             this.closedReason = reason;
         (0, trace_js_1.traceEvent)("thread:closed");
+        this.started();
         this.outbox = [];
         for (const [id, p] of [...this.inflight]) {
             const sent = this.acked(p);
@@ -1525,11 +1593,7 @@ class TransportThread {
         }
     }
     ref() {
-        if (!this.listening) {
-            this.listening = true;
-            this.poll();
-            this.port.on("message", (m) => { this.onMessage(m); });
-        }
+        this.listen();
         if (this.refd)
             return;
         this.refd = true;
@@ -1670,6 +1734,55 @@ function threadFor(origin) {
         return undefined;
     return t.ready() && !lookupReplaced() ? t : undefined;
 }
+function startingThread(origin) {
+    const t = transportThread;
+    if (t === undefined || t.origin !== origin || lookupReplaced())
+        return undefined;
+    return t.starting() ? t : undefined;
+}
+let raceTraced = false;
+function firstUp(t, pool, deadline, signal) {
+    const first = !raceTraced;
+    if (first) {
+        raceTraced = true;
+        (0, trace_js_1.traceEvent)("h2:race");
+    }
+    const stop = new AbortController();
+    const both = signal === undefined ? stop.signal : AbortSignal.any([signal, stop.signal]);
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const forget = t.whenStarted(() => {
+            if (done)
+                return;
+            const ready = threadFor(t.origin);
+            if (ready === undefined)
+                return;
+            done = true;
+            if (first)
+                (0, trace_js_1.traceEvent)("h2:race-thread");
+            stop.abort();
+            resolve({ thread: ready });
+        });
+        pool.acquire(deadline, both).then((entry) => {
+            if (done) {
+                if (entry !== null)
+                    pool.end(entry);
+                return;
+            }
+            done = true;
+            forget();
+            if (first)
+                (0, trace_js_1.traceEvent)("h2:race-pool");
+            resolve({ entry });
+        }, (err) => {
+            if (done)
+                return;
+            done = true;
+            forget();
+            reject(err);
+        });
+    });
+}
 function ownFile() {
     const frame = (new Error().stack ?? "").split("\n")[1] ?? "";
     const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
@@ -1712,7 +1825,7 @@ function startTransportThread(origin, onFail) {
             workerData: {
                 promigenceTransport: true, port: port2, acks, origin: origin.origin, sessions: knobs.sessions, gapUs: knobs.gapUs,
                 firstUseMs: exports.tuning.loadFirstUseMs, idleMs: IDLE_CLOSE_MS, connectTimeoutMs: CONNECT_TIMEOUT_MS,
-                lookupTimeoutMs: EARLY_TIMEOUT_MS, trace: trace_js_1.TRACE_ON,
+                lookupTimeoutMs: LOOKUP_FIRST_MS, lookupTries: LOOKUP_TRIES, lookupAtMs: LOOKUP_AT_MS, trace: trace_js_1.TRACE_ON,
                 servers: exports.tuning.earlyServers ?? (Array.isArray(seam.servers) ? seam.servers : undefined),
                 hostsFile: exports.tuning.earlyHostsFile ?? (typeof seam.hostsFile === "string" ? seam.hostsFile : undefined),
                 distrustedForTest: ca_guard_js_1.__caGuardInternals.testHashes(),
@@ -1730,6 +1843,11 @@ function startTransportThread(origin, onFail) {
         worker.on("exit", () => { t.poll(); t.close("exit"); });
         transportThread = t;
         (0, trace_js_1.traceEvent)("thread:start");
+        (0, trace_js_1.onTraceFlush)(() => {
+            t.poll();
+            for (const e of earlies.values())
+                pollEarly(e);
+        });
     }
     catch {
         transportThread = undefined;
@@ -1816,8 +1934,34 @@ class Http2Transport {
         const pool = poolFor(target.origin);
         if (!pool.usable())
             return this.viaFetch(url, init, deadline);
+        let raced = false;
         for (;;) {
-            const entry = pool.tryAcquire() ?? await pool.acquire(deadline, init.signal);
+            let entry = pool.tryAcquire();
+            if (entry === undefined) {
+                const starting = raced || resends > 0 || replays > 0 ? undefined : startingThread(target.origin);
+                if (starting !== undefined) {
+                    raced = true;
+                    const won = await firstUp(starting, pool, deadline, init.signal);
+                    if (won.thread !== undefined) {
+                        if (tr !== undefined)
+                            (0, trace_js_1.mark)(tr, "race");
+                        const out = await won.thread.send(target, init, replayable, deadline);
+                        if (out === VIA_FETCH)
+                            return this.viaFetch(url, init, deadline);
+                        if (!(out instanceof HandBack))
+                            return out;
+                        resends = out.resends;
+                        replays = out.replays;
+                        if (tr !== undefined)
+                            delete tr.via;
+                        continue;
+                    }
+                    entry = won.entry;
+                }
+                else {
+                    entry = await pool.acquire(deadline, init.signal);
+                }
+            }
             if (tr !== undefined)
                 (0, trace_js_1.mark)(tr, "acq");
             if (entry === null)
@@ -1917,7 +2061,7 @@ exports.__http2Internals = {
         if (t === undefined)
             return undefined;
         t.poll();
-        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason, messages: t.messages, posts: t.posts };
+        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason, messages: t.messages, posts: t.posts, startedAt: t.startedAt };
     },
     threadKnobs(env) {
         return threadKnobs(env);
@@ -1966,6 +2110,15 @@ function isMainThread() {
         return false;
     }
 }
+function standby(url) {
+    try {
+        (0, trace_js_1.traceEvent)("h2:standby");
+        warmTls();
+        poolFor(url.origin).warm(exports.tuning.loadFirstUseMs);
+    }
+    catch {
+    }
+}
 function connectAtLoad() {
     try {
         if (!isNode() || Number(process.versions.node.split(".")[0]) < 22)
@@ -1986,6 +2139,8 @@ function connectAtLoad() {
                 if (url.protocol === "https:" && !(0, dispatcher_js_1.customDispatcher)() && earlyPlatform() && v4First() && !threadOff && earlySeam().transportThread !== false) {
                     startTransportThread(url, () => { if (loadTurnRan)
                         warmAtLoad(); });
+                    if ((0, node_net_1.isIP)(host) === 0)
+                        earlyLookupFor(host);
                 }
                 else if (url.protocol === "https:" && !(0, dispatcher_js_1.customDispatcher)() && (0, node_net_1.isIP)(host) === 0 && earlyPlatform() && v4First())
                     earlyLookupFor(host);
@@ -2004,10 +2159,27 @@ function connectAtLoad() {
                 const url = new URL(raw ? raw : core_js_1.DEFAULT_API_URL);
                 if (url.protocol !== "https:" || (0, dispatcher_js_1.customDispatcher)())
                     return;
-                if (transportThread !== undefined && transportThread.origin === url.origin) {
-                    transportThread.poll();
-                    if (transportThread.state !== "closed" || transportThread.everReady)
+                const t = transportThread;
+                if (t !== undefined && t.origin === url.origin) {
+                    t.poll();
+                    if (t.everReady)
+                        return;
+                    if (t.state !== "closed") {
+                        const check = () => {
+                            t.poll();
+                            if (t.everReady || t.state === "closed")
+                                return;
+                            const wait = t.startedAt + exports.tuning.standbyAfterMs - performance.now();
+                            if (wait > 0) {
+                                const timer = setTimeout(check, wait);
+                                timer.unref?.();
+                                return;
+                            }
+                            standby(url);
+                        };
+                        check();
                         return;
+                    }
                 }
                 warmTls();
                 poolFor(url.origin).warm(exports.tuning.loadFirstUseMs);

package/dist/cjs/trace.d.ts

@@ -31,3 +31,5 @@ export declare function mark(s: TraceStamp | undefined, phase: string): void;
 export declare function traceEvent(name: string): void;
 /** A process event that happened at `t` (`performance.now()` terms), recorded now: one another thread reported. */
 export declare function traceEventAt(name: string, t: number): void;
+/** `fn` runs once at exit, before the trace is written (tracing on only). */
+export declare function onTraceFlush(fn: () => void): void;

package/dist/cjs/trace.js

@@ -6,6 +6,7 @@ exports.traceBegin = traceBegin;
 exports.mark = mark;
 exports.traceEvent = traceEvent;
 exports.traceEventAt = traceEventAt;
+exports.onTraceFlush = onTraceFlush;
 const node_fs_1 = require("node:fs");
 const core_js_1 = require("./core.js");
 exports.TRACE_ON = (() => {
@@ -68,7 +69,23 @@ function modulePath() {
     const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
     return m?.[1] ?? "";
 }
+const beforeFlush = [];
+function onTraceFlush(fn) {
+    if (!exports.TRACE_ON)
+        return;
+    beforeFlush.push(fn);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+}
 function flush() {
+    for (const fn of beforeFlush.splice(0)) {
+        try {
+            fn();
+        }
+        catch { }
+    }
     const head = {
         trace: "promigence-sdk",
         version: core_js_1.VERSION,

package/dist/cjs/transport-worker.js

@@ -36,6 +36,11 @@ function start(init) {
         }
         catch { }
     };
+    const ev = (n) => {
+        if (init.trace === true)
+            post({ t: "ev", n, hr: hrNow() });
+    };
+    ev("boot");
     const live = () => sessions.filter((e) => !e.retired && !e.session.closed && !e.session.destroyed);
     const end = (reason) => {
         if (closed)
@@ -96,14 +101,14 @@ function start(init) {
     catch {
         context = undefined;
     }
-    const connect = (address) => new Promise((resolve) => {
+    const connect = (address, k) => new Promise((resolve) => {
         let done = false;
         const finish = (e) => { if (!done) {
             done = true;
             clearTimeout(timer);
             resolve(e);
         } };
-        const timer = setTimeout(() => { try {
+        const timer = setTimeout(() => { ev(`timeout${k}`); try {
             socket.destroy();
         }
         catch { } finish(null); }, init.connectTimeoutMs);
@@ -115,8 +120,11 @@ function start(init) {
             checkServerIdentity: ca_guard_js_1.guardCertChain,
             ...(context === undefined ? {} : { secureContext: context }),
         });
-        socket.once("error", () => finish(null));
+        if (init.trace === true)
+            socket.once("connect", () => { ev(`tcp${k}`); });
+        socket.once("error", (e) => { ev(`fail${k} ${e?.code ?? "error"}`); finish(null); });
         socket.once("secureConnect", () => {
+            ev(`tls${k}`);
             if (socket.alpnProtocol !== "h2") {
                 socket.destroy();
                 finish(null);
@@ -169,14 +177,66 @@ function start(init) {
             resolve(v4);
             return;
         }
-        try {
-            const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: 1 });
-            if (Array.isArray(init.servers) && init.servers.length > 0)
-                r.setServers(init.servers);
-            r.resolve4(name, (err, addrs) => resolve(!err && Array.isArray(addrs) ? addrs : []));
-        }
-        catch {
-            resolve([]);
+        const at = init.lookupAtMs.length > 0 ? init.lookupAtMs : [0];
+        const resolvers = [];
+        const timers = [];
+        let done = false;
+        let asked = 0;
+        let failed = 0;
+        const finish = (addrs) => {
+            if (done)
+                return;
+            done = true;
+            for (const t of timers)
+                clearTimeout(t);
+            for (const r of resolvers) {
+                try {
+                    r.cancel();
+                }
+                catch { }
+            }
+            resolve(addrs);
+        };
+        const gaveUp = () => {
+            if (++failed < asked)
+                return;
+            if (asked < at.length)
+                ask();
+            else
+                finish([]);
+        };
+        const ask = () => {
+            if (done || asked >= at.length)
+                return;
+            const k = asked++;
+            try {
+                const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: init.lookupTries });
+                const list = Array.isArray(init.servers) && init.servers.length > 0 ? init.servers : r.getServers();
+                if (list.length > 0)
+                    r.setServers(list.map((_, i) => list[(i + k) % list.length]));
+                resolvers.push(r);
+                ev(`lookup${k + 1}`);
+                r.resolve4(name, (err, addrs) => {
+                    if (done)
+                        return;
+                    if (!err && Array.isArray(addrs) && addrs.length > 0) {
+                        ev(`addrs${k + 1} ${addrs.length}`);
+                        finish(addrs);
+                        return;
+                    }
+                    ev(`nolookup${k + 1} ${err?.code ?? "empty"}`);
+                    gaveUp();
+                });
+            }
+            catch {
+                gaveUp();
+            }
+        };
+        for (const ms of at) {
+            if (ms <= 0)
+                ask();
+            else
+                timers.push(setTimeout(ask, ms));
         }
     });
     const limitOf = (e) => {
@@ -198,7 +258,7 @@ function start(init) {
         }
         const n = Math.max(1, init.sessions);
         pendingConnects = n;
-        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length]).then((e) => {
+        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length], i).then((e) => {
             pendingConnects--;
             if (closed) {
                 if (e)

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.13";
+export declare const VERSION = "0.1.0-beta.14";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";

package/dist/core.js

@@ -1,5 +1,5 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.13";
+export const VERSION = "0.1.0-beta.14";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";

package/dist/http2.d.ts

@@ -189,6 +189,7 @@ export declare const __http2Internals: {
         closedReason: string;
         messages: number;
         posts: number;
+        startedAt: number;
     } | undefined;
     /** The transport thread's number of connections and spacing between new requests on one, for an environment (`threadKnobs`). */
     threadKnobs(env: NodeJS.ProcessEnv): {

package/dist/http2.js

@@ -6,11 +6,12 @@ import * as zlib from "node:zlib";
 import { __caGuardInternals, guardCertChain } from "./ca-guard.js";
 import { DEFAULT_API_URL } from "./core.js";
 import { customDispatcher } from "./dispatcher.js";
-import { mark, TRACE_ON, traceEvent, traceEventAt } from "./trace.js";
+import { mark, onTraceFlush, TRACE_ON, traceEvent, traceEventAt } from "./trace.js";
 const MAX_SESSIONS = 4;
 const FIRST_SESSIONS = 2;
 const BURST_MIN = 8;
 const HOLD_MS = 10;
+const STANDBY_AFTER_MS = 300;
 const LOAD_FIRST_USE_MS = 120_000;
 const CONNECT_TIMEOUT_MS = 10_000;
 const IDLE_CLOSE_MS = 10_000;
@@ -561,6 +562,7 @@ export const tuning = {
     holdMs: HOLD_MS,
     burstMin: BURST_MIN,
     loadFirstUseMs: LOAD_FIRST_USE_MS,
+    standbyAfterMs: STANDBY_AFTER_MS,
     earlyPlatform: undefined,
     earlyServers: undefined,
     earlyHostsFile: undefined,
@@ -844,7 +846,9 @@ function apiLookup(asked, observe, ipv4First = v4First(), earlyOk = true) {
 const earlies = new Map();
 const MAX_EARLIES = 4;
 const EARLY_MAX_AGE_MS = 60_000;
-const EARLY_TIMEOUT_MS = 2_000;
+const LOOKUP_FIRST_MS = 150;
+const LOOKUP_TRIES = 3;
+const LOOKUP_AT_MS = [0, 100, 250];
 const DNS_AT_LOAD = (() => {
     try {
         return nodeDns();
@@ -865,8 +869,8 @@ function lookupReplaced() {
 const EARLY_WORKER = `
 const { workerData } = require("node:worker_threads");
 const { isIPv4 } = require("node:net");
-const { port, host, timeoutMs, servers, hostsFile } = workerData;
-const done = (m) => { try { port.postMessage(m); } catch {} try { port.close(); } catch {} };
+const { port, host, timeoutMs, tries, atMs, servers, hostsFile } = workerData;
+const done = (m) => { m.hr = Number(process.hrtime.bigint()) / 1e6; try { port.postMessage(m); } catch {} try { port.close(); } catch {} };
 try {
   let named = false;
   const v4 = [];
@@ -880,12 +884,28 @@ try {
   } catch {}
   if (named) done(v4.length > 0 ? { host, addrs: v4, ttl: 60, at: Date.now() } : { host, none: "hosts" });
   else {
-    const r = new (require("node:dns").Resolver)({ timeout: timeoutMs, tries: 1 });
-    if (Array.isArray(servers) && servers.length > 0) r.setServers(servers);
-    r.resolve4(host, { ttl: true }, (err, recs) => {
-      if (err || !Array.isArray(recs) || recs.length === 0) return done({ host, none: (err && err.code) || "empty" });
-      done({ host, addrs: recs.map((x) => x.address), ttl: Math.min(...recs.map((x) => x.ttl)), at: Date.now() });
-    });
+    const { Resolver } = require("node:dns");
+    const rs = [];
+    const timers = [];
+    let fin = false, asked = 0, failed = 0;
+    const finish = (m) => { if (fin) return; fin = true; for (const t of timers) clearTimeout(t); for (const r of rs) { try { r.cancel(); } catch {} } done(m); };
+    const gaveUp = (why) => { if (++failed < asked) return; if (asked < atMs.length) ask(); else finish({ host, none: why }); };
+    const ask = () => {
+      if (fin || asked >= atMs.length) return;
+      const k = asked++;
+      try {
+        const r = new Resolver({ timeout: timeoutMs, tries });
+        const list = Array.isArray(servers) && servers.length > 0 ? servers : r.getServers();
+        if (list.length > 0) r.setServers(list.map((_, i) => list[(i + k) % list.length]));
+        rs.push(r);
+        r.resolve4(host, { ttl: true }, (err, recs) => {
+          if (fin) return;
+          if (!err && Array.isArray(recs) && recs.length > 0) return finish({ host, addrs: recs.map((x) => x.address), ttl: Math.min(...recs.map((x) => x.ttl)), at: Date.now() });
+          gaveUp((err && err.code) || "empty");
+        });
+      } catch { gaveUp("error"); }
+    };
+    for (const ms of atMs) { if (ms <= 0) ask(); else timers.push(setTimeout(ask, ms)); }
   }
 } catch { done({ host, none: "error" }); }
 `;
@@ -916,7 +936,7 @@ function earlyLookupFor(host) {
         const worker = new Worker(EARLY_WORKER, {
             eval: true,
             workerData: {
-                port: port2, host, timeoutMs: EARLY_TIMEOUT_MS,
+                port: port2, host, timeoutMs: LOOKUP_FIRST_MS, tries: LOOKUP_TRIES, atMs: LOOKUP_AT_MS,
                 servers: tuning.earlyServers ?? (Array.isArray(earlySeam().servers) ? earlySeam().servers : undefined),
                 hostsFile: tuning.earlyHostsFile ?? (typeof earlySeam().hostsFile === "string" ? earlySeam().hostsFile : undefined),
             },
@@ -964,6 +984,10 @@ function settleEarly(e, message) {
     else {
         e.state = "none";
     }
+    if (TRACE_ON) {
+        const at = typeof m?.hr === "number" ? m.hr - (Number(process.hrtime.bigint()) / 1e6 - performance.now()) : performance.now();
+        traceEventAt(e.state === "answered" ? `dns:early-answer ${addrs.length}` : `dns:early-none ${typeof m?.none === "string" ? m.none : "gone"}`, at);
+    }
     safely(() => { e.port.close(); });
     const waiters = e.waiters.splice(0);
     for (const w of waiters)
@@ -1327,6 +1351,8 @@ class TransportThread {
     everReady = false;
     closedReason = "";
     onFail;
+    startedAt = performance.now();
+    startWaiters = [];
     inflight = new Map();
     nextId = 1;
     listening = false;
@@ -1366,10 +1392,41 @@ class TransportThread {
         }
     }
     ready() {
-        if (!this.listening && this.state !== "closed")
+        if ((!this.listening || this.state === "starting") && this.state !== "closed")
             this.poll();
         return this.state === "ready" && this.sessions > 0 && this.inflight.size < this.sessions * this.limit && this.freeMarks.length > 0;
     }
+    starting() {
+        if (this.state === "starting")
+            this.poll();
+        return this.state === "starting";
+    }
+    whenStarted(cb) {
+        if (!this.starting()) {
+            queueMicrotask(cb);
+            return () => { };
+        }
+        this.startWaiters.push(cb);
+        this.listen();
+        return () => {
+            const i = this.startWaiters.indexOf(cb);
+            if (i >= 0)
+                this.startWaiters.splice(i, 1);
+        };
+    }
+    started() {
+        for (const cb of this.startWaiters.splice(0))
+            safely(cb);
+    }
+    listen() {
+        if (this.listening)
+            return;
+        this.listening = true;
+        this.poll();
+        this.port.on("message", (m) => { this.onMessage(m); });
+        if (!this.refd)
+            safely(() => { this.port.unref(); });
+    }
     onMessage(m) {
         const msg = m;
         this.messages++;
@@ -1392,8 +1449,16 @@ class TransportThread {
                         if (typeof c.index === "number" && typeof c.addr === "string" && typeof c.localPort === "number")
                             traceEventAt(`thread:conn${c.index} ${c.addr} ${c.localPort}`, t);
                     }
+                    if (first)
+                        this.started();
                 }
                 return;
+            case "ev": {
+                const e = msg;
+                if (typeof e.n === "string" && typeof e.hr === "number")
+                    traceEventAt(`thread:w-${e.n}`, e.hr - this.hrOffset);
+                return;
+            }
             case "sessions":
                 if (typeof msg.sessions === "number")
                     this.sessions = msg.sessions;
@@ -1404,6 +1469,7 @@ class TransportThread {
                     if (this.closedReason === "")
                         this.closedReason = msg.reason ?? "draining";
                     traceEvent("thread:draining");
+                    this.started();
                 }
                 return;
             case "closed":
@@ -1484,6 +1550,7 @@ class TransportThread {
             this.port.postMessage({ t: "drain" });
         }
         catch { }
+        this.started();
     }
     close(reason) {
         if (this.state === "closed")
@@ -1492,6 +1559,7 @@ class TransportThread {
         if (this.closedReason === "")
             this.closedReason = reason;
         traceEvent("thread:closed");
+        this.started();
         this.outbox = [];
         for (const [id, p] of [...this.inflight]) {
             const sent = this.acked(p);
@@ -1514,11 +1582,7 @@ class TransportThread {
         }
     }
     ref() {
-        if (!this.listening) {
-            this.listening = true;
-            this.poll();
-            this.port.on("message", (m) => { this.onMessage(m); });
-        }
+        this.listen();
         if (this.refd)
             return;
         this.refd = true;
@@ -1659,6 +1723,55 @@ function threadFor(origin) {
         return undefined;
     return t.ready() && !lookupReplaced() ? t : undefined;
 }
+function startingThread(origin) {
+    const t = transportThread;
+    if (t === undefined || t.origin !== origin || lookupReplaced())
+        return undefined;
+    return t.starting() ? t : undefined;
+}
+let raceTraced = false;
+function firstUp(t, pool, deadline, signal) {
+    const first = !raceTraced;
+    if (first) {
+        raceTraced = true;
+        traceEvent("h2:race");
+    }
+    const stop = new AbortController();
+    const both = signal === undefined ? stop.signal : AbortSignal.any([signal, stop.signal]);
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const forget = t.whenStarted(() => {
+            if (done)
+                return;
+            const ready = threadFor(t.origin);
+            if (ready === undefined)
+                return;
+            done = true;
+            if (first)
+                traceEvent("h2:race-thread");
+            stop.abort();
+            resolve({ thread: ready });
+        });
+        pool.acquire(deadline, both).then((entry) => {
+            if (done) {
+                if (entry !== null)
+                    pool.end(entry);
+                return;
+            }
+            done = true;
+            forget();
+            if (first)
+                traceEvent("h2:race-pool");
+            resolve({ entry });
+        }, (err) => {
+            if (done)
+                return;
+            done = true;
+            forget();
+            reject(err);
+        });
+    });
+}
 function ownFile() {
     const frame = (new Error().stack ?? "").split("\n")[1] ?? "";
     const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
@@ -1701,7 +1814,7 @@ function startTransportThread(origin, onFail) {
             workerData: {
                 promigenceTransport: true, port: port2, acks, origin: origin.origin, sessions: knobs.sessions, gapUs: knobs.gapUs,
                 firstUseMs: tuning.loadFirstUseMs, idleMs: IDLE_CLOSE_MS, connectTimeoutMs: CONNECT_TIMEOUT_MS,
-                lookupTimeoutMs: EARLY_TIMEOUT_MS, trace: TRACE_ON,
+                lookupTimeoutMs: LOOKUP_FIRST_MS, lookupTries: LOOKUP_TRIES, lookupAtMs: LOOKUP_AT_MS, trace: TRACE_ON,
                 servers: tuning.earlyServers ?? (Array.isArray(seam.servers) ? seam.servers : undefined),
                 hostsFile: tuning.earlyHostsFile ?? (typeof seam.hostsFile === "string" ? seam.hostsFile : undefined),
                 distrustedForTest: __caGuardInternals.testHashes(),
@@ -1719,6 +1832,11 @@ function startTransportThread(origin, onFail) {
         worker.on("exit", () => { t.poll(); t.close("exit"); });
         transportThread = t;
         traceEvent("thread:start");
+        onTraceFlush(() => {
+            t.poll();
+            for (const e of earlies.values())
+                pollEarly(e);
+        });
     }
     catch {
         transportThread = undefined;
@@ -1805,8 +1923,34 @@ export class Http2Transport {
         const pool = poolFor(target.origin);
         if (!pool.usable())
             return this.viaFetch(url, init, deadline);
+        let raced = false;
         for (;;) {
-            const entry = pool.tryAcquire() ?? await pool.acquire(deadline, init.signal);
+            let entry = pool.tryAcquire();
+            if (entry === undefined) {
+                const starting = raced || resends > 0 || replays > 0 ? undefined : startingThread(target.origin);
+                if (starting !== undefined) {
+                    raced = true;
+                    const won = await firstUp(starting, pool, deadline, init.signal);
+                    if (won.thread !== undefined) {
+                        if (tr !== undefined)
+                            mark(tr, "race");
+                        const out = await won.thread.send(target, init, replayable, deadline);
+                        if (out === VIA_FETCH)
+                            return this.viaFetch(url, init, deadline);
+                        if (!(out instanceof HandBack))
+                            return out;
+                        resends = out.resends;
+                        replays = out.replays;
+                        if (tr !== undefined)
+                            delete tr.via;
+                        continue;
+                    }
+                    entry = won.entry;
+                }
+                else {
+                    entry = await pool.acquire(deadline, init.signal);
+                }
+            }
             if (tr !== undefined)
                 mark(tr, "acq");
             if (entry === null)
@@ -1905,7 +2049,7 @@ export const __http2Internals = {
         if (t === undefined)
             return undefined;
         t.poll();
-        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason, messages: t.messages, posts: t.posts };
+        return { state: t.state, sessions: t.sessions, limit: t.limit, answered: t.answered, everReady: t.everReady, closedReason: t.closedReason, messages: t.messages, posts: t.posts, startedAt: t.startedAt };
     },
     threadKnobs(env) {
         return threadKnobs(env);
@@ -1954,6 +2098,15 @@ function isMainThread() {
         return false;
     }
 }
+function standby(url) {
+    try {
+        traceEvent("h2:standby");
+        warmTls();
+        poolFor(url.origin).warm(tuning.loadFirstUseMs);
+    }
+    catch {
+    }
+}
 function connectAtLoad() {
     try {
         if (!isNode() || Number(process.versions.node.split(".")[0]) < 22)
@@ -1974,6 +2127,8 @@ function connectAtLoad() {
                 if (url.protocol === "https:" && !customDispatcher() && earlyPlatform() && v4First() && !threadOff && earlySeam().transportThread !== false) {
                     startTransportThread(url, () => { if (loadTurnRan)
                         warmAtLoad(); });
+                    if (isIP(host) === 0)
+                        earlyLookupFor(host);
                 }
                 else if (url.protocol === "https:" && !customDispatcher() && isIP(host) === 0 && earlyPlatform() && v4First())
                     earlyLookupFor(host);
@@ -1992,10 +2147,27 @@ function connectAtLoad() {
                 const url = new URL(raw ? raw : DEFAULT_API_URL);
                 if (url.protocol !== "https:" || customDispatcher())
                     return;
-                if (transportThread !== undefined && transportThread.origin === url.origin) {
-                    transportThread.poll();
-                    if (transportThread.state !== "closed" || transportThread.everReady)
+                const t = transportThread;
+                if (t !== undefined && t.origin === url.origin) {
+                    t.poll();
+                    if (t.everReady)
+                        return;
+                    if (t.state !== "closed") {
+                        const check = () => {
+                            t.poll();
+                            if (t.everReady || t.state === "closed")
+                                return;
+                            const wait = t.startedAt + tuning.standbyAfterMs - performance.now();
+                            if (wait > 0) {
+                                const timer = setTimeout(check, wait);
+                                timer.unref?.();
+                                return;
+                            }
+                            standby(url);
+                        };
+                        check();
                         return;
+                    }
                 }
                 warmTls();
                 poolFor(url.origin).warm(tuning.loadFirstUseMs);

package/dist/trace.d.ts

@@ -31,3 +31,5 @@ export declare function mark(s: TraceStamp | undefined, phase: string): void;
 export declare function traceEvent(name: string): void;
 /** A process event that happened at `t` (`performance.now()` terms), recorded now: one another thread reported. */
 export declare function traceEventAt(name: string, t: number): void;
+/** `fn` runs once at exit, before the trace is written (tracing on only). */
+export declare function onTraceFlush(fn: () => void): void;

package/dist/trace.js

@@ -60,7 +60,23 @@ function modulePath() {
     const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
     return m?.[1] ?? "";
 }
+const beforeFlush = [];
+export function onTraceFlush(fn) {
+    if (!TRACE_ON)
+        return;
+    beforeFlush.push(fn);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+}
 function flush() {
+    for (const fn of beforeFlush.splice(0)) {
+        try {
+            fn();
+        }
+        catch { }
+    }
     const head = {
         trace: "promigence-sdk",
         version: VERSION,

package/dist/transport-worker.js

@@ -34,6 +34,11 @@ function start(init) {
         }
         catch { }
     };
+    const ev = (n) => {
+        if (init.trace === true)
+            post({ t: "ev", n, hr: hrNow() });
+    };
+    ev("boot");
     const live = () => sessions.filter((e) => !e.retired && !e.session.closed && !e.session.destroyed);
     const end = (reason) => {
         if (closed)
@@ -94,14 +99,14 @@ function start(init) {
     catch {
         context = undefined;
     }
-    const connect = (address) => new Promise((resolve) => {
+    const connect = (address, k) => new Promise((resolve) => {
         let done = false;
         const finish = (e) => { if (!done) {
             done = true;
             clearTimeout(timer);
             resolve(e);
         } };
-        const timer = setTimeout(() => { try {
+        const timer = setTimeout(() => { ev(`timeout${k}`); try {
             socket.destroy();
         }
         catch { } finish(null); }, init.connectTimeoutMs);
@@ -113,8 +118,11 @@ function start(init) {
             checkServerIdentity: guardCertChain,
             ...(context === undefined ? {} : { secureContext: context }),
         });
-        socket.once("error", () => finish(null));
+        if (init.trace === true)
+            socket.once("connect", () => { ev(`tcp${k}`); });
+        socket.once("error", (e) => { ev(`fail${k} ${e?.code ?? "error"}`); finish(null); });
         socket.once("secureConnect", () => {
+            ev(`tls${k}`);
             if (socket.alpnProtocol !== "h2") {
                 socket.destroy();
                 finish(null);
@@ -167,14 +175,66 @@ function start(init) {
             resolve(v4);
             return;
         }
-        try {
-            const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: 1 });
-            if (Array.isArray(init.servers) && init.servers.length > 0)
-                r.setServers(init.servers);
-            r.resolve4(name, (err, addrs) => resolve(!err && Array.isArray(addrs) ? addrs : []));
-        }
-        catch {
-            resolve([]);
+        const at = init.lookupAtMs.length > 0 ? init.lookupAtMs : [0];
+        const resolvers = [];
+        const timers = [];
+        let done = false;
+        let asked = 0;
+        let failed = 0;
+        const finish = (addrs) => {
+            if (done)
+                return;
+            done = true;
+            for (const t of timers)
+                clearTimeout(t);
+            for (const r of resolvers) {
+                try {
+                    r.cancel();
+                }
+                catch { }
+            }
+            resolve(addrs);
+        };
+        const gaveUp = () => {
+            if (++failed < asked)
+                return;
+            if (asked < at.length)
+                ask();
+            else
+                finish([]);
+        };
+        const ask = () => {
+            if (done || asked >= at.length)
+                return;
+            const k = asked++;
+            try {
+                const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: init.lookupTries });
+                const list = Array.isArray(init.servers) && init.servers.length > 0 ? init.servers : r.getServers();
+                if (list.length > 0)
+                    r.setServers(list.map((_, i) => list[(i + k) % list.length]));
+                resolvers.push(r);
+                ev(`lookup${k + 1}`);
+                r.resolve4(name, (err, addrs) => {
+                    if (done)
+                        return;
+                    if (!err && Array.isArray(addrs) && addrs.length > 0) {
+                        ev(`addrs${k + 1} ${addrs.length}`);
+                        finish(addrs);
+                        return;
+                    }
+                    ev(`nolookup${k + 1} ${err?.code ?? "empty"}`);
+                    gaveUp();
+                });
+            }
+            catch {
+                gaveUp();
+            }
+        };
+        for (const ms of at) {
+            if (ms <= 0)
+                ask();
+            else
+                timers.push(setTimeout(ask, ms));
         }
     });
     const limitOf = (e) => {
@@ -196,7 +256,7 @@ function start(init) {
         }
         const n = Math.max(1, init.sessions);
         pendingConnects = n;
-        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length]).then((e) => {
+        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length], i).then((e) => {
             pendingConnects--;
             if (closed) {
                 if (e)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.14",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",