@prized/sdk 0.0.0-stage → 0.1.1

package/dist/cjs/toolbox.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_FILE_BYTES = exports.MAX_OUTPUT_BYTES = void 0;
+exports.rawExec = rawExec;
+exports.helperExec = helperExec;
+// The exec/files edge for one sandbox: POST {base}/process/execute,
+// POST {base}/files/upload?path=, GET {base}/files/download?path=.
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const outcome_js_1 = require("./outcome.js");
+/** Each stream of one call keeps at most this many bytes. */
+exports.MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** One upload or download moves at most this many bytes. */
+exports.MAX_FILE_BYTES = 100 * 1024 * 1024;
+/** Slack on top of a command's own timeout before the SDK stops waiting for the answer. */
+const EXEC_ANSWER_SLACK_MS = 30_000;
+/**
+ * How many of the stream's bytes the sandbox kept, from the text its answer
+ * carried. The sandbox keeps exactly the first MAX_OUTPUT_BYTES; each byte
+ * of that which was not valid UTF-8 arrives as one U+FFFD, so U+FFFD counts
+ * as one byte here, not the three it encodes to (as the Python SDK counts):
+ * 2 MiB of binary output is not a full stream.
+ */
+function keptBytes(text) {
+    // Fast path: fewer than MAX/3 UTF-16 units can never encode to MAX bytes.
+    if (text.length * 3 < exports.MAX_OUTPUT_BYTES)
+        return text.length;
+    let replaced = 0;
+    for (let at = text.indexOf('\uFFFD'); at !== -1; at = text.indexOf('\uFFFD', at + 1))
+        replaced += 1;
+    return new TextEncoder().encode(text).length - 2 * replaced;
+}
+/** One command over the edge, answered when it finishes. */
+async function rawExec(toolbox, req, options) {
+    if (!(req.timeoutMs > 0))
+        throw new errors_js_1.PrizedError('invalid_argument', 'A command sent on one call needs a timeout > 0 ms');
+    const effect = options.effect ?? (options.retry === 'exec' ? (0, outcome_js_1.commandEffect)() : undefined);
+    const body = { command: req.command };
+    if (req.cwd !== undefined)
+        body.cwd = req.cwd;
+    if (req.env !== undefined && Object.keys(req.env).length > 0)
+        body.env = req.env;
+    body.timeout = req.timeoutMs / 1000;
+    const result = await (0, http_js_1.request)(toolbox.config, {
+        method: 'POST',
+        url: `${toolbox.base()}/process/execute`,
+        json: body,
+        retry: options.retry,
+        timeoutMs: req.timeoutMs + EXEC_ANSWER_SLACK_MS,
+        signal: options.signal,
+        deadline: options.deadline,
+        sandboxId: toolbox.sandboxId,
+        ...(effect === undefined ? {} : { effect }),
+    });
+    const doc = result.json;
+    if (doc === null || typeof doc !== 'object' || typeof doc.exitCode !== 'number') {
+        const unread = new errors_js_1.PrizedError('bad_response', 'The exec answer carried no exit code.', {
+            status: result.status,
+            sandboxId: toolbox.sandboxId,
+        });
+        // A 2xx: the command ran, whatever its answer lacks.
+        throw effect === undefined ? unread : (0, outcome_js_1.withOutcome)(unread, effect, 'did');
+    }
+    const stdout = typeof doc.stdout === 'string' ? doc.stdout : '';
+    const stderr = typeof doc.stderr === 'string' ? doc.stderr : '';
+    const truncated = keptBytes(stdout) >= exports.MAX_OUTPUT_BYTES || keptBytes(stderr) >= exports.MAX_OUTPUT_BYTES;
+    return {
+        stdout,
+        stderr,
+        exitCode: doc.exitCode,
+        durationMs: typeof doc.durationMs === 'number' ? doc.durationMs : 0,
+        timedOut: doc.timedOut === true,
+        truncated,
+        ...(truncated ? { truncatedReason: 'output_limit' } : {}),
+    };
+}
+/** A helper command the SDK sends itself; a non-zero exit is the caller's to judge. */
+function helperExec(toolbox, command, options = {}) {
+    const retry = options.retry ?? 'safe';
+    return rawExec(toolbox, { command, timeoutMs: options.timeoutMs ?? 60_000 }, {
+        retry,
+        signal: options.signal,
+        deadline: options.deadline,
+        // Not the caller's command: an `exec` helper that names no effect (a
+        // kill) gets words that claim nothing about what it does.
+        effect: options.effect ?? (retry === 'exec' ? (0, outcome_js_1.helperEffect)() : undefined),
+    });
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,111 @@
+/** A sandbox's lifecycle state. */
+export type SandboxState = 'starting' | 'running' | 'pausing' | 'paused' | 'resizing' | 'deleting' | 'deleted' | 'error';
+/** A sandbox shape. Memory travels in MiB; `memoryGb` is the same number in GiB. */
+export interface Resources {
+    vcpu: number;
+    memoryMb: number;
+    memoryGb: number;
+    diskGb: number;
+}
+/** What a create asks for. Every field is optional: the template's default fills the gaps. */
+export interface ResourcesInput {
+    vcpu?: number;
+    /** Memory in GiB (`memoryGb: 4` is 4096 MiB). Give this or `memoryMb`, not both. */
+    memoryGb?: number;
+    /** Memory in MiB. */
+    memoryMb?: number;
+    diskGb?: number;
+}
+/** What the API says about a sandbox. */
+export interface SandboxInfo {
+    id: string;
+    state: SandboxState;
+    template: string | null;
+    resources: Resources;
+    labels: Record<string, string>;
+    /** Idle minutes before a running sandbox pauses itself (null: never). */
+    autoPauseMin: number | null;
+    /** Minutes after pausing before the sandbox deletes itself (null: never). */
+    autoDeleteMin: number | null;
+    /**
+     * When the sandbox's run time ends and it is deleted. Null while a paused
+     * sandbox's clock is stopped: a resume on a paid plan starts a fresh one;
+     * on the free tier it carries on the running time left.
+     */
+    expiresAt: Date | null;
+    createdAt: Date | null;
+    lastActiveAt: Date | null;
+    /** Why the sandbox is in `error`, when it is. */
+    errorReason: string | null;
+    /** The base URL its exec and files calls go to. */
+    toolboxBase: string | null;
+    /** The document exactly as the API sent it. */
+    raw: Record<string, unknown>;
+}
+/** One entry of `Sandbox.templates()`. */
+export interface Template {
+    id: string;
+    defaults: Resources;
+    min: Resources;
+    max: Resources;
+    durability: string;
+    /** The run time a sandbox gets when its create gives no `maxRuntimeMin` (for your workspace's plan). */
+    defaultMaxRuntimeMin: number;
+}
+/** What one command produced. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    /** The command's exit code; -1 when it timed out or ended without reporting one. */
+    exitCode: number;
+    /** How long the command ran, in ms. */
+    durationMs: number;
+    /**
+     * True when the command hit its timeout and was killed (`exitCode` is then
+     * -1). `exec()` and `wait()` throw CommandTimeoutError with such a result
+     * rather than return it.
+     */
+    timedOut: boolean;
+    /**
+     * True when stdout or stderr reached the 4 MiB per-stream cap of a single
+     * call: the command kept running, the rest of that stream was dropped.
+     * Pass `fullOutput: true` for commands that may print more (it keeps up
+     * to 100 MiB of each stream, and sets this past that). `truncatedReason`
+     * says why.
+     */
+    truncated: boolean;
+    /**
+     * Why `truncated` is true; absent when it is false. `output_limit`: a
+     * stream reached its cap (4 MiB in one call, 100 MiB with `fullOutput`).
+     * `write_failed` (`fullOutput` only): the sandbox could not save a stream
+     * as the command printed it, most often because its disk is full, so that
+     * stream stops where the write failed, however short; free some space and
+     * run it again.
+     */
+    truncatedReason?: TruncatedReason;
+}
+/** Why a command's output was cut: ExecResult.truncatedReason. */
+export type TruncatedReason = 'output_limit' | 'write_failed';
+/** One directory entry, as `sandbox.files.list()` returns it. */
+export interface FileInfo {
+    name: string;
+    path: string;
+    /** Size in bytes. */
+    size: number;
+    isDir: boolean;
+    isSymlink: boolean;
+    /** Permissions as `ls -l` prints them, e.g. `-rw-r--r--`. */
+    mode: string;
+    modified: Date | null;
+}
+/** What a write or an upload reports. */
+export interface WriteInfo {
+    path: string;
+    size: number;
+}
+export declare function parseTime(value: unknown): Date | null;
+export declare function parseResources(value: unknown): Resources;
+export declare function parseSandbox(doc: unknown): SandboxInfo;
+export declare function parseTemplate(entry: unknown): Template | null;
+/** The wire shape of a create's `resources`: memory in MiB, integers only. */
+export declare function resourcesToWire(input: ResourcesInput): Record<string, number>;

