@alchemy.run/archil 0.0.0 → 2.0.0-beta.87

package/src/ConnectSandbox.ts

@@ -0,0 +1,91 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ApiAccess } from "./ArchilBindings.ts";
+import { makeSandboxOps, type SandboxOps } from "./Clients.ts";
+import type { Sandbox } from "./Sandbox.ts";
+
+/**
+ * The handle on a deploy-time sandbox: a {@link SandboxHandle} whose id and
+ * name resolve at run time.
+ */
+export interface ConnectSandboxClient extends SandboxOps {
+  readonly sandboxId: Effect.Effect<string, never, RuntimeContext>;
+  readonly name: Effect.Effect<string, never, RuntimeContext>;
+}
+
+/**
+ * Act on a sandbox declared at deploy time from a Worker, Lambda, or any
+ * other host: run commands, start background processes and terminals,
+ * move files, pause and resume, fork it into a new sandbox, open ports,
+ * and change its network policy. A program sandbox (`Archil.Sandbox` with
+ * `main`) is a sandbox too.
+ *
+ * ### Driving a Dev Box
+ * **Example:** Build on the dev box, fork a preview per pull request
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const devbox = yield* Archil.ConnectSandbox(DevBox);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* devbox.exec("git pull && pnpm build", { cwd: "/workspace" });
+ *         yield* devbox.files.write("/workspace/.env", "PREVIEW=1\n");
+ *         const preview = yield* devbox.fork({ name: "pr-42" });
+ *         const port = yield* preview.exposePort(3000);
+ *         return HttpServerResponse.text(`https://${port.hostname}`);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Archil.ConnectSandboxHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Proxying to a Port
+ * **Example:** A Worker in front of the dev box's server
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const devbox = yield* Archil.ConnectSandbox(DevBox);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const port = yield* devbox.getTcpPort(3000);
+ *         return yield* port.fetch(yield* HttpServerRequest);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Archil.ConnectSandboxHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface ConnectSandbox extends Binding.Service<
+  ConnectSandbox,
+  "Archil.ConnectSandbox",
+  (sandbox: Sandbox) => Effect.Effect<ConnectSandboxClient>
+> {}
+
+export const ConnectSandbox = Binding.Service<ConnectSandbox>("Archil.ConnectSandbox");
+
+/** {@link ConnectSandbox} over Archil's HTTP API, usable from any host. */
+export const ConnectSandboxHttp = Layer.effect(
+  ConnectSandbox,
+  Effect.gen(function* () {
+    const access = yield* ApiAccess;
+    return Effect.fn(function* (sandbox: Sandbox) {
+      const authorize = yield* access();
+      const sandboxId = yield* sandbox.sandboxId;
+      const name = yield* sandbox.name;
+      return {
+        sandboxId,
+        name,
+        ...makeSandboxOps(sandboxId, authorize),
+      } satisfies ConnectSandboxClient;
+    });
+  }),
+);

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "archil",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.ArchilAuth,
+  ),
+});

package/src/CreateDisk.ts

