@prized/sdk 0.0.0-stage → 0.1.1

package/dist/esm/outcome.d.ts

@@ -0,0 +1,76 @@
+import { PrizedError } from './errors.js';
+/**
+ * What one request does in the sandbox, in the words its errors use: `maybe`
+ * when no clear answer came back (a lost connection, a timeout, a 5xx other
+ * than the ones that prove it never arrived), `did` when a 2xx came back that
+ * could not be read (the sandbox acted on it), and `check`, how to find out
+ * which.
+ */
+export interface Effect {
+    readonly maybe: string;
+    readonly did: string;
+    readonly check: string;
+    /** What the sandbox does once the connection closes, said when the caller aborts after it may have been sent (withAbort). */
+    readonly onClose?: string;
+}
+export declare function commandEffect(): Effect;
+export declare function writeEffect(path: string): Effect;
+export declare function removeEffect(path: string): Effect;
+/** For CommandHandle.kill (`signal` without its SIG prefix). */
+export declare function signalEffect(runId: string, signal: string): Effect;
+/** For a background start (or a streamed or long exec, which runs as one): said before what the SDK did about it (startAbandoned). A 2xx proves only that the start ran. */
+export declare function startEffect(): Effect;
+/** For an SDK helper sent in `exec` mode that names no effect of its own. */
+export declare function helperEffect(): Effect;
+/**
+ * How a request that is not sent again ended: `never` reached the sandbox,
+ * `maybe` acted (no clear answer), `did` act (a 2xx that could not be read),
+ * or null for a refusal whose own words say what happened.
+ */
+export type Outcome = 'never' | 'maybe' | 'did' | null;
+/** Whether withOutcome said the sandbox may have acted on the request. */
+export declare function mayHaveActed(error: unknown): error is PrizedError;
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
+export declare function restate(error: PrizedError, message: string, init?: {
+    status?: number;
+    code?: string;
+    sandboxId?: string;
+    exitCode?: number;
+    cause?: unknown;
+}): PrizedError;
+/** `error` (same code, status and body), its message saying what it means for `effect`. */
+export declare function withOutcome(error: PrizedError, effect: Effect, outcome: Outcome): PrizedError;
+/**
+ * `error` (code `aborted`) for a request with an `effect`: `never` when
+ * nothing that may have reached the sandbox was sent (the signal was
+ * aborted before an attempt, or while the SDK waited to send one again
+ * after attempts that never arrived), `did` when a 2xx status came before
+ * the abort cut its body, else `maybe`, with what the sandbox does once a
+ * connection closes. TypeScript only: the Python SDK takes no signal.
+ */
+export declare function withAbort(error: PrizedError, effect: Effect, outcome: 'never' | 'maybe' | 'did'): PrizedError;
+/**
+ * A background start that may have started (`error`, from withOutcome or
+ * withAbort) and that the SDK then stopped by its run id (`stopped`: the
+ * abandon script answered exit 0, so the run can no longer start, was
+ * killed with its group, or had already ended), or could not confirm it did
+ * (no answer, or exit 3: no pid came, so the command may yet run). The
+ * Python SDK's start_abandoned.
+ */
+export declare function startAbandoned(error: PrizedError, runId: string, stopped: boolean): PrizedError;
+/**
+ * A streamed or long exec the caller aborted after its run started
+ * (`error`, code `aborted`, from `sandboxId`), saying whether the SDK then
+ * stopped the run by its id (`stopped`: its KILL was sent, or the run had
+ * already ended), or could not confirm it did.
+ */
+export declare function runAborted(error: PrizedError, runId: string, stopped: boolean, sandboxId: string): PrizedError;
+/**
+ * A streamed or long exec whose poll failed after its run started (`error`:
+ * a lost connection, a 5xx, an answer that could not be read, a refused
+ * key), saying whether the SDK then stopped the run by its id (`stopped`),
+ * or could not confirm it did: with the network down, the command may still
+ * be running. Same code, status and body (and `sandboxId` when it names
+ * none); `error` itself is the cause. The Python SDK's poll_failed.
+ */
+export declare function pollFailed(error: PrizedError, runId: string, stopped: boolean, sandboxId: string): PrizedError;

