@promigence/sdk 0.1.0-beta.12

package/dist/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/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/trace.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-request phase stamps for measuring the SDK's own client-side cost.
+ *
+ * Off unless `PROMIGENCE_SDK_TRACE=1`, in which case every `request()` records `performance.now()`
+ * at each phase it passes through and the process prints one JSON line per request to stderr
+ * when it exits (buffered: writing in the hot path would be the skew being measured). Nothing
+ * here is part of the API.
+ */
+export interface TraceStamp {
+    seq: number;
+    method: string;
+    path: string;
+    /** `performance.now()` at each phase, by name. */
+    t: Record<string, number>;
+    /** How the request travelled: "h2" or "fetch". */
+    via?: string;
+    /** The server's wall stamps (unix ns) when the answer carried them (`x-promigence-rx-ns` / `-tx-ns`). */
+    rx?: string;
+    tx?: string;
+    status?: number;
+    /** Over the transport thread: which of its connections (0-based, in the order they came up). */
+    conn?: number;
+}
+export declare const TRACE_ON: boolean;
+/** Run `fn` with tracing off. */
+export declare function untraced<T>(fn: () => T): T;
+/** Start a stamp for one request, or `undefined` when tracing is off (the common case: one branch). */
+export declare function traceBegin(method: string, path: string): TraceStamp | undefined;
+export declare function mark(s: TraceStamp | undefined, phase: string): void;
+/** A one-off process event (a constructor, a handshake step), for the same output. */
+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;

package/dist/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/transport-worker.d.ts

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