@@ -0,0 +1,165 @@
+import * as archil from "@distilled.cloud/archil";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { ApiAccess, runtimeName, runtimePrefix } from "./ArchilBindings.ts";
+import { makeDiskHandle, type DiskHandle } from "./Clients.ts";
+import { deleteDisk, ensureDisk, type DiskStorage } from "./Disk.ts";
+import type { ArchilFailed, ArchilNotReady } from "./internal/archil.ts";
+import { findDiskByName, listAllDisks } from "./internal/archil.ts";
+
+export interface CreateDiskOptions {
+  /**
+   * Where disks created by this client keep their files. Omit for
+   * Archil-managed storage. A run-time `create` can override it.
+   */
+  storage?: DiskStorage;
+}
+
+export type CreateDiskError =
+  | archil.CreateDiskError
+  | archil.GetDiskError
+  | archil.ListDisksError
+  | ArchilFailed
+  | ArchilNotReady;
+
+export interface CreateDiskClient {
+  /**
+   * The name prefix this client puts on everything it creates,
+   * `alc-<id>-<hash of stack/stage/id>`.
+   */
+  readonly prefix: string;
+  /**
+   * Create a disk (or return the one that already has this name). Names
+   * are stamped with this binding's prefix, so `create({ name: "user-1" })`
+   * is the same disk on every call.
+   */
+  create(
+    name: string,
+    options?: { readonly storage?: DiskStorage },
+  ): Effect.Effect<DiskHandle, CreateDiskError, RuntimeContext>;
+  /** A disk this client created, or `undefined`. */
+  get(name: string): Effect.Effect<DiskHandle | undefined, archil.ListDisksError, RuntimeContext>;
+  /** Every disk this client created. */
+  list(): Effect.Effect<DiskHandle[], archil.ListDisksError, RuntimeContext>;
+  /** Delete a disk this client created. Deleting a missing disk succeeds. */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    archil.ListDisksError | Effect.Error<ReturnType<typeof deleteDisk>>,
+    RuntimeContext
+  >;
+}
+
+/**
+ * Create disks at run time, one per user, session, or task, by name. This
+ * is how most apps use Archil: a disk mounts in about 50 ms, so it can
+ * belong to a single request. The client returns full disk handles (exec,
+ * grep, objects, branches, disk tokens), the same shape the deploy-time
+ * bindings return.
+ *
+ * Objects created at run time are tagged with the stack, stage and binding
+ * (`alchemy::stack`, `alchemy::stage`, `alchemy::id`) and are not deleted
+ * when the stack is destroyed. List them by those tags to clean them up.
+ * Archil has no tags, labels or descriptions, so the tags are a name
+ * prefix, `alc-<id>-<hash of stack/stage/id>`: every name this client
+ * creates is `<prefix>-<name>`, and `prefix` on the client is the value.
+ *
+ * ### Disks per User
+ * **Example:** A home disk for each user
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const disks = yield* Archil.CreateDisk();
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const user = request.headers["x-user"] ?? "anonymous";
+ *         const home = yield* disks.create(`user-${user}`);
+ *         const result = yield* home.exec("ls -la /mnt/archil");
+ *         return HttpServerResponse.text(result.stdout);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Archil.CreateDiskHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Cleaning Up
+ * **Example:** Delete the disks one binding created
+ * ```typescript
+ * const disks = yield* Archil.CreateDisk();
+ * for (const disk of yield* disks.list()) {
+ *   yield* disks.delete(disk.name.slice(disks.prefix.length + 1));
+ * }
+ * ```
+ *
+ * @binding
+ * @product Disk
+ */
+export interface CreateDisk extends Binding.Service<
+  CreateDisk,
+  "Archil.CreateDisk",
+  (options?: CreateDiskOptions) => Effect.Effect<CreateDiskClient>
+> {}
+
+export const CreateDisk = Binding.Service<CreateDisk>("Archil.CreateDisk");
+
+/** {@link CreateDisk} over Archil's HTTP API, usable from any host. */
+export const CreateDiskHttp = Layer.effect(
+  CreateDisk,
+  Effect.gen(function* () {
+    const access = yield* ApiAccess;
+    return Effect.fn(function* (options?: CreateDiskOptions) {
+      const authorize = yield* access();
+      const { prefix: owner } = yield* runtimePrefix("Disks");
+      const prefix = Effect.succeed(owner);
+      const fullName = (name: string) => Effect.succeed(runtimeName(owner, name));
+      const handle = (disk: { id: string; name: string }) =>
+        makeDiskHandle({ diskId: disk.id, name: disk.name }, authorize);
+      return {
+        prefix: owner,
+        create: (name, createOptions) =>
+          authorize(
+            Effect.gen(function* () {
+              const disk = yield* ensureDisk(
+                yield* fullName(name),
+                createOptions?.storage ?? options?.storage,
+              );
+              return handle(disk);
+            }),
+          ),
+        get: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              const diskName = yield* fullName(name);
+              const disk = yield* findDiskByName(diskName);
+              return disk && disk.status !== "deleted" ? handle(disk) : undefined;
+            }),
+          ),
+        list: () =>
+          authorize(
+            Effect.gen(function* () {
+              const p = yield* prefix;
+              const disks = yield* Stream.runCollect(listAllDisks());
+              return disks
+                .filter((d) => d.name.startsWith(`${p}-`) && d.status !== "deleted")
+                .map(handle);
+            }),
+          ),
+        delete: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              const diskName = yield* fullName(name);
+              const disk = yield* findDiskByName(diskName);
+              if (disk) yield* deleteDisk(disk.id);
+            }),
+          ),
+      } satisfies CreateDiskClient;
+    });
+  }),
+);

