withruntime 0.8.4 → 0.10.0

package/dist/errors.js

@@ -1,8 +1,21 @@
 /** Every failure the SDK raises. `code` is stable and machine-readable,
  * `hint` says what to do next, and `requestId` is what to quote in a report
  * (runtime.feedback.submit, `runtime feedback`, or support). */
-/** Switched off on purpose: retrying cannot change them. */
-const DELIBERATE = new Set(["fork_unavailable", "previews_unavailable", "unavailable"]);
+/** A product switched off on this deployment, or paused on purpose: the API
+ * answers these 503s in fixed words (`serverFault` "off" in
+ * packages/cloud/src/api/respond.ts) and retrying cannot change them.
+ * host_unavailable and busy pass, and are retried. */
+export const DELIBERATE = new Set([
+    "unavailable",
+    "unsupported",
+    "fork_unavailable",
+    "previews_unavailable",
+    "network_unavailable",
+    "network_rules_unavailable",
+    "secrets_unavailable",
+    "identity_unavailable",
+    "env_unavailable",
+]);
 /** Refusals that pass on their own: a host frees room, a trial slot frees. */
 const PASSING = new Set(["no_capacity", "trial_busy"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host

package/dist/file-source.d.ts

@@ -0,0 +1,16 @@
+export type StreamUploadSource = string | Blob | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
+export type UploadScope = {
+    signal?: AbortSignal;
+    check(): void;
+    wait<T>(pending: Promise<T>): Promise<T>;
+};
+export type PreparedFileSource = {
+    size: number;
+    sha256: string;
+    chunkAt(offset: number, length: number): Promise<Uint8Array>;
+    close(): Promise<void>;
+};
+/** ARCHITECTURE.md section 10, Folders over HTTP: unknown-length inputs use
+ * bounded private disk staging; known files and Blobs remain repeatable inputs.
+ * Size and digest are established before the remote upload can begin. */
+export declare function prepareFileSource(input: StreamUploadSource, scope: UploadScope): Promise<PreparedFileSource>;

package/dist/file-source.js

@@ -0,0 +1,162 @@
+import { RuntimeError } from "./errors.js";
+const CHUNK = 1_048_576;
+function failure(message, code, cause) {
+    return new RuntimeError({ message, code, status: 0, ...(cause === undefined ? {} : { cause }) });
+}
+async function exact(handle, offset, length) {
+    const data = new Uint8Array(length);
+    let held = 0;
+    while (held < length) {
+        const read = await handle.read(data, held, length - held, offset + held);
+        if (read.bytesRead === 0)
+            throw failure("The local upload source changed or ended before its declared size.", "source_changed");
+        held += read.bytesRead;
+    }
+    return data;
+}
+/** ARCHITECTURE.md section 10, Folders over HTTP: unknown-length inputs use
+ * bounded private disk staging; known files and Blobs remain repeatable inputs.
+ * Size and digest are established before the remote upload can begin. */
+export async function prepareFileSource(input, scope) {
+    const fs = await import("node:fs/promises");
+    const { createHash } = await import("node:crypto");
+    const { Readable } = await import("node:stream");
+    scope.check();
+    const hash = createHash("sha256");
+    let size = 0;
+    let handle;
+    let staging;
+    let iterator;
+    // What is used of a reader, so the code compiles against Node's stream types
+    // as well as the DOM's (packages/cloud compiles this file without DOM).
+    let reader;
+    const cleanup = async () => {
+        try {
+            await handle?.close();
+        }
+        finally {
+            if (staging)
+                await fs.rm(staging, { recursive: true, force: true });
+        }
+    };
+    try {
+        if (typeof input === "string") {
+            handle = await fs.open(input, "r");
+            const info = await handle.stat();
+            if (!info.isFile() || !Number.isSafeInteger(info.size))
+                throw failure("A streamed file upload requires a regular local file.", "invalid_upload_source");
+            size = info.size;
+            for (let offset = 0; offset < size; offset += CHUNK) {
+                scope.check();
+                hash.update(await scope.wait(exact(handle, offset, Math.min(CHUNK, size - offset))));
+            }
+        }
+        else if (input instanceof Blob) {
+            // Bun's types leave out Blob.slice when the DOM library is off, as it is
+            // where packages/cloud compiles this file; every runtime has it.
+            const blob = input;
+            size = blob.size;
+            for (let offset = 0; offset < size; offset += CHUNK) {
+                scope.check();
+                hash.update(new Uint8Array(await scope.wait(blob.slice(offset, offset + CHUNK).arrayBuffer())));
+            }
+            return {
+                size,
+                sha256: hash.digest("hex"),
+                chunkAt: async (offset, length) => new Uint8Array(await blob.slice(offset, offset + length).arrayBuffer()),
+                close: async () => undefined,
+            };
+        }
+        else {
+            if (!input ||
+                (typeof input.getReader !== "function" &&
+                    typeof input[Symbol.asyncIterator] !== "function"))
+                throw failure("A streamed upload requires a byte stream or local file.", "invalid_upload_source");
+            const { tmpdir } = await import("node:os");
+            const path = await import("node:path");
+            staging = await fs.mkdtemp(path.join(tmpdir(), "runtime-upload-"));
+            await fs.chmod(staging, 0o700);
+            handle = await fs.open(path.join(staging, "source"), "wx+", 0o600);
+            const space = await fs.statfs(staging, { bigint: true });
+            const available = space.bavail * space.bsize;
+            if ("getReader" in input)
+                reader = input.getReader();
+            else
+                iterator = input[Symbol.asyncIterator]();
+            for (;;) {
+                scope.check();
+                const next = await scope.wait(reader ? reader.read() : iterator.next());
+                if (next.done)
+                    break;
+                if (!(next.value instanceof Uint8Array))
+                    throw failure("A streamed upload must produce byte chunks.", "invalid_upload_source");
+                for (let offset = 0; offset < next.value.length; offset += CHUNK) {
+                    scope.check();
+                    const part = next.value.subarray(offset, offset + CHUNK);
+                    if (!Number.isSafeInteger(size + part.length))
+                        throw failure("The streamed upload exceeds the native file size range.", "upload_too_large");
+                    if (BigInt(size + part.length) > available)
+                        throw failure("There is not enough local temporary disk space to stage the streamed upload.", "local_disk_full");
+                    let written = 0;
+                    while (written < part.length) {
+                        scope.check();
+                        const result = await handle.write(part, written, part.length - written, size + written);
+                        if (result.bytesWritten === 0)
+                            throw failure("The local temporary file accepted no upload bytes.", "local_disk_full");
+                        written += result.bytesWritten;
+                    }
+                    size += part.length;
+                    hash.update(part);
+                }
+            }
+        }
+        scope.check();
+        const owned = handle;
+        if (!owned)
+            throw failure("The local upload file did not open.", "invalid_upload_source");
+        return {
+            size,
+            sha256: hash.digest("hex"),
+            chunkAt: (offset, length) => exact(owned, offset, length),
+            close: cleanup,
+        };
+    }
+    catch (error) {
+        // Calling return/cancel can itself throw synchronously. Cleanup still owns
+        // the file and directory, and must preserve the original source failure.
+        let timer;
+        try {
+            // Node's pending next() must settle before iterator.return() can finish.
+            // Web readers own cancellation directly; arbitrary iterators may not.
+            if (input instanceof Readable)
+                input.destroy();
+            const closing = reader ? reader.cancel(scope.signal?.reason) : iterator?.return?.();
+            if (closing)
+                await Promise.race([
+                    closing,
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, 1000);
+                    }),
+                ]);
+        }
+        catch {
+            /* Preserve the caller's original failure. */
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            await cleanup().catch(() => undefined);
+        }
+        if (error?.code === "ENOSPC")
+            throw failure("There is not enough local temporary disk space to stage the streamed upload.", "local_disk_full", error);
+        throw error;
+    }
+    finally {
+        try {
+            reader?.releaseLock();
+        }
+        catch {
+            /* Cancellation may leave a pending caller-owned read. */
+        }
+    }
+}

