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

package/src/Errors.ts

@@ -0,0 +1,47 @@
+import * as Data from "effect/Data";
+
+/** E2B answered in a way a lifecycle step cannot continue from (e.g. a resource vanished right after create). */
+export class E2BUnexpectedResponse extends Data.TaggedError("E2B.UnexpectedResponse")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/** A template build finished in a failed state. */
+export class TemplateBuildFailed extends Data.TaggedError("E2B.TemplateBuildFailed")<{
+  readonly message: string;
+  readonly templateId: string;
+  readonly buildId: string;
+  readonly reason?: string;
+  readonly logs?: ReadonlyArray<string>;
+}> {}
+
+/** A Dockerfile uses something E2B's builder does not support. Raised at plan time. */
+export class UnsupportedDockerfileInstruction extends Data.TaggedError(
+  "E2B.UnsupportedDockerfileInstruction",
+)<{
+  readonly message: string;
+  readonly line?: number;
+}> {}
+
+/** A command run while building a snapshot exited non-zero. */
+export class SnapshotSetupFailed extends Data.TaggedError("E2B.SnapshotSetupFailed")<{
+  readonly message: string;
+  readonly command: string;
+  readonly exitCode: number;
+  readonly stderr: string;
+}> {}
+
+/** `E2B.CreateSandbox()` was bound without a base and `create()` was called without `templateID`. */
+export class SandboxBaseMissing extends Data.TaggedError("E2B.SandboxBaseMissing")<{
+  readonly message: string;
+}> {}
+
+/** `exec` killed a command that ran past its `timeout`. */
+export class ExecTimedOut extends Data.TaggedError("E2B.ExecTimedOut")<{
+  readonly pid: number;
+  readonly timeoutMs: number;
+}> {
+  override get message() {
+    return `process ${this.pid} ran longer than ${this.timeoutMs}ms and was killed`;
+  }
+}

package/src/InferEnv.ts

@@ -0,0 +1,27 @@
+import type * as Effect from "effect/Effect";
+
+/**
+ * Typed `env` for an async (non-Effect) {@link Template} program. A
+ * template program reads its bindings from environment variables, so every
+ * entry is a `string`: cast `process.env` to it.
+ *
+ * @example
+ * ```typescript
+ * export const Worker = E2B.Template("Worker", {
+ *   image: "node:22-bookworm",
+ *   main: "./src/worker.mjs",
+ *   env: { QUEUE_URL: queue.url },
+ * });
+ * export type WorkerEnv = E2B.InferEnv<typeof Worker>;
+ * ```
+ */
+export type InferEnv<F> =
+  F extends Effect.Effect<infer A, infer _E, infer _R>
+    ? InferEnv<A>
+    : F extends { readonly Props: { readonly env?: infer E } }
+      ? InferEnvRecord<Exclude<E, undefined>>
+      : InferEnvRecord<F>;
+
+type InferEnvRecord<E> = {
+  readonly [K in keyof E]: string;
+};

package/src/MountVolume.ts

