@promigence/sdk 0.1.0-beta.12

package/dist/gitlab.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The GitLab connection (`/v1/integrations/gitlab/*`): the answers' types, and the project path
+ * `snapshots.create({ repo: "gitlab:group/project" })` takes.
+ *
+ * A person authorizes the platform's GitLab application once, read-only (`promigence gitlab
+ * connect`), and an owner of the organization confirms it in the browser; after that a snapshot is
+ * built from a private project by its path, with no credential ever passing through the client.
+ */
+/** `POST /integrations/gitlab/connect`: open `authorize_url` in a browser. */
+export interface GitlabConnect {
+    authorize_url: string;
+    /** RFC 3339: the link works for 15 minutes. */
+    expires_at: string;
+    gitlab_url: string;
+    /** Read-only: `read_api`, `read_repository`. */
+    scopes: string[];
+}
+/** One GitLab user whose read-only authorization is connected. */
+export interface GitlabConnection {
+    connection_id: string;
+    username: string;
+    user_id: number;
+    gitlab_url: string;
+    connected_at: string;
+    /** The authorization stopped working on GitLab: connect again. */
+    broken: boolean;
+    broken_reason?: string;
+    /** Optional: a project webhook (push events) for instant rebuilds of tracked branches. */
+    webhook_url: string;
+    webhook_token: string;
+}
+/** An authorization waiting for an owner of the organization to confirm it. */
+export interface GitlabPending {
+    connection_id: string;
+    username: string;
+    authorized_at: string;
+    expires_at: string;
+    message: string;
+}
+/** A snapshot that follows a GitLab branch: each new commit builds it again (each build billed per second). */
+export interface GitlabTrack {
+    track_id: string;
+    repo: string;
+    branch: string;
+    alias: string;
+    head_sha?: string;
+    built_sha?: string;
+    snapshot_id?: string;
+    build_id?: string;
+    last_error?: string;
+    created_at: string;
+}
+/** `GET /integrations/gitlab`. `configured: false` on a deployment with no GitLab application. */
+export interface GitlabStatus {
+    configured: boolean;
+    gitlab_url?: string;
+    message?: string;
+    connections: GitlabConnection[];
+    pending: GitlabPending[];
+    tracks: GitlabTrack[];
+}
+/** `DELETE /integrations/gitlab/connections/:connection_id`. */
+export interface GitlabDisconnected {
+    connection_id: string;
+    username: string;
+    disconnected: boolean;
+    /** Our token was revoked on GitLab. */
+    revoked: boolean;
+    tracks_removed: number;
+    message: string;
+}
+/** One GitLab project a connection can read. */
+export interface GitlabRepo {
+    /** `group/sub/project`: what `snapshots.create({ repo: "gitlab:<path>" })` takes. */
+    path: string;
+    project_id: number;
+    private: boolean;
+    default_branch: string;
+    archived: boolean;
+    connection_id: string;
+    last_activity_at?: string;
+}
+/** `GET /integrations/gitlab/repos`: one page of one connection's projects. */
+export interface GitlabRepos {
+    repos: GitlabRepo[];
+    page: number;
+    per_page: number;
+    has_more: boolean;
+}
+/** `DELETE /integrations/gitlab/tracks/:track_id`. */
+export interface GitlabUntracked {
+    track_id: string;
+    repo: string;
+    branch: string;
+    alias: string;
+    untracked: boolean;
+}
+/** The prefix that names a connected GitLab project in `repo`. */
+export declare const GITLAB_REPO_PREFIX = "gitlab:";
+/**
+ * `gitlab:group/sub/project` as `group/sub/project`; `undefined` for anything that is not one (2 to
+ * 20 path segments of letters, digits, `.` `_` `-`). The same rule as the API's.
+ */
+export declare function parseGitlabRepo(repo: string | undefined): string | undefined;

package/dist/gitlab.js

@@ -0,0 +1,20 @@
+export const GITLAB_REPO_PREFIX = "gitlab:";
+const SEGMENT_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,99}$/;
+export function parseGitlabRepo(repo) {
+    if (typeof repo !== "string")
+        return undefined;
+    let r = repo.trim();
+    if (!r.startsWith(GITLAB_REPO_PREFIX))
+        return undefined;
+    r = r.slice(GITLAB_REPO_PREFIX.length);
+    if (r.endsWith(".git"))
+        r = r.slice(0, -4);
+    if (!r || r.length > 255)
+        return undefined;
+    const segs = r.split("/");
+    if (segs.length < 2 || segs.length > 20)
+        return undefined;
+    if (!segs.every((s) => SEGMENT_RE.test(s) && s !== ".." && !s.endsWith(".atom")))
+        return undefined;
+    return r;
+}

package/dist/handles.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `CommandHandle` — the handle `commands.run(cmd, { background: true })` returns.
+ *
+ * Output is read the way the API serves it: by byte range, polled. There is no second streaming
+ * transport for background execs, and a poll at 100–500 ms is below the resolution anyone reads a
+ * dev server's log at. `wait()` parks on the API's `wait_ms` long-poll between reads, so a
+ * process that ends is noticed within one round trip, not one poll interval.
+ *
+ * Stated once: `pid` is the API's `exec_id` (a string), not a process number —
+ * it is what `commands.kill(pid)` and `commands.connect(pid)` take.
+ */
+import { type CommandResult } from "./core.js";
+import { inspect, type InspectOptions } from "node:util";
+import type { BackgroundExecRecord, PromigenceClient } from "./client.js";
+export interface CommandHandleOpts {
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    /** Poll interval while only callbacks are attached (default 250 ms). */
+    pollMs?: number;
+    /**
+     * The bound the command was started with, in ms: `wait()` then throws `CommandTimeoutError`
+     * for a command killed there rather than a bare `CommandExitError(137)`.
+     */
+    timeoutMs?: number;
+}
+export declare class CommandHandle {
+    #private;
+    /** The `exec_id`. */
+    readonly pid: string;
+    readonly sandboxId: string;
+    /** Everything read so far, decoded as UTF-8. */
+    stdout: string;
+    stderr: string;
+    private readonly opts;
+    private readonly offset;
+    private readonly decoder;
+    private record;
+    private pumping;
+    private stopped;
+    private draining;
+    constructor(client: PromigenceClient, record: BackgroundExecRecord, opts?: CommandHandleOpts);
+    /** The last status the API reported. */
+    get state(): BackgroundExecRecord["state"];
+    get exitCode(): number | undefined;
+    get error(): string | undefined;
+    /** Started with `stdin: true`, so `sendStdin` / `closeStdin` reach the process. */
+    get stdinOpen(): boolean;
+    /**
+     * Write to the process's standard input. Text is sent as UTF-8; bytes are sent as they are.
+     *
+     * Only for a command started with `{ stdin: true }` — a child's stdin cannot be opened after
+     * it has been spawned, and this throws (`no_stdin`) rather than dropping the bytes.
+     */
+    sendStdin(data: string | Uint8Array): Promise<number>;
+    /**
+     * Close stdin (EOF). A process reading to end-of-input — `sort`, `cat`, a REPL — does nothing
+     * until this arrives, so it is the other half of `sendStdin` and not an optional tidy-up.
+     */
+    closeStdin(): Promise<void>;
+    /** Read every byte that is buffered now, on both streams. Serialised: one drain at a time. */
+    private drain;
+    private pump;
+    /**
+     * Wait for the process to end and return its result. A non-zero exit throws
+     * `CommandExitError` (it carries `stdout`/`stderr`/`exitCode`); a command killed at the
+     * `timeoutMs` it was started with throws `CommandTimeoutError`, a `CommandExitError` that says so.
+     */
+    wait(): Promise<CommandResult>;
+    /** SIGKILL. `true` if the process was running and the signal was delivered. */
+    kill(): Promise<boolean>;
+    /** Stop polling for output. The process keeps running; `commands.connect(pid)` re-attaches. */
+    disconnect(): Promise<void>;
+    /** What `JSON.stringify` shows: ids and status. The client (and its key) is never part of it. */
+    toJSON(): {
+        pid: string;
+        sandboxId: string;
+        state: BackgroundExecRecord["state"];
+        exitCode: number | undefined;
+    };
+    /** What `console.log` / `util.inspect` show: the same as `toJSON`. */
+    [inspect.custom](_depth: number, opts: InspectOptions): string;
+}

package/dist/handles.js

@@ -0,0 +1,135 @@
+import { CommandExitError, EnvFailedError } from "./core.js";
+import { inspect } from "node:util";
+import { CommandTimeoutError, exitTimedOut } from "./command-errors.js";
+const HANDLE_WAIT_MS = 30_000;
+const HANDLE_POLL_MS = 250;
+export class CommandHandle {
+    pid;
+    sandboxId;
+    stdout = "";
+    stderr = "";
+    #client;
+    opts;
+    offset = { stdout: 0, stderr: 0 };
+    decoder = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+    record;
+    pumping = false;
+    stopped = false;
+    draining;
+    constructor(client, record, opts = {}) {
+        this.#client = client;
+        this.record = record;
+        this.pid = record.exec_id;
+        this.sandboxId = record.sandbox_id;
+        this.opts = opts;
+        if (opts.onStdout || opts.onStderr)
+            void this.pump();
+    }
+    get state() { return this.record.state; }
+    get exitCode() {
+        const e = this.record.exit;
+        if (!e)
+            return undefined;
+        return e.exit_code ?? (e.signal ? 128 + e.signal : -1);
+    }
+    get error() { return this.record.error?.msg; }
+    get stdinOpen() { return Boolean(this.record.stdin_open); }
+    async sendStdin(data) {
+        const r = await this.#client.sandboxes.execs.stdin(this.sandboxId, this.pid, { data });
+        return r.written;
+    }
+    async closeStdin() {
+        await this.#client.sandboxes.execs.stdin(this.sandboxId, this.pid, { eof: true });
+    }
+    drain() {
+        const run = async () => {
+            for (const s of ["stdout", "stderr"]) {
+                for (;;) {
+                    const r = await this.#client.sandboxes.execs.read(this.sandboxId, this.pid, s, { offset: this.offset[s] });
+                    this.record = r.record;
+                    if (r.data.length === 0)
+                        break;
+                    this.offset[s] += r.data.length;
+                    const text = this.decoder[s].decode(r.data, { stream: true });
+                    this[s] += text;
+                    if (text)
+                        (s === "stdout" ? this.opts.onStdout : this.opts.onStderr)?.(text);
+                    if (r.eof)
+                        break;
+                }
+            }
+        };
+        const next = (this.draining ?? Promise.resolve()).then(run, run);
+        this.draining = next.catch(() => { });
+        return next;
+    }
+    async pump() {
+        if (this.pumping)
+            return;
+        this.pumping = true;
+        try {
+            while (!this.stopped) {
+                await this.drain();
+                if (this.record.state !== "running") {
+                    await this.drain();
+                    break;
+                }
+                await new Promise((r) => { setTimeout(r, this.opts.pollMs ?? 250); });
+            }
+        }
+        catch {
+        }
+        finally {
+            this.pumping = false;
+        }
+    }
+    async wait() {
+        for (;;) {
+            await this.drain();
+            if (this.record.state !== "running")
+                break;
+            this.record = await this.#client.sandboxes.execs.get(this.sandboxId, this.pid, { waitMs: HANDLE_WAIT_MS });
+            if (this.record.state === "running" && !((this.record.waited_ms ?? 0) >= HANDLE_WAIT_MS)) {
+                await new Promise((r) => { setTimeout(r, HANDLE_POLL_MS); });
+            }
+        }
+        await this.drain();
+        for (const s of ["stdout", "stderr"]) {
+            const tail = this.decoder[s].decode();
+            if (tail) {
+                this[s] += tail;
+                (s === "stdout" ? this.opts.onStdout : this.opts.onStderr)?.(tail);
+            }
+        }
+        if (this.record.state === "failed") {
+            const e = this.record.error;
+            throw new EnvFailedError(e?.code ?? "sandbox_unresponsive", `background exec ${this.pid} failed: ${e?.msg ?? "no exit record"}`, "Not your command's failure. Check the sandbox is still ready (`promigence run report <run_id>`) and start it again.");
+        }
+        const result = {
+            exitCode: this.exitCode ?? -1,
+            stdout: this.stdout,
+            stderr: this.stderr,
+            truncated: Boolean(this.record.truncated),
+            execId: this.pid,
+        };
+        if (result.exitCode !== 0) {
+            if (exitTimedOut(this.record.exit, this.opts.timeoutMs))
+                throw new CommandTimeoutError(result, this.opts.timeoutMs);
+            throw new CommandExitError(result);
+        }
+        return result;
+    }
+    async kill() {
+        const r = await this.#client.sandboxes.execs.signal(this.sandboxId, this.pid, "SIGKILL");
+        return r.delivered;
+    }
+    async disconnect() {
+        this.stopped = true;
+    }
+    toJSON() {
+        return { pid: this.pid, sandboxId: this.sandboxId, state: this.state, exitCode: this.exitCode };
+    }
+    [inspect.custom](_depth, opts) {
+        return `CommandHandle ${inspect(this.toJSON(), opts)}`;
+    }
+}

package/dist/hint.d.ts

@@ -0,0 +1 @@
+export declare function hintArg(value: string | number): string;

package/dist/hint.js

@@ -0,0 +1,7 @@
+const PLAIN = /^[A-Za-z0-9_./:@,][A-Za-z0-9_./:@,=-]*$/;
+export function hintArg(value) {
+    const s = String(value);
+    if (PLAIN.test(s))
+        return s;
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/dist/http2.d.ts

@@ -0,0 +1,206 @@
+/**
+ * HTTP/2 transport for `PromigenceClient.request()` on Node.js.
+ *
+ * Why: a process that opens many sandboxes at once sends many API requests at once. Over the
+ * global `fetch` each concurrent request gets its own HTTP/1.1 connection, so a burst of 100 pays
+ * for 100 TCP + TLS handshakes before the first byte of work. One HTTP/2 connection carries all
+ * of them as streams: one handshake, then every request goes out immediately.
+ *
+ * When it is used — all of these, otherwise the request goes to `fetch` exactly as before:
+ *   - the runtime is Node.js (not Bun, Deno, a browser or an edge worker);
+ *   - the caller did not inject `opts.fetch`, did not pass `http2: false`, did not set
+ *     `PROMIGENCE_HTTP2=0`, did not replace `globalThis.fetch` or install a custom undici
+ *     dispatcher (a proxy, a mock), and has no proxy variable in the environment;
+ *   - the URL is `https:` and the server picks `h2` during the TLS handshake (ALPN);
+ *   - the request is a control call: JSON or no body, JSON answer. File transfers and the
+ *     streamed exec stay on `fetch`.
+ *
+ * Connections. One pool per origin, shared by every client in the process. Connecting is lazy
+ * and shared: 100 first requests wait on one connect, not 100. The first connect to an origin
+ * opens one session per address the API's name resolves to (up to FIRST_SESSIONS, of the address
+ * family Node tries first), all started together before any request is sent, and the requests
+ * waiting for it are spread over them (`Opening`); a name with one address gets one session, as
+ * before. More (up to MAX_SESSIONS) open only when every open session is at the server's
+ * SETTINGS_MAX_CONCURRENT_STREAMS. `PromigenceClient.preconnect()` starts the first connect
+ * before the first request instead, sending nothing; so does the SDK itself once it has loaded in
+ * a process with an API key in its environment (`connectAtLoad`; `PROMIGENCE_PRECONNECT=0` turns
+ * that off). A session is `unref()`ed whenever it has no request in flight, so a script can exit,
+ * and closed after IDLE_CLOSE_MS without one.
+ *
+ * Cost per request. At 100 requests in flight the client's own work is serial and every request
+ * queues behind the others', so the hot path allocates as little as it can: the answer is an `H2Response` (status, the raw header map, the bytes — a real `Headers`
+ * only if someone asks for it), the bound is one timer instead of an `AbortSignal` and its
+ * listeners, and a request that finds a ready session takes it without a promise in between.
+ *
+ * Failure rules. The worst case must be "behaves like fetch", never "a request is lost or runs
+ * twice":
+ *   - the server does not speak h2 (ALPN picked http/1.1 or nothing), refuses HTTP/2 for the
+ *     request (HTTP_1_1_REQUIRED, 421), or the TLS handshake itself fails: nothing was sent, so
+ *     this request goes to `fetch`, and so does every later one to that origin;
+ *   - the TCP connect fails or times out: this request goes to `fetch`; h2 is retried for the
+ *     origin after RETRY_AFTER_MS, and given up after three such failures in a row;
+ *   - the server provably did not process the request (REFUSED_STREAM, a stream above a GOAWAY's
+ *     last stream id, a session that closed before the request was handed to it): it is sent
+ *     again on a fresh session, any method;
+ *   - the connection died after the request may have reached the server and before any response
+ *     arrived: sent again ONLY when replaying is harmless (GET, DELETE, or a request with an
+ *     `Idempotency-Key`), once; otherwise the error surfaces exactly as a `fetch` failure does;
+ *   - a response has started: never sent again.
+ *   - sessions that keep dying with requests on them, or streams that keep failing on a live
+ *     session, turn h2 off for the origin for the rest of the process.
+ */
+import type { LookupAddress } from "node:dns";
+import * as http2 from "node:http2";
+import { type TraceStamp } from "./trace.js";
+type FetchLike = typeof globalThis.fetch;
+/** What `request()` hands the transport. */
+export interface Http2Init {
+    method: string;
+    headers: Record<string, string>;
+    /** JSON text. Byte bodies never come here. */
+    body?: string;
+    /**
+     * The request's bound, in ms from the call. On h2 it is the transport's own timer: a stream
+     * waits exactly this long, never less, and there is no socket-level timeout underneath. On
+     * fallback `fetch` gets `AbortSignal.timeout` of whatever is left of it.
+     */
+    timeoutMs: number;
+    /** The caller's own signal, when it gave one. */
+    signal?: AbortSignal;
+    /** Read by `fetch` on fallback only. */
+    dispatcher?: object;
+    /** Phase stamps when `PROMIGENCE_SDK_TRACE=1`. */
+    trace?: TraceStamp;
+}
+/**
+ * Decide, once per client, whether HTTP/2 may be tried at all. `opt` is `PromigenceClientOpts.http2`;
+ * the caller has already ruled out an injected `fetch`.
+ */
+export declare function http2Allowed(opt: boolean | undefined, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * What an h2 exchange answers with: the subset of `Response` that `request()` reads, without a
+ * `Response`, a `Headers` or a `ReadableStream` behind it. `headers` builds the real `Headers`
+ * on first use, so a caller's `onHeaders` sees exactly what it always saw.
+ */
+export declare class H2Response {
+    readonly status: number;
+    /** node:http2's header map: lower-case names, `set-cookie` as an array. */
+    private readonly raw;
+    /** Already content-decoded; `null` for a HEAD / 204 / 205 / 304 answer, as `fetch` has it. */
+    private readonly bytes;
+    readonly ok: boolean;
+    private built;
+    constructor(status: number, 
+    /** node:http2's header map: lower-case names, `set-cookie` as an array. */
+    raw: http2.IncomingHttpHeaders, 
+    /** Already content-decoded; `null` for a HEAD / 204 / 205 / 304 answer, as `fetch` has it. */
+    bytes: Buffer | null);
+    /**
+     * True when this answers a resend of a request that may already have been processed (a
+     * replay-safe request whose connection died after it was sent): a DELETE answered 404 here was
+     * most likely done by the attempt whose answer was lost.
+     */
+    replayed: boolean;
+    /** `Headers.get`: the value, joined with ", " when the header was sent more than once. */
+    header(name: string): string | null;
+    /** `text()` without the promise around it: the body has already arrived. */
+    textNow(): string;
+    get headers(): Headers;
+    /** The body as text, decoded the way `Response.text()` decodes it (UTF-8, BOM dropped). */
+    text(): Promise<string>;
+}
+/** What a request needs of its URL: the origin of its pool, and its `:authority` and `:path`. */
+interface Target {
+    origin: string;
+    host: string;
+    path: string;
+}
+/** The scheme and authority of a URL that parsed as `https:`, and what the URL parser made of them. */
+interface Prefix {
+    /** `https://` and the authority, exactly as written: up to the `/` that starts the path. */
+    text: string;
+    origin: string;
+    host: string;
+}
+export declare class Http2Transport {
+    private readonly fallback;
+    /** `fallback` is the `fetch` this client would have used without HTTP/2. */
+    constructor(fallback: FetchLike);
+    /**
+     * Start the connection `url`'s requests would use, without sending anything. The same checks as
+     * a request: an `https:` URL, no custom dispatcher, HTTP/2 not turned off for the origin. Never
+     * throws; the first request connects as before if this could not.
+     */
+    preconnect(url: string): void;
+    /** The request, sent with `fetch` instead: bounded by what is left of its budget. */
+    private viaFetch;
+    /**
+     * Send one control request. Resolves or rejects the way `fallback(url, init)` would: an answer
+     * (`H2Response` over h2, `Response` on fallback), the timeout's or the signal's reason on abort,
+     * `TypeError("fetch failed")` on a network failure. `replayable`: sending it twice is harmless
+     * (see the module comment).
+     */
+    fetch(url: string, init: Http2Init, replayable: boolean): Promise<Response | H2Response>;
+}
+export declare function warmTransport(): void;
+/** Test and diagnostics view of the process-wide pools. Not part of the public API. */
+export declare const __http2Internals: {
+    pools(): Array<{
+        origin: string;
+        sessions: number;
+        opened: number;
+        warmed: number;
+        off: boolean;
+        suspended: boolean;
+        offReason: string;
+        active: number;
+        split: number[];
+        connecting: boolean;
+        parked: boolean;
+    }>;
+    /** What a request to `url` sends as `:authority` and `:path`, read with `known` as a transport does. */
+    targetOf(url: string, known?: {
+        text: string;
+        origin: string;
+        host: string;
+    }): {
+        target: Target | undefined;
+        prefix: Prefix | undefined;
+    };
+    /** The schemes and authorities requests have parsed, newest first. */
+    prefixes(): string[];
+    /** Close every session and forget every origin's state. */
+    reset(): void;
+    /** A pool for `origin` of its own, outside the process-wide map, for unit tests of its logic. */
+    pool(origin: string): unknown;
+    /** The transport thread, for tests and diagnostics. */
+    thread(): {
+        state: string;
+        sessions: number;
+        limit: number;
+        answered: number;
+        everReady: boolean;
+        closedReason: string;
+    } | undefined;
+    /** The transport thread's number of connections and spacing between new requests on one, for an environment (`threadKnobs`). */
+    threadKnobs(env: NodeJS.ProcessEnv): {
+        sessions: number;
+        gapUs: number;
+        pace: string;
+    };
+    /** Tests: make the transport thread fail as a crash would. */
+    crashThreadForTest(): void;
+    /** The early lookup, for tests: start one with a platform, DNS servers and hosts file of the test's own. */
+    early: {
+        start(host: string): boolean;
+        /** Its state and answer, read without waiting. */
+        state(host: string): {
+            state: string;
+            answer?: LookupAddress[];
+            fresh: boolean;
+        } | undefined;
+        hosts(): string[];
+        reset(): void;
+    };
+};
+export {};