package/dist/cjs/types.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTime = parseTime;
+exports.parseResources = parseResources;
+exports.parseSandbox = parseSandbox;
+exports.parseTemplate = parseTemplate;
+exports.resourcesToWire = resourcesToWire;
+// Public types and the parsers that turn API documents into them.
+const errors_js_1 = require("./errors.js");
+function int(value, fallback = 0) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : fallback;
+}
+function optInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : null;
+}
+function optString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function parseTime(value) {
+    if (typeof value !== 'string' || value === '')
+        return null;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : new Date(at);
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function parseResources(value) {
+    const r = record(value);
+    const memoryMb = int(r.memoryMb);
+    return { vcpu: int(r.vcpu), memoryMb, memoryGb: memoryMb / 1024, diskGb: int(r.diskGb) };
+}
+function parseSandbox(doc) {
+    const d = record(doc);
+    if (typeof d.id !== 'string' || d.id === '') {
+        throw new errors_js_1.PrizedError('bad_response', 'The API answered without a sandbox document.');
+    }
+    const labels = {};
+    for (const [key, value] of Object.entries(record(d.labels))) {
+        if (typeof value === 'string')
+            labels[key] = value;
+    }
+    return {
+        id: d.id,
+        state: (typeof d.state === 'string' ? d.state : 'error'),
+        template: optString(d.template),
+        resources: parseResources(d.resources),
+        labels,
+        autoPauseMin: optInt(d.autoPauseMin),
+        autoDeleteMin: optInt(d.autoDeleteMin),
+        expiresAt: parseTime(d.expiresAt),
+        createdAt: parseTime(d.createdAt),
+        lastActiveAt: parseTime(d.lastActiveAt),
+        errorReason: optString(d.errorReason),
+        toolboxBase: optString(d.toolboxBase),
+        raw: d,
+    };
+}
+function parseTemplate(entry) {
+    const e = record(entry);
+    if (typeof e.id !== 'string' || e.id === '')
+        return null;
+    const resources = record(e.resources);
+    return {
+        id: e.id,
+        defaults: parseResources(resources.defaults),
+        min: parseResources(resources.min),
+        max: parseResources(resources.max),
+        durability: optString(e.durability) ?? 'ephemeral',
+        defaultMaxRuntimeMin: int(e.defaultMaxRuntimeMin),
+    };
+}
+/** The wire shape of a create's `resources`: memory in MiB, integers only. */
+function resourcesToWire(input) {
+    const out = {};
+    const whole = (name, value) => {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new errors_js_1.PrizedError('invalid_argument', `resources.${name} must be a positive whole number (got ${value})`);
+        }
+        return value;
+    };
+    if (input.vcpu !== undefined)
+        out.vcpu = whole('vcpu', input.vcpu);
+    if (input.memoryGb !== undefined && input.memoryMb !== undefined) {
+        if (Math.round(input.memoryGb * 1024) !== input.memoryMb) {
+            throw new errors_js_1.PrizedError('invalid_argument', 'Give resources.memoryGb or resources.memoryMb, not both');
+        }
+    }
+    if (input.memoryMb !== undefined) {
+        out.memoryMb = whole('memoryMb', input.memoryMb);
+    }
+    else if (input.memoryGb !== undefined) {
+        const mb = input.memoryGb * 1024;
+        if (!Number.isInteger(mb) || mb <= 0) {
+            throw new errors_js_1.PrizedError('invalid_argument', `resources.memoryGb must be a whole number of MiB (got ${input.memoryGb} GiB)`);
+        }
+        out.memoryMb = mb;
+    }
+    if (input.diskGb !== undefined)
+        out.diskGb = whole('diskGb', input.diskGb);
+    return out;
+}