@@ -0,0 +1,92 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Volume } from "./Volume.ts";
+
+/**
+ * A volume to mount: a declared `E2B.Volume`, or a volume `CreateVolume`
+ * returned. E2B mounts volumes by name.
+ */
+export interface MountableVolume {
+  readonly name: string;
+}
+
+/** A volume mounted into a sandbox at `path`. */
+export interface VolumeMount {
+  readonly volume: MountableVolume;
+  /** Absolute path inside the sandbox. */
+  readonly path: string;
+}
+
+/**
+ * A volume bound to a host with `E2B.MountVolume`. Its name is read at
+ * runtime, so pass the whole reference to `mounts`.
+ */
+export interface BoundVolumeMount {
+  readonly volume: { readonly name: Effect.Effect<string, never, RuntimeContext> };
+  /** Absolute path inside the sandbox. */
+  readonly path: string;
+}
+
+export interface MountVolumeOptions {
+  /** Absolute path inside the sandbox. */
+  readonly path: string;
+}
+
+/**
+ * Mount a declared `E2B.Volume` at a path.
+ *
+ * In an `E2B.Template` program, the mount becomes part of the template:
+ * every sandbox created from it (with `CreateSandbox(template)` or
+ * `E2B.Sandbox({ template })`) mounts the volume, and the program finds its
+ * files at `path`. E2B attaches volumes when a sandbox is created, so a
+ * sandbox already running keeps the mounts it started with.
+ *
+ * Anywhere else (a Worker, a Function), it returns a reference to pass to
+ * `create({ mounts })`.
+ *
+ * E2B enables volumes per team; on a team without them, deploying the
+ * volume fails with `VolumesNotEnabled`.
+ *
+ * ### In a template program
+ * **Example:** A program that serves a volume's files
+ * ```typescript
+ * export default class Api extends E2B.Template<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const data = yield* E2B.MountVolume(Data, { path: "/data" });
+ *     const fs = yield* FileSystem.FileSystem;
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const files = yield* fs.readDirectory(data.path);
+ *         return yield* HttpServerResponse.json(files);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(E2B.MountVolumeLive)),
+ * ) {}
+ * ```
+ *
+ * ### From a Worker
+ * **Example:** Mount a shared volume and a per-user one
+ * ```typescript
+ * const data = yield* E2B.MountVolume(Data, { path: "/data" });
+ * const sandboxes = yield* E2B.CreateSandbox(Agent);
+ * const volumes = yield* E2B.CreateVolume();
+ * // in fetch:
+ * const home = yield* volumes.getOrCreate(`home-${user}`);
+ * const sandbox = yield* sandboxes.create({
+ *   mounts: [data, { volume: home, path: "/home/user/work" }],
+ * });
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface MountVolume extends Binding.Service<
+  MountVolume,
+  "E2B.MountVolume",
+  (volume: Volume, options: MountVolumeOptions) => Effect.Effect<BoundVolumeMount>
+> {}
+
+export const MountVolume = Binding.Service<MountVolume>("E2B.MountVolume");

package/src/MountVolumeLive.ts

@@ -0,0 +1,49 @@
+import * as Binding from "alchemy/Binding";
+import * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { MountVolume, type BoundVolumeMount, type MountVolumeOptions } from "./MountVolume.ts";
+import type { Template } from "./Template.ts";
+import type { Volume } from "./Volume.ts";
+
+/**
+ * The implementation of {@link MountVolume}. It makes no API call: E2B
+ * mounts a volume by name when a sandbox is created, so the binding binds
+ * the name onto the host and, in an `E2B.Template` program, adds the mount
+ * to the template.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const data = yield* E2B.MountVolume(Data, { path: "/data" });
+ *   // ...
+ * }).pipe(Effect.provide(E2B.MountVolumeLive))
+ * ```
+ *
+ * @layer
+ * @product Volume
+ * @provides E2B.MountVolume
+ */
+export const MountVolumeLive = Layer.succeed(
+  MountVolume,
+  Effect.fn("E2B.MountVolume")(function* (volume: Volume, options: MountVolumeOptions) {
+    if (!globalThis.__ALCHEMY_RUNTIME__) {
+      const host = yield* Binding.Host;
+      // A mount is part of a template program's own sandboxes, so it is
+      // attached to the template itself. `Binding.Host` is typed as a bare
+      // `ResourceLike` (a host's binding contract is only known per type),
+      // hence the cast once the type is checked.
+      if (host?.Type === "E2B.Template") {
+        yield* (host as unknown as Template).bind`${volume}`({
+          volumes: [{ volume: { name: volume.name }, path: options.path }],
+        });
+      }
+    }
+    const name = yield* Output.named(
+      volume.name as Output.Output<string, never>,
+      `E2B_VOLUME_${volume.LogicalId}`,
+    ).asEffect();
+    return { volume: { name }, path: options.path } satisfies BoundVolumeMount;
+  }),
+);

package/src/Providers.ts

