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

package/src/internal/Declared.ts

@@ -0,0 +1,80 @@
+import type { PropsInput } from "alchemy/Input";
+import * as Output from "alchemy/Output";
+import { isResource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { Providers } from "../Providers.ts";
+
+type Leaf =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | null
+  | undefined
+  | Redacted.Redacted<any>
+  | Uint8Array
+  | Date
+  | ((...args: any[]) => any);
+
+/**
+ * A prop value, or the declaration of a resource that has it: `template: Node`
+ * instead of `template: yield* Node`, at any depth.
+ */
+export type Declared<T> = T extends Leaf
+  ? T
+  : T extends Output.Output<any>
+    ? T
+    : T extends ReadonlyArray<infer U>
+      ? Declared<U>[] | Effect.Effect<T, never, Providers>
+      : { [K in keyof T]: Declared<T[K]> } | Effect.Effect<T, never, Providers>;
+
+/** Props where any value may be a resource declaration. */
+export type DeclaredProps<P> = { [K in keyof PropsInput<P>]: Declared<PropsInput<P>[K]> };
+
+const isPlain = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+/** A declaration still to be yielded: an Effect that isn't an Output or a resource. */
+const isDeclaration = (value: unknown): value is Effect.Effect<unknown, never, Providers> =>
+  Effect.isEffect(value) && !Output.isOutput(value) && !isResource(value);
+
+const hasDeclarations = (value: unknown): boolean =>
+  isDeclaration(value) ||
+  (Array.isArray(value) && value.some(hasDeclarations)) ||
+  (isPlain(value) && !isResource(value) && Object.values(value).some(hasDeclarations));
+
+/** Yield every declaration in `value`, at any depth. */
+export const resolveDeclarations = (value: unknown): Effect.Effect<unknown, never, Providers> =>
+  isDeclaration(value)
+    ? value
+    : Array.isArray(value)
+      ? Effect.forEach(value, resolveDeclarations)
+      : isPlain(value) && !isResource(value) && hasDeclarations(value)
+        ? Effect.map(
+            Effect.forEach(Object.entries(value), ([key, entry]) =>
+              Effect.map(resolveDeclarations(entry), (resolved) => [key, resolved] as const),
+            ),
+            Object.fromEntries,
+          )
+        : Effect.succeed(value);
+
+/**
+ * Let a resource's props hold declarations of other resources, which are
+ * yielded when the resource is: `E2B.Sandbox("DevBox", { template: Node })`.
+ * Props without declarations are passed through unchanged.
+ */
+export const declarable =
+  <R extends { readonly Props: any }>() =>
+  <C extends object>(
+    resource: C,
+  ): C & ((id: string, props: DeclaredProps<R["Props"]>) => Effect.Effect<R, never, Providers>) =>
+    new Proxy(resource as C & ((...args: unknown[]) => unknown), {
+      apply: (target, self, args: unknown[]) =>
+        typeof args[0] === "string" && hasDeclarations(args[1])
+          ? Reflect.apply(target, self, [args[0], resolveDeclarations(args[1])])
+          : Reflect.apply(target, self, args),
+    }) as never;

package/src/internal/Login.ts

@@ -0,0 +1,210 @@
+/**
+ * E2B's browser login, as the E2B CLI runs it (`e2b auth login`).
+ *
+ * E2B's console signs the user in and redirects to a loopback URL with the
+ * OAuth grant in the query string: a short-lived JWT access token, a refresh
+ * token, and the token and revoke endpoints with the public client id they
+ * were issued to. Refresh and revoke are standard OAuth 2 requests against
+ * those endpoints.
+ */
+import * as http from "node:http";
+import type { AddressInfo } from "node:net";
+import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+
+export class E2BLoginError extends Data.TaggedError("E2BLoginError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/** The grant E2B's console hands the loopback listener. */
+export interface E2BGrant {
+  readonly email: string;
+  readonly access: Redacted.Redacted<string>;
+  readonly refresh: Redacted.Redacted<string>;
+  readonly tokenEndpoint: string;
+  readonly revokeEndpoint: string;
+  readonly clientId: string;
+  /** Epoch millis the access token expires at. */
+  readonly expires: number;
+}
+
+/**
+ * The E2B CLI release whose login flow this mirrors. E2B's console reads
+ * `cliVersion` and refuses ("CLI update required") a login without a current
+ * one. Bump it with the E2B CLI if the console starts refusing it.
+ */
+export const E2B_CLI_COMPAT_VERSION = "2.23.0";
+
+/** Where the console's CLI login starts, and where it shows the outcome. */
+const loginBase = (domain: string) =>
+  `https://${domain === "e2b.app" ? "e2b.dev" : domain}/docs/api/cli`;
+
+/** A JWT's `exp`, in epoch millis; 0 when it has none, so it refreshes at once. */
+export const jwtExpiry = (token: string): number => {
+  const payload = token.split(".")[1];
+  if (payload === undefined) return 0;
+  try {
+    const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as {
+      exp?: number;
+    };
+    return typeof decoded.exp === "number" ? decoded.exp * 1000 : 0;
+  } catch {
+    return 0;
+  }
+};
+
+const isLoginError = (value: E2BGrant | E2BLoginError): value is E2BLoginError => "_tag" in value;
+
+const grantOf = (params: URLSearchParams): E2BGrant | E2BLoginError => {
+  const error = params.get("error");
+  if (error) return new E2BLoginError({ message: `E2B login failed: ${error}` });
+  const field = (name: string) => params.get(name) ?? "";
+  const grant = {
+    email: field("email"),
+    accessToken: field("accessToken"),
+    refreshToken: field("refreshToken"),
+    tokenEndpoint: field("tokenEndpoint"),
+    revokeEndpoint: field("revokeEndpoint"),
+    clientId: field("clientId"),
+  };
+  const missing = Object.entries(grant)
+    .filter(([, value]) => value === "")
+    .map(([key]) => key);
+  if (missing.length > 0) {
+    return new E2BLoginError({
+      message: `E2B login returned an incomplete grant (missing ${missing.join(", ")})`,
+    });
+  }
+  return {
+    email: grant.email,
+    access: Redacted.make(grant.accessToken),
+    refresh: Redacted.make(grant.refreshToken),
+    tokenEndpoint: grant.tokenEndpoint,
+    revokeEndpoint: grant.revokeEndpoint,
+    clientId: grant.clientId,
+    expires: jwtExpiry(grant.accessToken),
+  };
+};
+
+/** Parses a pasted loopback URL (the manual fallback when the listener can't be reached). */
+export const grantFromUrl = (input: string): Effect.Effect<E2BGrant, E2BLoginError> =>
+  Effect.gen(function* () {
+    const url = yield* Effect.try({
+      try: () => new URL(input.trim()),
+      catch: () => new E2BLoginError({ message: "Paste the full URL the browser was sent to" }),
+    });
+    const grant = grantOf(url.searchParams);
+    return isLoginError(grant) ? yield* grant : grant;
+  });
+
+/**
+ * Starts the loopback listener on a free port and returns the console URL
+ * to open, plus the grant it receives. The listener closes with the scope.
+ */
+export const startLogin = Effect.fn(function* (domain: string) {
+  const base = loginBase(domain);
+  const received = yield* Deferred.make<E2BGrant, E2BLoginError>();
+  const server = yield* Effect.acquireRelease(
+    Effect.callback<http.Server, E2BLoginError>((resume) => {
+      const server = http.createServer((req, res) => {
+        const params = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const grant = grantOf(params);
+        const outcome = new URL(base);
+        if (isLoginError(grant)) {
+          outcome.searchParams.set("state", "error");
+          outcome.searchParams.set("error", grant.message);
+        } else {
+          outcome.searchParams.set("state", "success");
+          outcome.searchParams.set("email", grant.email);
+        }
+        res.writeHead(302, { Location: outcome.href, Connection: "close" });
+        res.end();
+        Deferred.doneUnsafe(
+          received,
+          isLoginError(grant) ? Effect.fail(grant) : Effect.succeed(grant),
+        );
+      });
+      server.once("error", (cause) =>
+        resume(
+          Effect.fail(new E2BLoginError({ message: "Could not start the login listener", cause })),
+        ),
+      );
+      server.listen(0, "127.0.0.1", () => resume(Effect.succeed(server)));
+    }),
+    (server) =>
+      Effect.sync(() => {
+        server.close();
+        server.closeAllConnections();
+      }),
+  );
+  const { port } = server.address() as AddressInfo;
+  const url = new URL(base);
+  url.searchParams.set("next", `http://localhost:${port}`);
+  url.searchParams.set("cliVersion", E2B_CLI_COMPAT_VERSION);
+  return { url: url.href, grant: Deferred.await(received) };
+});
+
+const TokenResponse = Schema.Struct({
+  access_token: Schema.String,
+  refresh_token: Schema.optional(Schema.String),
+});
+
+/** Exchanges the refresh token for a fresh access token (refresh tokens may rotate). */
+export const refreshGrant = (grant: E2BGrant): Effect.Effect<E2BGrant, E2BLoginError> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    // Raw HTTP: the token endpoint the console's login redirect handed back.
+    const response = yield* client.execute(
+      HttpClientRequest.post(grant.tokenEndpoint).pipe(
+        HttpClientRequest.setHeader("Accept", "application/json"),
+        HttpClientRequest.bodyUrlParams({
+          grant_type: "refresh_token",
+          refresh_token: Redacted.value(grant.refresh),
+          client_id: grant.clientId,
+        }),
+      ),
+    );
+    if (response.status >= 400) {
+      const body = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+      return yield* new E2BLoginError({
+        message: `E2B token refresh failed (${response.status}): ${body.slice(0, 200)}`,
+      });
+    }
+    const tokens = yield* Schema.decodeUnknownEffect(TokenResponse)(yield* response.json);
+    return {
+      ...grant,
+      access: Redacted.make(tokens.access_token),
+      refresh:
+        tokens.refresh_token === undefined ? grant.refresh : Redacted.make(tokens.refresh_token),
+      expires: jwtExpiry(tokens.access_token),
+    };
+  }).pipe(
+    Effect.catchIf(
+      (e): e is Exclude<typeof e, E2BLoginError> => e._tag !== "E2BLoginError",
+      (cause) => Effect.fail(new E2BLoginError({ message: "E2B token refresh failed", cause })),
+    ),
+    Effect.provide(FetchHttpClient.layer),
+  );
+
+/** Revokes the refresh token; best effort, like `e2b auth logout`. */
+export const revokeGrant = (grant: Pick<E2BGrant, "refresh" | "revokeEndpoint" | "clientId">) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    yield* client.execute(
+      // Raw HTTP: the revoke endpoint the console's login redirect handed back.
+      HttpClientRequest.post(grant.revokeEndpoint).pipe(
+        HttpClientRequest.bodyUrlParams({
+          token: Redacted.value(grant.refresh),
+          token_type_hint: "refresh_token",
+          client_id: grant.clientId,
+        }),
+      ),
+    );
+  }).pipe(Effect.ignore, Effect.provide(FetchHttpClient.layer));