package/dist/cjs/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version; test/version.test.ts holds it equal to package.json. */
+export declare const VERSION = "0.1.1";

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** This package's version; test/version.test.ts holds it equal to package.json. */
+exports.VERSION = '0.1.1';

package/dist/esm/commands.d.ts

@@ -0,0 +1,199 @@
+import { PrizedError } from './errors.js';
+import { type Toolbox } from './toolbox.js';
+import type { ExecResult } from './types.js';
+/** The timeout a command gets when the call names none. */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 60000;
+/**
+ * The longest command one blocking call carries. Longer timeouts (and
+ * `timeoutMs: 0`) run detached and are polled: Node's fetch gives up on an
+ * answer after 300 s, and load balancers drop idle connections not long after.
+ */
+export declare const MAX_BLOCKING_EXEC_MS = 240000;
+/**
+ * Whether a failed poll is one an outage window rides out (sdk/retry-spec.json
+ * `pollOutage`): no answer, an answer that could not be read, a rate limit or
+ * any 5xx. Any other (a refused key, any other refusal, an answer that
+ * settles the run, an abort) ends the wait at once. The Python SDK's
+ * rides_out.
+ */
+export declare function ridesOut(error: PrizedError): boolean;
+/**
+ * The failed polls of a wait that rides out an outage of up to `windowMs`
+ * (pollOutageMs), from when the first poll's retries ran out, and, while the
+ * command runs, never past the wait's own deadline (`waitDeadline`, epoch
+ * ms; null for none): polled again with backoff, each poll and its retries
+ * ending before the last look, which goes out LAST_LOOK_MAX_MS before the
+ * window's end (half the window, for one shorter than twice that) with room
+ * for its own retries. So an outage that ends inside the window is always
+ * seen to end. The Python SDK's Outage.
+ */
+export declare class Outage {
+    private readonly windowMs;
+    private readonly waitDeadline;
+    private end;
+    private last;
+    private tries;
+    private room;
+    private finished;
+    constructor(windowMs: number, waitDeadline?: number | null);
+    /** The command has ended: draining its output, and an outage meanwhile, are not held to the deadline. */
+    finish(): void;
+    /**
+     * Whether a wait's failed poll (`error`, at `now`; `cut`: its bound cut it
+     * short) means the wait's own time ran out: its deadline cut the poll
+     * short while the command ran, with no outage being ridden out, so the
+     * command was still running when last seen. With no window, any timeout
+     * while it runs says so, as it always has. Never once the command has
+     * ended. The Python SDK's Outage.ran_out.
+     */
+    ranOut(error: PrizedError, now: number, cut: boolean): boolean;
+    /** The bound on a poll sent `now`: undefined unless polls are failing; else the last look's start, or the window's end for the last look. */
+    deadline(now: number): number | undefined;
+    /** A poll was answered: the outage, if any, is over. */
+    answered(): void;
+    /**
+     * A poll sent at `sentAt` failed `now` with `error` (`cut`: its bound cut
+     * it short). Returns the pause before polling again, or null to give up,
+     * with the failure to give up with: the last one a poll met on its own,
+     * never the cut.
+     */
+    failed(error: PrizedError, sentAt: number, now: number, cut: boolean, backoff: (tries: number) => number): {
+        pause: number | null;
+        failure: PrizedError;
+    };
+}
+export interface ExecOptions {
+    /** Working directory. Relative paths start in /home/prized/work (the default). */
+    cwd?: string;
+    /**
+     * Environment variables for this command, on top of the sandbox's own.
+     * Background and streamed commands also get PYTHONUNBUFFERED=1 unless
+     * this or the sandbox sets it (`''` keeps Python's buffering).
+     */
+    env?: Record<string, string>;
+    /**
+     * Kill the command after this many ms. Default 60 000. `0` means no limit.
+     * For a background command the default is no limit.
+     */
+    timeoutMs?: number;
+    /** Called with stdout as it arrives (the command then runs detached and is polled). */
+    onStdout?: (chunk: string) => void;
+    /** Called with stderr as it arrives. */
+    onStderr?: (chunk: string) => void;
+    /** Start the command and return a handle at once instead of waiting for it. */
+    background?: boolean;
+    /**
+     * Keep the whole output, not just the first 4 MiB of each stream: up to
+     * 100 MiB each (`truncated` past that). Still one request when the output
+     * is small; past 4 MiB the SDK reads it back from files the command wrote
+     * in the sandbox. Use it for builds, test suites and anything else whose
+     * output you need whole. Background, streamed and long commands read
+     * their whole output already.
+     */
+    fullOutput?: boolean;
+    /**
+     * Abort the call. The command stops with it, as when a blocking call is
+     * cut off: the call rejects once the SDK has tried to stop it (a round
+     * trip or two; it gives up after about 20 s). With `background: true`
+     * this covers the start only; once exec has returned the handle, its
+     * kill() stops the command.
+     */
+    signal?: AbortSignal;
+    /**
+     * For a streamed or long command: how long the SDK keeps polling while
+     * its polls fail (no answer, a 5xx, a rate limit), in ms, before it gives
+     * up and stops the command. Default: the client's `pollOutageMs`
+     * (120 000). A refused key, or an answer that settles the run (the
+     * sandbox deleted or not running, the run gone), stops it at once.
+     */
+    pollOutageMs?: number;
+}
+export interface WaitOptions {
+    /**
+     * Stop waiting after this many ms (the command keeps running). Default: no
+     * limit. Once the command has ended, reading the rest of its output is not
+     * held to it.
+     */
+    timeoutMs?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    signal?: AbortSignal;
+    /**
+     * How long the wait keeps polling while its polls fail (no answer, a 5xx,
+     * a rate limit), in ms, before it gives up and throws what the polls met.
+     * While the command runs, never past `timeoutMs`. Default: the client's
+     * `pollOutageMs` (120 000).
+     * `0` gives up once one poll's retries run out. A refused key, or an
+     * answer that settles the run (the sandbox deleted or not running, the
+     * run gone), ends the wait at once. Giving up stops nothing: the command
+     * keeps running, and wait() can be called again.
+     */
+    pollOutageMs?: number;
+}
+export interface CommandStatus {
+    running: boolean;
+    /** The exit code once it has one; -1 if its time limit stopped it or it ended without reporting one. */
+    exitCode: number | null;
+}
+/**
+ * A command running in the background (`sandbox.exec(cmd, { background: true })`).
+ * It runs in its own session: it keeps running after this process exits, and
+ * while it runs, kill() reaches every process it started in its process group.
+ */
+export declare class CommandHandle {
+    /** The run's id (`run_…`). */
+    readonly id: string;
+    /** The process group id of the command inside the sandbox. */
+    readonly pid: number;
+    readonly sandboxId: string;
+    private readonly toolbox;
+    private readonly startedAt;
+    /** @internal The time limit exec gave the command, in ms; null for none. */
+    timeoutMs: number | null;
+    /** @internal */
+    constructor(toolbox: Toolbox, id: string, pid: number, startedAt: number);
+    private poll;
+    /** Whether the command is still running, and its exit code once it is not. */
+    status(): Promise<CommandStatus>;
+    /** Everything the command has printed so far. */
+    logs(): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /**
+     * Wait for the command to finish and return everything it printed.
+     * `onStdout`/`onStderr` receive the output as it arrives, from the start.
+     * A `timeoutMs` here bounds the wait only; the command keeps running. If
+     * the command ran past its own timeout (the one given to exec), it was
+     * killed and this throws CommandTimeoutError with what it printed. While
+     * polls fail (a dropped connection, a 5xx), it keeps polling for up to
+     * `pollOutageMs` (the client's, 120 000 by default) before it throws.
+     */
+    wait(options?: WaitOptions): Promise<ExecResult>;
+    /**
+     * @internal wait() without the timeout check: exec cleans up before it
+     * throws. `outageMs` (pollOutageMs): how long polls may fail before the
+     * wait gives up (Outage), never past the wait's own deadline.
+     */
+    waitRaw(options: WaitOptions, outageMs: number): Promise<ExecResult>;
+    private waitTimeout;
+    private result;
+    /**
+     * Send a signal (default SIGTERM) to the command and everything it
+     * started in its process group. Resolves true if it was sent, false if
+     * the run had already ended. Processes that left the group (`setsid`, a
+     * daemon) are not reached, nor anything after the run itself has ended.
+     */
+    kill(signal?: string): Promise<boolean>;
+    /**
+     * Remove the command's files (its output under `~/.prized/runs/<id>/`)
+     * from the sandbox once it has ended: call it after wait() resolves or
+     * throws CommandTimeoutError (after a kill(), await wait() first). On a
+     * command still running it does nothing, so status(), wait() and kill()
+     * keep working. Once its files are gone, status(), logs(), wait() and
+     * kill() reject with `not_found`. Best effort: it never rejects.
+     */
+    cleanup(): Promise<void>;
+}
+/** sandbox.exec's body. */
+export declare function execCommand(toolbox: Toolbox, command: string | readonly string[], options?: ExecOptions): Promise<ExecResult | CommandHandle>;