@boxd-sh/convex 0.1.0

package/dist/component/exec.js

@@ -0,0 +1,100 @@
+/**
+ * Run a command in a machine. Each run is recorded in `executions`
+ * (running → completed or failed), so the app can render live status and
+ * history from a reactive query.
+ *
+ * The call returns when the command exits. For work that can outlast the 10
+ * minute action ceiling, start it in the background inside the machine
+ * (`nohup ... &`) and poll it with later runs.
+ */
+import { v } from "convex/values";
+import { internal } from "./_generated/api.js";
+import { action } from "./_generated/server.js";
+import { withBoxd } from "./boxd.js";
+import { errorMessage, isNotFound } from "./errors.js";
+import { DEFAULT_EXEC_TIMEOUT_MS, MAX_EXEC_TIMEOUT_MS, MAX_RETURNED_OUTPUT, MAX_STORED_COMMAND, MAX_STORED_OUTPUT, truncate, } from "./limits.js";
+import { requireMachine } from "./records.js";
+import { boundedTimeout, requireAbsolutePath, requireNonEmpty, } from "./validate.js";
+const SAFE_ARG = /^[A-Za-z0-9_\-./=:@%+,]+$/;
+/** How the command reads in a shell, for the execution row. */
+function displayCommand(command) {
+    if (typeof command === "string")
+        return command;
+    return command
+        .map((arg) => SAFE_ARG.test(arg) ? arg : `'${arg.replace(/'/g, `'"'"'`)}'`)
+        .join(" ");
+}
+export const run = action({
+    args: {
+        machineId: v.string(),
+        ownerId: v.optional(v.string()),
+        /** A shell command line, or an argv array that is quoted for you. */
+        command: v.union(v.string(), v.array(v.string())),
+        /** Absolute working directory. A missing one fails the command. */
+        cwd: v.optional(v.string()),
+        /** Extra environment for this command only. Not stored. */
+        env: v.optional(v.record(v.string(), v.string())),
+        /** Kill the command after this many ms. Default 540s, capped at 570s. */
+        timeoutMs: v.optional(v.number()),
+    },
+    returns: v.object({
+        executionId: v.id("executions"),
+        exitCode: v.number(),
+        success: v.boolean(),
+        stdout: v.string(),
+        stderr: v.string(),
+    }),
+    handler: async (ctx, args) => {
+        // Validate before anything is recorded or sent.
+        const timeout = boundedTimeout(args.timeoutMs, DEFAULT_EXEC_TIMEOUT_MS, MAX_EXEC_TIMEOUT_MS, "timeoutMs");
+        if (args.cwd !== undefined)
+            requireAbsolutePath(args.cwd);
+        const line = displayCommand(args.command);
+        requireNonEmpty(line, "command");
+        const machine = await requireMachine(ctx, args.machineId, args.ownerId);
+        const executionId = await ctx.runMutation(internal.executions.begin, {
+            machineId: machine.machineId,
+            ownerId: machine.ownerId,
+            command: truncate(line, MAX_STORED_COMMAND),
+            cwd: args.cwd,
+            timeoutMs: timeout,
+        });
+        try {
+            const result = await withBoxd(ctx, (boxd) => boxd.machines.exec(machine.machineId, {
+                command: args.command,
+                cwd: args.cwd,
+                env: args.env,
+                timeout,
+            }));
+            await ctx.runMutation(internal.executions.finish, {
+                executionId,
+                status: "completed",
+                exitCode: result.exitCode,
+                stdout: truncate(result.stdout, MAX_STORED_OUTPUT),
+                stderr: truncate(result.stderr, MAX_STORED_OUTPUT),
+            });
+            return {
+                executionId,
+                exitCode: result.exitCode,
+                success: result.success,
+                stdout: truncate(result.stdout, MAX_RETURNED_OUTPUT),
+                stderr: truncate(result.stderr, MAX_RETURNED_OUTPUT),
+            };
+        }
+        catch (error) {
+            await ctx.runMutation(internal.executions.finish, {
+                executionId,
+                status: "failed",
+                error: errorMessage(error),
+            });
+            if (isNotFound(error)) {
+                // boxd no longer has the machine, e.g. after its auto-destroy timer.
+                await ctx.runMutation(internal.machines.markDestroyed, {
+                    machineId: machine.machineId,
+                });
+            }
+            throw error;
+        }
+    },
+});
+//# sourceMappingURL=exec.js.map

package/dist/component/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/component/exec.ts"],"names":[],"mappings":"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"}

package/dist/component/executions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Execution records: reactive queries over the `executions` table, plus the
+ * bookkeeping mutations `exec.run` writes through.
+ */
+/** A machine's executions, newest first. Empty for another owner's machine. */
+export declare const list: import("convex/server").RegisteredQuery<"public", {
+    ownerId?: string | undefined;
+    limit?: number | undefined;
+    machineId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"executions">;
+    _creationTime: number;
+    cwd?: string | undefined;
+    ownerId?: string | undefined;
+    exitCode?: number | undefined;
+    stdout?: string | undefined;
+    stderr?: string | undefined;
+    error?: string | undefined;
+    finishedAt?: number | undefined;
+    command: string;
+    machineId: string;
+    status: "running" | "completed" | "failed";
+    startedAt: number;
+}[]>>;
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    ownerId?: string | undefined;
+    executionId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"executions">;
+    _creationTime: number;
+    cwd?: string | undefined;
+    ownerId?: string | undefined;
+    exitCode?: number | undefined;
+    stdout?: string | undefined;
+    stderr?: string | undefined;
+    error?: string | undefined;
+    finishedAt?: number | undefined;
+    command: string;
+    machineId: string;
+    status: "running" | "completed" | "failed";
+    startedAt: number;
+} | null>>;
+/** Grace after the command's own timeout before the watchdog steps in. */
+export declare const WATCHDOG_GRACE_MS = 60000;
+/**
+ * Record a starting execution, and schedule a watchdog for it. The action
+ * marks the row finished itself, but an action that dies (a crash, a restart,
+ * running out of memory) never reaches its `catch`, and the row would stay
+ * "running" forever.
+ */
+export declare const begin: import("convex/server").RegisteredMutation<"internal", {
+    cwd?: string | undefined;
+    ownerId?: string | undefined;
+    command: string;
+    machineId: string;
+    timeoutMs: number;
+}, Promise<import("convex/values").GenericId<"executions">>>;
+/** Fail an execution whose action stopped before it could record a result. */
+export declare const expire: import("convex/server").RegisteredMutation<"internal", {
+    executionId: import("convex/values").GenericId<"executions">;
+}, Promise<null>>;
+export declare const finish: import("convex/server").RegisteredMutation<"internal", {
+    exitCode?: number | undefined;
+    stdout?: string | undefined;
+    stderr?: string | undefined;
+    error?: string | undefined;
+    executionId: import("convex/values").GenericId<"executions">;
+    status: "completed" | "failed";
+}, Promise<null>>;
+//# sourceMappingURL=executions.d.ts.map