package/dist/freestyle/index.d.ts

@@ -0,0 +1,309 @@
+import type { Runtime } from "../client.js";
+import type { Sandbox } from "../sandbox.js";
+import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+export { CompatibilityError };
+export type VmState = "starting" | "running" | "pausing" | "paused" | "stopped";
+export interface FirewallRule {
+    action: "allow";
+    source: Record<string, never>;
+    destination: {
+        public: true;
+    };
+}
+export interface CreateVmOptions {
+    snapshotId?: string | null;
+    slug?: string | null;
+    displayName?: string | null;
+    idleTimeoutSeconds?: number | null;
+    metadata?: Record<string, string>;
+    firewall: {
+        rules: FirewallRule[];
+    };
+}
+export interface ExecOptions {
+    command: string;
+    linuxUser?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    stdin?: string;
+}
+export declare class Freestyle {
+    readonly vms: VmsNamespace;
+    constructor(options?: ClientOptions);
+}
+export declare class VmsNamespace {
+    private readonly runtime;
+    readonly snapshots: {
+        get: (id: string) => Promise<{
+            id: string;
+            sourceVmId: string;
+            slug: string | null;
+            displayName: string | null;
+            public: boolean;
+            createdAt: string;
+            updatedAt: string;
+            ttlSeconds: number;
+        }>;
+        delete: (id: string) => Promise<void>;
+        list: (options?: {
+            sourceVmId?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            snapshots: {
+                id: string;
+                sourceVmId: string;
+                slug: string | null;
+                displayName: string | null;
+                public: boolean;
+                createdAt: string;
+                updatedAt: string;
+                ttlSeconds: number;
+            }[];
+            totalCount: number;
+        }>;
+    };
+    constructor(runtime: Runtime);
+    private resolveSnapshot;
+    create(options: CreateVmOptions): Promise<{
+        vm: Vm;
+        vmId: string;
+        data: {
+            id: string;
+            state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+            slug: string | null;
+            displayName: string | null;
+            resources: {
+                cpu: number;
+                memory: number;
+                storage: number;
+            };
+            metadata: {
+                [k: string]: string;
+            };
+            idleTimeoutSeconds: number | undefined;
+            vpcs: never[];
+            networks: never[];
+            createdAt: string;
+            updatedAt: string;
+        };
+        firewallRules: {
+            id: string;
+            source: {
+                vmId: string;
+            };
+            action: "allow";
+            destination: {
+                public: true;
+            };
+        }[];
+        tlsRules: never[];
+    }>;
+    ref(id: string): Vm;
+    get(id: string): Promise<{
+        id: string;
+        state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+        slug: string | null;
+        displayName: string | null;
+        resources: {
+            cpu: number;
+            memory: number;
+            storage: number;
+        };
+        metadata: {
+            [k: string]: string;
+        };
+        idleTimeoutSeconds: number | undefined;
+        vpcs: never[];
+        networks: never[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    delete(id: string): Promise<void>;
+    list(options?: {
+        state?: string;
+        slug?: string;
+        metadata?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        vms: {
+            id: string;
+            state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+            slug: string | null;
+            displayName: string | null;
+            resources: {
+                cpu: number;
+                memory: number;
+                storage: number;
+            };
+            metadata: {
+                [k: string]: string;
+            };
+            idleTimeoutSeconds: number | undefined;
+            vpcs: never[];
+            networks: never[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        totalCount: number;
+        runningCount: number;
+        startingCount: number;
+        pausingCount: number;
+        pausedCount: number;
+        stoppedCount: number;
+    }>;
+}
+export interface ReadFileOptions {
+    offset?: number;
+    length?: number;
+    signal?: AbortSignal;
+}
+export interface WriteFileOptions {
+    mode?: number;
+    signal?: AbortSignal;
+    chunkSize?: number;
+    maxAttempts?: number;
+    onProgress?: (progress: {
+        completedBytes: number;
+        totalBytes: number;
+    }) => void;
+}
+export declare class VmFilesystem {
+    private readonly get;
+    private readonly files;
+    constructor(get: () => Promise<Sandbox>);
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array<ArrayBuffer>>;
+    readTextFile(path: string, options?: ReadFileOptions): Promise<string>;
+    readFileStream(path: string, options?: ReadFileOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    writeFile(path: string, content: string | Uint8Array | Blob, options?: WriteFileOptions): Promise<void>;
+    writeTextFile(path: string, content: string, options?: WriteFileOptions): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): Promise<{
+        name: string;
+        kind: "file" | "directory" | "symlink" | "other";
+    }[]>;
+    stat(path: string): Promise<{
+        size: number;
+        isFile: boolean;
+        isDirectory: boolean;
+        isSymlink: boolean;
+        permissions: string;
+        owner: string;
+        group: string;
+        modified: string;
+    }>;
+}
+export declare class Vm {
+    private readonly runtime;
+    readonly id: string;
+    readonly fs: VmFilesystem;
+    constructor(runtime: Runtime, id: string);
+    data(): Promise<{
+        id: string;
+        state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+        slug: string | null;
+        displayName: string | null;
+        resources: {
+            cpu: number;
+            memory: number;
+            storage: number;
+        };
+        metadata: {
+            [k: string]: string;
+        };
+        idleTimeoutSeconds: number | undefined;
+        vpcs: never[];
+        networks: never[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    start(): Promise<{
+        id: string;
+        state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+        slug: string | null;
+        displayName: string | null;
+        resources: {
+            cpu: number;
+            memory: number;
+            storage: number;
+        };
+        metadata: {
+            [k: string]: string;
+        };
+        idleTimeoutSeconds: number | undefined;
+        vpcs: never[];
+        networks: never[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    pause(): Promise<{
+        id: string;
+        state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+        slug: string | null;
+        displayName: string | null;
+        resources: {
+            cpu: number;
+            memory: number;
+            storage: number;
+        };
+        metadata: {
+            [k: string]: string;
+        };
+        idleTimeoutSeconds: number | undefined;
+        vpcs: never[];
+        networks: never[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    delete(): Promise<void>;
+    update(options: {
+        slug?: string;
+        displayName?: string;
+        idleTimeoutSeconds?: number;
+        metadata?: Record<string, string>;
+    }): Promise<{
+        id: string;
+        state: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+        slug: string | null;
+        displayName: string | null;
+        resources: {
+            cpu: number;
+            memory: number;
+            storage: number;
+        };
+        metadata: {
+            [k: string]: string;
+        };
+        idleTimeoutSeconds: number | undefined;
+        vpcs: never[];
+        networks: never[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    exec(options: string | ExecOptions): Promise<{
+        stdout: string;
+        stderr: string;
+        statusCode: number | null;
+    }>;
+    snapshot(options?: {
+        slug?: string;
+        displayName?: string;
+        ttlSeconds?: number;
+    }): Promise<{
+        snapshotId: string;
+        sourceVmId: string;
+        snapshot: {
+            id: string;
+            sourceVmId: string;
+            slug: string | null;
+            displayName: string | null;
+            public: boolean;
+            createdAt: string;
+            updatedAt: string;
+            ttlSeconds: number;
+        };
+    }>;
+}