package/src/CreateImage.ts

@@ -0,0 +1,73 @@
+import type { ImageRegistry } from "@alchemy.run/docker/Registry";
+import * as archil from "@distilled.cloud/archil";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ApiAccess } from "./ArchilBindings.ts";
+import { pullImage, toImageAttributes, type ImageAttributes } from "./Image.ts";
+import type { ArchilFailed, ArchilNotReady } from "./internal/archil.ts";
+
+export interface CreateImageClient {
+  /**
+   * Pull an OCI reference into an Archil image and wait until it is ready.
+   * Takes the same `image` and `registry` props as {@link Image}.
+   */
+  build(props: {
+    readonly image: string;
+    readonly registry?: ImageRegistry;
+  }): Effect.Effect<
+    ImageAttributes,
+    archil.CreateImageError | archil.GetImageError | ArchilFailed | ArchilNotReady,
+    RuntimeContext
+  >;
+  /** An image by id, or `undefined` when it doesn't exist. */
+  get(
+    imageId: string,
+  ): Effect.Effect<ImageAttributes | undefined, archil.GetImageError, RuntimeContext>;
+}
+
+/**
+ * Build sandbox images at run time, e.g. one per customer repository, with
+ * the same props as the deploy-time {@link Image}. Pass the result's
+ * `imageId` to `CreateSandbox`.
+ *
+ * ### Building Images
+ * **Example:** An image per tenant
+ * ```typescript
+ * const images = yield* Archil.CreateImage();
+ * const image = yield* images.build({ image: `ghcr.io/acme/${tenant}:latest` });
+ * const sandbox = yield* sandboxes.create({ name: tenant, image: image.imageId });
+ * ```
+ *
+ * @binding
+ * @product Image
+ */
+export interface CreateImage extends Binding.Service<
+  CreateImage,
+  "Archil.CreateImage",
+  () => Effect.Effect<CreateImageClient>
+> {}
+
+export const CreateImage = Binding.Service<CreateImage>("Archil.CreateImage");
+
+/** {@link CreateImage} over Archil's HTTP API, usable from any host. */
+export const CreateImageHttp = Layer.effect(
+  CreateImage,
+  Effect.gen(function* () {
+    const access = yield* ApiAccess;
+    return Effect.fn(function* () {
+      const authorize = yield* access();
+      return {
+        build: (props) => authorize(pullImage(props.image, props.registry, props.image)),
+        get: (imageId) =>
+          authorize(
+            archil.getImage({ image_id: imageId }).pipe(
+              Effect.map(({ data }) => toImageAttributes(data, data.source)),
+              Effect.catchTag("NotFound", () => Effect.undefined),
+            ),
+          ),
+      } satisfies CreateImageClient;
+    });
+  }),
+);

package/src/CreateSandbox.ts