package/dist/component/executions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executions.d.ts","sourceRoot":"","sources":["../../src/component/executions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,+EAA+E;AAC/E,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;KAmBf,CAAC;AAEH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;UAWd,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;4DAsBhB,CAAC;AAEH,8EAA8E;AAC9E,eAAO,MAAM,MAAM;;iBAejB,CAAC;AAEH,eAAO,MAAM,MAAM;;;;;;;iBAiBjB,CAAC"}

package/dist/component/executions.js

@@ -0,0 +1,106 @@
+/**
+ * Execution records: reactive queries over the `executions` table, plus the
+ * bookkeeping mutations `exec.run` writes through.
+ */
+import { v } from "convex/values";
+import { internal } from "./_generated/api.js";
+import { internalMutation, query } from "./_generated/server.js";
+import { clampLimit } from "./limits.js";
+import { executionDoc } from "./records.js";
+/** A machine's executions, newest first. Empty for another owner's machine. */
+export const list = query({
+    args: {
+        machineId: v.string(),
+        ownerId: v.optional(v.string()),
+        limit: v.optional(v.number()),
+    },
+    returns: v.array(executionDoc),
+    handler: async (ctx, { machineId, ownerId, limit }) => {
+        const machine = await ctx.db
+            .query("machines")
+            .withIndex("by_machine_id", (q) => q.eq("machineId", machineId))
+            .unique();
+        if (!machine || machine.ownerId !== ownerId)
+            return [];
+        return await ctx.db
+            .query("executions")
+            .withIndex("by_machine", (q) => q.eq("machineId", machineId))
+            .order("desc")
+            .take(clampLimit(limit));
+    },
+});
+export const get = query({
+    args: { executionId: v.string(), ownerId: v.optional(v.string()) },
+    returns: v.union(v.null(), executionDoc),
+    handler: async (ctx, { executionId, ownerId }) => {
+        // Ids cross the component boundary as strings; a malformed one is simply
+        // not found.
+        const id = ctx.db.normalizeId("executions", executionId);
+        if (!id)
+            return null;
+        const row = await ctx.db.get("executions", id);
+        return row && row.ownerId === ownerId ? row : null;
+    },
+});
+/** Grace after the command's own timeout before the watchdog steps in. */
+export const WATCHDOG_GRACE_MS = 60_000;
+/**
+ * Record a starting execution, and schedule a watchdog for it. The action
+ * marks the row finished itself, but an action that dies (a crash, a restart,
+ * running out of memory) never reaches its `catch`, and the row would stay
+ * "running" forever.
+ */
+export const begin = internalMutation({
+    args: {
+        machineId: v.string(),
+        ownerId: v.optional(v.string()),
+        command: v.string(),
+        cwd: v.optional(v.string()),
+        timeoutMs: v.number(),
+    },
+    returns: v.id("executions"),
+    handler: async (ctx, { timeoutMs, ...fields }) => {
+        const executionId = await ctx.db.insert("executions", {
+            ...fields,
+            status: "running",
+            startedAt: Date.now(),
+        });
+        await ctx.scheduler.runAfter(timeoutMs + WATCHDOG_GRACE_MS, internal.executions.expire, { executionId });
+        return executionId;
+    },
+});
+/** Fail an execution whose action stopped before it could record a result. */
+export const expire = internalMutation({
+    args: { executionId: v.id("executions") },
+    returns: v.null(),
+    handler: async (ctx, { executionId }) => {
+        const row = await ctx.db.get("executions", executionId);
+        if (row?.status === "running") {
+            await ctx.db.patch("executions", executionId, {
+                status: "failed",
+                error: "the action running this command stopped before it recorded a result",
+                finishedAt: Date.now(),
+            });
+        }
+        return null;
+    },
+});
+export const finish = internalMutation({
+    args: {
+        executionId: v.id("executions"),
+        status: v.union(v.literal("completed"), v.literal("failed")),
+        exitCode: v.optional(v.number()),
+        stdout: v.optional(v.string()),
+        stderr: v.optional(v.string()),
+        error: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, { executionId, ...result }) => {
+        await ctx.db.patch("executions", executionId, {
+            ...result,
+            finishedAt: Date.now(),
+        });
+        return null;
+    },
+});
+//# sourceMappingURL=executions.js.map

