@promigence/sdk 0.1.0-beta.12

package/dist/models.gen.js

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

package/dist/proxy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY` for the SDK and the CLI.
+ *
+ * Node's built-in `fetch` ignores the proxy variables (Node 22 has no `NODE_USE_ENV_PROXY`), so
+ * behind a corporate proxy the CLI could not reach the API while the Python SDK, which honours
+ * them, could. This is a small `fetch` over `node:http`/`node:https` that goes through the proxy
+ * the environment names: an `http://` URL is sent to the proxy in absolute form, an `https://` URL
+ * through a `CONNECT` tunnel with TLS to the API inside it (the proxy never sees the key). It is
+ * used only when a proxy variable applies to the API's host; otherwise nothing changes.
+ *
+ * No dependency: the proxy agents live in the `undici` package, which this SDK does not ship.
+ */
+import { type ClientRequest, type RequestOptions } from "node:http";
+type FetchLike = typeof globalThis.fetch;
+/**
+ * Every variable `proxyFor` and `http2Allowed` read (a test holds them to this list), each read once
+ * from the process environment into a plain object the two then read instead: each is a lookup in
+ * the environment, and the two checks read six of them each. NO_PROXY matters only once a proxy
+ * variable names a proxy, so it is read only then.
+ */
+export declare const TRANSPORT_ENV: readonly string[];
+/** The variables of `TRANSPORT_ENV`, read now from `env`. */
+export declare function transportEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Does `NO_PROXY` exempt `host` (`*`, an exact name, a `.suffix` or `suffix`, with an optional port)? */
+export declare function noProxy(host: string, port: string, env?: NodeJS.ProcessEnv): boolean;
+/** The proxy URL the environment names for `url`, or `undefined` for a direct connection. */
+export declare function proxyFor(url: string, env?: NodeJS.ProcessEnv): URL | undefined;
+/**
+ * A `fetch` that sends every request through `proxy`. Request bodies are buffered (the SDK
+ * sends JSON and file chunks of at most 16 MiB); response bodies stream.
+ */
+export declare function proxyFetch(proxy: URL): FetchLike;
+/**
+ * `node:http(s).request(url, options)`, through the proxy the environment names for `url` when one
+ * applies ([`proxyFor`]): an https URL over a `CONNECT` tunnel with TLS to the server inside it
+ * (the proxy never sees what is sent), an http URL in absolute form. For what `fetch` cannot
+ * carry: the terminal's and the SSH tunnel's WebSocket upgrades. With no proxy, the plain request.
+ */
+export declare function requestVia(url: URL, options: RequestOptions, env?: NodeJS.ProcessEnv): ClientRequest;
+export {};

package/dist/proxy.js

