withruntime 0.8.4 → 0.10.0

package/dist/cloudflare/index.js

@@ -0,0 +1,592 @@
+import { createHash } from "node:crypto";
+import { Runtime } from "../client.js";
+import { NotFoundError } from "../errors.js";
+import { client, closeShell, CompatibilityError, destroy, environment, execOptions, only, pathAt, saveEnvironment, shellCommand, shellRoot, } from "../compat/core.js";
+export { CompatibilityError };
+export class SandboxSecurityError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "SandboxSecurityError";
+    }
+}
+export function sanitizeSandboxId(id) {
+    if (!id || id.length > 63)
+        throw new SandboxSecurityError("Sandbox ID must be 1-63 characters long.", "INVALID_SANDBOX_ID_LENGTH");
+    if (id.startsWith("-") || id.endsWith("-"))
+        throw new SandboxSecurityError("Sandbox ID cannot start or end with hyphens (DNS requirement).", "INVALID_SANDBOX_ID_HYPHENS");
+    if (["www", "api", "admin", "root", "system", "cloudflare", "workers"].includes(id.toLowerCase()))
+        throw new SandboxSecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
+    return id;
+}
+const cleanEnv = (env = {}) => Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== undefined));
+function sleepSeconds(value = 600) {
+    let seconds;
+    if (typeof value === "number")
+        seconds = value;
+    else {
+        const match = /^(\d+)(s|m|h)$/.exec(value);
+        if (!match)
+            throw new TypeError("sleepAfter must be seconds or a duration such as 5m");
+        seconds = Number(match[1]) * ({ s: 1, m: 60, h: 3600 }[match[2]] ?? 1);
+    }
+    if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > 86_400)
+        throw new CompatibilityError("Cloudflare", "sleepAfter outside whole seconds from 0 to 86400");
+    return seconds;
+}
+export function validateSandboxConfiguration(options) {
+    if (options.sleepAfter !== undefined)
+        sleepSeconds(options.sleepAfter);
+    if (options.keepAlive !== undefined && typeof options.keepAlive !== "boolean")
+        throw new TypeError("keepAlive must be a boolean");
+}
+/** Worker bindings are deliberately not inspected or invoked. Supply Runtime credentials
+ * through options.runtime in Workers; Node also supports RUNTIME_API_KEY/login. */
+export function getSandbox(namespace, id, options = {}) {
+    sanitizeSandboxId(id);
+    only("Cloudflare getSandbox", options, ["sleepAfter", "keepAlive", "normalizeId", "runtime"]);
+    const runtime = namespace instanceof Runtime ? namespace : client(options.runtime);
+    return new Sandbox(runtime, options.normalizeId ? id.toLowerCase() : id, options);
+}
+export class Sandbox {
+    runtime;
+    options;
+    pending;
+    existing;
+    id;
+    constructor(runtime, id, options = {}) {
+        this.runtime = runtime;
+        this.options = options;
+        validateSandboxConfiguration(options);
+        this.id = id;
+    }
+    async configure(options) {
+        only("Cloudflare configure", options, ["sleepAfter", "keepAlive"]);
+        validateSandboxConfiguration(options);
+        const changed = (options.sleepAfter !== undefined && options.sleepAfter !== this.options.sleepAfter) ||
+            (options.keepAlive !== undefined && options.keepAlive !== this.options.keepAlive);
+        const next = { ...this.options, ...options };
+        if (changed && this.pending) {
+            const s = await this.pending;
+            await s.update({
+                idlePauseSeconds: next.keepAlive ? 0 : sleepSeconds(next.sleepAfter),
+                ...(options.keepAlive !== undefined ? { persistent: options.keepAlive } : {}),
+            });
+        }
+        Object.assign(this.options, options);
+    }
+    /** Only a successfully initialized native handle can supply a recovery id. */
+    existingNativeId() {
+        return this.existing?.id;
+    }
+    /** Reconcile an uncertain update from an authoritative read, without allocation. */
+    async reconcileConfiguration(nativeId = this.existingNativeId()) {
+        if (!nativeId)
+            throw new Error("The uncertain Runtime configuration has no existing sandbox identity.");
+        const sandbox = await this.runtime.sandboxes.get(nativeId);
+        const { idlePauseSeconds, persistent } = sandbox.info;
+        if (typeof idlePauseSeconds !== "number" ||
+            !Number.isSafeInteger(idlePauseSeconds) ||
+            idlePauseSeconds < 0 ||
+            idlePauseSeconds > 86_400 ||
+            typeof persistent !== "boolean")
+            throw new Error("Runtime did not return authoritative idle and persistence settings.");
+        const configuration = { sleepAfter: idlePauseSeconds, keepAlive: persistent };
+        Object.assign(this.options, configuration);
+        this.existing = sandbox;
+        this.pending = Promise.resolve(sandbox);
+        return configuration;
+    }
+    async native() {
+        if (!this.pending) {
+            this.pending = (async () => {
+                const s = await this.runtime.sandboxes.create({
+                    name: /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(this.id)
+                        ? this.id
+                        : `cf-${createHash("sha256").update(this.id).digest("hex").slice(0, 40)}`,
+                    getOrCreate: true,
+                    labels: { "compat.provider": "cloudflare" },
+                    idlePauseSeconds: this.options.keepAlive ? 0 : sleepSeconds(this.options.sleepAfter),
+                    persistent: !!this.options.keepAlive,
+                });
+                if (!s.info.reused) {
+                    try {
+                        await saveEnvironment(s, {});
+                    }
+                    catch (e) {
+                        await destroy(s);
+                        throw e;
+                    }
+                }
+                this.existing = s;
+                return s;
+            })();
+            this.pending.catch(() => {
+                this.pending = undefined;
+            });
+        }
+        return this.pending;
+    }
+    session(id = `sandbox-${this.id}`, options = {}) {
+        return new ExecutionSession(this, id, options);
+    }
+    exec(command, options) {
+        return this.session().exec(command, options);
+    }
+    execStream(command, options) {
+        return this.session().execStream(command, options);
+    }
+    startProcess(command, options = {}) {
+        return this.session(options.sessionId).startProcess(command, options);
+    }
+    async createSession(options = {}) {
+        only("Cloudflare session", options, [
+            "id",
+            "name",
+            "env",
+            "cwd",
+            "isolation",
+            "commandTimeoutMs",
+        ]);
+        if (options.isolation)
+            throw new CompatibilityError("Cloudflare", "session PID namespace isolation");
+        const id = options.id ?? crypto.randomUUID();
+        await (await this.native()).files.write(`/workspace/.runtime-compat/cloudflare/${encodeURIComponent(id)}.json`, JSON.stringify(options), { mode: 0o600 });
+        return this.session(id, options);
+    }
+    async getSession(id) {
+        if (id === `sandbox-${this.id}`)
+            return this.session();
+        const options = JSON.parse(await (await this.native()).files.readText(`/workspace/.runtime-compat/cloudflare/${encodeURIComponent(id)}.json`));
+        return this.session(id, options);
+    }
+    async deleteSession(id) {
+        if (id === `sandbox-${this.id}`)
+            throw new Error("The default session cannot be deleted; destroy the sandbox instead");
+        await closeShell(await this.native(), `cf:${id}`);
+        await (await this.native()).files.remove(`/workspace/.runtime-compat/cloudflare/${encodeURIComponent(id)}.json`);
+        return { success: true, sessionId: id, timestamp: new Date().toISOString() };
+    }
+    async destroy() {
+        await destroy(await this.native());
+        this.pending = undefined;
+    }
+    async setEnvVars(env) {
+        const s = await this.native();
+        await saveEnvironment(s, { ...(await environment(s)), ...cleanEnv(env) });
+    }
+    writeFile(path, content, options) {
+        return this.session().writeFile(path, content, options);
+    }
+    readFile(path, options) {
+        return options?.encoding === "none"
+            ? this.session().readFile(path, { encoding: "none" })
+            : this.session().readFile(path, options);
+    }
+    mkdir(path, options) {
+        return this.session().mkdir(path, options);
+    }
+    deleteFile(path) {
+        return this.session().deleteFile(path);
+    }
+    renameFile(from, to) {
+        return this.session().renameFile(from, to);
+    }
+    moveFile(from, to) {
+        return this.renameFile(from, to);
+    }
+    listFiles(path, options) {
+        return this.session().listFiles(path, options);
+    }
+    exists(path) {
+        return this.session().exists(path);
+    }
+    async listProcesses() {
+        const s = await this.native();
+        return Promise.all((await s.processes.list()).map((p) => s.processes.get(p.id).then((p) => new Process(this, p))));
+    }
+    async getProcess(id) {
+        try {
+            return new Process(this, await (await this.native()).processes.get(id));
+        }
+        catch (e) {
+            if (e instanceof NotFoundError)
+                return null;
+            throw e;
+        }
+    }
+    async killProcess(id, signal = "SIGTERM") {
+        const p = await this.getProcess(id);
+        if (!p)
+            throw new Error(`Process ${id} not found`);
+        await p.kill(signal);
+    }
+    async killAllProcesses() {
+        const processes = (await this.listProcesses()).filter((p) => p.status === "running");
+        await Promise.all(processes.map((p) => p.kill()));
+        return processes.length;
+    }
+    async getProcessLogs(id) {
+        const s = await this.native();
+        let cursor = 0;
+        let stdout = "", stderr = "";
+        for (;;) {
+            const r = await this.runtime.transport.json({
+                method: "GET",
+                path: `/v1/sandboxes/${encodeURIComponent(s.id)}/processes/${encodeURIComponent(id)}/output`,
+                query: { cursor, maxBytes: 196608 },
+            });
+            if (r.truncated)
+                throw new Error("Process logs were truncated by the host");
+            for (const c of r.chunks) {
+                if (c.stream === "stdout")
+                    stdout += c.text;
+                else
+                    stderr += c.text;
+            }
+            if (r.chunks.length === 0 || r.nextCursor <= cursor)
+                break;
+            cursor = r.nextCursor;
+        }
+        return { stdout, stderr, processId: id };
+    }
+    async exposePort(port, options) {
+        only("Cloudflare exposePort", options, ["name", "hostname", "token"]);
+        if (options.token)
+            throw new CompatibilityError("Cloudflare", "caller-chosen preview tokens");
+        const p = await (await this.native()).previews.create(port);
+        // Cloudflare's hostname routes through its Worker. Runtime returns its own signed URL.
+        return { url: p.urlWithToken ?? p.url, port, name: options.name };
+    }
+    async unexposePort(port) {
+        await (await this.native()).previews.delete(port);
+    }
+}
+export class ExecutionSession {
+    sandbox;
+    id;
+    options;
+    constructor(sandbox, id, options) {
+        this.sandbox = sandbox;
+        this.id = id;
+        this.options = options;
+    }
+    async context(options = {}) {
+        only("Cloudflare exec", options, [
+            "timeout",
+            "env",
+            "cwd",
+            "encoding",
+            "stream",
+            "onOutput",
+            "onComplete",
+            "onError",
+            "signal",
+        ]);
+        if (options.encoding && !["utf8", "utf-8"].includes(options.encoding))
+            throw new CompatibilityError("Cloudflare", `process encoding ${options.encoding}`);
+        const s = await this.sandbox.native();
+        return {
+            s,
+            options: await execOptions(s, {
+                cwd: options.cwd ?? this.options.cwd,
+                env: { ...cleanEnv(this.options.env), ...cleanEnv(options.env) },
+                timeoutMs: options.timeout ?? this.options.commandTimeoutMs,
+                signal: options.signal,
+                onStdout: (data) => {
+                    if (options.stream)
+                        options.onOutput?.("stdout", data);
+                },
+                onStderr: (data) => {
+                    if (options.stream)
+                        options.onOutput?.("stderr", data);
+                },
+            }),
+        };
+    }
+    async exec(command, options = {}) {
+        options.signal?.throwIfAborted();
+        const started = Date.now();
+        try {
+            const c = await this.context(options);
+            const r = await c.s.exec(await shellCommand(c.s, command, `cf:${this.id}`, {
+                env: { ...cleanEnv(this.options.env), ...cleanEnv(options.env) },
+                cwd: options.cwd,
+            }), c.options);
+            const result = {
+                success: r.exitCode === 0 && !r.timedOut,
+                exitCode: r.exitCode ?? -1,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                command,
+                duration: Date.now() - started,
+                timestamp: new Date(started).toISOString(),
+                sessionId: this.id,
+            };
+            if (options.stream)
+                options.onComplete?.(result);
+            return result;
+        }
+        catch (e) {
+            options.onError?.(e instanceof Error ? e : new Error(String(e)));
+            throw e;
+        }
+    }
+    async execStream(command, options = {}) {
+        const encode = new TextEncoder();
+        const started = new Date().toISOString();
+        const run = this.exec.bind(this);
+        const sessionId = this.id;
+        const cancellation = new AbortController();
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, cancellation.signal])
+            : cancellation.signal;
+        return new ReadableStream({
+            async start(controller) {
+                const send = (event) => {
+                    if (!signal.aborted)
+                        controller.enqueue(encode.encode(`data: ${JSON.stringify(event)}\n\n`));
+                };
+                try {
+                    send({ type: "start", command, timestamp: started, sessionId: sessionId });
+                    const result = await run(command, {
+                        ...options,
+                        signal,
+                        stream: true,
+                        onOutput: (type, data) => send({ type, data, timestamp: new Date().toISOString(), sessionId: sessionId }),
+                    });
+                    send({
+                        type: "complete",
+                        result,
+                        exitCode: result.exitCode,
+                        timestamp: new Date().toISOString(),
+                    });
+                    if (!cancellation.signal.aborted)
+                        controller.close();
+                }
+                catch (error) {
+                    if (!cancellation.signal.aborted)
+                        controller.error(error);
+                }
+            },
+            cancel(reason) {
+                cancellation.abort(reason);
+            },
+        });
+    }
+    async startProcess(command, options = {}) {
+        only("Cloudflare startProcess", options, [
+            "timeout",
+            "env",
+            "cwd",
+            "encoding",
+            "sessionId",
+            "onOutput",
+            "onExit",
+            "onStart",
+            "onError",
+        ]);
+        const c = await this.context({
+            timeout: options.timeout,
+            env: options.env,
+            cwd: options.cwd,
+            encoding: options.encoding,
+        });
+        const { stdin: _stdin, ...spawnOptions } = c.options;
+        const p = await c.s.spawn(await shellCommand(c.s, command, `cf:${this.id}`, {
+            env: { ...cleanEnv(this.options.env), ...cleanEnv(options.env) },
+            cwd: options.cwd,
+            persist: false,
+        }), spawnOptions);
+        const process = new Process(this.sandbox, p, this.id);
+        options.onStart?.(process);
+        if (options.onOutput || options.onExit || options.onError)
+            void (async () => {
+                for await (const e of p.output())
+                    if (e.type === "stdout" || e.type === "stderr")
+                        options.onOutput?.(e.type, e.data);
+                    else if (e.type === "exit")
+                        options.onExit?.(e.exitCode);
+                    else if (e.type === "truncated")
+                        throw new Error("Process output was truncated");
+            })().catch((e) => options.onError?.(e instanceof Error ? e : new Error(String(e))));
+        return process;
+    }
+    async path(path) {
+        if (path.startsWith("/"))
+            return path;
+        let cwd = this.options.cwd ?? "/workspace";
+        try {
+            cwd = await (await this.sandbox.native()).files.readText(`${await shellRoot(`cf:${this.id}`)}/cwd`);
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+        }
+        return pathAt(path, cwd);
+    }
+    async writeFile(path, content, options = {}) {
+        if (options.encoding && !["utf8", "utf-8", "base64"].includes(options.encoding))
+            throw new CompatibilityError("Cloudflare", `file encoding ${options.encoding}`);
+        let bytes;
+        if (typeof content === "string")
+            bytes =
+                options.encoding === "base64"
+                    ? Uint8Array.from(atob(content), (c) => c.charCodeAt(0))
+                    : new TextEncoder().encode(content);
+        else {
+            const buffer = await new Response(content).arrayBuffer();
+            bytes = new Uint8Array(buffer);
+        }
+        await (await this.sandbox.native()).files.write(await this.path(path), bytes);
+        return { success: true, path, bytesWritten: bytes.length, timestamp: new Date().toISOString() };
+    }
+    async readFile(path, options = {}) {
+        const s = await this.sandbox.native(), bytes = await s.files.read(await this.path(path));
+        if (options.encoding === "none")
+            return {
+                success: true,
+                path,
+                content: new ReadableStream({
+                    start(c) {
+                        c.enqueue(bytes);
+                        c.close();
+                    },
+                }),
+                size: bytes.length,
+                mimeType: "application/octet-stream",
+                timestamp: new Date().toISOString(),
+            };
+        const text = new TextDecoder().decode(bytes), binary = text.includes("\0") || text.includes("\ufffd"), encoded = options.encoding === "base64" || (options.encoding === undefined && binary);
+        let raw = "";
+        if (encoded)
+            for (let i = 0; i < bytes.length; i += 32768)
+                raw += String.fromCharCode(...bytes.subarray(i, i + 32768));
+        return {
+            success: true,
+            path,
+            content: encoded ? btoa(raw) : text,
+            encoding: encoded ? "base64" : "utf-8",
+            isBinary: binary,
+            size: bytes.length,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    async mkdir(path, options = {}) {
+        await (await this.sandbox.native()).files.mkdir(await this.path(path), { parents: options.recursive });
+        return { success: true, path, timestamp: new Date().toISOString() };
+    }
+    async deleteFile(path) {
+        await (await this.sandbox.native()).files.remove(await this.path(path));
+        return { success: true, path, timestamp: new Date().toISOString() };
+    }
+    async renameFile(path, newPath) {
+        await (await this.sandbox.native()).files.rename(await this.path(path), await this.path(newPath));
+        return { success: true, path, newPath, timestamp: new Date().toISOString() };
+    }
+    async exists(path) {
+        return {
+            success: true,
+            path,
+            exists: await (await this.sandbox.native()).files.exists(await this.path(path)),
+            timestamp: new Date().toISOString(),
+        };
+    }
+    async listFiles(path, options = {}) {
+        const s = await this.sandbox.native();
+        const directory = await this.path(path);
+        const entries = await s.files.list(directory, { hidden: options.includeHidden });
+        if (options.recursive) {
+            for (let i = 0; i < entries.length; i++)
+                if (entries[i].type === "directory")
+                    entries.push(...(await s.files.list(entries[i].path, { hidden: options.includeHidden })));
+        }
+        const files = entries.map((e) => ({
+            ...e,
+            absolutePath: e.path,
+            relativePath: e.path.slice(directory.replace(/\/$/, "").length + 1),
+            permissions: {
+                readable: !!(parseInt(e.mode, 8) & 0o444),
+                writable: !!(parseInt(e.mode, 8) & 0o222),
+                executable: !!(parseInt(e.mode, 8) & 0o111),
+            },
+        }));
+        return { success: true, path, files, count: files.length, timestamp: new Date().toISOString() };
+    }
+    async setEnvVars(env) {
+        this.options = { ...this.options, env: { ...this.options.env, ...cleanEnv(env) } };
+        await (await this.sandbox.native()).files.write(`/workspace/.runtime-compat/cloudflare/${encodeURIComponent(this.id)}.json`, JSON.stringify(this.options), { mode: 0o600 });
+    }
+}
+export class Process {
+    sandbox;
+    native;
+    sessionId;
+    constructor(sandbox, native, sessionId) {
+        this.sandbox = sandbox;
+        this.native = native;
+        this.sessionId = sessionId;
+    }
+    get id() {
+        return this.native.id;
+    }
+    get command() {
+        return this.native.info.command;
+    }
+    get status() {
+        return this.native.info.state === "exited"
+            ? this.native.info.exitCode === 0
+                ? "completed"
+                : "failed"
+            : this.native.info.state === "timed_out"
+                ? "failed"
+                : this.native.info.state;
+    }
+    get startTime() {
+        return new Date(this.native.info.startedAt);
+    }
+    get endTime() {
+        return this.native.info.endedAt ? new Date(this.native.info.endedAt) : undefined;
+    }
+    get exitCode() {
+        return this.native.info.exitCode ?? undefined;
+    }
+    async kill(signal = "SIGTERM") {
+        if (!["SIGTERM", "SIGKILL", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2"].includes(signal))
+            throw new TypeError(`Unsupported signal ${signal}`);
+        await this.native.kill(signal);
+    }
+    async getStatus() {
+        await this.native.refresh();
+        return this.status;
+    }
+    getLogs() {
+        return this.sandbox.getProcessLogs(this.id);
+    }
+    async waitForExit(timeout) {
+        const r = await this.native.wait({
+            signal: timeout ? AbortSignal.timeout(timeout) : undefined,
+        });
+        return { exitCode: r.exitCode ?? -1 };
+    }
+    async waitForLog(pattern, timeout = 30000) {
+        let output = "";
+        for await (const e of this.native.output({ signal: AbortSignal.timeout(timeout) })) {
+            if (e.type === "stdout" || e.type === "stderr") {
+                output += e.data;
+                const match = typeof pattern === "string" ? output.includes(pattern) : output.match(pattern);
+                if (match)
+                    return {
+                        line: output
+                            .split("\n")
+                            .find((line) => typeof pattern === "string"
+                            ? line.includes(pattern)
+                            : new RegExp(pattern.source, pattern.flags.replace("g", "")).test(line)) ?? output,
+                        ...(typeof pattern === "string" ? {} : { match }),
+                    };
+            }
+        }
+        throw new Error("Process exited before expected output");
+    }
+}