withruntime 0.7.2 → 0.8.1

package/dist/blaxel/errors.js

@@ -0,0 +1,171 @@
+import { RuntimeError } from "../errors.js";
+/* Blaxel's error classes by the same names, so a
+   `catch (e) { if (e instanceof ResponseError) ... }` or an
+   `isGatewayError(e)` written for Blaxel keeps working. One made from a
+   Runtime answer also carries Runtime's own code (`runtimeCode`), `hint` and
+   `requestId`, and the original error as `cause`. */
+const GATEWAY = new Set([502, 503, 504]);
+/** An error answer. `status` is the HTTP status; `code` is the same number,
+ * as Blaxel's control-plane errors carry it (`e.code === 404`); `data` is
+ * `{ error, code, hint, requestId }`. */
+export class ResponseError extends Error {
+    response;
+    error;
+    status;
+    statusText;
+    data;
+    code;
+    runtimeCode;
+    hint;
+    requestId;
+    constructor(response, data, error) {
+        const status = response.status || undefined;
+        const detail = data && typeof data === "object" && typeof data.error === "string"
+            ? data.error
+            : undefined;
+        super(`Sandbox request failed with status ${status ?? "unknown"}${detail ? `: ${detail}` : ""}`);
+        this.name = new.target.name;
+        this.response = response;
+        this.error = error;
+        this.data = data;
+        if (status !== undefined) {
+            this.status = status;
+            this.code = status;
+        }
+        if (response.statusText)
+            this.statusText = response.statusText;
+    }
+}
+/** A 502, 503 or 504: nothing usable came back. Safe to retry an idempotent
+ * call. */
+export class SandboxGatewayError extends ResponseError {
+}
+/** True when `err` carries a gateway status (502, 503 or 504). */
+export function isGatewayError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        GATEWAY.has(err.status));
+}
+/** True when `err` is a gateway timeout (504). */
+export function isGatewayTimeout(err) {
+    return typeof err === "object" && err !== null && err.status === 504;
+}
+/** No Runtime key was found. A Blaxel key (BL_API_KEY) is never sent. */
+export class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** A call that Blaxel supports and Runtime does not, or not in the same way.
+ * Thrown before anything is done, never after doing something different.
+ * `feature` names what was asked for; `alternative` says what to use on
+ * Runtime instead. */
+export class NotSupportedError extends Error {
+    code = "not_supported";
+    feature;
+    alternative;
+    constructor(feature, alternative, message) {
+        super(message ?? `${feature} is not supported on Runtime. ${alternative}`);
+        this.name = new.target.name;
+        this.feature = feature;
+        this.alternative = alternative;
+    }
+}
+/** A ResponseError of this status and message, made here rather than by
+ * Runtime: a process or preview that is not there, a wait that ran out. */
+export function responseError(status, message) {
+    const data = { error: message };
+    const Kind = GATEWAY.has(status) ? SandboxGatewayError : ResponseError;
+    return new Kind(new Response(JSON.stringify(data), {
+        status,
+        headers: { "content-type": "application/json" },
+    }), data, data);
+}
+const LS = "List the directory with sandbox.fs.ls(path).";
+/** Runtime's hints that name Runtime's calls, in the Blaxel calls a Blaxel
+ * program makes (the Python adapter uses the same words). */
+const AGAIN = "Try again in a moment.";
+const BLAXEL_HINTS = {
+    name_taken: "SandboxInstance.createIfNotExists({ name }) answers the sandbox that has the name.",
+    file_not_found: LS,
+    path_not_found: LS,
+    is_a_directory: "That path is a directory: list it with sandbox.fs.ls(path), or name a file in it.",
+    cwd_not_found: "Make the directory with sandbox.fs.mkdir(path), or pass an existing workingDir to sandbox.process.exec.",
+    sandbox_paused: "Call sandbox.unarchive(), then try again.",
+    not_running: "The sandbox is not running: call sandbox.unarchive() if it was archived, or make a new one with SandboxInstance.create if it was deleted.",
+    trial_busy: "The trial's sandboxes are all in use: delete one you no longer need (sandbox.delete()) or archive it (sandbox.archive()), then try again. Moving to paid credit is the account owner's decision.",
+    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt). A public preview needs a paid sandbox, which is the account owner's decision.",
+    busy: AGAIN,
+    guest_busy: AGAIN,
+    rate_limited: AGAIN,
+    unauthorized: "Set RUNTIME_API_KEY to a Runtime key (https://withruntime.com/account/keys), or run `npx withruntime login` once. A Blaxel key (BL_API_KEY) is never sent.",
+};
+/** A trial create over the trial's size, in Blaxel's field. */
+const TRIAL_CAP = "A trial sandbox has at most 4096 MB of memory (2 vCPUs); pass memory 4096 or add credit.";
+/** A Runtime SDK error as Blaxel's: ResponseError (SandboxGatewayError for a
+ * 502, 503 or 504), NotSupportedError for a product Runtime has switched off,
+ * CredentialsError when there is no Runtime key. Anything else passes through
+ * unchanged. */
+export function translate(error) {
+    if (!(error instanceof RuntimeError))
+        return error;
+    if (error.code === "missing_api_key")
+        return Object.assign(new CredentialsError("No Runtime key found. A Blaxel key (BL_API_KEY) is never sent anywhere: set RUNTIME_API_KEY to a " +
+            "Runtime key (https://withruntime.com/account/keys), put a Runtime key (rtcloud_...) in BL_API_KEY, " +
+            "or run `npx withruntime login` once."), { cause: error });
+    if (error.status === 503 && error.code.endsWith("_unavailable"))
+        return new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", error.message);
+    if (error.status < 200 || error.status > 599)
+        return error;
+    const trialCap = error.code === "invalid_trial";
+    const hint = trialCap ? undefined : (BLAXEL_HINTS[error.code] ?? error.hint);
+    const message = [
+        trialCap ? TRIAL_CAP : error.message,
+        hint ? `Hint: ${hint}` : "",
+        error.requestId ? `Request: ${error.requestId}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const data = {
+        error: message,
+        code: error.code,
+        ...(hint ? { hint } : {}),
+        ...(error.requestId ? { requestId: error.requestId } : {}),
+    };
+    const Kind = GATEWAY.has(error.status) ? SandboxGatewayError : ResponseError;
+    const out = new Kind(new Response(JSON.stringify(data), {
+        status: error.status,
+        headers: { "content-type": "application/json" },
+    }), data, data);
+    out.runtimeCode = error.code;
+    if (hint)
+        out.hint = hint;
+    if (error.requestId)
+        out.requestId = error.requestId;
+    out.cause = error;
+    return out;
+}
+/** Runs `work`, turning any Runtime error into Blaxel's. */
+export async function guard(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw translate(error);
+    }
+}
+/** True for a 404 in either shape: Runtime's or Blaxel's. */
+export function isNotFound(error) {
+    if (error instanceof RuntimeError)
+        return error.status === 404;
+    return error instanceof ResponseError && error.status === 404;
+}
+/** Runtime's error code on either shape. */
+export function codeOf(error) {
+    if (error instanceof RuntimeError)
+        return error.code;
+    if (error instanceof ResponseError)
+        return error.runtimeCode;
+    return undefined;
+}

package/dist/blaxel/filesystem.d.ts

@@ -0,0 +1,147 @@
+import type { RuntimeSandbox } from "./client.js";
+export type File = {
+    group: string;
+    lastModified: string;
+    name: string;
+    owner: string;
+    path: string;
+    permissions: string;
+    size: number;
+};
+export type FileWithContent = File & {
+    content: string;
+};
+export type Subdirectory = {
+    name: string;
+    path: string;
+};
+export type Directory = {
+    files: Array<File>;
+    name: string;
+    path: string;
+    subdirectories: Array<Subdirectory>;
+};
+export type SuccessResponse = {
+    message: string;
+    path?: string;
+};
+export type FindMatch = {
+    path: string;
+    type: string;
+};
+export type FindResponse = {
+    matches: Array<FindMatch>;
+    total: number;
+};
+export type FuzzySearchMatch = {
+    path: string;
+    score: number;
+    type: string;
+};
+export type FuzzySearchResponse = {
+    matches: Array<FuzzySearchMatch>;
+    total: number;
+};
+export type ContentSearchMatch = {
+    column: number;
+    context?: string;
+    line: number;
+    path: string;
+    text: string;
+};
+export type ContentSearchResponse = {
+    matches: Array<ContentSearchMatch>;
+    query: string;
+    total: number;
+};
+export type CopyResponse = {
+    message: string;
+    source: string;
+    destination: string;
+};
+export type WatchEvent = {
+    op: "CREATE" | "WRITE" | "REMOVE" | "RENAME" | "CHMOD";
+    path: string;
+    name: string;
+    content?: string;
+};
+export type SandboxFilesystemFile = {
+    path: string;
+    content: string;
+};
+export interface FilesystemSearchOptions {
+    maxResults?: number;
+    patterns?: string[];
+    excludeDirs?: string[];
+    excludeHidden?: boolean;
+}
+export interface FilesystemFindOptions {
+    type?: "file" | "directory";
+    patterns?: string[];
+    maxResults?: number;
+    excludeDirs?: string[];
+    excludeHidden?: boolean;
+}
+export interface FilesystemGrepOptions {
+    caseSensitive?: boolean;
+    contextLines?: number;
+    maxResults?: number;
+    filePattern?: string;
+    excludeDirs?: string[];
+}
+/** What `sandbox.fs` needs from its sandbox. */
+export interface FsContext {
+    /** Runs `work` on the live sandbox, woken if it was paused. */
+    run<T>(work: (runtime: RuntimeSandbox) => Promise<T>): Promise<T>;
+}
+/** `sandbox.fs`. */
+export declare class SandboxFileSystem {
+    #private;
+    constructor(ctx: FsContext);
+    /** Makes a directory and its parents. */
+    mkdir(path: string, permissions?: string): Promise<SuccessResponse>;
+    /** Writes a text file, making its directories. */
+    write(path: string, content: string): Promise<SuccessResponse>;
+    /** Writes bytes: a Buffer, Blob, File or Uint8Array, or a string naming a
+     * local file to upload. */
+    writeBinary(path: string, content: Buffer | Blob | Uint8Array | string): Promise<SuccessResponse>;
+    /** Writes files under `destinationPath` (the working directory by
+     * default) and answers the listing of it: one command for a small tree. */
+    writeTree(files: SandboxFilesystemFile[], destinationPath?: string | null): Promise<Directory | undefined>;
+    /** A text file's content. */
+    read(path: string): Promise<string>;
+    /** A file's bytes, as a Blob. */
+    readBinary(path: string): Promise<Blob>;
+    /** Copies a sandbox file to the local disk with `mode` (default 0o644). */
+    download(src: string, destinationPath: string, { mode }?: {
+        mode?: number;
+    }): Promise<void>;
+    /** Removes a file, or a directory (its contents too with `recursive`). */
+    rm(path: string, recursive?: boolean): Promise<SuccessResponse>;
+    /** A directory's files and subdirectories, as Blaxel lists them. */
+    ls(path: string): Promise<Directory>;
+    /** Paths under `path` fuzzily matching `query`, best first. */
+    search(query: string, path?: string, options?: FilesystemSearchOptions): Promise<FuzzySearchResponse>;
+    /** Files (or directories) under `path` whose name matches a pattern. */
+    find(path: string, options?: FilesystemFindOptions): Promise<FindResponse>;
+    /** Lines containing `query` (a plain string, case-insensitive by default)
+     * in the files under `path`. */
+    grep(query: string, path?: string, options?: FilesystemGrepOptions): Promise<ContentSearchResponse>;
+    /** Copies a file or directory (cp -r). */
+    cp(source: string, destination: string, _options?: {
+        maxWait?: number;
+    }): Promise<CopyResponse>;
+    /** Calls `callback` for each change in `path` (and below it for
+     * `path/**`) until `close()`. `withContent` adds a created or written
+     * file's text; `ignore` skips paths. */
+    watch(path: string, callback: (fileEvent: WatchEvent) => void | Promise<void>, options?: {
+        onError?: (error: Error) => void;
+        withContent?: boolean;
+        ignore?: string[];
+    }): {
+        close: () => void;
+    };
+}
+/** Blaxel's own retry helper: Runtime's SDK retries transient failures
+ * itself, so this runs `fn` once. */
+export declare function retryOnTransient<T>(fn: () => Promise<T>): Promise<T>;