@@ -0,0 +1,249 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { connect as tlsConnect } from "node:tls";
+import { Readable } from "node:stream";
+import { guardCertChain, makeCertChainGuard } from "./ca-guard.js";
+function withCertGuard(existing) {
+    return existing === undefined ? guardCertChain : makeCertChainGuard(existing);
+}
+function envOf(env, name) {
+    const v = env[name] ?? env[name.toLowerCase()];
+    return v !== undefined && v.trim() !== "" ? v.trim() : undefined;
+}
+export const TRANSPORT_ENV = [
+    "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy", "PROMIGENCE_HTTP2", "NO_PROXY", "no_proxy",
+];
+export function transportEnv(env = process.env) {
+    const view = {};
+    let proxied = false;
+    for (let i = 0; i < 6; i++) {
+        const k = TRANSPORT_ENV[i];
+        const v = env[k];
+        if (v === undefined)
+            continue;
+        view[k] = v;
+        proxied = true;
+    }
+    const h2 = env["PROMIGENCE_HTTP2"];
+    if (h2 !== undefined)
+        view["PROMIGENCE_HTTP2"] = h2;
+    if (proxied) {
+        const a = env["NO_PROXY"];
+        const b = env["no_proxy"];
+        if (a !== undefined)
+            view["NO_PROXY"] = a;
+        if (b !== undefined)
+            view["no_proxy"] = b;
+    }
+    return view;
+}
+export function noProxy(host, port, env = process.env) {
+    const list = envOf(env, "NO_PROXY");
+    if (!list)
+        return false;
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    for (const raw of list.split(/[,\s]+/)) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (entry === "*")
+            return true;
+        const [name, p] = entry.startsWith("[") ? [entry.replace(/\]:?.*$/, "").slice(1), entry.split("]:")[1]] : entry.split(":");
+        if (p && p !== port)
+            continue;
+        const bare = (name ?? "").replace(/^\*?\./, "");
+        if (h === bare || h.endsWith(`.${bare}`))
+            return true;
+    }
+    return false;
+}
+export function proxyFor(url, env = process.env) {
+    const https = envOf(env, "HTTPS_PROXY");
+    const http = envOf(env, "HTTP_PROXY");
+    const all = envOf(env, "ALL_PROXY");
+    if (https === undefined && http === undefined && all === undefined)
+        return undefined;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const port = u.port || (u.protocol === "https:" ? "443" : "80");
+    if (noProxy(u.hostname, port, env))
+        return undefined;
+    const raw = (u.protocol === "https:" ? https : http) ?? all;
+    if (!raw)
+        return undefined;
+    try {
+        const p = new URL(raw.includes("://") ? raw : `http://${raw}`);
+        if (p.protocol !== "http:" && p.protocol !== "https:")
+            return undefined;
+        return p;
+    }
+    catch {
+        return undefined;
+    }
+}
+function proxyAuth(p) {
+    if (!p.username)
+        return {};
+    const cred = `${decodeURIComponent(p.username)}:${decodeURIComponent(p.password)}`;
+    return { "proxy-authorization": `Basic ${Buffer.from(cred).toString("base64")}` };
+}
+function headersOf(init) {
+    const out = {};
+    const h = init?.headers;
+    if (!h)
+        return out;
+    if (h instanceof Headers)
+        h.forEach((v, k) => { out[k] = v; });
+    else if (Array.isArray(h))
+        for (const [k, v] of h)
+            out[k.toLowerCase()] = v;
+    else
+        for (const [k, v] of Object.entries(h))
+            out[k.toLowerCase()] = v;
+    return out;
+}
+async function bodyOf(init) {
+    const b = init?.body;
+    if (b === undefined || b === null)
+        return undefined;
+    if (typeof b === "string")
+        return Buffer.from(b);
+    if (b instanceof Uint8Array)
+        return Buffer.from(b.buffer, b.byteOffset, b.byteLength);
+    if (b instanceof ArrayBuffer)
+        return Buffer.from(b);
+    return Buffer.from(await new Response(b).arrayBuffer());
+}
+function toResponse(res) {
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(res.headers)) {
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v))
+            for (const x of v)
+                headers.append(k, x);
+        else
+            headers.set(k, String(v));
+    }
+    const status = res.statusCode ?? 502;
+    const noBody = status === 204 || status === 304;
+    return new Response(noBody ? null : Readable.toWeb(res), {
+        status, statusText: res.statusMessage ?? "", headers,
+    });
+}
+function abortError(signal) {
+    const r = signal.reason;
+    return r instanceof Error ? r : Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+}
+export function proxyFetch(proxy) {
+    const fetchViaProxy = async (input, init) => {
+        const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+        const method = (init?.method ?? "GET").toUpperCase();
+        const headers = headersOf(init);
+        const body = await bodyOf(init);
+        if (body)
+            headers["content-length"] = String(body.length);
+        const signal = init?.signal ?? undefined;
+        if (signal?.aborted)
+            throw abortError(signal);
+        const proxyRequest = proxy.protocol === "https:" ? httpsRequest : httpRequest;
+        const proxyPort = Number(proxy.port || (proxy.protocol === "https:" ? 443 : 80));
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (e) => {
+                if (settled)
+                    return;
+                settled = true;
+                const isAbort = e?.name === "AbortError" || e?.name === "TimeoutError";
+                reject(isAbort || e instanceof TypeError ? e : new TypeError("fetch failed", { cause: e }));
+            };
+            const onAbort = () => fail(abortError(signal));
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const done = (res) => {
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                resolve(toResponse(res));
+            };
+            if (url.protocol === "http:") {
+                const req = proxyRequest({
+                    host: proxy.hostname, port: proxyPort, method, path: url.href,
+                    headers: { ...headers, host: url.host, ...proxyAuth(proxy) }, ...(signal ? { signal } : {}),
+                }, done);
+                req.on("error", fail);
+                req.end(body);
+                return;
+            }
+            const port = Number(url.port || 443);
+            const connect = proxyRequest({
+                host: proxy.hostname, port: proxyPort, method: "CONNECT", path: `${url.hostname}:${port}`,
+                headers: { host: `${url.hostname}:${port}`, ...proxyAuth(proxy) }, ...(signal ? { signal } : {}),
+            });
+            connect.on("error", fail);
+            connect.on("connect", (res, socket) => {
+                if (res.statusCode !== 200) {
+                    socket.destroy();
+                    fail(new TypeError(`fetch failed: the proxy ${proxy.host} refused CONNECT ${url.host} (HTTP ${res.statusCode})`));
+                    return;
+                }
+                const tls = tlsConnect({ socket, servername: url.hostname, ALPNProtocols: ["http/1.1"], checkServerIdentity: guardCertChain });
+                tls.on("error", fail);
+                const req = httpsRequest({
+                    host: url.hostname, port, method, path: `${url.pathname}${url.search}`,
+                    headers: { ...headers, host: url.host }, createConnection: () => tls, agent: false,
+                    ...(signal ? { signal } : {}),
+                }, done);
+                req.on("error", fail);
+                req.end(body);
+            });
+            connect.end();
+        });
+    };
+    return fetchViaProxy;
+}
+export function requestVia(url, options, env = process.env) {
+    const proxy = proxyFor(url.href, env);
+    const httpsOptions = (o) => {
+        if (url.protocol !== "https:")
+            return o;
+        const prev = o.checkServerIdentity;
+        return Object.assign({}, o, { checkServerIdentity: withCertGuard(prev) });
+    };
+    if (!proxy)
+        return (url.protocol === "https:" ? httpsRequest : httpRequest)(url, httpsOptions(options));
+    const proxyRequest = proxy.protocol === "https:" ? httpsRequest : httpRequest;
+    const proxyPort = Number(proxy.port || (proxy.protocol === "https:" ? 443 : 80));
+    if (url.protocol === "http:") {
+        return proxyRequest({
+            ...options, host: proxy.hostname, port: proxyPort, path: url.href,
+            headers: { ...options.headers, host: url.host, ...proxyAuth(proxy) },
+        });
+    }
+    const port = Number(url.port || 443);
+    const createConnection = (_opts, done) => {
+        const connect = proxyRequest({
+            host: proxy.hostname, port: proxyPort, method: "CONNECT", path: `${url.hostname}:${port}`,
+            headers: { host: `${url.hostname}:${port}`, ...proxyAuth(proxy) },
+        });
+        connect.on("error", (e) => done(e));
+        connect.on("connect", (res, socket) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                done(new Error(`the proxy ${proxy.host} refused CONNECT ${url.host} (HTTP ${res.statusCode})`));
+                return;
+            }
+            done(null, tlsConnect({ socket, servername: url.hostname, ALPNProtocols: ["http/1.1"], checkServerIdentity: guardCertChain }));
+        });
+        connect.end();
+        return undefined;
+    };
+    const { agent: _agent, ...direct } = options;
+    return httpsRequest(url, {
+        ...direct,
+        createConnection: createConnection,
+    });
+}

