@alchemy.run/e2b 0.0.0-stage → 2.0.0-beta.86

package/lib/Snapshot.js

@@ -0,0 +1,158 @@
+import * as crypto from "node:crypto";
+import * as templates from "@distilled.cloud/e2b/templates";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { declarable } from "./internal/Declared.js";
+import { e2bName, isGeneratedName } from "./internal/Ownership.js";
+import { takeSnapshot } from "./internal/SnapshotBuild.js";
+/**
+ * A warm base to fork sandboxes from: a template booted, set up with your
+ * commands, and snapshotted — memory included, so sandboxes created from it
+ * start exactly where the setup left off.
+ *
+ * Use a snapshot for work that is too slow to repeat per sandbox and does
+ * not belong in an image: cloning a repository, installing its
+ * dependencies, starting a language server. A deploy re-runs the setup only
+ * when the template or the commands change. E2B stores a snapshot as a
+ * template, so it is created from with `E2B.CreateSandbox(snapshot)` and
+ * deleted with its template.
+ *
+ * ### Creating a Snapshot
+ * **Example:** A repository with its dependencies installed
+ * ```typescript
+ * export const Agent = E2B.Template("Agent", { image: "node:22-bookworm" });
+ *
+ * export const Warm = E2B.Snapshot("Warm", {
+ *   template: Agent,
+ *   run: [
+ *     "git clone https://github.com/alchemy-run/alchemy /home/user/alchemy",
+ *     "cd /home/user/alchemy && pnpm install",
+ *   ],
+ * });
+ * ```
+ *
+ * ### Forking sandboxes from a Snapshot
+ * **Example:** Every sandbox starts from the warm base
+ * ```typescript
+ * const sandboxes = yield* E2B.CreateSandbox(Warm);
+ * const sandbox = yield* sandboxes.create({ timeout: 600 });
+ * yield* sandbox.exec("cd alchemy && pnpm test");
+ * ```
+ *
+ * ### Referencing a snapshot the stack doesn't manage
+ * `E2B.Snapshot.lookup` finds an existing snapshot by name. Nothing is created,
+ * adopted or deleted.
+ *
+ * **Example:** Look one up by name
+ * ```typescript
+ * const warm = E2B.Snapshot.lookup({ name: "warm-repo" });
+ * const sandboxes = yield* E2B.CreateSandbox(warm);
+ * ```
+ *
+ * @resource
+ * @product Snapshot
+ */
+export const Snapshot = declarable()(Resource("E2B.Snapshot"));
+const setupHashOf = (props) => crypto
+    .createHash("sha256")
+    .update(JSON.stringify({
+    template: props.template.templateId,
+    build: props.template.buildId ?? props.template.setupHash,
+    run: props.run,
+    envs: props.envs,
+    cwd: props.cwd,
+    memory: props.memory ?? true,
+}))
+    .digest("hex");
+/** The snapshot template, by alias. */
+const observe = (name) => templates.getTemplateByAlias({ alias: name }).pipe(Effect.flatMap((alias) => templates.getTemplate({ templateID: alias.templateID })), Effect.map((template) => template), Effect.catchTag("NotFound", () => Effect.undefined));
+export const SnapshotProvider = () => Provider.effect(Snapshot, Effect.gen(function* () {
+    return {
+        stables: ["name", "templateId"],
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+            if (!isResolved(news))
+                return undefined;
+            const name = output?.name ?? (yield* e2bName(id, olds?.name));
+            if (news.name !== undefined && news.name !== name)
+                return { action: "replace" };
+            if (output !== undefined && setupHashOf(news) !== output.setupHash) {
+                return { action: "update" };
+            }
+            return undefined;
+        }),
+        lookup: Effect.fn(function* ({ name }) {
+            const template = yield* observe(name);
+            if (template === undefined)
+                return undefined;
+            return {
+                snapshotId: template.names[0] ?? template.templateID,
+                name,
+                templateId: template.templateID,
+                names: [...template.names],
+                setupHash: "",
+            };
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+            const name = output?.name ?? (yield* e2bName(id, olds?.name));
+            const template = yield* observe(name);
+            if (template === undefined)
+                return undefined;
+            const attrs = {
+                snapshotId: output?.snapshotId ?? template.names[0] ?? template.templateID,
+                name,
+                templateId: template.templateID,
+                names: [...template.names],
+                setupHash: output?.setupHash ?? "",
+            };
+            return output !== undefined || olds?.name === undefined ? attrs : Unowned(attrs);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+            const name = output?.name ?? (yield* e2bName(id, news.name));
+            const setupHash = setupHashOf(news);
+            // Observe — an existing ready snapshot of this exact setup is kept.
+            const observed = yield* observe(name);
+            if (observed !== undefined &&
+                observed.buildStatus === "ready" &&
+                output?.setupHash === setupHash) {
+                return { ...output, names: [...observed.names], templateId: observed.templateID };
+            }
+            // Ensure — snapshotting under an existing name adds a new build to
+            // the same template.
+            yield* session.note(`Snapshotting ${name}...`);
+            const snapshot = yield* takeSnapshot(name, {
+                ...news,
+                template: news.template.templateId,
+            });
+            const template = yield* observe(name);
+            return {
+                snapshotId: snapshot.snapshotID,
+                name,
+                templateId: template?.templateID ?? snapshot.snapshotID,
+                names: [...snapshot.names],
+                setupHash,
+            };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            yield* templates
+                .deleteTemplate({ templateID: output.templateId })
+                .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+            const all = Array.from(yield* Stream.runCollect(templates.listTemplates.items({ limit: 100 })));
+            return all
+                .filter((template) => template.aliases.some(isGeneratedName))
+                .map((template) => ({
+                snapshotId: template.names[0] ?? template.templateID,
+                name: template.aliases.find(isGeneratedName) ?? template.templateID,
+                templateId: template.templateID,
+                names: [...template.names],
+                setupHash: "",
+            }));
+        }),
+    };
+}));
+//# sourceMappingURL=Snapshot.js.map