package/dist/esm/outcome.js

@@ -0,0 +1,155 @@
+// What an error says about a command that may have run. A command, a file
+// write's rename, a remove or a signal (`exec` retry mode) is never sent again
+// once it may have reached the sandbox, so its error has to say what the
+// caller cannot see: whether it happened. A write's staged upload (`staged`)
+// may have been sent again, and its error says whether a copy may have
+// reached the sandbox. The Python SDK words these the same (_core.py).
+import { defaultMessage, PrizedError } from './errors.js';
+const NOT_SENT_AGAIN = 'It was not sent again';
+export function commandEffect() {
+    return {
+        maybe: 'the command may or may not have run',
+        did: 'The command ran',
+        check: `${NOT_SENT_AGAIN}: check for its effects (the files it writes, the processes it starts) before you run it again.`,
+        // The sandbox runs a command under its request, in a process group of
+        // its own that it KILLs when the request ends, and the edge forwards the
+        // request under the caller's connection: a closed connection kills it.
+        onClose: 'The sandbox stops a command (and its process group) once its connection closes, so it may have run in part.',
+    };
+}
+export function writeEffect(path) {
+    return {
+        maybe: `${path} may or may not have been written`,
+        did: `${path} was written`,
+        check: `${NOT_SENT_AGAIN}: read it back with files.read() to see which.`,
+    };
+}
+export function removeEffect(path) {
+    return {
+        maybe: `${path} may or may not have been removed`,
+        did: `The remove of ${path} ran`,
+        check: `${NOT_SENT_AGAIN}: files.exists() tells you which.`,
+    };
+}
+/** For CommandHandle.kill (`signal` without its SIG prefix). */
+export function signalEffect(runId, signal) {
+    return {
+        maybe: `SIG${signal} may or may not have reached ${runId}`,
+        did: `The kill of ${runId} ran`,
+        check: `${NOT_SENT_AGAIN}: status() tells you whether the command is still running.`,
+    };
+}
+/** For a background start (or a streamed or long exec, which runs as one): said before what the SDK did about it (startAbandoned). A 2xx proves only that the start ran. */
+export function startEffect() {
+    return { maybe: 'the command may or may not have started', did: 'The sandbox ran the start', check: '' };
+}
+/** For an SDK helper sent in `exec` mode that names no effect of its own. */
+export function helperEffect() {
+    return { maybe: 'it may or may not have taken effect', did: 'It ran', check: `${NOT_SENT_AGAIN}.` };
+}
+const acted = new WeakSet();
+/** Whether withOutcome said the sandbox may have acted on the request. */
+export function mayHaveActed(error) {
+    return error instanceof PrizedError && acted.has(error);
+}
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
+export function restate(error, message, init = {}) {
+    return new PrizedError(init.code ?? error.code, message, {
+        status: init.status ?? error.status,
+        reason: error.reason,
+        sandboxId: error.sandboxId ?? init.sandboxId ?? null,
+        body: error.body,
+        retryAfter: error.retryAfter,
+        exitCode: init.exitCode ?? error.exitCode,
+        cause: 'cause' in init ? init.cause : error.cause,
+    });
+}
+/** `error` restated with `message` (and, given, another sandbox or cause), as one after which the sandbox may have acted. */
+function acting(error, message, init = {}) {
+    const restated = restate(error, message, init);
+    acted.add(restated);
+    return restated;
+}
+function trimmed(text) {
+    return text.replace(/[.\s]+$/, '');
+}
+/** The failure in a few words, for inside a sentence. */
+function detail(error) {
+    const message = trimmed(error.message);
+    if (error.status === null || error.code === 'http_error' || error.code === 'bad_response')
+        return message;
+    const head = `HTTP ${error.status} ${error.code}`;
+    return message === trimmed(defaultMessage(error.code)) ? head : `${head}: ${message}`;
+}
+/** What follows "so" when no clear answer came: what may have happened, then (`closed`: the caller aborted) what a closed connection does, then how to check. */
+function maybeTail(effect, closed) {
+    let tail = `${effect.maybe}.`;
+    if (closed && effect.onClose)
+        tail += ` ${effect.onClose}`;
+    if (effect.check)
+        tail += ` ${effect.check}`;
+    return tail;
+}
+/** `error` (same code, status and body), its message saying what it means for `effect`. */
+export function withOutcome(error, effect, outcome) {
+    if (outcome === null)
+        return error;
+    if (outcome === 'never')
+        return restate(error, `${trimmed(error.message)}. It never reached the sandbox, so it had no effect.`);
+    if (outcome === 'did')
+        return acting(error, `${effect.did}, but the answer could not be read (${detail(error)}).`);
+    return acting(error, `No clear answer came back (${detail(error)}), so ${maybeTail(effect, false)}`);
+}
+/**
+ * `error` (code `aborted`) for a request with an `effect`: `never` when
+ * nothing that may have reached the sandbox was sent (the signal was
+ * aborted before an attempt, or while the SDK waited to send one again
+ * after attempts that never arrived), `did` when a 2xx status came before
+ * the abort cut its body, else `maybe`, with what the sandbox does once a
+ * connection closes. TypeScript only: the Python SDK takes no signal.
+ */
+export function withAbort(error, effect, outcome) {
+    if (outcome !== 'maybe')
+        return withOutcome(error, effect, outcome);
+    return acting(error, `Aborted before a clear answer came, so ${maybeTail(effect, true)}`);
+}
+/** What the SDK did about a run it stopped by its id (`stopped`), or could not confirm it did. */
+function stopTail(runId, stopped) {
+    return stopped
+        ? ` The SDK stopped ${runId}, or it had already ended.`
+        : ` The SDK could not confirm it stopped: it may still be running as ${runId} (exec('ps -ef | grep ${runId}') finds it).`;
+}
+/**
+ * A background start that may have started (`error`, from withOutcome or
+ * withAbort) and that the SDK then stopped by its run id (`stopped`: the
+ * abandon script answered exit 0, so the run can no longer start, was
+ * killed with its group, or had already ended), or could not confirm it did
+ * (no answer, or exit 3: no pid came, so the command may yet run). The
+ * Python SDK's start_abandoned.
+ */
+export function startAbandoned(error, runId, stopped) {
+    const said = error.message.trimEnd();
+    return acting(error, (/[.!?]$/.test(said) ? said : `${said}.`) + stopTail(runId, stopped));
+}
+/**
+ * A streamed or long exec the caller aborted after its run started
+ * (`error`, code `aborted`, from `sandboxId`), saying whether the SDK then
+ * stopped the run by its id (`stopped`: its KILL was sent, or the run had
+ * already ended), or could not confirm it did.
+ */
+export function runAborted(error, runId, stopped, sandboxId) {
+    return acting(error, `${trimmed(error.message)}.${stopTail(runId, stopped)}`, { sandboxId });
+}
+/**
+ * A streamed or long exec whose poll failed after its run started (`error`:
+ * a lost connection, a 5xx, an answer that could not be read, a refused
+ * key), saying whether the SDK then stopped the run by its id (`stopped`),
+ * or could not confirm it did: with the network down, the command may still
+ * be running. Same code, status and body (and `sandboxId` when it names
+ * none); `error` itself is the cause. The Python SDK's poll_failed.
+ */
+export function pollFailed(error, runId, stopped, sandboxId) {
+    // One sentence, whatever lines the poll's own error carries (a script's stderr).
+    const said = detail(error).replace(/\s+/g, ' ');
+    return acting(error, `Polling the command failed (${said}).${stopTail(runId, stopped)}`, { sandboxId, cause: error });
+}