package/src/internal/Ownership.ts

@@ -0,0 +1,67 @@
+import { createPhysicalName } from "alchemy/PhysicalName";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+/**
+ * Naming and ownership helpers shared by every E2B resource and binding.
+ *
+ * E2B has metadata only on secrets and sandboxes. Templates, snapshots,
+ * volumes, webhooks and API keys carry nothing but a name, so a resource
+ * whose name the engine generated (stack, stage, logical id, instance
+ * suffix) is recognised as ours by that name; an explicit, user-chosen name
+ * found without prior state is reported `Unowned`.
+ */
+import { createInternalTags } from "alchemy/Tags";
+import * as Effect from "effect/Effect";
+
+/** E2B names: letters, digits, `-` and `_`. Lowercased (secrets and templates are lowercased by E2B). */
+export const e2bName = (id: string, name: string | undefined, maxLength = 64) =>
+  name !== undefined
+    ? Effect.succeed(name)
+    : createPhysicalName({ id, lowercase: true, maxLength, delimiter: "-" });
+
+/**
+ * Whether a name looks generated by `createPhysicalName` (lowercase, ending
+ * in a base32 instance suffix). Used by `list` to report only resources
+ * Alchemy created, for nuke.
+ */
+export const isGeneratedName = (name: string | undefined): boolean =>
+  name !== undefined && /^[a-z0-9][a-z0-9_-]*-[a-z2-7]{8,16}$/.test(name);
+
+/** The `alchemy::stack` / `alchemy::stage` / `alchemy::id` stamp for metadata maps. */
+export const ownershipMetadata = (id: string) => createInternalTags(id);
+
+/**
+ * The stamp runtime-created objects carry: the stack and stage that created
+ * them and the binding's logical id. Destroy sweeps by it.
+ */
+export const runtimeMetadata = Effect.fn(function* (bindingId: string) {
+  const stack = yield* Stack;
+  const stage = yield* Stage;
+  return {
+    "alchemy::stack": stack.name,
+    "alchemy::stage": stage,
+    "alchemy::binding": bindingId,
+  } as Record<string, string>;
+});
+
+/** Whether a metadata map carries this resource's ownership stamp. */
+export const hasOwnershipMetadata = Effect.fn(function* (
+  id: string,
+  metadata: Readonly<Record<string, string>> | null | undefined,
+) {
+  const expected = yield* createInternalTags(id);
+  return Object.entries(expected).every(([key, value]) => metadata?.[key] === value);
+});
+
+/** Whether a metadata map was stamped by any Alchemy stack (for nuke). */
+export const hasAnyAlchemyMetadata = (
+  metadata: Readonly<Record<string, string>> | null | undefined,
+): boolean => metadata !== undefined && metadata !== null && "alchemy::stack" in metadata;
+
+/** User metadata with the internal `alchemy::*` keys removed. */
+export const userMetadata = (
+  metadata: Readonly<Record<string, string>> | null | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(metadata ?? {}).filter(([key]) => !key.startsWith("alchemy::")),
+  );

