@prized/sdk 0.0.0-stage → 0.1.0

package/dist/cjs/commands.d.ts

@@ -0,0 +1,168 @@
+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`
+ * (exec's pollOutageMs), from when the first poll's retries ran out: 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 end;
+    private last;
+    private tries;
+    private readonly room;
+    constructor(windowMs: number);
+    /** 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. */
+    timeoutMs?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    signal?: AbortSignal;
+}
+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.
+     */
+    wait(options?: WaitOptions): Promise<ExecResult>;
+    /**
+     * @internal wait() without the timeout check: exec cleans up before it
+     * throws. `outageMs` (exec's pollOutageMs; a wait with no limit only):
+     * how long polls may fail before the wait gives up (Outage).
+     */
+    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>;