@@ -0,0 +1,48 @@
+import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
+import { ProfileStoreLive } from "alchemy/Auth/Profile";
+import * as Provider from "alchemy/Provider";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { ApiKey, ApiKeyProvider } from "./ApiKey.ts";
+import { E2BAuth } from "./AuthProvider.ts";
+import * as Credentials from "./Credentials.ts";
+import { Sandbox, SandboxProvider } from "./Sandbox.ts";
+import { Secret, SecretProvider } from "./Secret.ts";
+import { Snapshot, SnapshotProvider } from "./Snapshot.ts";
+import { Template, TemplateProvider } from "./Template.ts";
+import { Volume, VolumeProvider } from "./Volume.ts";
+import { Webhook, WebhookProvider } from "./Webhook.ts";
+
+export { Credentials } from "@distilled.cloud/e2b/Credentials";
+
+export class Providers extends Provider.ProviderCollection<Providers>()("E2B") {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * E2B providers and credentials. Wires up every E2B resource and registers
+ * the E2B AuthProvider so `alchemy profile edit --add E2B` can configure it.
+ */
+export const providers = () =>
+  Layer.effect(
+    Providers,
+    Provider.collection([ApiKey, Sandbox, Secret, Snapshot, Template, Volume, Webhook]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ApiKeyProvider(),
+        SandboxProvider(),
+        SecretProvider(),
+        SnapshotProvider(),
+        TemplateProvider(),
+        VolumeProvider(),
+        WebhookProvider(),
+      ),
+    ),
+    Layer.provideMerge(Credentials.fromAuthProvider()),
+    Layer.provideMerge(FetchHttpClient.layer),
+    Layer.provideMerge(E2BAuth),
+    Layer.provideMerge(ProfileStoreLive),
+    Layer.provideMerge(CredentialsStoreLive),
+    Layer.orDie,
+  );

package/src/ReadTeam.ts

@@ -0,0 +1,55 @@
+import type * as auth from "@distilled.cloud/e2b/auth";
+import type * as events from "@distilled.cloud/e2b/events";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { E2BError } from "./SandboxClient.ts";
+
+/** Team usage and the sandbox lifecycle event log. */
+export interface TeamClient {
+  /** The team's id: the deployer's team, which the host's key belongs to. */
+  readonly teamId: Effect.Effect<string, never, RuntimeContext>;
+  /** Concurrent sandboxes and sandbox start rate over time (unix seconds). */
+  metrics(
+    options?: Omit<auth.ListTeamMetricsRequest, "teamID">,
+  ): Effect.Effect<auth.ListTeamMetricsResponse, E2BError, RuntimeContext>;
+  /** The peak of one metric over a window. */
+  maxMetric(
+    options: Omit<auth.GetTeamMetricsMaxRequest, "teamID">,
+  ): Effect.Effect<auth.MaxTeamMetric, E2BError, RuntimeContext>;
+  /** Lifecycle events of every sandbox in the team, newest first by default. */
+  events(
+    options?: events.ListTeamSandboxEventsRequest,
+  ): Effect.Effect<events.ListTeamSandboxEventsResponse, E2BError, RuntimeContext>;
+  /** Lifecycle events of one sandbox. */
+  sandboxEvents(
+    sandboxId: string,
+    options?: Omit<events.ListSandboxEventsRequest, "sandboxID">,
+  ): Effect.Effect<events.ListSandboxEventsResponse, E2BError, RuntimeContext>;
+}
+
+/**
+ * Read the team's sandbox usage and lifecycle event log: dashboards, quotas,
+ * auditing which sandboxes started, paused and were killed.
+ *
+ * To react to lifecycle events as they happen, use `E2B.SandboxEvents`.
+ *
+ * ### Reading usage
+ * **Example:** Concurrent sandboxes over the last hour
+ * ```typescript
+ * const team = yield* E2B.ReadTeam();
+ * // in fetch:
+ * const now = Math.floor(Date.now() / 1000);
+ * const metrics = yield* team.metrics({ start: now - 3600, end: now });
+ * ```
+ *
+ * @binding
+ * @product Team
+ */
+export interface ReadTeam extends Binding.Service<
+  ReadTeam,
+  "E2B.ReadTeam",
+  () => Effect.Effect<TeamClient>
+> {}
+
+export const ReadTeam = Binding.Service<ReadTeam>("E2B.ReadTeam");

package/src/ReadTeamHttp.ts