package/src/internal/Program.ts

@@ -0,0 +1,75 @@
+/**
+ * How a template runs its `main` program.
+ *
+ * `@alchemy.run/docker/BuildPlan` bundles `main` and adds the layer that
+ * runs it with Bun from `/app`; E2B starts that command when it builds the
+ * template and captures it running in the template's snapshot, so every
+ * sandbox boots with it already serving on `PORT`. An Effect program (the
+ * class form) is wrapped in the generated bootstrap entry; an async program
+ * (`main` with no Effect impl) is bundled and run as-is.
+ */
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+
+/** The port a template's program serves on unless `port` says otherwise. */
+export const DEFAULT_PORT = 3000;
+
+/**
+ * The generated entry: raises the runtime flag BEFORE the user's module is
+ * evaluated (hence the dynamic import), then boots the program. It imports
+ * only `@alchemy.run/e2b/Bootstrap` and `main` — see `alchemy/Runtime/Bootstrap`.
+ */
+export const makeBootstrap =
+  (handler: string) =>
+  (importPath: string): string =>
+    `
+import { bootstrap } from "@alchemy.run/e2b/Bootstrap";
+
+globalThis.__ALCHEMY_RUNTIME__ = true;
+const { ${handler}: entrypoint } = await import(${JSON.stringify(importPath)});
+
+await bootstrap(entrypoint);
+`;
+
+/**
+ * A value as the env var the program reads, verbatim. Bound values arrive
+ * already packed by the host (`packEnvValue`, so a `Redacted` keeps its
+ * marker); packing again would double-encode them, and a user's `env` is read
+ * raw (`Config`, `process.env`).
+ */
+const envValue = (value: unknown): string | undefined =>
+  value === undefined || value === null
+    ? undefined
+    : Redacted.isRedacted(value)
+      ? String(Redacted.value(value))
+      : typeof value === "string"
+        ? value
+        : JSON.stringify(value);
+
+/** The program's environment: Alchemy's runtime vars, bound env, then the user's `env`. */
+export const programEnv = Effect.fn(function* (
+  port: number,
+  bound: Readonly<Record<string, unknown>>,
+  env: Readonly<Record<string, unknown>> | undefined,
+) {
+  const stack = yield* Stack;
+  const values = Object.fromEntries(
+    Object.entries({ ...bound, ...env }).flatMap(([key, value]) => {
+      const text = envValue(value);
+      return text === undefined ? [] : [[key, text]];
+    }),
+  ) as Record<string, string>;
+  return {
+    ALCHEMY_STACK_NAME: stack.name,
+    ALCHEMY_STAGE: stack.stage,
+    ALCHEMY_PHASE: "runtime",
+    HOST: "0.0.0.0",
+    PORT: String(port),
+    ...values,
+  };
+});
+
+/** The template's snapshot is taken once the program answers HTTP. */
+export const programReadyCmd = (port: number) =>
+  `bun -e "fetch('http://127.0.0.1:${port}/').then(()=>process.exit(0),()=>process.exit(1))"`;