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

package/src/ConnectSandbox.ts

@@ -0,0 +1,60 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Sandbox } from "./Sandbox.ts";
+import type { ConnectedSandbox } from "./SandboxClient.ts";
+
+/**
+ * Work with one {@link Sandbox} declared in the stack, from a Worker,
+ * Function or any other host: run commands, read and write files, call its
+ * ports, stop, resume or snapshot it. The handle has the same operations
+ * as the sandboxes `CreateSandbox` returns, except `fork` and `delete`; its
+ * `sandboxId` is an Effect, read at runtime.
+ *
+ * A declared sandbox stops after its `autoStop`. Calls into it then fail
+ * with `SandboxNotRunning` until you `resume()` it.
+ *
+ * The host gets its own Boat API key, minted at deploy and revoked when the
+ * host is destroyed. The key reaches only this sandbox.
+ *
+ * ### Running commands in a dev box
+ * **Example:** Pull and test on request
+ * ```typescript
+ * const devBox = yield* Boat.ConnectSandbox(DevBox);
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     yield* devBox.resume({ autoStop: "10 minutes" });
+ *     const test = yield* devBox.exec("git pull && npm test", { cwd: "/home/user/repo" });
+ *     return yield* HttpServerResponse.json(test);
+ *   }),
+ * };
+ * ```
+ *
+ * ### Calling a program in the sandbox
+ * **Example:** Call port 3000
+ * ```typescript
+ * const port = yield* devBox.getTcpPort(3000);
+ * const response = yield* port.fetch(HttpClientRequest.get("/health"));
+ * ```
+ *
+ * **Example:** Proxy the Worker's request to port 3000
+ * ```typescript
+ * const port = yield* devBox.getTcpPort(3000);
+ * return yield* port.fetch(yield* HttpServerRequest);
+ * ```
+ *
+ * ### Stopping it early
+ * **Example:** Stop when the work is done
+ * ```typescript
+ * yield* devBox.stop();
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface ConnectSandbox extends Binding.Service<
+  ConnectSandbox,
+  "Boat.ConnectSandbox",
+  (sandbox: Sandbox) => Effect.Effect<ConnectedSandbox>
+> {}
+
+export const ConnectSandbox = Binding.Service<ConnectSandbox>("Boat.ConnectSandbox");

package/src/ConnectSandboxHttp.ts

@@ -0,0 +1,59 @@
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { ApiKeyAction } from "./ApiKey.ts";
+import { bindBoat } from "./BoatBindings.ts";
+import { ConnectSandbox } from "./ConnectSandbox.ts";
+import { makeConnectedSandbox } from "./internal/SandboxHandle.ts";
+import type { Sandbox } from "./Sandbox.ts";
+
+/** What a `ConnectSandbox` host may do, on its one sandbox. */
+const CONNECT_SANDBOX_ACTIONS: ApiKeyAction[] = [
+  "sandbox.read",
+  "sandbox.update",
+  "sandbox.stop",
+  "sandbox.resume",
+  "exec",
+  "file.read",
+  "file.write",
+  "host",
+  "snapshot.read",
+  "snapshot.write",
+];
+
+/** `DevBox` → `DEV_BOX`, for the env var that carries its key. */
+const envSuffix = (logicalId: string) =>
+  logicalId
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .toUpperCase();
+
+/**
+ * HTTP implementation of {@link ConnectSandbox}: Boat's REST API with a key
+ * that reaches only the bound sandbox. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Cloudflare Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const devBox = yield* Boat.ConnectSandbox(DevBox);
+ *   // ...
+ * }).pipe(Effect.provide(Boat.ConnectSandboxHttp))
+ * ```
+ *
+ * @layer
+ * @product Sandbox
+ * @provides Boat.ConnectSandbox
+ */
+export const ConnectSandboxHttp = Layer.succeed(
+  ConnectSandbox,
+  Effect.fn("Boat.ConnectSandbox")(function* (sandbox: Sandbox) {
+    const auth = yield* bindBoat(
+      `${sandbox.LogicalId}Key`,
+      `BOAT_${envSuffix(sandbox.LogicalId)}_KEY`,
+      { actions: CONNECT_SANDBOX_ACTIONS, sandboxIds: [sandbox.sandboxId] },
+    );
+    const sandboxId = yield* (sandbox.sandboxId as Output.Output<string, never>).asEffect();
+    return makeConnectedSandbox(auth, sandboxId);
+  }),
+);

