withruntime 0.8.4 → 0.9.0

package/dist/sprites/index.js

@@ -0,0 +1,552 @@
+import { EventEmitter } from "node:events";
+import { PassThrough, Writable } from "node:stream";
+import { RuntimeError } from "../errors.js";
+import { all, client, CompatibilityError, create, destroy, execOptions, lookup, only, ready, region, } from "../compat/core.js";
+import { GuestFiles } from "../compat/files.js";
+export { CompatibilityError };
+export class FilesystemError extends Error {
+    code;
+    path;
+    syscall;
+    constructor(message, code, path, syscall) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.syscall = syscall;
+        this.name = "FilesystemError";
+    }
+}
+async function fileOperation(path, syscall, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeError))
+            throw error;
+        const codes = {
+            file_not_found: "ENOENT",
+            not_found: "ENOENT",
+            already_exists: "EEXIST",
+            file_exists: "EEXIST",
+            not_a_directory: "ENOTDIR",
+            is_a_directory: "EISDIR",
+            permission_denied: "EACCES",
+            directory_not_empty: "ENOTEMPTY",
+            invalid_request: "EINVAL",
+        };
+        throw new FilesystemError(error.message, codes[error.code] ?? (error.status === 404 ? "ENOENT" : "UNKNOWN"), path, syscall);
+    }
+}
+export class ExecError extends Error {
+    exitCode;
+    stdout;
+    stderr;
+    constructor(message, exitCode, stdout, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.name = "ExecError";
+    }
+}
+export class SpritesClient {
+    runtime;
+    constructor(token, options = {}) {
+        only("Sprites client", options, [
+            "apiKey",
+            "baseUrl",
+            "baseURL",
+            "timeout",
+            "timeoutMs",
+            "maxRetries",
+            "fetch",
+            "client",
+            "controlMode",
+            "waitForCapacityMs",
+        ]);
+        if (options.controlMode)
+            throw new CompatibilityError("Sprites", "control-mode wire protocol");
+        this.runtime = client({
+            ...options,
+            apiKey: options.apiKey ?? token,
+            baseUrl: options.baseUrl ?? options.baseURL,
+            timeoutMs: options.timeoutMs ?? options.timeout,
+        });
+    }
+    sprite(name) {
+        return new Sprite(name, this);
+    }
+    async createSprite(name, input = {}, extra = {}) {
+        const o = ["ramMB", "cpus", "region", "storageGB"].some((k) => k in input)
+            ? { ...extra, config: input }
+            : { ...input, ...extra };
+        only("Sprites create", o, [
+            "config",
+            "environment",
+            "labels",
+            "urlSettings",
+            "runtime",
+            "waitForCapacity",
+        ]);
+        if (o.runtime !== undefined)
+            throw new CompatibilityError("Sprites", `vendor runtime image ${o.runtime}; import it into Runtime first`);
+        if (o.urlSettings?.privateAccess)
+            throw new CompatibilityError("Sprites", "privateAccess roles");
+        const c = o.config ?? {};
+        only("Sprites config", c, ["ramMB", "cpus", "region", "storageGB"]);
+        const s = await create(this.runtime, "sprites", {
+            name,
+            persistent: true,
+            vcpu: c.cpus,
+            memoryMiB: c.ramMB,
+            diskMiB: c.storageGB === undefined ? undefined : Math.ceil((c.storageGB * 1e9) / 1048576),
+            region: region("Sprites", c.region),
+            labels: { "compat.labels": JSON.stringify(o.labels ?? []) },
+        }, o.environment);
+        const sprite = new Sprite(name, this);
+        sprite.hydrate(s);
+        if (o.urlSettings) {
+            try {
+                await sprite.updateURLSettings(o.urlSettings);
+            }
+            catch (e) {
+                await destroy(s);
+                throw e;
+            }
+        }
+        return sprite;
+    }
+    async getSprite(name) {
+        const sprite = this.sprite(name);
+        sprite.hydrate(await lookup(this.runtime, name));
+        return sprite;
+    }
+    async deleteSprite(name) {
+        await destroy(await lookup(this.runtime, name));
+    }
+    async listSprites(options = {}) {
+        only("Sprites list", options, ["prefix", "maxResults", "continuationToken", "bulkLoad"]);
+        const values = (await all(this.runtime, "sprites")).filter((s) => (s.info.name ?? s.id).startsWith(options.prefix ?? ""));
+        const offset = Number(options.continuationToken ?? 0), limit = options.maxResults ?? 100;
+        return {
+            sprites: values.slice(offset, offset + limit).map((s) => ({
+                id: s.id,
+                name: s.info.name ?? s.id,
+                status: s.state,
+                createdAt: new Date(s.info.createdAt),
+                updatedAt: new Date(s.info.createdAt),
+                config: {
+                    cpus: s.info.vcpu,
+                    ramMB: s.info.memoryMiB,
+                    storageGB: (s.info.diskMiB * 1048576) / 1e9,
+                    region: s.info.region,
+                },
+            })),
+            hasMore: offset + limit < values.length,
+            nextContinuationToken: offset + limit < values.length ? String(offset + limit) : undefined,
+        };
+    }
+    async listAllSprites(prefix) {
+        return (await all(this.runtime, "sprites"))
+            .filter((s) => (s.info.name ?? s.id).startsWith(prefix ?? ""))
+            .map((s) => {
+            const sprite = this.sprite(s.info.name ?? s.id);
+            sprite.hydrate(s);
+            return sprite;
+        });
+    }
+    async restartSprite(name) {
+        const s = await lookup(this.runtime, name);
+        await s.stop();
+        await s.restart();
+        return { spriteName: name, machineId: s.id, message: "Restarted" };
+    }
+    updateURLSettings(name, settings) {
+        return this.sprite(name).updateURLSettings(settings);
+    }
+}
+export class Sprite {
+    name;
+    client;
+    id;
+    status;
+    config;
+    createdAt;
+    updatedAt;
+    url;
+    labels = [];
+    constructor(name, client) {
+        this.name = name;
+        this.client = client;
+    }
+    hydrate(s) {
+        this.id = s.id;
+        this.status = s.state;
+        this.config = {
+            cpus: s.info.vcpu,
+            ramMB: s.info.memoryMiB,
+            region: s.info.region,
+            storageGB: (s.info.diskMiB * 1048576) / 1e9,
+        };
+        this.createdAt = new Date(s.info.createdAt);
+        this.updatedAt = this.createdAt;
+        this.labels = JSON.parse(s.info.labels["compat.labels"] ?? "[]");
+    }
+    async native() {
+        const s = await lookup(this.client.runtime, this.id ?? this.name);
+        this.hydrate(s);
+        return s;
+    }
+    spawn(command, args = [], options = {}) {
+        return new SpriteCommand(this, command, args, options);
+    }
+    exec(command, options) {
+        return this.execFile("bash", ["-c", command], options);
+    }
+    async execFile(file, args = [], options = {}) {
+        options.signal?.throwIfAborted();
+        if (options.encoding &&
+            options.encoding !== "buffer" &&
+            !Buffer.isEncoding(options.encoding))
+            throw new TypeError(`Unknown encoding: ${String(options.encoding)}`);
+        only("Sprites exec", options, [
+            "cwd",
+            "env",
+            "tty",
+            "rows",
+            "cols",
+            "detachable",
+            "sessionId",
+            "controlMode",
+            "encoding",
+            "maxBuffer",
+            "signal",
+            "timeout",
+        ]);
+        if (options.controlMode)
+            throw new CompatibilityError("Sprites", "control-mode wire protocol");
+        const cmd = this.spawn(file, args, options);
+        const out = [], err = [];
+        let bytes = 0;
+        let failure;
+        const capture = (target) => (chunk) => {
+            bytes += chunk.length;
+            if (bytes > (options.maxBuffer ?? 10 * 1024 * 1024)) {
+                failure = new Error("maxBuffer exceeded");
+                cmd.kill("SIGKILL");
+            }
+            else
+                target.push(chunk);
+        };
+        cmd.stdout.on("data", capture(out));
+        cmd.stderr.on("data", capture(err));
+        const abort = () => {
+            failure = new Error("Command aborted");
+            cmd.kill("SIGTERM");
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const timer = options.timeout ? setTimeout(abort, options.timeout) : undefined;
+        try {
+            const exitCode = await cmd.wait();
+            if (failure)
+                throw failure;
+            const stdout = Buffer.concat(out), stderr = Buffer.concat(err);
+            const r = {
+                stdout: options.encoding === "buffer"
+                    ? stdout
+                    : stdout.toString(options.encoding ?? "utf8"),
+                stderr: options.encoding === "buffer"
+                    ? stderr
+                    : stderr.toString(options.encoding ?? "utf8"),
+                exitCode,
+            };
+            if (exitCode !== 0)
+                throw new ExecError(`Command exited with code ${exitCode}`, exitCode, r.stdout, r.stderr);
+            return r;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+        }
+    }
+    execFileHTTP(file, args, options) {
+        return this.execFile(file, args, options);
+    }
+    createSession(command, args = [], options = {}) {
+        return this.spawn(command, args, { ...options, detachable: true });
+    }
+    attachSession(sessionId, options = {}) {
+        return this.spawn("", [], { ...options, sessionId });
+    }
+    async listSessions() {
+        return (await (await this.native()).processes.list())
+            .filter((p) => p.state === "running")
+            .map((p) => ({
+            id: p.id,
+            command: p.command,
+            created: new Date(p.startedAt),
+            workdir: p.cwd,
+            isActive: p.state === "running",
+            tty: p.pty,
+        }));
+    }
+    delete() {
+        return this.client.deleteSprite(this.id ?? this.name);
+    }
+    destroy() {
+        return this.delete();
+    }
+    restart() {
+        return this.client.restartSprite(this.id ?? this.name);
+    }
+    filesystem(workingDir = "/") {
+        return new SpriteFilesystem(() => this.native(), workingDir);
+    }
+    async createCheckpoint(_comment) {
+        throw new CompatibilityError("Sprites", "filesystem-only checkpoints; Runtime snapshots also include running memory");
+    }
+    async listCheckpoints() {
+        throw new CompatibilityError("Sprites", "filesystem-only checkpoints");
+    }
+    async getCheckpoint(_id) {
+        throw new CompatibilityError("Sprites", "filesystem-only checkpoints");
+    }
+    async updateURLSettings(settings) {
+        only("Sprites URL settings", settings, ["auth"]);
+        if (settings.auth !== "public" && settings.auth !== "sprite")
+            throw new TypeError("auth must be public or sprite");
+        const p = await (await this.native()).previews.create(8080, { visibility: settings.auth === "public" ? "public" : "private" });
+        this.url = p.urlWithToken ?? p.url;
+    }
+    async update(options) {
+        only("Sprites update", options, ["labels", "urlSettings"]);
+        const s = await this.native();
+        if (options.labels)
+            await s.update({
+                labels: { ...s.info.labels, "compat.labels": JSON.stringify(options.labels) },
+            });
+        if (options.urlSettings)
+            await this.updateURLSettings(options.urlSettings);
+        this.hydrate(s);
+        return this;
+    }
+}
+export class SpriteCommand extends EventEmitter {
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    stdin;
+    process;
+    completion;
+    code = -1;
+    controller = new AbortController();
+    constructor(sprite, command, args = [], options = {}) {
+        super();
+        only("Sprites spawn", options, [
+            "cwd",
+            "env",
+            "tty",
+            "rows",
+            "cols",
+            "detachable",
+            "sessionId",
+            "controlMode",
+            "encoding",
+            "maxBuffer",
+            "signal",
+            "timeout",
+        ]);
+        if (options.controlMode)
+            throw new CompatibilityError("Sprites", "control-mode wire protocol");
+        this.process = (async () => {
+            const s = await ready(await sprite.native());
+            return options.sessionId
+                ? s.processes.get(options.sessionId)
+                : s.spawn([command, ...args], {
+                    ...(await execOptions(s, { cwd: options.cwd, env: options.env })),
+                    stdin: "pipe",
+                    outputEncoding: "base64",
+                    pty: options.tty ? { rows: options.rows, cols: options.cols } : undefined,
+                });
+        })();
+        this.stdin = new Writable({
+            write: (chunk, _encoding, callback) => {
+                void this.process.then((p) => p.write(chunk)).then(() => callback(), callback);
+            },
+            final: (callback) => {
+                void this.process.then((p) => p.write("", { eof: true })).then(() => callback(), callback);
+            },
+        });
+        this.completion = this.follow();
+        this.completion.catch((error) => {
+            if (this.listenerCount("error"))
+                this.emit("error", error);
+        });
+    }
+    async follow() {
+        try {
+            const p = await this.process;
+            this.emit("spawn");
+            this.emit("session", p.id);
+            for await (const e of p.outputBytes({ signal: this.controller.signal })) {
+                if (e.type === "stdout")
+                    this.stdout.write(e.data);
+                else if (e.type === "stderr")
+                    this.stderr.write(e.data);
+                else if (e.type === "truncated")
+                    throw new Error("Sprite command output was truncated");
+                else if (e.type === "exit")
+                    this.code = e.exitCode ?? -1;
+            }
+            this.emit("exit", this.code);
+            this.emit("close", this.code);
+            return this.code;
+        }
+        finally {
+            this.stdout.end();
+            this.stderr.end();
+        }
+    }
+    async start() {
+        await this.process;
+    }
+    wait() {
+        return this.completion;
+    }
+    kill(signal = "SIGTERM") {
+        this.signal(signal);
+    }
+    signal(signal) {
+        if (!["SIGTERM", "SIGKILL", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2"].includes(signal))
+            throw new TypeError(`Unsupported signal ${signal}`);
+        void this.process
+            .then((p) => p.kill(signal))
+            .catch((error) => {
+            if (this.listenerCount("error"))
+                this.emit("error", error);
+        });
+    }
+    resize(cols, rows) {
+        void this.process
+            .then((p) => p.resize(cols, rows))
+            .catch((error) => {
+            if (this.listenerCount("error"))
+                this.emit("error", error);
+        });
+    }
+    close() {
+        this.controller.abort();
+    }
+    exitCode() {
+        return this.code;
+    }
+}
+export class SpriteFilesystem {
+    get;
+    files;
+    constructor(get, cwd = "/") {
+        this.get = get;
+        this.files = new GuestFiles(get, cwd);
+    }
+    async readFile(path, encoding) {
+        const bytes = Buffer.from(await fileOperation(path, "read", () => this.files.readFile(path)));
+        return encoding === "utf8" ? bytes.toString("utf8") : bytes;
+    }
+    writeFile(path, data, options) {
+        return fileOperation(path, "write", () => this.files.writeFile(path, data, options));
+    }
+    async readdir(path, options = {}) {
+        only("Sprites readdir", options, ["withFileTypes", "recursive", "pattern", "encoding"]);
+        if (options.encoding && options.encoding !== "utf8")
+            throw new CompatibilityError("Sprites", "directory name encodings other than utf8");
+        const s = await this.get();
+        const entries = await s.files.list(this.files.path(path), {
+            hidden: true,
+            glob: options.pattern,
+        });
+        if (options.recursive) {
+            if (options.pattern)
+                throw new CompatibilityError("Sprites", "recursive listing with a glob pattern");
+            for (let i = 0; i < entries.length; i++)
+                if (entries[i].type === "directory")
+                    entries.push(...(await s.files.list(entries[i].path, { hidden: true })));
+        }
+        return entries.map((e) => options.withFileTypes
+            ? {
+                name: e.name,
+                parentPath: path,
+                isDirectory: () => e.type === "directory",
+                isFile: () => e.type === "file",
+                isSymbolicLink: () => e.type === "symlink",
+            }
+            : e.name);
+    }
+    async mkdir(path, options = {}) {
+        await fileOperation(path, "mkdir", () => this.files.mkdir(path, options.recursive));
+        if (options.mode !== undefined)
+            await this.files.chmod(path, options.mode);
+    }
+    async rm(path, options = {}) {
+        if (!options.force && !(await this.files.exists(path)))
+            throw new FilesystemError(`Path not found: ${path}`, "ENOENT", path, "rm");
+        await fileOperation(path, "rm", () => this.files.remove(path, options.recursive));
+    }
+    async stat(path) {
+        const e = await fileOperation(path, "stat", () => this.files.stat(path));
+        return {
+            size: e.size,
+            mode: parseInt(e.mode, 8),
+            mtime: new Date(e.modifiedAt),
+            atime: new Date(e.modifiedAt),
+            birthtime: new Date(e.modifiedAt),
+            isDirectory: () => e.type === "directory",
+            isFile: () => e.type === "file",
+            isSymbolicLink: () => e.type === "symlink",
+        };
+    }
+    rename(from, to) {
+        return fileOperation(from, "rename", () => this.files.rename(from, to, true));
+    }
+    copyFile(from, to, options = {}) {
+        return fileOperation(from, "copyFile", () => this.files.copy(from, to, options.recursive, true));
+    }
+    chmod(path, mode, options = {}) {
+        return fileOperation(path, "chmod", () => this.files.chmod(path, mode, options.recursive));
+    }
+    exists(path) {
+        return this.files.exists(path);
+    }
+    appendFile(path, data) {
+        return fileOperation(path, "appendFile", () => this.files.appendFile(path, data));
+    }
+    async readJSON(path) {
+        return JSON.parse(await this.readFile(path, "utf8"));
+    }
+    writeJSON(path, data, options = {}) {
+        return this.writeFile(path, JSON.stringify(data, null, options.spaces));
+    }
+}
+export class CheckpointStream {
+    messages;
+    index = 0;
+    constructor(messages) {
+        this.messages = messages;
+    }
+    async next() {
+        return this.messages[this.index++] ?? null;
+    }
+    async processAll(handler) {
+        for await (const message of this)
+            await handler(message);
+    }
+    close() {
+        this.index = this.messages.length;
+    }
+    async *[Symbol.asyncIterator]() {
+        let message;
+        while ((message = await this.next()))
+            yield message;
+    }
+}

package/dist/tar.d.ts

@@ -1,4 +1,11 @@
 export declare function tarHeader(name: string, size: number, mode: number, type: "0" | "5" | "2", link?: string, mtime?: number): Uint8Array;
 export declare function packDirectory(root: string): Promise<Uint8Array>;
-/** Unpacks into `target`, refusing any entry that would land outside it. */
+/** Unpacks a gzipped tar that arrives as a stream into `target`, refusing any
+ * entry that would land outside it, holding no more than a chunk at a time.
+ * It unpacks into a folder beside the target and moves it into place only
+ * once the whole archive arrived, so an archive cut short leaves nothing
+ * behind that could pass for the folder. A target that exists is merged
+ * into, files of the same name replaced. */
+export declare function unpackStream(source: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, target: string): Promise<void>;
+/** Unpacks a whole gzipped tar held in memory, by the same rules. */
 export declare function unpackArchive(archive: Uint8Array, target: string): Promise<void>;