@@ -0,0 +1,44 @@
+import * as auth from "@distilled.cloud/e2b/auth";
+import * as events from "@distilled.cloud/e2b/events";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { bindE2B } from "./E2BBindings.ts";
+import { ReadTeam, type TeamClient } from "./ReadTeam.ts";
+
+/**
+ * HTTP implementation of {@link ReadTeam}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const team = yield* E2B.ReadTeam();
+ *   // ...
+ * }).pipe(Effect.provide(E2B.ReadTeamHttp))
+ * ```
+ *
+ * @layer
+ * @product Team
+ * @provides E2B.ReadTeam
+ */
+export const ReadTeamHttp = Layer.succeed(
+  ReadTeam,
+  Effect.fn("E2B.ReadTeam")(function* () {
+    const e2b = yield* bindE2B;
+    const client: TeamClient = {
+      teamId: e2b.teamId,
+      metrics: Effect.fn("E2B.ReadTeam.metrics")(function* (options) {
+        const teamID = yield* e2b.teamId;
+        return yield* e2b.authorize(auth.listTeamMetrics({ ...options, teamID }));
+      }),
+      maxMetric: Effect.fn("E2B.ReadTeam.maxMetric")(function* (options) {
+        const teamID = yield* e2b.teamId;
+        return yield* e2b.authorize(auth.getTeamMetricsMax({ ...options, teamID }));
+      }),
+      events: (options) => e2b.authorize(events.listTeamSandboxEvents({ ...options })),
+      sandboxEvents: (sandboxId, options) =>
+        e2b.authorize(events.listSandboxEvents({ ...options, sandboxID: sandboxId })),
+    };
+    return client;
+  }),
+);

package/src/ReadVolume.ts

@@ -0,0 +1,29 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Volume } from "./Volume.ts";
+import type { ReadVolumeClient } from "./VolumeFiles.ts";
+
+/**
+ * Read a {@link Volume}'s files from outside any sandbox: a report a sandbox wrote, a dataset to inspect.
+ *
+ * The client talks to E2B's volume content API with the volume's own token,
+ * looked up once through the host's API key.
+ *
+ * ### Using the client
+ * **Example:** In a Worker
+ * ```typescript
+ * const reports = yield* E2B.ReadVolume(Reports);
+ * // in fetch:
+ * const report = yield* reports.readText("/report.json");
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface ReadVolume extends Binding.Service<
+  ReadVolume,
+  "E2B.ReadVolume",
+  (volume: Volume) => Effect.Effect<ReadVolumeClient>
+> {}
+
+export const ReadVolume = Binding.Service<ReadVolume>("E2B.ReadVolume");

package/src/ReadVolumeHttp.ts

@@ -0,0 +1,32 @@
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { bindE2B } from "./E2BBindings.ts";
+import { makeVolumeFiles } from "./internal/VolumeHttp.ts";
+import { ReadVolume } from "./ReadVolume.ts";
+import type { Volume } from "./Volume.ts";
+
+/**
+ * HTTP implementation of {@link ReadVolume}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const reports = yield* E2B.ReadVolume(Reports);
+ *   // ...
+ * }).pipe(Effect.provide(E2B.ReadVolumeHttp))
+ * ```
+ *
+ * @layer
+ * @product Volume
+ * @provides E2B.ReadVolume
+ */
+export const ReadVolumeHttp = Layer.succeed(
+  ReadVolume,
+  Effect.fn("E2B.ReadVolume")(function* (volume: Volume) {
+    const auth = yield* bindE2B;
+    const volumeId = yield* (volume.volumeId as Output.Output<string, never>).asEffect();
+    return makeVolumeFiles(auth, volumeId);
+  }),
+);

package/src/ReadWebhook.ts

@@ -0,0 +1,41 @@
+import type * as webhooks from "@distilled.cloud/e2b/webhooks";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { E2BError } from "./SandboxClient.ts";
+import type { Webhook } from "./Webhook.ts";
+
+/** A webhook's delivery history and stats. */
+export interface WebhookClient {
+  /** Deliveries grouped by event, newest first, with each attempt's request and response. */
+  deliveries(
+    options?: Omit<webhooks.ListWebhookDeliveriesRequest, "webhookID">,
+  ): Effect.Effect<webhooks.WebhookDeliveriesListPayload, E2BError, RuntimeContext>;
+  /** Delivery counts, failures and latency over time. */
+  stats(
+    options?: Omit<webhooks.GetWebhookStatsRequest, "webhookID">,
+  ): Effect.Effect<webhooks.WebhookDeliveryStats, E2BError, RuntimeContext>;
+}
+
+/**
+ * Read an E2B {@link Webhook}'s delivery history and stats: debug a failing
+ * endpoint, or alert on failed deliveries.
+ *
+ * ### Reading deliveries
+ * **Example:** Failed deliveries in the last hour
+ * ```typescript
+ * const hook = yield* E2B.ReadWebhook(Lifecycle);
+ * // in fetch:
+ * const failed = yield* hook.deliveries({ deliveryStatus: ["failed"] });
+ * ```
+ *
+ * @binding
+ * @product Webhook
+ */
+export interface ReadWebhook extends Binding.Service<
+  ReadWebhook,
+  "E2B.ReadWebhook",
+  (webhook: Webhook) => Effect.Effect<WebhookClient>
+> {}
+
+export const ReadWebhook = Binding.Service<ReadWebhook>("E2B.ReadWebhook");