package/dist/component/executions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executions.js","sourceRoot":"","sources":["../../src/component/executions.ts"],"names":[],"mappings":"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"}

package/dist/component/files.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Files inside a machine. Whole files cross the function boundary, so each
+ * is capped well below Convex's 16 MiB argument and return limits. Move
+ * bigger files with `exec` (for example `curl` to or from storage).
+ */
+/** Largest file `readFile` returns or `writeFile` accepts. */
+export declare const MAX_FILE_BYTES: number;
+/** Read a file as UTF-8 text. A file that isn't valid UTF-8 is refused. */
+export declare const readFile: import("convex/server").RegisteredAction<"public", {
+    ownerId?: string | undefined;
+    machineId: string;
+    path: string;
+}, Promise<string>>;
+/** Read a file byte for byte. */
+export declare const readFileBytes: import("convex/server").RegisteredAction<"public", {
+    ownerId?: string | undefined;
+    machineId: string;
+    path: string;
+}, Promise<ArrayBuffer>>;
+/** Create or replace a file. The parent directory must exist. */
+export declare const writeFile: import("convex/server").RegisteredAction<"public", {
+    ownerId?: string | undefined;
+    machineId: string;
+    path: string;
+    content: string | ArrayBuffer;
+}, Promise<{
+    bytesWritten: number;
+}>>;
+/** The immediate contents of a directory. */
+export declare const listDir: import("convex/server").RegisteredAction<"public", {
+    ownerId?: string | undefined;
+    machineId: string;
+    path: string;
+}, Promise<{
+    entries: {
+        name: string;
+        isDir: boolean;
+        sizeBytes: number;
+        permissions: string;
+        modifiedAt: number;
+    }[];
+    truncated: boolean;
+}>>;
+//# sourceMappingURL=files.d.ts.map

