@boxd-sh/convex 0.1.0

package/src/client/index.ts

@@ -0,0 +1,199 @@
+/**
+ * App-facing client for the boxd Convex component.
+ *
+ * Create one with `components.boxd` in your `convex/` directory and call it
+ * from your queries and actions. Reads (`get`, `list`, `listExecutions`,
+ * `getExecution`) run in queries and are reactive. Everything that talks to
+ * boxd runs in actions.
+ *
+ * The component can't see your users: `ctx.auth` doesn't reach into a
+ * component. Derive `ownerId` from your own auth and pass it on every call.
+ * Never take it from a client argument. A machine created with an `ownerId`
+ * is reachable only with that same `ownerId`.
+ */
+
+import { ConvexError, type Infer } from "convex/values";
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericQueryCtx,
+} from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { BoxdErrorData, errorCode } from "../component/errors.js";
+
+type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+type ActionCtx = Pick<
+  GenericActionCtx<GenericDataModel>,
+  "runQuery" | "runMutation" | "runAction"
+>;
+
+type Machines = ComponentApi["machines"];
+type Args<F extends FunctionReference<any, "internal">> = FunctionArgs<F>;
+type Returns<F extends FunctionReference<any, "internal">> =
+  FunctionReturnType<F>;
+
+/** A machine's row: boxd's last observed state plus the component's fields. */
+export type MachineRecord = Returns<Machines["create"]>;
+/** One `exec`, as stored in the component. */
+export type ExecutionRecord = NonNullable<
+  Returns<ComponentApi["executions"]["get"]>
+>;
+export type ExecResult = Returns<ComponentApi["exec"]["run"]>;
+export type DirListing = Returns<ComponentApi["files"]["listDir"]>;
+
+export type CreateArgs = Args<Machines["create"]>;
+export type ForkArgs = Args<Machines["fork"]>;
+export type ExecArgs = Args<ComponentApi["exec"]["run"]>;
+export type ExposeArgs = Args<Machines["expose"]>;
+
+/** Addresses one machine: its boxd id, and the owner it belongs to. */
+export type MachineRef = { machineId: string; ownerId?: string };
+/** Addresses a machine that wakes up: optionally wait until it takes an exec. */
+export type WakeArgs = Args<Machines["start"]>;
+export type FileRef = MachineRef & { path: string };
+
+export type BoxdErrorCode = Infer<typeof errorCode>;
+export type { BoxdErrorData, ComponentApi };
+
+/**
+ * True when `error` is a `ConvexError` this component threw, and, with
+ * `code`, carries that code:
+ *
+ * ```ts
+ * if (isBoxdError(error, "NOT_FOUND")) return null;
+ * ```
+ */
+export function isBoxdError(
+  error: unknown,
+  code?: BoxdErrorCode,
+): error is ConvexError<BoxdErrorData> {
+  if (!(error instanceof ConvexError)) return false;
+  const data = error.data as Partial<BoxdErrorData> | null;
+  if (typeof data !== "object" || data === null) return false;
+  if (typeof data.code !== "string" || typeof data.message !== "string") {
+    return false;
+  }
+  return code === undefined || data.code === code;
+}
+
+export class Boxd {
+  constructor(public readonly component: ComponentApi) {}
+
+  // ---- Reactive reads (component tables only, no boxd call) --------------
+
+  /** The machine's row, or null if it doesn't exist for this owner. */
+  async get(ctx: QueryCtx, args: MachineRef) {
+    return await ctx.runQuery(this.component.machines.get, args);
+  }
+
+  /** The owner's machines, newest first, destroyed ones included. */
+  async list(ctx: QueryCtx, args: { ownerId?: string; limit?: number } = {}) {
+    return await ctx.runQuery(this.component.machines.list, args);
+  }
+
+  /** A machine's executions, newest first. */
+  async listExecutions(ctx: QueryCtx, args: MachineRef & { limit?: number }) {
+    return await ctx.runQuery(this.component.executions.list, args);
+  }
+
+  /** One execution by the id `exec` returned, or null. */
+  async getExecution(
+    ctx: QueryCtx,
+    args: { executionId: string; ownerId?: string },
+  ) {
+    return await ctx.runQuery(this.component.executions.get, args);
+  }
+
+  // ---- Lifecycle -----------------------------------------------------------
+
+  /** Create a machine and, by default, wait until it accepts an exec. */
+  async create(ctx: ActionCtx, args: CreateArgs = {}) {
+    return await ctx.runAction(this.component.machines.create, args);
+  }
+
+  /** Fork a machine, disk and memory, into a new one with the same owner. */
+  async fork(ctx: ActionCtx, args: ForkArgs) {
+    return await ctx.runAction(this.component.machines.fork, args);
+  }
+
+  /** Re-read the machine from boxd into its row. */
+  async refresh(ctx: ActionCtx, args: MachineRef) {
+    return await ctx.runAction(this.component.machines.refresh, args);
+  }
+
+  /** Boot a stopped machine. */
+  async start(ctx: ActionCtx, args: WakeArgs) {
+    return await ctx.runAction(this.component.machines.start, args);
+  }
+
+  /** Shut the machine down. The disk is kept. */
+  async stop(ctx: ActionCtx, args: MachineRef) {
+    return await ctx.runAction(this.component.machines.stop, args);
+  }
+
+  /** Suspend to RAM. An exec or an HTTPS request wakes it again. */
+  async pause(ctx: ActionCtx, args: MachineRef) {
+    return await ctx.runAction(this.component.machines.pause, args);
+  }
+
+  /** Resume a paused machine. */
+  async resume(ctx: ActionCtx, args: WakeArgs) {
+    return await ctx.runAction(this.component.machines.resume, args);
+  }
+
+  /** Suspend to disk, freeing the host's memory. */
+  async hibernate(ctx: ActionCtx, args: MachineRef) {
+    return await ctx.runAction(this.component.machines.hibernate, args);
+  }
+
+  /** Restore a hibernated machine, memory included. */
+  async wake(ctx: ActionCtx, args: WakeArgs) {
+    return await ctx.runAction(this.component.machines.wake, args);
+  }
+
+  /** Destroy the machine. Its row stays, with status "destroyed". */
+  async destroy(ctx: ActionCtx, args: MachineRef) {
+    return await ctx.runAction(this.component.machines.destroy, args);
+  }
+
+  /**
+   * Route public HTTPS to a port. Without `name`: the machine's default URL.
+   * With `name`: an extra `https://<name>.<machine>.<zone>`.
+   */
+  async expose(ctx: ActionCtx, args: ExposeArgs) {
+    return await ctx.runAction(this.component.machines.expose, args);
+  }
+
+  // ---- Commands and files ------------------------------------------------
+
+  /** Run a command and wait for it to exit. Recorded in `executions`. */
+  async exec(ctx: ActionCtx, args: ExecArgs) {
+    return await ctx.runAction(this.component.exec.run, args);
+  }
+
+  /** Read a file as UTF-8 text. */
+  async readFile(ctx: ActionCtx, args: FileRef) {
+    return await ctx.runAction(this.component.files.readFile, args);
+  }
+
+  /** Read a file byte for byte. */
+  async readFileBytes(ctx: ActionCtx, args: FileRef) {
+    return await ctx.runAction(this.component.files.readFileBytes, args);
+  }
+
+  /** Create or replace a file from text or bytes. */
+  async writeFile(
+    ctx: ActionCtx,
+    args: FileRef & { content: string | ArrayBuffer },
+  ) {
+    return await ctx.runAction(this.component.files.writeFile, args);
+  }
+
+  /** The immediate contents of a directory. */
+  async listDir(ctx: ActionCtx, args: FileRef) {
+    return await ctx.runAction(this.component.files.listDir, args);
+  }
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,68 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as boxd from "../boxd.js";
+import type * as errors from "../errors.js";
+import type * as exec from "../exec.js";
+import type * as executions from "../executions.js";
+import type * as files from "../files.js";
+import type * as limits from "../limits.js";
+import type * as machines from "../machines.js";
+import type * as records from "../records.js";
+import type * as sessions from "../sessions.js";
+import type * as validate from "../validate.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  boxd: typeof boxd;
+  errors: typeof errors;
+  exec: typeof exec;
+  executions: typeof executions;
+  files: typeof files;
+  limits: typeof limits;
+  machines: typeof machines;
+  records: typeof records;
+  sessions: typeof sessions;
+  validate: typeof validate;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,430 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    exec: {
+      run: FunctionReference<
+        "action",
+        "internal",
+        {
+          command: string | Array<string>;
+          cwd?: string;
+          env?: Record<string, string>;
+          machineId: string;
+          ownerId?: string;
+          timeoutMs?: number;
+        },
+        {
+          executionId: string;
+          exitCode: number;
+          stderr: string;
+          stdout: string;
+          success: boolean;
+        },
+        Name
+      >;
+    };
+    executions: {
+      get: FunctionReference<
+        "query",
+        "internal",
+        { executionId: string; ownerId?: string },
+        null | {
+          _creationTime: number;
+          _id: string;
+          command: string;
+          cwd?: string;
+          error?: string;
+          exitCode?: number;
+          finishedAt?: number;
+          machineId: string;
+          ownerId?: string;
+          startedAt: number;
+          status: "running" | "completed" | "failed";
+          stderr?: string;
+          stdout?: string;
+        },
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number; machineId: string; ownerId?: string },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          command: string;
+          cwd?: string;
+          error?: string;
+          exitCode?: number;
+          finishedAt?: number;
+          machineId: string;
+          ownerId?: string;
+          startedAt: number;
+          status: "running" | "completed" | "failed";
+          stderr?: string;
+          stdout?: string;
+        }>,
+        Name
+      >;
+    };
+    files: {
+      listDir: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string; path: string },
+        {
+          entries: Array<{
+            isDir: boolean;
+            modifiedAt: number;
+            name: string;
+            permissions: string;
+            sizeBytes: number;
+          }>;
+          truncated: boolean;
+        },
+        Name
+      >;
+      readFile: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string; path: string },
+        string,
+        Name
+      >;
+      readFileBytes: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string; path: string },
+        ArrayBuffer,
+        Name
+      >;
+      writeFile: FunctionReference<
+        "action",
+        "internal",
+        {
+          content: string | ArrayBuffer;
+          machineId: string;
+          ownerId?: string;
+          path: string;
+        },
+        { bytesWritten: number },
+        Name
+      >;
+    };
+    machines: {
+      create: FunctionReference<
+        "action",
+        "internal",
+        {
+          autoDestroySeconds?: number;
+          autoSuspendSeconds?: number;
+          env?: Record<string, string>;
+          image?: string;
+          isolated?: boolean;
+          memory?: string;
+          name?: string;
+          ownerId?: string;
+          readyTimeoutMs?: number;
+          vcpu?: number;
+          waitUntilReady?: boolean;
+        },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      destroy: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      expose: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; name?: string; ownerId?: string; port: number },
+        { port: number; url: string },
+        Name
+      >;
+      fork: FunctionReference<
+        "action",
+        "internal",
+        {
+          machineId: string;
+          name?: string;
+          ownerId?: string;
+          readyTimeoutMs?: number;
+          waitUntilReady?: boolean;
+        },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      get: FunctionReference<
+        "query",
+        "internal",
+        { machineId: string; ownerId?: string },
+        null | {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      hibernate: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number; ownerId?: string },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        }>,
+        Name
+      >;
+      pause: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      refresh: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      resume: FunctionReference<
+        "action",
+        "internal",
+        {
+          machineId: string;
+          ownerId?: string;
+          readyTimeoutMs?: number;
+          waitUntilReady?: boolean;
+        },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      start: FunctionReference<
+        "action",
+        "internal",
+        {
+          machineId: string;
+          ownerId?: string;
+          readyTimeoutMs?: number;
+          waitUntilReady?: boolean;
+        },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      stop: FunctionReference<
+        "action",
+        "internal",
+        { machineId: string; ownerId?: string },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+      wake: FunctionReference<
+        "action",
+        "internal",
+        {
+          machineId: string;
+          ownerId?: string;
+          readyTimeoutMs?: number;
+          waitUntilReady?: boolean;
+        },
+        {
+          _creationTime: number;
+          _id: string;
+          forkedFrom?: string;
+          image?: string;
+          lastError?: string;
+          machineId: string;
+          memoryBytes?: number;
+          name: string;
+          ownerId?: string;
+          status: string;
+          updatedAt: number;
+          url?: string;
+          vcpu?: number;
+        },
+        Name
+      >;
+    };
+  };