package/dist/pty.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Interactive terminals: `GET /v1/sandboxes/:id/pty` over a WebSocket (RFC 6455).
+ *
+ * The protocol:
+ *
+ *   client → server  binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
+ *   server → client  binary = terminal output; text = `{"event":"open",…}` first and
+ *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame
+ *
+ * Zero dependencies, so this is a small client over `node:http` rather than the global
+ * `WebSocket`: that one cannot send an `Authorization` header, and a key in the query string is
+ * a key in every access log between here and the sandbox.
+ */
+/** Largest terminal input frame sent; the server's cap is 1 MiB per client frame. */
+export declare const PTY_INPUT_CHUNK: number;
+/** How much of what was typed a session keeps, to send again to a terminal picked up again. */
+export declare const PTY_INPUT_KEEP: number;
+/** The header a terminal is picked up again with (its resume token). */
+export declare const PTY_RESUME_HEADER = "promigence-resume";
+export interface PtySize {
+    cols: number;
+    rows: number;
+}
+/** How a terminal ended. `exitCode` is `null` when the shell died of a signal. */
+export interface PtyExit {
+    exitCode: number | null;
+    signal: number | null;
+    wallMs?: number;
+    /** Set when the session ended without an exit record (`error`, or the socket just closed). */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** The header the terminal's command travels in, base64. Never a query parameter. */
+export declare const PTY_COMMAND_HEADER = "promigence-pty-command";
+/** The header the terminal's secret **names** travel in, base64 JSON. */
+export declare const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+export interface PtyConnectOpts {
+    /** `http(s)://host[:port]/v1/sandboxes/<id>/pty?cols=&rows=` — dimensions only. */
+    url: string;
+    apiKey: string;
+    userAgent: string;
+    /**
+     * The command to run, sent as a header rather than in the URL.
+     *
+     * It used to be `?cmd=`, with `envs` composed into it as `export K=v;` — so a terminal opened
+     * with an API key in its environment wrote that key into the query string of every request,
+     * and therefore into every access log along the path. Names and values both stay out of the
+     * URL now.
+     */
+    command?: string;
+    /** Stored secret names (or `{name, as}` bindings), resolved server-side into the terminal's
+     *  environment. JSON, base64, in a header. */
+    secrets?: unknown[];
+    /** The `promigence-caller` label, when one is set (`setCaller`). */
+    caller?: string;
+    onData?: (data: Uint8Array) => void;
+    onExit?: (exit: PtyExit) => void;
+    /**
+     * Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+     * terminal cannot be picked up again ([`resume`]). The session goes on over a new connection,
+     * with its callbacks, its size and what was typed meanwhile, in a NEW shell: what ran in the old
+     * one has ended. Tried for up to 30 s ([`PTY_RECONNECT_FOR_MS`]); past that the session ends with
+     * `error.code` `"service_restart"`.
+     *
+     * Default: on for a shell, off when `command` is set (reconnecting starts the command again,
+     * which may not be safe to run twice); `true` or `false` decides either way.
+     */
+    reconnect?: boolean;
+    /**
+     * Pick the same terminal up again when its connection drops or the service restarts (default
+     * on): the terminal keeps running for a short while, and the session picks up where it left off
+     * over a new connection, with what was typed meanwhile delivered once — the same shell, or the
+     * same command, still running. Where it cannot be picked up (it ended meanwhile, or too much time
+     * passed), a restart falls back to [`reconnect`]; a dropped connection ends the session, as
+     * before.
+     */
+    resume?: boolean;
+    /**
+     * Called after each reconnect: `resumed` is `true` when it is the same terminal picked up
+     * again, `false` when it is a new shell (what ran in the old one has ended).
+     */
+    onReconnected?: (how: {
+        resumed: boolean;
+    }) => void;
+    /** Handshake bound (default 30 s). The session itself has none. */
+    timeoutMs?: number;
+    /** Maps a refused upgrade (`status`, body text, its `Retry-After`) onto the SDK's error classes. */
+    refuse: (status: number, body: string, retryAfter?: string) => Error;
+}
+/** The accept value a server must echo for `key` (RFC 6455 §4.2.2). */
+export declare function wsAccept(key: string): string;
+/** One client → server frame: FIN, the opcode, a 4-byte mask (mandatory from a client). */
+export declare function encodeFrame(opcode: number, payload: Uint8Array): Buffer;
+/**
+ * Incremental frame decoder. Feed it bytes as they arrive; it returns whole frames. Continuation
+ * frames are reassembled, so a server that fragments is read correctly.
+ */
+export declare class FrameReader {
+    private buf;
+    private partial;
+    push(chunk: Uint8Array): Array<{
+        opcode: number;
+        payload: Buffer;
+    }>;
+}
+/**
+ * A live terminal. Resolved by [`connectPty`] once the server's `open` event has arrived, so a
+ * keystroke written immediately is never written into a pty that does not exist yet.
+ */
+export declare class PtySession {
+    #private;
+    private socket;
+    /**
+     * The id of the terminal's process inside the sandbox (`req_id`); what `pty.kill(pid)`
+     * addresses. It names this session: it stays the same after a reconnect.
+     */
+    readonly pid: number;
+    cols: number;
+    rows: number;
+    private closed;
+    private readonly done;
+    /** Frames written while the session reconnects, sent once it has (at most 1 MiB). */
+    private pending;
+    /** Keystrokes written to a connection, in all, and the last of them, from `inputBase` on: what a
+     *  terminal picked up again did not take is sent again. */
+    private inputSent;
+    private inputBase;
+    private inputLog;
+    /** `true` once the terminal has ended (its exit arrived, or the socket closed). */
+    get ended(): boolean;
+    private flush;
+    /** Write a frame to the connection now, counting keystrokes. */
+    private writeNow;
+    private send;
+    /** Keystrokes / a paste. A string is sent as UTF-8. */
+    write(data: string | Uint8Array): void;
+    resize(size: PtySize): void;
+    /** Deliver a signal to the terminal's process group (`9` = SIGKILL). */
+    signal(sig: number): void;
+    /** Close the terminal's stdin (`^D` without the line discipline). */
+    eof(): void;
+    /** Resolves with how the terminal ended. Never rejects. */
+    wait(): Promise<PtyExit>;
+    /**
+     * Hang up. The shell is sent `SIGHUP` when the socket goes away, which is what a
+     * terminal emulator closing its window does.
+     */
+    disconnect(): void;
+}
+/** The `Close` code a terminal is asked to reconnect with: 1012, "service restart" (RFC 6455's registry). */
+export declare const PTY_RECONNECT_CODE = 1012;
+/** How long a terminal tries to reconnect before it ends (`error.code` `"service_restart"`). */
+export declare const PTY_RECONNECT_FOR_MS = 30000;
+/** The first wait before a reconnect, doubled each try up to [`PTY_RECONNECT_MAX_WAIT_MS`]; each wait is jittered (50-100 %). */
+export declare const PTY_RECONNECT_FIRST_WAIT_MS = 250;
+export declare const PTY_RECONNECT_MAX_WAIT_MS = 4000;
+/** How a session that could not reconnect within [`PTY_RECONNECT_FOR_MS`] ends. */
+export declare const PTY_RESTART_EXIT: PtyExit;
+/** How a session that is not to reconnect (`reconnect` off, or a command's) ends at a 1012. */
+export declare const PTY_RESTART_CLOSED_EXIT: PtyExit;
+/**
+ * Open a terminal. Rejects with `opts.refuse(...)` if the server does not switch protocols.
+ *
+ * When its connection drops, or the service asks it to reconnect (`Close` 1012), the session goes
+ * on over a new connection: the same terminal picked up again where the service still holds it
+ * ([`PtyConnectOpts.resume`]), else, at a restart, a new shell ([`PtyConnectOpts.reconnect`]).
+ * `wait()` resolves only when the session really ends.
+ */
+export declare function connectPty(opts: PtyConnectOpts): Promise<PtySession>;