package/dist/component/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/component/files.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,QAAkB,CAAC;AA+B9C,2EAA2E;AAC3E,eAAO,MAAM,QAAQ;;;;mBAenB,CAAC;AAEH,iCAAiC;AACjC,eAAO,MAAM,aAAa;;;;wBAQxB,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,SAAS;;;;;;;GAgBpB,CAAC;AAEH,6CAA6C;AAC7C,eAAO,MAAM,OAAO;;;;;;;;;;;;;GAiClB,CAAC"}

package/dist/component/files.js

@@ -0,0 +1,105 @@
+/**
+ * Files inside a machine. Whole files cross the function boundary, so each
+ * is capped well below Convex's 16 MiB argument and return limits. Move
+ * bigger files with `exec` (for example `curl` to or from storage).
+ */
+import { v } from "convex/values";
+import { action } from "./_generated/server.js";
+import { withBoxd } from "./boxd.js";
+import { invalidArgument } from "./errors.js";
+import { requireMachine } from "./records.js";
+import { requireAbsolutePath } from "./validate.js";
+/** Largest file `readFile` returns or `writeFile` accepts. */
+export const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const target = {
+    machineId: v.string(),
+    ownerId: v.optional(v.string()),
+    /** Absolute path inside the machine. */
+    path: v.string(),
+};
+function requireSize(bytes, path) {
+    if (bytes > MAX_FILE_BYTES) {
+        throw invalidArgument(`${path} is ${bytes} bytes, over the ${MAX_FILE_BYTES} byte limit. ` +
+            "Move large files with exec instead.");
+    }
+}
+async function download(ctx, args) {
+    requireAbsolutePath(args.path);
+    await requireMachine(ctx, args.machineId, args.ownerId);
+    const bytes = await withBoxd(ctx, (boxd) => boxd.machines.files.download(args.machineId, args.path));
+    requireSize(bytes.byteLength, args.path);
+    return bytes;
+}
+/** Read a file as UTF-8 text. A file that isn't valid UTF-8 is refused. */
+export const readFile = action({
+    args: target,
+    returns: v.string(),
+    handler: async (ctx, args) => {
+        const bytes = await download(ctx, args);
+        try {
+            // Strict: a lenient decode would turn each bad byte into a 3-byte
+            // U+FFFD, and could push a binary file past the return limit.
+            return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw invalidArgument(`${args.path} is not UTF-8 text. Read it with readFileBytes.`);
+        }
+    },
+});
+/** Read a file byte for byte. */
+export const readFileBytes = action({
+    args: target,
+    returns: v.bytes(),
+    handler: async (ctx, args) => {
+        const bytes = await download(ctx, args);
+        // A standalone copy: `bytes` can be a view into a larger buffer.
+        return bytes.slice().buffer;
+    },
+});
+/** Create or replace a file. The parent directory must exist. */
+export const writeFile = action({
+    args: { ...target, content: v.union(v.string(), v.bytes()) },
+    returns: v.object({ bytesWritten: v.number() }),
+    handler: async (ctx, { machineId, ownerId, path, content }) => {
+        requireAbsolutePath(path);
+        const data = typeof content === "string"
+            ? new TextEncoder().encode(content)
+            : new Uint8Array(content);
+        requireSize(data.byteLength, path);
+        await requireMachine(ctx, machineId, ownerId);
+        const bytesWritten = await withBoxd(ctx, (boxd) => boxd.machines.files.upload(machineId, path, data));
+        return { bytesWritten };
+    },
+});
+/** The immediate contents of a directory. */
+export const listDir = action({
+    args: target,
+    returns: v.object({
+        entries: v.array(v.object({
+            name: v.string(),
+            isDir: v.boolean(),
+            sizeBytes: v.number(),
+            permissions: v.string(),
+            /** Epoch milliseconds. */
+            modifiedAt: v.number(),
+        })),
+        /** The directory held more entries than boxd returns in one listing. */
+        truncated: v.boolean(),
+    }),
+    handler: async (ctx, { machineId, ownerId, path }) => {
+        requireAbsolutePath(path);
+        await requireMachine(ctx, machineId, ownerId);
+        const listing = await withBoxd(ctx, (boxd) => boxd.machines.files.listDir(machineId, path));
+        return {
+            entries: listing.entries.map((entry) => ({
+                name: entry.name,
+                isDir: entry.isDir,
+                sizeBytes: entry.sizeBytes,
+                permissions: entry.permissions,
+                modifiedAt: entry.modifiedAt.getTime(),
+            })),
+            truncated: listing.truncated,
+        };
+    },
+});
+//# sourceMappingURL=files.js.map

