@boxd-sh/convex 0.1.0

package/src/component/executions.ts

@@ -0,0 +1,115 @@
+/**
+ * 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;
+  },
+});

package/src/component/files.ts

@@ -0,0 +1,128 @@
+/**
+ * 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, type ActionCtx } 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: number, path: string): void {
+  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: ActionCtx,
+  args: { machineId: string; ownerId?: string; path: string },
+): Promise<Uint8Array> {
+  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,
+    };
+  },
+});

package/src/component/limits.ts

@@ -0,0 +1,48 @@
+/**
+ * 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: string, max: number): string {
+  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: number | undefined): number {
+  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);
+}