@@ -0,0 +1,258 @@
+import * as archil from "@distilled.cloud/archil";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+import { ApiAccess, runtimeName, runtimePrefix } from "./ArchilBindings.ts";
+import { makeSandboxHandle, type SandboxHandle } from "./Clients.ts";
+import type { Image } from "./Image.ts";
+import type { ArchilFailed, ArchilNotReady } from "./internal/archil.ts";
+import { findSandboxByName, listSandboxes, waitForSandbox } from "./internal/archil.ts";
+import {
+  deleteSandbox,
+  toCreateSandboxRequest,
+  type Sandbox,
+  type SandboxProps,
+} from "./Sandbox.ts";
+import {
+  MountDiskUnresolved,
+  mountDiskId,
+  toSandboxMount,
+  type DiskRef,
+  type MountableDisk,
+  type MountOptionUnsupported,
+} from "./SandboxOptions.ts";
+
+/**
+ * A run-time create: a box {@link Sandbox}'s props (no program), with a
+ * required name. A mount's disk is a `DiskHandle` (e.g. from
+ * `CreateDisk`), or a `MountDisk` reference this host bound at deploy.
+ */
+export interface CreateSandboxRequest extends Omit<
+  SandboxProps,
+  "name" | "main" | "handler" | "port" | "build" | "extraFiles" | "isExternal"
+> {
+  /** Name, stamped with this binding's prefix. Lowercase letters, digits and `-`. */
+  readonly name: string;
+}
+
+export type CreateSandboxError =
+  | archil.CreateSandboxError
+  | archil.ForkSandboxError
+  | archil.GetSandboxError
+  | archil.ListSandboxesError
+  | ArchilFailed
+  | ArchilNotReady
+  | MountOptionUnsupported
+  | MountDiskUnresolved;
+
+/**
+ * A mount's disk id at run time: a handle carries it; a declared disk
+ * reads the id `MountDisk` bound into this host at deploy.
+ */
+const runtimeDiskId = Effect.fn(function* (disk: MountableDisk, path: string) {
+  if (isDiskRef(disk)) return disk.diskId;
+  if (Effect.isEffect(disk)) {
+    return yield* new MountDiskUnresolved({
+      path,
+      message: `The disk mounted at ${path} is a declaration: bind it with Archil.MountDisk(disk) and pass that reference, or pass a DiskHandle.`,
+    });
+  }
+  const diskId = yield* disk.diskId;
+  return yield* diskId;
+});
+
+const isDiskRef = (disk: MountableDisk): disk is DiskRef => mountDiskId(disk) !== undefined;
+
+export interface CreateSandboxClient {
+  /**
+   * The name prefix this client puts on everything it creates,
+   * `alc-<id>-<hash of stack/stage/id>`.
+   */
+  readonly prefix: string;
+  /**
+   * Create a sandbox (or return the one that already has this name) and
+   * wait until it is running. Takes a {@link Sandbox}'s props; the bound
+   * image is the default.
+   */
+  create(
+    request: CreateSandboxRequest,
+  ): Effect.Effect<SandboxHandle, CreateSandboxError, RuntimeContext>;
+  /** A sandbox this client created, or `undefined`. */
+  get(
+    name: string,
+  ): Effect.Effect<SandboxHandle | undefined, archil.ListSandboxesError, RuntimeContext>;
+  /** Every sandbox this client created. */
+  list(): Effect.Effect<SandboxHandle[], archil.ListSandboxesError, RuntimeContext>;
+  /** Delete a sandbox this client created. Deleting a missing sandbox succeeds. */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    archil.ListSandboxesError | Effect.Error<ReturnType<typeof deleteSandbox>>,
+    RuntimeContext
+  >;
+}
+
+/**
+ * Create sandboxes at run time, one per user, session, or task: Firecracker
+ * microVMs with disks mounted, public ports, and an outbound network policy
+ * that can inject credentials at the boundary. Bind an {@link Image} to make
+ * it the default image; a run-time `create` takes the same props as a
+ * deploy-time {@link Sandbox}. Bind a {@link Sandbox} instead and `create`
+ * forks it: each sandbox starts from its memory and disk, with whatever its
+ * `run` commands set up, and changes only its own copy.
+ *
+ * Objects created at run time are tagged with the stack, stage and binding
+ * (`alchemy::stack`, `alchemy::stage`, `alchemy::id`) and are not deleted
+ * when the stack is destroyed. List them by those tags to clean them up.
+ * Archil has no tags, labels or descriptions, so the tags are a name
+ * prefix, `alc-<id>-<hash of stack/stage/id>`: every sandbox (and fork)
+ * this client creates is `<prefix>-<name>`, and `prefix` on the client is the value.
+ *
+ * ### Sandboxes per Task
+ * **Example:** Run a task in a sandbox with the user's disk mounted
+ * ```typescript
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const disks = yield* Archil.CreateDisk();
+ *     const sandboxes = yield* Archil.CreateSandbox(Agent);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const home = yield* disks.create("user-1");
+ *         const sandbox = yield* sandboxes.create({
+ *           name: "task-1",
+ *           mounts: [{ disk: home, path: "/home/user" }],
+ *           network: { egress: { default: "deny", allow: ["registry.npmjs.org"] } },
+ *           idleTtlSeconds: 300,
+ *         });
+ *         const result = yield* sandbox.exec("npm test", { cwd: "/home/user/app" });
+ *         yield* sandbox.pause();
+ *         return HttpServerResponse.text(result.stdout);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Archil.CreateDiskHttp, Archil.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * ### Forking a Sandbox Built at Deploy
+ * **Example:** A fork per user from a sandbox set up at deploy
+ * ```typescript
+ * export const Golden = Archil.Sandbox("Golden", {
+ *   run: ["git clone --depth 1 https://github.com/sindresorhus/is ~/is"],
+ * });
+ *
+ * // in a Worker or program:
+ * const sandboxes = yield* Archil.CreateSandbox(Golden);
+ * const sandbox = (yield* sandboxes.get(`user-${user}`)) ?? (yield* sandboxes.create({ name: `user-${user}` }));
+ * const result = yield* sandbox.exec("git log -1", { cwd: "~/is" });
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface CreateSandbox extends Binding.Service<
+  CreateSandbox,
+  "Archil.CreateSandbox",
+  (base?: Image | Sandbox) => Effect.Effect<CreateSandboxClient>
+> {}
+
+export const CreateSandbox = Binding.Service<CreateSandbox>("Archil.CreateSandbox");
+
+/** {@link CreateSandbox} over Archil's HTTP API, usable from any host. */
+export const CreateSandboxHttp = Layer.effect(
+  CreateSandbox,
+  Effect.gen(function* () {
+    const access = yield* ApiAccess;
+    return Effect.fn(function* (base?: Image | Sandbox) {
+      const authorize = yield* access();
+      const { prefix: owner } = yield* runtimePrefix("Sandboxes");
+      const prefix = Effect.succeed(owner);
+      // Resources are proxies (every property reads as an Output), so tell a
+      // bound sandbox from a bound image by its type, not by `in`.
+      const isSandbox = (b: Image | Sandbox): b is Sandbox => b.Type === "Archil.Sandbox";
+      const source = base !== undefined && isSandbox(base) ? yield* base.sandboxId : undefined;
+      const imageId = base !== undefined && !isSandbox(base) ? yield* base.imageId : undefined;
+      const fullName = (name: string) => Effect.succeed(runtimeName(owner, name));
+      // Forks carry the same prefix as the sandboxes they come from; an
+      // unnamed fork gets a random name.
+      const forkName = Effect.fn(function* (name: string | undefined) {
+        const id = (yield* Random.nextIntBetween(0, 2 ** 31)).toString(36);
+        return yield* fullName(name ?? `fork-${id}`);
+      });
+      const handle = (s: { sandbox_id: string; name: string }) =>
+        makeSandboxHandle({ sandboxId: s.sandbox_id, name: s.name }, authorize, forkName);
+      return {
+        prefix: owner,
+        create: (request) =>
+          authorize(
+            Effect.gen(function* () {
+              const name = yield* fullName(request.name);
+              const existing = yield* findSandboxByName(name);
+              if (existing) return handle(existing);
+              if (source !== undefined) {
+                // A bound sandbox is the base: fork its memory and disk.
+                const { data } = yield* archil.forkSandbox({
+                  sid: yield* source,
+                  wait: true,
+                  name,
+                });
+                return handle(yield* waitForSandbox(data.sandbox_id));
+              }
+              const defaultImage =
+                request.image === undefined && request.baseImage === undefined && imageId
+                  ? yield* imageId
+                  : request.image;
+              const mounts: archil.SandboxMount[] = [];
+              for (const mount of request.mounts ?? []) {
+                const diskId = yield* runtimeDiskId(mount.disk, mount.path);
+                mounts.push(yield* toSandboxMount(diskId, mount));
+              }
+              const { data } = yield* archil
+                .createSandbox(
+                  toCreateSandboxRequest(name, { ...request, image: defaultImage }, mounts),
+                )
+                .pipe(
+                  Effect.catchTag("SandboxNameConflict", (conflict) =>
+                    findSandboxByName(name).pipe(
+                      Effect.flatMap((found) =>
+                        found ? Effect.succeed({ data: found }) : Effect.fail(conflict),
+                      ),
+                    ),
+                  ),
+                );
+              return handle(yield* waitForSandbox(data.sandbox_id));
+            }),
+          ),
+        get: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              const sandboxName = yield* fullName(name);
+              const found = yield* findSandboxByName(sandboxName);
+              return found ? handle(found) : undefined;
+            }),
+          ),
+        list: () =>
+          authorize(
+            Effect.gen(function* () {
+              const p = yield* prefix;
+              return (yield* listSandboxes())
+                .filter((s) => s.name.startsWith(`${p}-`) && s.status !== "deleted")
+                .map(handle);
+            }),
+          ),
+        delete: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              const sandboxName = yield* fullName(name);
+              const found = yield* findSandboxByName(sandboxName);
+              if (found) yield* deleteSandbox(found.sandbox_id);
+            }),
+          ),
+      } satisfies CreateSandboxClient;
+    });
+  }),
+);