package/dist/component/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/component/files.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C,MAAM,MAAM,GAAG;IACb,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,wCAAwC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC;AAEF,SAAS,WAAW,CAAC,KAAa,EAAE,IAAY;IAC9C,IAAI,KAAK,GAAG,cAAc,EAAE,CAAC;QAC3B,MAAM,eAAe,CACnB,GAAG,IAAI,OAAO,KAAK,oBAAoB,cAAc,eAAe;YAClE,qCAAqC,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,GAAc,EACd,IAA2D;IAE3D,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CACxD,CAAC;IACF,WAAW,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;IAC7B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,kEAAkE;YAClE,8DAA8D;YAC9D,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,eAAe,CACnB,GAAG,IAAI,CAAC,IAAI,iDAAiD,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,iCAAiC;AACjC,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;IAClC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE;IAClB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,iEAAiE;QACjE,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;IAC9B,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE;IAC5D,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC/C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC5D,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,IAAI,GACR,OAAO,OAAO,KAAK,QAAQ;YACzB,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;YACnC,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QAC9B,WAAW,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAChD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAClD,CAAC;QACF,OAAO,EAAE,YAAY,EAAE,CAAC;IAC1B,CAAC;CACF,CAAC,CAAC;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,OAAO,EAAE,CAAC,CAAC,KAAK,CACd,CAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;YAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;YACvB,0BAA0B;YAC1B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;SACvB,CAAC,CACH;QACD,wEAAwE;QACxE,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;KACvB,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE;QACnD,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAC3C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAC7C,CAAC;QACF,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACvC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE;aACvC,CAAC,CAAC;YACH,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/component/limits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bounds that keep every value this component stores or returns inside
+ * Convex's limits: 1 MiB per document, 16 MiB per function return value,
+ * and a 10 minute ceiling on an action.
+ */
+/** Stored per stream on an execution row: two of these stay far below 1 MiB. */
+export declare const MAX_STORED_OUTPUT = 64000;
+/** Stored command line on an execution row. */
+export declare const MAX_STORED_COMMAND = 4000;
+/** Stored error message on any row. */
+export declare const MAX_STORED_ERROR = 4000;
+/**
+ * Returned per stream from `exec`. A character is at most 3 UTF-8 bytes, so
+ * two streams at this cap stay under the 16 MiB return limit.
+ */
+export declare const MAX_RETURNED_OUTPUT = 2000000;
+/**
+ * A command that outlives its action would leave its execution row stuck at
+ * "running", because the action's `catch` never runs. So the remote command
+ * is always bounded below the 10 minute action ceiling.
+ */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 540000;
+export declare const MAX_EXEC_TIMEOUT_MS = 570000;
+/** How long `create` and `fork` wait for the machine to accept an exec. */
+export declare const DEFAULT_READY_TIMEOUT_MS = 120000;
+export declare const MAX_READY_TIMEOUT_MS = 480000;
+export declare const DEFAULT_LIST_LIMIT = 100;
+export declare const MAX_LIST_LIMIT = 500;
+/** Truncate to at most `max` characters, the marker included. */
+export declare function truncate(text: string, max: number): string;
+/** A caller-supplied page size, forced into `[1, MAX_LIST_LIMIT]`. */
+export declare function clampLimit(limit: number | undefined): number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/component/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/component/limits.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,+CAA+C;AAC/C,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AACtC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAC/C,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAE3C,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAChD,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAE5C,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,cAAc,MAAM,CAAC;AAIlC,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI5D"}