package/dist/esm/output.d.ts

@@ -0,0 +1,70 @@
+import { type Toolbox } from './toolbox.js';
+import type { ExecResult, TruncatedReason } from './types.js';
+export declare const OUTPUT_DIR = "/home/prized/.prized/exec";
+export declare const OUTPUT_ID_RE: RegExp;
+/** Each stream of a fullOutput command keeps at most this many bytes: one download. */
+export declare const FULL_OUTPUT_BYTES: number;
+/**
+ * The variables that carry the script and the caller's command, so neither
+ * is in the argv of any process but the command's own shell: `pkill -f`
+ * finds what it finds in a plain exec. The script unsets both first.
+ */
+export declare const SCRIPT_VAR = "PRIZED_EXEC_SCRIPT";
+export declare const COMMAND_VAR = "PRIZED_EXEC_COMMAND";
+/** What a fullOutput exec sends as its command: the script, from SCRIPT_VAR. */
+export declare const RUN_SCRIPT = "eval \"${PRIZED_EXEC_SCRIPT:?}\"";
+/**
+ * The script a fullOutput exec runs (RUN_SCRIPT, from SCRIPT_VAR). The
+ * caller's command, from COMMAND_VAR, runs as a plain exec runs it (`bash
+ * -c`, or `sh -c` where there is no bash, stdin from /dev/null), with the
+ * request's cwd and env.
+ *
+ * Nothing is assigned before it runs but the positional parameters, so every
+ * variable the caller's env sets reaches it unchanged, PATH included; and
+ * every step holds under an errexit the env may switch on (SHELLOPTS). As in
+ * a plain exec, the relays stop 5 s after the command ends if a process it
+ * left running still holds its output, keeping what came through. A command
+ * a signal ends exits 128+n, as a background command does. A reader that
+ * could not write its file (failedLines) sends the output to the files API
+ * whatever its size, with the marker saying which. Without /bin/sh, setsid,
+ * cat or a directory to write to, the command runs as a plain exec.
+ */
+export declare function captureScript(id: string): string;
+/**
+ * What a fullOutput command left when the script could not print it (its
+ * time limit, or a signal, ended the script): the marker line, or `gone`,
+ * with the directory removed, when there is nothing to read (it was never
+ * made, or its output was already printed back). A failed write is read from
+ * the reader's flag, before the size, which is final once the flag is there
+ * (the script's wait for the reader's exit status went with the script); a
+ * reader killed, or one that could not make its flag, is not seen here.
+ */
+export declare function collectScript(id: string): string;
+/**
+ * Remove a fullOutput command's directory (keyed by the SDK's own id, safe to
+ * send again), and any an earlier one left over an hour ago, when it got no
+ * answer to remove its own.
+ */
+export declare function removeOutputScript(id: string): string;
+/** What the marker line says: each stream's byte count (one cut at FULL_OUTPUT_BYTES reads more), and whether its reader failed to write it. */
+export interface Marker {
+    out: number;
+    err: number;
+    outFailed: boolean;
+    errFailed: boolean;
+}
+/** The marker (one without failure flags, as an earlier SDK's collect printed, has none), `gone`, or null for no marker. */
+export declare function parseMarker(stdout: string, id: string): Marker | 'gone' | null;
+/** Why the read-back output is cut, if it is: a failed write first, since it is the one the caller cannot foresee. */
+export declare function markerTruncation(marker: Marker): TruncatedReason | null;
+/**
+ * A blocking exec that keeps the whole output (up to FULL_OUTPUT_BYTES of
+ * each stream). The result is a plain exec's, timeouts included: the caller
+ * (execCommand) turns a timed-out one into CommandTimeoutError.
+ */
+export declare function execFullOutput(toolbox: Toolbox, id: string, req: {
+    command: string;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    timeoutMs: number;
+}, signal: AbortSignal | undefined): Promise<ExecResult>;