promigence 0.1.0-beta.12

package/dist/sdk/ssh.d.ts

@@ -0,0 +1,25 @@
+export interface SshTunnelOpts {
+    /** `https://api…/v1/sandboxes/:id/ssh/connect` */
+    url: string;
+    /** A `prom_ssh_` access credential, or an API key. */
+    token: string;
+    userAgent: string;
+    caller?: string;
+    timeoutMs?: number;
+    /** Bytes from the sandbox's SSH server. */
+    onData: (data: Uint8Array) => void;
+    /** The tunnel closed. */
+    onClose: () => void;
+    /** Build the error to reject with when the server does not switch protocols. */
+    refuse: (status: number, text: string) => Error;
+}
+export interface SshTunnel {
+    /** Send bytes to the sandbox's SSH server. */
+    write(data: Uint8Array): void;
+    /** Close the tunnel. */
+    close(): void;
+    /** Resolves when the tunnel is finished. */
+    done: Promise<void>;
+}
+/** Open the tunnel. Resolves once the socket has switched protocols. */
+export declare function connectSshTunnel(opts: SshTunnelOpts): Promise<SshTunnel>;

package/dist/sdk/ssh.js

@@ -0,0 +1,114 @@
+import { randomBytes } from "node:crypto";
+import { CALLER_HEADER } from "./caller.js";
+import { requestVia } from "./proxy.js";
+import { FrameReader, encodeFrame, wsAccept } from "./pty.js";
+export function connectSshTunnel(opts) {
+    const url = new URL(opts.url);
+    const key = randomBytes(16).toString("base64");
+    const req = requestVia(url, {
+        method: "GET",
+        agent: false,
+        headers: {
+            connection: "Upgrade",
+            upgrade: "websocket",
+            "sec-websocket-version": "13",
+            "sec-websocket-key": key,
+            authorization: `Bearer ${opts.token}`,
+            "user-agent": opts.userAgent,
+            ...(opts.caller ? { [CALLER_HEADER]: opts.caller } : {}),
+        },
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (e) => {
+            if (!settled) {
+                settled = true;
+                reject(e);
+            }
+        };
+        const timer = setTimeout(() => {
+            req.destroy();
+            fail(opts.refuse(504, JSON.stringify({
+                error: {
+                    code: "timeout",
+                    message: `the SSH tunnel to ${url.host} did not open within ${opts.timeoutMs ?? 30_000} ms`,
+                    fix: "Retry; if it repeats, check the sandbox is ready.",
+                },
+            })));
+        }, opts.timeoutMs ?? 30_000);
+        req.on("error", (e) => {
+            clearTimeout(timer);
+            fail(opts.refuse(0, JSON.stringify({
+                error: {
+                    code: "unreachable",
+                    message: `cannot reach ${url.host}: ${e.code ?? e.message}`,
+                },
+            })));
+        });
+        req.on("response", (res) => {
+            clearTimeout(timer);
+            const parts = [];
+            res.on("data", (d) => parts.push(d));
+            res.on("end", () => fail(opts.refuse(res.statusCode ?? 0, Buffer.concat(parts).toString("utf8"))));
+        });
+        req.on("upgrade", (res, socket, head) => {
+            clearTimeout(timer);
+            if (res.headers["sec-websocket-accept"] !== wsAccept(key)) {
+                socket.destroy();
+                fail(opts.refuse(502, JSON.stringify({
+                    error: {
+                        code: "internal",
+                        message: "the tunnel answered the WebSocket handshake with the wrong accept key",
+                    },
+                })));
+                return;
+            }
+            socket.setNoDelay(true);
+            const reader = new FrameReader();
+            let resolveDone;
+            const done = new Promise((r) => {
+                resolveDone = r;
+            });
+            let finished = false;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                opts.onClose();
+                resolveDone();
+            };
+            const onFrames = (chunk) => {
+                for (const f of reader.push(chunk)) {
+                    if (f.opcode === 0x2 || f.opcode === 0x1) {
+                        opts.onData(new Uint8Array(f.payload));
+                    }
+                    else if (f.opcode === 0x9) {
+                        socket.write(encodeFrame(0xa, f.payload));
+                    }
+                    else if (f.opcode === 0x8) {
+                        if (!socket.destroyed)
+                            socket.end(encodeFrame(0x8, f.payload.subarray(0, 2)));
+                    }
+                }
+            };
+            socket.on("data", onFrames);
+            socket.on("close", finish);
+            socket.on("error", finish);
+            if (head.length)
+                onFrames(head);
+            settled = true;
+            resolve({
+                write(data) {
+                    if (!socket.destroyed)
+                        socket.write(encodeFrame(0x2, data));
+                },
+                close() {
+                    if (!socket.destroyed)
+                        socket.end(encodeFrame(0x8, Buffer.from([0x03, 0xe8])));
+                },
+                done,
+            });
+        });
+        req.end();
+    });
+}