package/dist/component/limits.js

@@ -0,0 +1,44 @@
+/**
+ * Bounds that keep every value this component stores or returns inside
+ * Convex's limits: 1 MiB per document, 16 MiB per function return value,
+ * and a 10 minute ceiling on an action.
+ */
+/** Stored per stream on an execution row: two of these stay far below 1 MiB. */
+export const MAX_STORED_OUTPUT = 64_000;
+/** Stored command line on an execution row. */
+export const MAX_STORED_COMMAND = 4_000;
+/** Stored error message on any row. */
+export const MAX_STORED_ERROR = 4_000;
+/**
+ * Returned per stream from `exec`. A character is at most 3 UTF-8 bytes, so
+ * two streams at this cap stay under the 16 MiB return limit.
+ */
+export const MAX_RETURNED_OUTPUT = 2_000_000;
+/**
+ * A command that outlives its action would leave its execution row stuck at
+ * "running", because the action's `catch` never runs. So the remote command
+ * is always bounded below the 10 minute action ceiling.
+ */
+export const DEFAULT_EXEC_TIMEOUT_MS = 540_000;
+export const MAX_EXEC_TIMEOUT_MS = 570_000;
+/** How long `create` and `fork` wait for the machine to accept an exec. */
+export const DEFAULT_READY_TIMEOUT_MS = 120_000;
+export const MAX_READY_TIMEOUT_MS = 480_000;
+export const DEFAULT_LIST_LIMIT = 100;
+export const MAX_LIST_LIMIT = 500;
+const TRUNCATION_MARKER = "\n…[truncated]";
+/** Truncate to at most `max` characters, the marker included. */
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    const keep = Math.max(0, max - TRUNCATION_MARKER.length);
+    return `${text.slice(0, keep)}${TRUNCATION_MARKER}`;
+}
+/** A caller-supplied page size, forced into `[1, MAX_LIST_LIMIT]`. */
+export function clampLimit(limit) {
+    const value = Math.floor(limit ?? DEFAULT_LIST_LIMIT);
+    if (!Number.isFinite(value))
+        return DEFAULT_LIST_LIMIT;
+    return Math.min(Math.max(value, 1), MAX_LIST_LIMIT);
+}
+//# sourceMappingURL=limits.js.map

package/dist/component/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/component/limits.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACxC,uCAAuC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AACtC;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAE3C,iEAAiE;AACjE,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,GAAW;IAChD,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,iBAAiB,EAAE,CAAC;AACtD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,kBAAkB,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACvD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AACtD,CAAC"}