package/lib/Snapshot.js.map

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

package/lib/Template.d.ts

@@ -0,0 +1,313 @@
+import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
+import type { DockerfileBuild } from "@alchemy.run/docker/ImageSource";
+import * as templates from "@distilled.cloud/e2b/templates";
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import { type MountCapability } from "alchemy/Mount";
+import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import type { Resource } from "alchemy/Resource";
+import { type HostRuntimeContext, type ServerHost } from "alchemy/Runtime/Process";
+import * as Effect from "effect/Effect";
+import { type TemplateSteps } from "./internal/TemplateBuild.ts";
+import type { VolumeMount } from "./MountVolume.ts";
+import type { Providers } from "./Providers.ts";
+export type { TemplateFile, TemplateRegistry, TemplateSteps } from "./internal/TemplateBuild.ts";
+export interface TemplateProps extends Omit<TemplateSteps, "env">, PlatformProps {
+    /**
+     * A Dockerfile: a path (relative to the working directory) or inline
+     * content (`Dockerfile.inline` from `@alchemy.run/docker`). Lowered to
+     * E2B build steps; see the resource docs for what E2B supports.
+     * Exclusive with `image` and `fromTemplate` unless `main` is set, where
+     * it is the program's environment.
+     */
+    dockerfile?: string | InlineDockerfile;
+    /**
+     * The directory `COPY` / `ADD` sources are relative to, for a Dockerfile
+     * path. An inline Dockerfile has no build context.
+     * @default the working directory
+     */
+    context?: string;
+    /**
+     * A program to run in every sandbox: a module entrypoint, typically
+     * `import.meta.url` in the class form. Alchemy bundles it, copies it into
+     * the template under `/app`, and starts it with Bun as the template's start
+     * command, so every sandbox boots with it already serving on {@link port}.
+     * `image` / `dockerfile` are then the program's environment, which must
+     * have Bun; the default is `oven/bun:1`.
+     * @default no program
+     */
+    main?: string;
+    /**
+     * Named export to load from `main`.
+     * @default "default"
+     */
+    handler?: string;
+    /**
+     * Port the program serves HTTP on, as `PORT`. A sandbox serves it at
+     * `(yield* sandbox.getTcpPort(port)).url`.
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Bundler configuration for `main`, and `args` for the Dockerfile's
+     * `ARG`s (like `docker build --build-arg`).
+     */
+    build?: Bundle.BundleConfig & Pick<DockerfileBuild, "args">;
+    /**
+     * Environment variables for the template. With a program, also the
+     * program's environment, after the values its bindings set.
+     *
+     * Values are written into the template, so every sandbox created from it
+     * can read them. A `Redacted` value is not exposed in Alchemy's state or
+     * logs, but code inside the sandbox can read it.
+     */
+    env?: Record<string, any>;
+    /**
+     * Template name, used to create sandboxes from it. Lowercase letters,
+     * digits, `-` and `_`. If omitted, a unique name is generated from the
+     * stack, stage and logical ID. Changing it replaces the template.
+     */
+    name?: string;
+    /** Tags assigned to each build, e.g. `["v1"]`. */
+    tags?: string[];
+    /**
+     * vCPUs of every sandbox created from the template.
+     * @default 2
+     */
+    cpuCount?: number;
+    /**
+     * Memory of every sandbox created from the template, in MiB.
+     * @default 512
+     */
+    memoryMB?: number;
+    /** Free disk space every sandbox starts with, in MiB. */
+    minFreeDiskMb?: number;
+    /**
+     * Whether other E2B teams can create sandboxes from the template.
+     * @default false
+     */
+    public?: boolean;
+    /** Rebuild every layer on the next deploy, ignoring E2B's cache. */
+    force?: boolean;
+}
+export interface TemplateAttributes {
+    /** E2B's template id. Sandboxes are created from it. */
+    templateId: string;
+    /** The template's name (alias). */
+    name: string;
+    /** The current build. */
+    buildId: string;
+    /** Content hash of the build inputs. A deploy rebuilds only when it changes. */
+    buildHash: string;
+    /** Content hash of the build inputs other than bindings' env, compared at plan time. */
+    sourceHash: string;
+    /** Fully qualified names, e.g. `my-team/my-template:default`. */
+    names: string[];
+    public: boolean;
+    cpuCount: number | undefined;
+    memoryMB: number | undefined;
+    /**
+     * Volumes the template's program mounts (`E2B.MountVolume`). E2B attaches
+     * volumes when a sandbox is created, so `CreateSandbox(template)` and
+     * `E2B.Sandbox({ template })` mount them on every sandbox.
+     */
+    mounts: VolumeMount[];
+}
+/** What bindings attach to a template program. */
+export interface TemplateBinding {
+    /** The program's environment. */
+    env?: Record<string, any>;
+    /**
+     * Mount clients (`alchemy/Mount`) the program needs, installed into the
+     * template. E2B sandboxes have FUSE and NFS.
+     */
+    mounts?: ReadonlyArray<MountCapability>;
+    /** E2B volumes every sandbox from the template mounts (`E2B.MountVolume`). */
+    volumes?: VolumeMount[];
+}
+export interface Template extends Resource<"E2B.Template", TemplateProps, TemplateAttributes, TemplateBinding, Providers, {
+    name: string;
+}> {
+}
+/**
+ * An E2B template: the image every sandbox boots from, built by E2B into a
+ * Firecracker snapshot.
+ *
+ * Build from a registry `image`, a `dockerfile` (a path or inline content),
+ * or another template (`fromTemplate`). E2B builds remotely, so a deploy
+ * needs no Docker daemon: Alchemy plans the Dockerfile with
+ * `@alchemy.run/docker`'s build plan, lowers it to E2B's build steps, and
+ * uploads only the `COPY` sources E2B has not seen, by content hash. A
+ * deploy starts a new build only when the inputs change.
+ *
+ * E2B's builder runs one stage for `linux/amd64`. A Dockerfile with several
+ * `FROM`s, `COPY --from`, `ADD <url>`, heredocs, `RUN --mount` or `SHELL`
+ * fails at plan time with `UnsupportedDockerfile`, listing the lines.
+ * `EXPOSE`, `LABEL`, `VOLUME`, `HEALTHCHECK` and `STOPSIGNAL` are ignored,
+ * as E2B ignores them. An `ARG` becomes an environment variable. `CMD` / `ENTRYPOINT`
+ * become the template's start command: it is captured running in the
+ * snapshot, so every sandbox starts with it already up.
+ *
+ * E2B templates carry no labels, so Alchemy recognises its templates by
+ * their generated name.
+ *
+ * ### Building a Template
+ * **Example:** From a registry image
+ * ```typescript
+ * export const Python = E2B.Template("Python", { image: "python:3.12-slim" });
+ * ```
+ *
+ * **Example:** From an inline Dockerfile
+ * ```typescript
+ * import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
+ *
+ * export const Agent = E2B.Template("Agent", {
+ *   dockerfile: Dockerfile.inline`
+ *     FROM node:22-bookworm
+ *     RUN apt-get update && apt-get install -y git ripgrep
+ *     WORKDIR /work
+ *   `,
+ *   cpuCount: 2,
+ *   memoryMB: 4096,
+ * });
+ * ```
+ *
+ * **Example:** From a Dockerfile and its build context
+ * ```typescript
+ * export const Repo = E2B.Template("Repo", {
+ *   context: "./sandbox",
+ *   dockerfile: "./sandbox/Dockerfile",
+ *   build: { args: { NODE_VERSION: "22" } },
+ * });
+ * ```
+ *
+ * ### Starting a process in every sandbox
+ * **Example:** A dev server that is already running when a sandbox starts
+ * ```typescript
+ * export const Preview = E2B.Template("Preview", {
+ *   image: "node:22-bookworm",
+ *   run: ["npm create vite@latest app -- --template react", "cd app && npm install"],
+ *   startCmd: "cd /home/user/app && npm run dev -- --host 0.0.0.0 --port 3000",
+ *   readyCmd: "curl -sf http://localhost:3000",
+ * });
+ * ```
+ *
+ * ### Private base images
+ * **Example:** A base image in GHCR
+ * ```typescript
+ * export const Private = E2B.Template("Private", {
+ *   image: "ghcr.io/my-org/base:1",
+ *   registry: { username: "my-org", password: Config.Redacted("GHCR_TOKEN") },
+ * });
+ * ```
+ *
+ * ### Effect program
+ * Give the template a `main` and an Effect, and every sandbox from it boots
+ * with the program already serving HTTP on `port`. Alchemy bundles `main`,
+ * copies it into the template, and E2B snapshots the template once the
+ * program answers. The program runs with Bun; the image defaults to
+ * `oven/bun:1`.
+ *
+ * **Example:** A program in every sandbox
+ * ```typescript
+ * export default class Program extends E2B.Template<Program>()(
+ *   "Program",
+ *   { main: import.meta.url, port: 3000 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("hello from a sandbox")),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * **Example:** Call the program in a sandbox
+ * ```typescript
+ * const sandboxes = yield* E2B.CreateSandbox(Program);
+ * const sandbox = yield* sandboxes.create({ timeout: 300 });
+ * const port = yield* sandbox.getTcpPort(3000);
+ * const res = yield* port.fetch(HttpClientRequest.get("/"));
+ * ```
+ *
+ * ### Async program
+ * A `main` without an Effect is bundled and run with Bun as-is. It must
+ * listen on `PORT`. `E2B.InferEnv` types its `env`.
+ *
+ * **Example:** A plain server
+ * ```typescript
+ * export const Server = E2B.Template("Server", {
+ *   main: "./src/server.mjs",
+ *   env: { GREETING: "hi" },
+ * });
+ * export type ServerEnv = E2B.InferEnv<typeof Server>;
+ * ```
+ *
+ * ### Bindings in the sandbox
+ * Bindings work inside a template program like in any other host.
+ *
+ * :::caution[Values are part of the template]
+ * Config and binding values are written into the template, so code in a
+ * sandbox can read them, `Redacted` ones included. Use egress secrets for
+ * credentials untrusted code must not see.
+ * :::
+ *
+ * **Example:** Read a volume from the program
+ * ```typescript
+ * export default class Program extends E2B.Template<Program>()(
+ *   "Program",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const reports = yield* E2B.ReadVolume(Reports);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         return HttpServerResponse.text(yield* reports.readText("/latest.json"));
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(E2B.ReadVolumeHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Configuration
+ * **Example:** Size, image and port
+ * ```typescript
+ * export default class Program extends E2B.Template<Program>()(
+ *   "Program",
+ *   { main: import.meta.url, image: "oven/bun:1-debian", cpuCount: 4, memoryMB: 8192, port: 8080 },
+ *   Effect.gen(function* () {
+ *     return { fetch: Effect.succeed(HttpServerResponse.text("ok")) };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * **Example:** Sandboxes from the template, in a Worker
+ * ```typescript
+ * const sandboxes = yield* E2B.CreateSandbox(Agent);
+ * const sandbox = yield* sandboxes.create({ timeout: 600 });
+ * ```
+ *
+ * ### Referencing a template the stack doesn't manage
+ * `E2B.Template.lookup` finds an existing template by name. Nothing is created,
+ * adopted or deleted.
+ *
+ * **Example:** Look one up by name
+ * ```typescript
+ * const base = E2B.Template.lookup({ name: "my-team/base-image" });
+ * const sandboxes = yield* E2B.CreateSandbox(base);
+ * ```
+ *
+ * @resource
+ * @product Template
+ */
+export declare const Template: Platform<Template, ServerHost, Main<ServerHost>, HostRuntimeContext> & {
+    /**
+     * Reference a template this stack doesn't manage (E2B's `base`, or one
+     * another stack builds) by name, without managing it.
+     */
+    lookup(props: {
+        name: string;
+    }): Template;
+};
+/** A template by id, or by name (alias). */
+export declare const observeTemplate: (templateId: string | undefined, name: string) => Effect.Effect<templates.GetTemplateResponse | undefined, import("@distilled.cloud/e2b").BadRequest | import("@distilled.cloud/e2b").ConfigError | import("@distilled.cloud/e2b").Conflict | import("@distilled.cloud/e2b").Forbidden | import("effect/http/HttpClientError").HttpClientError | import("@distilled.cloud/core/protocol-http").InvalidInput | import("@distilled.cloud/e2b").Locked | import("@distilled.cloud/core/sdk-error").SdkError | import("@distilled.cloud/e2b").UnprocessableEntity | import("@distilled.cloud/e2b").ClientErrors | import("@distilled.cloud/core/errors").DefaultErrors, templates.E2BOpContext>;
+export declare const TemplateProvider: () => import("effect/Layer").Layer<Provider.Provider<Template>, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | templates.E2BOpContext>;
+//# sourceMappingURL=Template.d.ts.map

package/lib/Template.d.ts.map

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