@prized/sdk 0.1.0 → 0.1.1

package/dist/esm/http.js

@@ -17,7 +17,15 @@ function envApiKey() {
 function isLoopback(hostname) {
     return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
 }
-/** An http(s) origin, trailing slashes and a trailing /api/v1 dropped. */
+/**
+ * https anywhere, plain http only to this machine: the API key rides in
+ * every request's Authorization header. The same rule for the options and
+ * for an edge the API names.
+ */
+function secureEndpoint(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+}
+/** An https (or loopback http) origin, trailing slashes and a trailing /api/v1 dropped. */
 function normalizeOrigin(name, raw) {
     let url;
     try {
@@ -29,6 +37,9 @@ function normalizeOrigin(name, raw) {
     if (url.protocol !== 'https:' && url.protocol !== 'http:') {
         throw new PrizedError('invalid_argument', `${name} must be an http(s) URL`);
     }
+    if (!secureEndpoint(url)) {
+        throw new PrizedError('invalid_argument', `${name} must use https (plain http only for localhost, 127.0.0.1 or [::1])`);
+    }
     if (url.username || url.password || url.search || url.hash) {
         throw new PrizedError('invalid_argument', `${name} must not carry credentials, a query or a fragment`);
     }
@@ -53,10 +64,10 @@ export function abortableSleep(ms, signal) {
     });
 }
 /**
- * How long a streamed or long exec keeps polling while its polls fail
- * before it stops the command (pollOutageMs): long enough to ride out a
- * dropped connection or an edge that restarts. The Python SDK's
- * DEFAULT_POLL_OUTAGE.
+ * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
+ * while its polls fail before it gives up (pollOutageMs), and a streamed or
+ * long exec stops its command: long enough to ride out a dropped connection
+ * or an edge that restarts. The Python SDK's DEFAULT_POLL_OUTAGE.
  */
 export const DEFAULT_POLL_OUTAGE_MS = 120_000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -100,20 +111,51 @@ export function resolveConfig(options = {}) {
         random: options.random ?? Math.random,
     };
 }
+/** Prized's own domain: its API and its edges are hosts under it. */
+const PRIZED_DOMAIN = 'prized.dev';
+function under(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** A URL's hostname (lowercase, as URL gives it), or '' if it does not parse. */
+function hostOf(raw) {
+    try {
+        return new URL(raw).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Where a toolboxBase may point, given the API's host: the API host itself;
+ * prized.dev's own hosts when the API is one of them; loopback when the API
+ * is. Never a domain guessed from the API host's name (a public suffix such
+ * as co.uk would trust everyone under it). The Python SDK's _trusted_edge.
+ */
+function trustedEdge(edgeHost, apiHost) {
+    if (edgeHost === '' || apiHost === '')
+        return false;
+    if (isLoopback(apiHost) || isLoopback(edgeHost))
+        return isLoopback(apiHost) && isLoopback(edgeHost);
+    return edgeHost === apiHost || (under(apiHost, PRIZED_DOMAIN) && under(edgeHost, PRIZED_DOMAIN));
+}
 /**
  * Where exec and files go for one sandbox. An explicit edgeUrl wins; else the
  * API's own `toolboxBase` when it has the expected shape (https, or plain
- * http on loopback for local development); else the default edge.
+ * http on loopback for local development, ending /v1/sandbox/<id>) on a host
+ * trusted beside the API's (term.prized.dev beside api.prized.dev; see
+ * trustedEdge); else the default edge, for Prized's own API only. The API key
+ * is never sent anywhere else: discovery is routing, not authority.
  */
 export function toolboxBaseFor(config, sandboxId, toolboxBase) {
     const path = `/v1/sandbox/${encodeURIComponent(sandboxId)}`;
     if (config.edgeUrl !== null)
         return `${config.edgeUrl}${path}`;
+    const apiHost = hostOf(config.baseUrl);
     if (toolboxBase) {
         try {
             const url = new URL(toolboxBase);
-            const secure = url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
-            if (secure &&
+            if (secureEndpoint(url) &&
+                trustedEdge(url.hostname, apiHost) &&
                 !url.username &&
                 !url.password &&
                 !url.search &&
@@ -126,7 +168,11 @@ export function toolboxBaseFor(config, sandboxId, toolboxBase) {
             // fall through to the default
         }
     }
-    return `${DEFAULT_EDGE_URL}${path}`;
+    // Prized's own edge only for Prized's own API: a key for another
+    // deployment is never sent to it. That deployment names its edge.
+    if (under(apiHost, PRIZED_DOMAIN))
+        return `${DEFAULT_EDGE_URL}${path}`;
+    throw new PrizedError('edge_unknown', `The API at ${config.baseUrl} named no command endpoint this SDK trusts for ${sandboxId}; pass edgeUrl for that deployment.`, { sandboxId });
 }
 /**
  * The edge this config's sandboxes answer on, before the API has named one:
@@ -223,7 +269,7 @@ export function retryable(error, mode, method) {
     // have done a write's work, so a write is left to its caller (a create
     // that may have made a sandbox finds and deletes it). A GET did nothing:
     // a poll that meets one is sent again rather than failing its create.
-    if (error.status === 500 && method === 'GET')
+    if (mode === 'safe' && error.status === 500 && method === 'GET')
         return true;
     return error.status === 429 || error.status === 502 || error.status === 503 || error.status === 504;
 }
@@ -410,8 +456,9 @@ export function outcomeOf(error) {
 /**
  * The error a request throws. With an `effect`, it says whether the sandbox
  * acted on the request: by this attempt, or by an earlier one that was sent
- * again (`acted`: only a keyed request, the background start, is sent again
- * after it may have arrived). `cutStatus`: the 2xx whose body broke off.
+ * again (`acted`: only a keyed request, the background start, and a staged
+ * upload are sent again after they may have arrived). `cutStatus`: the 2xx
+ * whose body broke off.
  */
 function raised(failure, outcome, acted, effect, cutStatus = null) {
     if (effect === undefined)
@@ -426,7 +473,8 @@ export async function request(config, spec) {
     const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
     const sandboxId = spec.sandboxId ?? null;
     const effect = spec.effect ?? (spec.retry === 'exec' ? commandEffect() : undefined);
-    const unsent = spec.retry === 'exec' ? effect : undefined;
+    // Whether an attempt that was sent again may have reached the sandbox.
+    let acted = false;
     // Names the last attempt's failure, if any, so a call cut short by its
     // deadline still says what it was waiting out (a 503, a rate limit).
     const pastDeadline = (last) => {
@@ -434,9 +482,10 @@ export async function request(config, spec) {
         const tail = what === null ? '' : ` The last attempt failed with ${what}.`;
         let error = new PrizedError('timeout', `The time allowed for this call ran out.${tail}`, { sandboxId, cause: last });
         // A command is sent again only when it provably never arrived, so every
-        // attempt of one cut short this way never reached the sandbox.
-        if (unsent !== undefined)
-            error = withOutcome(error, unsent, 'never');
+        // attempt of one cut short this way never reached the sandbox. A staged
+        // upload's copies may have, unless each provably never arrived.
+        if (effect !== undefined && spec.retry !== 'safe')
+            error = withOutcome(error, effect, spec.retry === 'staged' && acted ? 'maybe' : 'never');
         cutShort.add(error);
         return error;
     };
@@ -445,8 +494,6 @@ export async function request(config, spec) {
         return error;
     };
     let last;
-    // Whether an attempt that was sent again may have reached the sandbox.
-    let acted = false;
     // An abort with an `effect` says whether the sandbox may have acted:
     // before an attempt, or while waiting to send one again, nothing was sent
     // that might have, unless an earlier attempt of a keyed request (`acted`)
@@ -483,8 +530,9 @@ export async function request(config, spec) {
             // The status came and the body did not: the sandbox acted on it.
             const cut = outcome.status !== null && outcome.status >= 200 && outcome.status < 300;
             const said = cut ? 'did' : unsentAttempt ? 'never' : 'maybe';
-            // A command or upload is sent again only if it never left.
-            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt);
+            // A command is sent again only if it never left; a staged upload
+            // unless its 2xx came (its bytes are there).
+            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt) || (spec.retry === 'staged' && !cut);
             if (!resend || attempt >= config.maxRetries)
                 throw raised(failure, said, acted, effect, cut ? outcome.status : null);
             acted = acted || said !== 'never';

package/dist/esm/index.d.ts

@@ -4,9 +4,9 @@ export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './
 export type { CommandStatus, ExecOptions, WaitOptions } from './commands.js';
 export { Files } from './files.js';
 export type { FileData, WriteOptions } from './files.js';
-export { CommandTimeoutError, PrizedError } from './errors.js';
-export type { PrizedErrorInit } from './errors.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
+export type { OutputReadErrorInit, PrizedErrorInit } from './errors.js';
 export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
 export type { ClientOptions } from './http.js';
-export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, WriteInfo, } from './types.js';
+export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, TruncatedReason, WriteInfo, } from './types.js';
 export { VERSION } from './version.js';

package/dist/esm/index.js

@@ -2,6 +2,6 @@
 export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
 export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './commands.js';
 export { Files } from './files.js';
-export { CommandTimeoutError, PrizedError } from './errors.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
 export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
 export { VERSION } from './version.js';

package/dist/esm/outcome.d.ts

@@ -30,11 +30,12 @@ export declare function helperEffect(): Effect;
 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 or cause), every other field kept. */
+/** `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`. */

package/dist/esm/outcome.js

@@ -1,7 +1,9 @@
 // What an error says about a command that may have run. A command, a file
-// write, 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. The Python SDK words these the same (_core.py).
+// 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() {
@@ -50,7 +52,7 @@ const acted = new WeakSet();
 export function mayHaveActed(error) {
     return error instanceof PrizedError && acted.has(error);
 }
-/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+/** `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,
@@ -58,6 +60,7 @@ export function restate(error, message, init = {}) {
         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,
     });
 }

package/dist/esm/output.d.ts

@@ -1,5 +1,5 @@
 import { type Toolbox } from './toolbox.js';
-import type { ExecResult } from './types.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. */
@@ -22,17 +22,22 @@ export declare const RUN_SCRIPT = "eval \"${PRIZED_EXEC_SCRIPT:?}\"";
  * 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 readers stop 5 s after the command ends if a process it
+ * 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. Without tee,
- * setsid or a directory to write to, the command runs as a plain exec.
+ * 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).
+ * 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;
 /**
@@ -41,11 +46,17 @@ export declare function collectScript(id: string): string;
  * answer to remove its own.
  */
 export declare function removeOutputScript(id: string): string;
-/** The marker's byte counts (a stream cut at FULL_OUTPUT_BYTES reads more), `gone`, or null for no marker. */
-export declare function parseMarker(stdout: string, id: 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;
-} | 'gone' | null;
+    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