package/dist/sdk/trace.js

@@ -0,0 +1,80 @@
+import { writeSync } from "node:fs";
+import { VERSION } from "./core.js";
+export const TRACE_ON = (() => {
+    try {
+        return typeof process === "object" && process.env?.["PROMIGENCE_SDK_TRACE"] === "1";
+    }
+    catch {
+        return false;
+    }
+})();
+const stamps = [];
+let seq = 0;
+let hooked = false;
+let muted = 0;
+export function untraced(fn) {
+    muted++;
+    try {
+        return fn();
+    }
+    finally {
+        muted--;
+    }
+}
+export function traceBegin(method, path) {
+    if (!TRACE_ON || muted > 0)
+        return undefined;
+    const s = { seq: seq++, method, path, t: { call: performance.now() } };
+    stamps.push(s);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+    return s;
+}
+export function mark(s, phase) {
+    if (s !== undefined)
+        s.t[phase] = performance.now();
+}
+const events = [];
+export function traceEvent(name) {
+    if (!TRACE_ON || muted > 0)
+        return;
+    events.push([name, performance.now()]);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+}
+export function traceEventAt(name, t) {
+    if (!TRACE_ON || muted > 0)
+        return;
+    events.push([name, t]);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+}
+function modulePath() {
+    const frame = (new Error().stack ?? "").split("\n")[1] ?? "";
+    const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
+    return m?.[1] ?? "";
+}
+function flush() {
+    const head = {
+        trace: "promigence-sdk",
+        version: VERSION,
+        node: process.versions.node,
+        timeOrigin: performance.timeOrigin,
+        module: modulePath(),
+        requests: stamps.length,
+        events,
+    };
+    let out = `PROMIGENCE_SDK_TRACE ${JSON.stringify(head)}\n`;
+    for (const s of stamps)
+        out += `PROMIGENCE_SDK_TRACE ${JSON.stringify(s)}\n`;
+    try {
+        writeSync(2, out);
+    }
+    catch { }
+}

package/dist/sdk/transport-worker.js