package/src/Contributions.ts

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

package/src/CreateSandbox.ts

@@ -0,0 +1,143 @@
+import type * as boat from "@distilled.cloud/boat-dev/boat";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Duration from "effect/Duration";
+import type * as Effect from "effect/Effect";
+import type { BoatError, BoatSandbox } from "./SandboxClient.ts";
+import type { Snapshot } from "./Snapshot.ts";
+
+/**
+ * Boat's `createSandbox` parameters, with `autoStop` in place of
+ * `ttlSeconds`. `from` defaults to the bound snapshot; `labels` are merged
+ * under the host's ownership labels.
+ */
+export type CreateSandboxOptions = Omit<boat.CreateSandboxRequest, "count" | "ttlSeconds"> & {
+  /**
+   * How long the sandbox runs before Boat stops it, saving its disk;
+   * `false` never stops it.
+   * @default "1 hour"
+   */
+  readonly autoStop?: Duration.Input | false;
+};
+
+/** Boat's `listSandboxes` filters, with `labels` as a record. */
+export interface ListSandboxesOptions {
+  /** Only sandboxes with all of these labels. */
+  readonly labels?: Readonly<Record<string, string>>;
+  /** Only sandboxes in these states, e.g. `["ready", "idle", "running"]`. */
+  readonly state?: ReadonlyArray<boat.SandboxState>;
+}
+
+/** Boat sandboxes: create, connect to, list and delete them. */
+export interface SandboxesClient {
+  /** Creates a sandbox, from the bound snapshot unless `from` says otherwise. */
+  create(options?: CreateSandboxOptions): Effect.Effect<BoatSandbox, BoatError, RuntimeContext>;
+  /** A handle to an existing sandbox. */
+  connect(sandboxId: string): Effect.Effect<BoatSandbox, BoatError, RuntimeContext>;
+  /** A sandbox's details. */
+  get(sandboxId: string): Effect.Effect<boat.Sandbox, BoatError, RuntimeContext>;
+  /** Sandboxes, filtered by labels or state. */
+  list(
+    options?: ListSandboxesOptions,
+  ): Effect.Effect<ReadonlyArray<boat.Sandbox>, BoatError, RuntimeContext>;
+  /**
+   * Deletes a sandbox this host created, with its disk. Deleting one that
+   * is gone succeeds.
+   */
+  delete(sandboxId: string): Effect.Effect<void, BoatError, RuntimeContext>;
+}
+
+/**
+ * Create and manage Boat sandboxes from a Worker, Function or any other
+ * host.
+ *
+ * `Boat.CreateSandbox(snapshot)` creates sandboxes from a snapshot declared
+ * in the stack; `Boat.CreateSandbox()` creates them from scratch, or from
+ * the `from` each call passes. Both return the same client, whose calls take
+ * Boat's own parameters.
+ *
+ * Sandboxes created at run time are labelled with the stack, stage and
+ * host (`alchemy.stack`, `alchemy.stage`, `alchemy.id`) and are not deleted
+ * when the stack is destroyed. List them by those labels to clean them up:
+ * `sandboxes.list({ labels: { "alchemy.stack": "my-app", "alchemy.stage": "prod" } })`.
+ * Labels you pass to `create` merge underneath; they never replace the
+ * `alchemy.*` ones.
+ *
+ * The host gets its own Boat API key, minted at deploy and revoked when the
+ * host is destroyed. It may create sandboxes and work in them, and delete
+ * only the sandboxes it created; it can't touch the account's other
+ * sandboxes, environments, keys or billing.
+ *
+ * ### Creating sandboxes
+ * **Example:** One sandbox per request, deleted when the request ends
+ * ```typescript
+ * const sandboxes = yield* Boat.CreateSandbox();
+ * // in fetch:
+ * const sandbox = yield* Effect.acquireRelease(
+ *   sandboxes.create({ type: "small", noEnv: true, autoStop: "10 minutes" }),
+ *   (sandbox) => Effect.ignore(sandbox.delete()),
+ * );
+ * const result = yield* sandbox.exec("node --version");
+ * ```
+ *
+ * **Example:** From a snapshot declared in the stack
+ * ```typescript
+ * const sandboxes = yield* Boat.CreateSandbox(Golden);
+ * const sandbox = yield* sandboxes.create();
+ * ```
+ *
+ * **Example:** A long-lived sandbox per task, found by label
+ * ```typescript
+ * const [existing] = yield* sandboxes.list({ labels: { task } });
+ * const sandbox = existing
+ *   ? yield* sandboxes.connect(existing.id)
+ *   : yield* sandboxes.create({ labels: { task }, autoStop: "30 minutes" });
+ * ```
+ *
+ * ### Running commands
+ * `exec` runs to completion and returns `{ exitCode, stdout, stderr }`; a
+ * non-zero exit is returned, not failed. A string runs in a shell, an
+ * array runs its arguments quoted.
+ *
+ * **Example:** A shell line, an argument vector, stdin and a timeout
+ * ```typescript
+ * const test = yield* sandbox.exec("npm test", { cwd: "/home/user/app" });
+ * const version = yield* sandbox.exec(["node", "--version"]);
+ * const sorted = yield* sandbox.exec("sort", { stdin: "b\na\n" });
+ * const slow = yield* sandbox.exec("make", { timeout: "2 minutes" }); // Boat.ExecTimedOut
+ * ```
+ *
+ * **Example:** Start a server in the background and stream its output
+ * ```typescript
+ * const server = yield* sandbox.start("npm run dev", { cwd: "/home/user/app" });
+ * yield* server.output.pipe(
+ *   Stream.take(5),
+ *   Stream.runForEach((chunk) => Effect.log(new TextDecoder().decode(chunk.data))),
+ * );
+ * ```
+ *
+ * ### Calling a port
+ * **Example:** Proxy the Worker's request to port 3000
+ * ```typescript
+ * const port = yield* sandbox.getTcpPort(3000);
+ * return yield* port.fetch(yield* HttpServerRequest);
+ * ```
+ *
+ * ### Forking and snapshots
+ * **Example:** Save a sandbox and fork it
+ * ```typescript
+ * yield* sandbox.stop(); // stopping snapshots it
+ * const copy = yield* sandbox.fork({ autoStop: "10 minutes" });
+ * yield* sandbox.resume();
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface CreateSandbox extends Binding.Service<
+  CreateSandbox,
+  "Boat.CreateSandbox",
+  (base?: Snapshot) => Effect.Effect<SandboxesClient>
+> {}
+
+export const CreateSandbox = Binding.Service<CreateSandbox>("Boat.CreateSandbox");

package/src/CreateSandboxHttp.ts

@@ -0,0 +1,115 @@
+import * as boat from "@distilled.cloud/boat-dev/boat";
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import type { ApiKeyAction } from "./ApiKey.ts";
+import { bindBoat, bindOwnerLabels } from "./BoatBindings.ts";
+import { CreateSandbox, type CreateSandboxOptions, type SandboxesClient } from "./CreateSandbox.ts";
+import { BoatUnexpectedResponse } from "./Errors.ts";
+import { labelFilter } from "./internal/Ownership.ts";
+import { makeSandboxHandle, ttlOf } from "./internal/SandboxHandle.ts";
+import type { Snapshot } from "./Snapshot.ts";
+
+/** What a `CreateSandbox` host may do: work in sandboxes, and delete only its own. */
+const CREATE_SANDBOX_ACTIONS: ApiKeyAction[] = [
+  "sandbox.create",
+  "sandbox.read",
+  "sandbox.update",
+  "sandbox.stop",
+  "sandbox.resume",
+  "sandbox.fork",
+  "sandbox.delete-own",
+  "exec",
+  "file.read",
+  "file.write",
+  "host",
+  "snapshot.read",
+  "snapshot.write",
+];
+
+/**
+ * HTTP implementation of {@link CreateSandbox}: Boat's REST API with the
+ * host's own key. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Cloudflare Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const sandboxes = yield* Boat.CreateSandbox();
+ *   // ...
+ * }).pipe(Effect.provide(Boat.CreateSandboxHttp))
+ * ```
+ *
+ * @layer
+ * @product Sandbox
+ * @provides Boat.CreateSandbox
+ */
+export const CreateSandboxHttp = Layer.succeed(
+  CreateSandbox,
+  Effect.fn("Boat.CreateSandbox")(function* (base?: Snapshot) {
+    const auth = yield* bindBoat("BoatSandboxesKey", "BOAT_SANDBOXES_KEY", {
+      actions: CREATE_SANDBOX_ACTIONS,
+    });
+    const owner = yield* bindOwnerLabels;
+    const baseName: Effect.Effect<string> | undefined =
+      base === undefined
+        ? undefined
+        : yield* (base.name as Output.Output<string, never>).asEffect();
+
+    const handleOf = (sandbox: boat.Sandbox) => makeSandboxHandle(auth, sandbox, owner);
+
+    const client: SandboxesClient = {
+      create: Effect.fn("Boat.CreateSandbox.create")(function* (
+        createOptions: CreateSandboxOptions = {},
+      ) {
+        const { autoStop, ...options } = createOptions;
+        const from = options.from ?? (baseName === undefined ? undefined : yield* baseName);
+        const created = yield* auth.authorize(
+          boat.createSandbox({
+            ...options,
+            ...(autoStop === undefined ? {} : { ttlSeconds: ttlOf(autoStop) }),
+            ...(from === undefined ? {} : { from }),
+            labels: { ...options.labels, ...(yield* owner) },
+          }),
+        );
+        return handleOf(created.sandbox);
+      }),
+      connect: Effect.fn("Boat.CreateSandbox.connect")(function* (sandboxId) {
+        const got = yield* auth.authorize(boat.getSandbox({ sandboxId }));
+        if (got.sandbox === undefined) {
+          return yield* new BoatUnexpectedResponse({
+            message: `Boat returned no sandbox for ${sandboxId}`,
+          });
+        }
+        return handleOf(got.sandbox);
+      }),
+      get: Effect.fn("Boat.CreateSandbox.get")(function* (sandboxId) {
+        const got = yield* auth.authorize(boat.getSandbox({ sandboxId }));
+        if (got.sandbox === undefined) {
+          return yield* new BoatUnexpectedResponse({
+            message: `Boat returned no sandbox for ${sandboxId}`,
+          });
+        }
+        return got.sandbox;
+      }),
+      list: Effect.fn("Boat.CreateSandbox.list")(function* (options) {
+        const all = yield* auth.authorize(
+          Stream.runCollect(
+            boat.listSandboxes.items({
+              ...(options?.labels === undefined ? {} : { label: labelFilter(options.labels) }),
+              ...(options?.state === undefined ? {} : { state: options.state.join(",") }),
+            }),
+          ),
+        );
+        return Array.from(all);
+      }),
+      delete: (sandboxId) =>
+        auth.authorize(boat.deleteSandbox({ sandboxId, xAsciiConfirmDelete: sandboxId })).pipe(
+          Effect.asVoid,
+          Effect.catchTag("NotFound", () => Effect.void),
+        ),
+    };
+    return client;
+  }),
+);