package/src/ReadWebhookHttp.ts

@@ -0,0 +1,42 @@
+import * as webhooks from "@distilled.cloud/e2b/webhooks";
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { bindE2B } from "./E2BBindings.ts";
+import { ReadWebhook, type WebhookClient } from "./ReadWebhook.ts";
+import type { Webhook } from "./Webhook.ts";
+
+/**
+ * HTTP implementation of {@link ReadWebhook}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const hook = yield* E2B.ReadWebhook(Lifecycle);
+ *   // ...
+ * }).pipe(Effect.provide(E2B.ReadWebhookHttp))
+ * ```
+ *
+ * @layer
+ * @product Webhook
+ * @provides E2B.ReadWebhook
+ */
+export const ReadWebhookHttp = Layer.succeed(
+  ReadWebhook,
+  Effect.fn("E2B.ReadWebhook")(function* (webhook: Webhook) {
+    const auth = yield* bindE2B;
+    const webhookId = yield* (webhook.webhookId as Output.Output<string, never>).asEffect();
+    const client: WebhookClient = {
+      deliveries: (options) =>
+        Effect.flatMap(webhookId, (id) =>
+          auth.authorize(webhooks.listWebhookDeliveries({ ...options, webhookID: id })),
+        ),
+      stats: (options) =>
+        Effect.flatMap(webhookId, (id) =>
+          auth.authorize(webhooks.getWebhookStats({ ...options, webhookID: id })),
+        ),
+    };
+    return client;
+  }),
+);

package/src/ReadWriteVolume.ts

@@ -0,0 +1,30 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Volume } from "./Volume.ts";
+import type { ReadWriteVolumeClient } from "./VolumeFiles.ts";
+
+/**
+ * Read and write a {@link Volume}'s files from outside any sandbox.
+ *
+ * The client talks to E2B's volume content API with the volume's own token,
+ * looked up once through the host's API key.
+ *
+ * ### Using the client
+ * **Example:** In a Worker
+ * ```typescript
+ * const cache = yield* E2B.ReadWriteVolume(Cache);
+ * // in fetch:
+ * yield* cache.write("/notes.md", "hello");
+ * const notes = yield* cache.readText("/notes.md");
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface ReadWriteVolume extends Binding.Service<
+  ReadWriteVolume,
+  "E2B.ReadWriteVolume",
+  (volume: Volume) => Effect.Effect<ReadWriteVolumeClient>
+> {}
+
+export const ReadWriteVolume = Binding.Service<ReadWriteVolume>("E2B.ReadWriteVolume");

package/src/ReadWriteVolumeHttp.ts

@@ -0,0 +1,32 @@
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { bindE2B } from "./E2BBindings.ts";
+import { makeVolumeFiles } from "./internal/VolumeHttp.ts";
+import { ReadWriteVolume } from "./ReadWriteVolume.ts";
+import type { Volume } from "./Volume.ts";
+
+/**
+ * HTTP implementation of {@link ReadWriteVolume}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const cache = yield* E2B.ReadWriteVolume(Cache);
+ *   // ...
+ * }).pipe(Effect.provide(E2B.ReadWriteVolumeHttp))
+ * ```
+ *
+ * @layer
+ * @product Volume
+ * @provides E2B.ReadWriteVolume
+ */
+export const ReadWriteVolumeHttp = Layer.succeed(
+  ReadWriteVolume,
+  Effect.fn("E2B.ReadWriteVolume")(function* (volume: Volume) {
+    const auth = yield* bindE2B;
+    const volumeId = yield* (volume.volumeId as Output.Output<string, never>).asEffect();
+    return makeVolumeFiles(auth, volumeId);
+  }),
+);