@@ -0,0 +1,466 @@
+import * as dns from "node:dns";
+import { readFileSync } from "node:fs";
+import * as http2 from "node:http2";
+import { isIP, isIPv4 } from "node:net";
+import * as tls from "node:tls";
+import * as wt from "node:worker_threads";
+import { __caGuardInternals, guardCertChain } from "./ca-guard.js";
+const { NGHTTP2_CANCEL, NGHTTP2_REFUSED_STREAM } = http2.constants;
+const MAX_UNPROCESSED_RESENDS = 3;
+const MAX_REPLAYS = 1;
+const STREAM_WINDOW = 8 * 1024 * 1024;
+const SESSION_WINDOW = 32 * 1024 * 1024;
+const DEFAULT_STREAM_LIMIT = 100;
+const MAX_STREAM_LIMIT = 1_000;
+const hrNow = () => Number(process.hrtime.bigint()) / 1e6;
+function start(init) {
+    const port = init.port;
+    const origin = new URL(init.origin);
+    const host = origin.hostname.replace(/^\[(.*)\]$/, "$1");
+    const tcpPort = origin.port ? Number(origin.port) : 443;
+    for (const h of init.distrustedForTest ?? [])
+        __caGuardInternals.addForTest(h);
+    const sessions = [];
+    const inflight = new Map();
+    let everReady = false;
+    let closed = false;
+    let draining;
+    let running = 0;
+    let idleTimer;
+    let pendingConnects = 0;
+    const post = (m, transfer) => {
+        try {
+            port.postMessage(m, transfer ?? []);
+        }
+        catch { }
+    };
+    const live = () => sessions.filter((e) => !e.retired && !e.session.closed && !e.session.destroyed);
+    const end = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        if (pumpTimer !== undefined)
+            clearTimeout(pumpTimer);
+        if (pumpSoon !== undefined)
+            clearImmediate(pumpSoon);
+        for (const w of waiting.splice(0))
+            w.resolve(null);
+        for (const e of sessions) {
+            try {
+                e.session.close();
+            }
+            catch { }
+        }
+        for (const c of inflight.values())
+            c.cancel();
+        post({ t: "closed", reason });
+        try {
+            port.close();
+        }
+        catch { }
+    };
+    const armIdle = (ms) => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => { if (running === 0)
+            end("idle"); }, ms);
+    };
+    const drain = (reason) => {
+        if (closed || draining !== undefined)
+            return;
+        draining = reason;
+        post({ t: "draining", reason });
+        if (running === 0)
+            end(reason);
+    };
+    const retire = (e) => {
+        if (e.retired)
+            return;
+        e.retired = true;
+        if (!everReady)
+            return;
+        const n = live().length;
+        if (n === 0 && pendingConnects === 0)
+            drain("sessions closed");
+        else
+            post({ t: "sessions", sessions: n });
+    };
+    let context;
+    try {
+        context = tls.createSecureContext();
+    }
+    catch {
+        context = undefined;
+    }
+    const connect = (address) => new Promise((resolve) => {
+        let done = false;
+        const finish = (e) => { if (!done) {
+            done = true;
+            clearTimeout(timer);
+            resolve(e);
+        } };
+        const timer = setTimeout(() => { try {
+            socket.destroy();
+        }
+        catch { } finish(null); }, init.connectTimeoutMs);
+        const socket = tls.connect({
+            host: address,
+            port: tcpPort,
+            ...(isIP(host) !== 0 ? {} : { servername: host }),
+            ALPNProtocols: ["h2", "http/1.1"],
+            checkServerIdentity: guardCertChain,
+            ...(context === undefined ? {} : { secureContext: context }),
+        });
+        socket.once("error", () => finish(null));
+        socket.once("secureConnect", () => {
+            if (socket.alpnProtocol !== "h2") {
+                socket.destroy();
+                finish(null);
+                return;
+            }
+            let session;
+            try {
+                session = http2.connect(origin.origin, { createConnection: () => socket, settings: { enablePush: false, initialWindowSize: STREAM_WINDOW } });
+            }
+            catch {
+                socket.destroy();
+                finish(null);
+                return;
+            }
+            const entry = { session, active: 0, retired: false, goawayLast: undefined, nextFree: 0, granted: 0, index: -1, addr: address, localPort: socket.localPort ?? 0 };
+            try {
+                session.setLocalWindowSize(SESSION_WINDOW);
+            }
+            catch { }
+            session.on("error", () => retire(entry));
+            session.on("close", () => retire(entry));
+            session.on("frameError", () => { });
+            session.on("goaway", (_c, last) => {
+                entry.goawayLast = Math.min(entry.goawayLast ?? last, last);
+                retire(entry);
+            });
+            session.once("remoteSettings", () => finish(entry));
+        });
+    });
+    const lookup = () => new Promise((resolve) => {
+        if (isIP(host) !== 0) {
+            resolve([host]);
+            return;
+        }
+        const name = host.toLowerCase();
+        let named = false;
+        const v4 = [];
+        try {
+            for (const line of readFileSync(init.hostsFile || "/etc/hosts", "utf8").split("\n")) {
+                const f = line.replace(/#.*/, "").trim().split(/\s+/);
+                if (f.length < 2 || !f.slice(1).some((n) => n.toLowerCase() === name))
+                    continue;
+                named = true;
+                if (isIPv4(f[0]) && !v4.includes(f[0]))
+                    v4.push(f[0]);
+            }
+        }
+        catch { }
+        if (named) {
+            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 limitOf = (e) => {
+        try {
+            const m = e.session.remoteSettings?.maxConcurrentStreams;
+            return typeof m === "number" && m > 0 ? Math.min(m, MAX_STREAM_LIMIT) : DEFAULT_STREAM_LIMIT;
+        }
+        catch {
+            return DEFAULT_STREAM_LIMIT;
+        }
+    };
+    const open = async () => {
+        const addrs = await lookup();
+        if (closed)
+            return;
+        if (addrs.length === 0) {
+            end("lookup failed");
+            return;
+        }
+        const n = Math.max(1, init.sessions);
+        pendingConnects = n;
+        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length]).then((e) => {
+            pendingConnects--;
+            if (closed) {
+                if (e)
+                    try {
+                        e.session.close();
+                    }
+                    catch { }
+                return;
+            }
+            if (e !== null) {
+                e.index = sessions.length;
+                sessions.push(e);
+                if (!everReady) {
+                    everReady = true;
+                    armIdle(init.firstUseMs);
+                }
+                post({ t: "ready", sessions: live().length, limit: limitOf(e), index: e.index, addr: e.addr, localPort: e.localPort, hr: Number(process.hrtime.bigint()) / 1e6 });
+            }
+            else if (pendingConnects === 0 && live().length === 0) {
+                if (everReady)
+                    drain("sessions closed");
+                else
+                    end("connect failed");
+            }
+        }));
+        await Promise.all(tries);
+    };
+    const gapMs = Math.max(0, init.gapUs) / 1000;
+    const waiting = [];
+    let rr = 0;
+    let rrAny = 0;
+    let pumpTimer;
+    let pumpSoon;
+    const freeNow = (l, now) => {
+        for (let i = 0; i < l.length; i++) {
+            const k = (rr + i) % l.length;
+            const e = l[k];
+            if (e.nextFree <= now) {
+                rr = k + 1;
+                return e;
+            }
+        }
+        return undefined;
+    };
+    const pump = () => {
+        pumpTimer = undefined;
+        pumpSoon = undefined;
+        while (waiting.length > 0) {
+            const l = live();
+            if (l.length === 0) {
+                for (const w of waiting.splice(0))
+                    w.resolve(null);
+                return;
+            }
+            const now = hrNow();
+            const e = freeNow(l, now);
+            if (e === undefined)
+                break;
+            e.nextFree = now + gapMs;
+            e.granted = now;
+            waiting.shift().resolve(e);
+        }
+        if (waiting.length === 0)
+            return;
+        let next = Infinity;
+        for (const e of live())
+            next = Math.min(next, e.nextFree);
+        const wait = next - hrNow();
+        if (wait > 2)
+            pumpTimer = setTimeout(pump, Math.floor(wait) - 1);
+        else
+            pumpSoon = setImmediate(pump);
+    };
+    const nextSession = (id, paced) => {
+        const l = live();
+        if (l.length === 0)
+            return null;
+        if (gapMs <= 0) {
+            let best = l[0];
+            for (const e of l)
+                if (e.active < best.active)
+                    best = e;
+            return best;
+        }
+        if (!paced) {
+            const e = l[rrAny % l.length];
+            rrAny = (rrAny % l.length) + 1;
+            return e;
+        }
+        if (waiting.length === 0) {
+            const now = hrNow();
+            const e = freeNow(l, now);
+            if (e !== undefined) {
+                e.nextFree = now + gapMs;
+                e.granted = now;
+                return e;
+            }
+        }
+        return new Promise((resolve) => {
+            waiting.push({ id, resolve });
+            if (pumpTimer === undefined && pumpSoon === undefined)
+                pump();
+        });
+    };
+    const unwait = (id) => {
+        const i = waiting.findIndex((w) => w.id === id);
+        if (i >= 0)
+            waiting.splice(i, 1)[0].resolve(null);
+    };
+    const attempt = async (req, deadline) => {
+        const paced = req.paced !== false;
+        const given = nextSession(req.id, paced);
+        const entry = given instanceof Promise ? await given : given;
+        if (entry === null || cancelled.has(req.id) || entry.retired || entry.session.closed || entry.session.destroyed) {
+            return { kind: "failed", processed: "no", code: "ERR_HTTP2_NO_SESSION", message: "no session", unsent: true };
+        }
+        return send(req, deadline, entry, gapMs > 0 && paced ? entry.granted : 0);
+    };
+    const send = (req, deadline, entry, granted) => new Promise((resolve) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            resolve({ kind: "timeout" });
+            return;
+        }
+        const headers = { ...req.headers };
+        headers[http2.sensitiveHeaders] = req.sensitive;
+        const body = req.body === undefined ? undefined : Buffer.from(req.body, "utf8");
+        let stream;
+        try {
+            stream = entry.session.request(headers, { endStream: body === undefined });
+        }
+        catch (e) {
+            retire(entry);
+            resolve({ kind: "failed", processed: "no", code: e.code ?? "ERR", message: String(e.message ?? e), unsent: true });
+            return;
+        }
+        entry.active++;
+        post({ t: "ack", id: req.id });
+        const sent = init.trace !== true ? 0 : granted > 0 ? granted : hrNow();
+        let head = 0;
+        let status = 0;
+        let resHeaders = {};
+        const chunks = [];
+        let settled = false;
+        const finish = (o) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            inflight.delete(req.id);
+            resolve(o);
+        } };
+        const timer = setTimeout(() => { try {
+            stream.close(NGHTTP2_CANCEL);
+        }
+        catch { } finish({ kind: "timeout" }); }, remaining);
+        inflight.set(req.id, { cancel: () => { try {
+                stream.close(NGHTTP2_CANCEL);
+            }
+            catch { } finish({ kind: "failed", processed: "maybe", code: "ABORT", message: "cancelled" }); } });
+        stream.on("response", (h) => { resHeaders = h; status = Number(h[":status"]); if (init.trace === true)
+            head = hrNow(); });
+        stream.on("data", (c) => { chunks.push(c); });
+        stream.on("error", () => { });
+        stream.on("end", () => { if (status !== 0)
+            finish({ kind: "res", status, headers: resHeaders, body: Buffer.concat(chunks), sent, head, end: init.trace === true ? hrNow() : 0, conn: entry.index }); });
+        stream.on("close", () => {
+            entry.active = Math.max(0, entry.active - 1);
+            if (settled)
+                return;
+            const rst = stream.rstCode;
+            let processed;
+            if (status !== 0)
+                processed = "yes";
+            else if (rst === NGHTTP2_REFUSED_STREAM || stream.id === undefined)
+                processed = "no";
+            else if (entry.goawayLast !== undefined && stream.id > entry.goawayLast)
+                processed = "no";
+            else
+                processed = "maybe";
+            finish({ kind: "failed", processed, code: "ERR_HTTP2_STREAM_ERROR", message: `HTTP/2 stream closed (code ${rst ?? "?"})` });
+        });
+        if (body !== undefined)
+            stream.end(body);
+    });
+    const active = new Set();
+    const cancelled = new Set();
+    const run = async (req) => {
+        if (idleTimer !== undefined) {
+            clearTimeout(idleTimer);
+            idleTimer = undefined;
+        }
+        running++;
+        active.add(req.id);
+        const got = init.trace === true ? hrNow() : 0;
+        const deadline = Date.now() + req.timeoutMs;
+        let resends = 0;
+        let replays = 0;
+        const back = () => { post({ t: "err", id: req.id, kind: "back", resends, replays }); };
+        for (;;) {
+            if (cancelled.has(req.id))
+                break;
+            const out = await attempt(req, deadline);
+            if (cancelled.has(req.id))
+                break;
+            if (out.kind === "res") {
+                const ab = out.body.buffer.slice(out.body.byteOffset, out.body.byteOffset + out.body.byteLength);
+                post({ t: "res", id: req.id, status: out.status, headers: out.headers, body: ab, replayed: replays > 0, ...(init.trace === true ? { w: [got, out.sent, out.head, out.end], conn: out.conn } : {}) }, [ab]);
+                break;
+            }
+            if (out.kind === "timeout") {
+                post({ t: "err", id: req.id, kind: "timeout" });
+                break;
+            }
+            if (out.unsent === true) {
+                back();
+                break;
+            }
+            if (out.processed === "no") {
+                if (++resends <= MAX_UNPROCESSED_RESENDS) {
+                    if (live().length > 0)
+                        continue;
+                    back();
+                    break;
+                }
+                post({ t: "err", id: req.id, kind: "failed", processed: "no", code: out.code, message: out.message });
+                break;
+            }
+            if (out.processed === "maybe" && req.replayable && replays < MAX_REPLAYS) {
+                replays++;
+                if (live().length > 0)
+                    continue;
+                back();
+                break;
+            }
+            post({ t: "err", id: req.id, kind: "failed", processed: out.processed, code: out.code, message: out.message });
+            break;
+        }
+        active.delete(req.id);
+        cancelled.delete(req.id);
+        running--;
+        if (running > 0 || closed)
+            return;
+        if (draining !== undefined)
+            end(draining);
+        else
+            armIdle(init.idleMs);
+    };
+    port.on("message", (m) => {
+        if (closed)
+            return;
+        if (m?.t === "req")
+            void run(m);
+        else if (m?.t === "drain")
+            drain("asked");
+        else if (m?.t === "cancel" && typeof m.id === "number") {
+            if (active.has(m.id))
+                cancelled.add(m.id);
+            unwait(m.id);
+            inflight.get(m.id)?.cancel();
+        }
+        else if (m?.t === "crash-for-test")
+            setImmediate(() => { throw new Error("transport thread crash (test)"); });
+    });
+    void open();
+}
+if (!wt.isMainThread && wt.workerData && typeof wt.workerData === "object" && wt.workerData.promigenceTransport === true) {
+    start(wt.workerData);
+}