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

package/src/CreateQueue.ts

@@ -0,0 +1,95 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { QueuesOps } from "./CreateQueueHttp.ts";
+import type { Environment } from "./Environment.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+import type { ensureQueue, lookupQueue } from "./Queue.ts";
+import type { QueueAttributes } from "./Queue.ts";
+import type { ReadWriteQueueClient } from "./QueueClient.ts";
+
+/** A queue created or found at runtime: its attributes plus a read-write client. */
+export interface QueueHandle extends ReadWriteQueueClient {
+  readonly queueId: Effect.Effect<string>;
+  readonly name: string;
+  /** The attributes, to pass where a `Modal.Queue` is accepted (e.g. sandbox mounts). */
+  readonly attributes: QueueAttributes;
+}
+
+/** Get, create, list and delete queues by name in one environment. */
+export interface QueuesClientOf<R> {
+  /** The queue named `name`, created when missing (Modal's own get-or-create). */
+  getOrCreate(name: string): Effect.Effect<QueueHandle, ErrorOf<typeof ensureQueue>, R>;
+  /** The queue named `name`, or `undefined`. */
+  get(name: string): Effect.Effect<QueueHandle | undefined, ErrorOf<typeof lookupQueue>, R>;
+  /** Delete the queue named `name` (no-op when missing). */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    | ErrorOf<typeof lookupQueue>
+    | Exclude<OpError<QueuesOps, "delete">, { readonly _tag: "QueueNotFound" }>,
+    R
+  >;
+  /** Names of every queue in the environment. */
+  list(): Effect.Effect<ReadonlyArray<string>, OpError<QueuesOps, "list">, R>;
+}
+
+/** A QueuesClient whose calls run inside a deployed runtime. */
+export type QueuesClient = QueuesClientOf<RuntimeContext>;
+
+/**
+ * Create queues by name at runtime: one per user, session or task.
+ * Modal's native shape is get-or-create by name, so `getOrCreate` is
+ * idempotent and safe to call on every request.
+ *
+ * Bind it to a `Modal.Environment` to keep these runtime objects in their
+ * own namespace (or to nothing, for the workspace's default environment).
+ * They aren't in Alchemy state: deleting the environment removes them.
+ *
+ * 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. A Modal queue has only a name, so the tags become
+ * its name prefix, `Modal.runtimePrefix({ stack, stage, id })`: list them
+ * with `modal queue list` and delete the ones whose name starts with it.
+ *
+ * ### One queue per user
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ * import { HttpServerRequest } from "effect/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Agents, Coder } from "./Coder.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const queues = yield* Modal.CreateQueue(Agents);
+ *     const sandboxes = yield* Modal.CreateSandbox(Coder);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const user = request.headers["x-user"] ?? "anonymous";
+ *         const inbox = yield* queues.getOrCreate(`inbox-${user}`);
+ *         yield* inbox.put({ task: "review" });
+ *         return HttpServerResponse.text("ok");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Modal.CreateQueueHttp, Modal.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Queue
+ */
+export interface CreateQueue extends Binding.Service<
+  CreateQueue,
+  "Modal.CreateQueue",
+  (environment?: Environment) => Effect.Effect<QueuesClient>
+> {}
+
+export const CreateQueue = Binding.Service<CreateQueue>("Modal.CreateQueue");

package/src/CreateQueueHttp.ts

@@ -0,0 +1,91 @@
+import * as queue from "@distilled.cloud/modal/queue";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeOpenModalBinding } from "./BindingHttp.ts";
+import { CreateQueue, type QueueHandle, type QueuesClientOf } from "./CreateQueue.ts";
+import type { Environment } from "./Environment.ts";
+import { environmentOf, listAll, operations } from "./internal.ts";
+import { ensureQueue, lookupQueue, type QueueAttributes } from "./Queue.ts";
+import { QueueOps, makeReadWriteQueueClient } from "./QueueClient.ts";
+import { ownedName, type RuntimeOwner, RuntimeOwnerOf, unownedName } from "./RuntimeOwner.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+export const QueuesOps = operations({
+  getOrCreate: queue.queueGetOrCreate,
+  delete: queue.deleteQueue,
+  list: queue.listQueue,
+  client: QueueOps,
+});
+
+export type QueuesOps = Effect.Success<typeof QueuesOps>;
+
+const handleOf = (attributes: QueueAttributes, ops: QueuesOps, name: string): QueueHandle => ({
+  ...makeReadWriteQueueClient(Effect.succeed(attributes.queueId), ops.client),
+  queueId: Effect.succeed(attributes.queueId),
+  name,
+  attributes,
+});
+
+/** A queues client over an environment name resolved per call. */
+export const makeQueuesClient = (
+  environment: Effect.Effect<string | undefined>,
+  ops: QueuesOps,
+  owner: Effect.Effect<RuntimeOwner | undefined> = Effect.undefined,
+): QueuesClientOf<never> => ({
+  getOrCreate: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      ensureQueue(ops.getOrCreate, ownedName(stamp, name), env),
+    ).pipe(Effect.map((attributes) => handleOf(attributes, ops, name))),
+  get: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      lookupQueue(ops.getOrCreate, ownedName(stamp, name), env),
+    ).pipe(Effect.map((attributes) => (attributes ? handleOf(attributes, ops, name) : undefined))),
+  delete: (name) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const found = yield* lookupQueue(ops.getOrCreate, ownedName(yield* owner, name), env);
+      if (!found) return;
+      yield* ops
+        .delete({ queueId: found.queueId })
+        .pipe(Effect.catchTag("QueueNotFound", () => Effect.void));
+    }),
+  list: () =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const stamp = yield* owner;
+      const items = yield* listAll(
+        (pagination) =>
+          ops
+            .list({ environmentName: environmentOf(env), pagination })
+            .pipe(Effect.map((response) => response.queues ?? [])),
+        (item) => item.createdAt,
+      );
+      return items.flatMap((item) => {
+        const own = item.name ? unownedName(stamp, item.name) : undefined;
+        return own ? [own] : [];
+      });
+    }),
+});
+
+/**
+ * {@link CreateQueue} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the environment.
+ *
+ * @layer
+ * @product Queue
+ * @provides Modal.CreateQueue
+ */
+export const CreateQueueHttp = Layer.effect(
+  CreateQueue,
+  makeOpenModalBinding({
+    tag: "Modal.CreateQueue",
+    operations: QueuesOps,
+    role: "contributor",
+    environmentOf: (environment?: Environment) => environment?.name,
+    make: Effect.fn(function* (ops, environment?: Environment) {
+      const name = environment ? yield* environment.name : Effect.undefined;
+      const owner = yield* RuntimeOwnerOf();
+      return makeQueuesClient(name, ops, owner);
+    }),
+  }),
+);

package/src/CreateSandbox.ts

@@ -0,0 +1,228 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { App } from "./App.ts";
+import type { Image } from "./Image.ts";
+import type { ErrorOf } from "./internal.ts";
+import type { Sandbox } from "./Sandbox.ts";
+import type {
+  createPersistentSandbox,
+  createSandbox,
+  listSandboxes,
+  PersistentSandboxCreateOptions,
+  PersistentSandboxHandle,
+  restoreSandbox,
+  SandboxCreateOptions,
+  SandboxHandle,
+  sandboxFromName,
+  SandboxOpError,
+} from "./SandboxClient.ts";
+
+export type {
+  ExecOptions,
+  PersistentSandboxCreateOptions,
+  PersistentSandboxHandle,
+  ExecResult,
+  HeaderReplacement,
+  SandboxCreateOptions,
+  SandboxFileEntry,
+  SandboxHandle,
+  SandboxTunnel,
+} from "./SandboxClient.ts";
+
+/** A sandbox as `list` reports it. */
+export interface SandboxSummary {
+  readonly sandboxId: string;
+  readonly name: string | undefined;
+  readonly createdAt: number | undefined;
+  readonly tags: Record<string, string>;
+}
+
+/** Sandbox cost for one combination of tag values. */
+export interface SandboxUsageGroup {
+  /** The grouped tags' values. */
+  readonly tags: Record<string, string>;
+  /** Total cost in USD. */
+  readonly cost: number;
+  /** Cost by resource (`cpu`, `memory`, `gpu`, ...). */
+  readonly costByResource: Record<string, number>;
+}
+
+/** Create and find sandboxes in one App. Every handle method calls Modal. */
+export interface SandboxesClient {
+  /** The App sandboxes are created in. */
+  readonly appId: Effect.Effect<string>;
+  /** Create a sandbox. Modal's own sandbox parameters; the bound image is the default `image`. */
+  create(
+    options?: SandboxCreateOptions,
+  ): Effect.Effect<SandboxHandle, ErrorOf<typeof createSandbox>, RuntimeContext>;
+  /** A running sandbox by name, or `undefined`. */
+  fromName(
+    name: string,
+  ): Effect.Effect<SandboxHandle | undefined, ErrorOf<typeof sandboxFromName>, RuntimeContext>;
+  /** A sandbox by id. */
+  fromId(sandboxId: string): Effect.Effect<SandboxHandle>;
+  /** Running sandboxes of the App, optionally filtered by tags. */
+  list(options?: {
+    readonly tags?: Record<string, string>;
+    readonly includeFinished?: boolean;
+  }): Effect.Effect<ReadonlyArray<SandboxSummary>, ErrorOf<typeof listSandboxes>, RuntimeContext>;
+  /**
+   * Create a persistent sandbox: one box whose filesystem outlives its
+   * sessions. Each session runs up to an hour and pauses after five idle
+   * minutes; `session()` resumes it from where it stopped.
+   */
+  createPersistent(
+    options?: PersistentSandboxCreateOptions,
+  ): Effect.Effect<
+    PersistentSandboxHandle,
+    ErrorOf<typeof createPersistentSandbox>,
+    RuntimeContext
+  >;
+  /** A persistent sandbox by id (a `Modal.PersistentSandbox`, or one `createPersistent` made). */
+  persistent(
+    box: string | { readonly persistentSandboxId: string },
+  ): Effect.Effect<PersistentSandboxHandle>;
+  /**
+   * What the App's sandboxes cost over a time range, grouped by tag values
+   * (`groupByTags: ["user"]` gives one group per user). Modal reports
+   * whole hours: `since` rounds down and `until` (default now) up to the
+   * hour.
+   */
+  usage(query: {
+    readonly since: Date | string | number;
+    readonly until?: Date | string | number;
+    readonly groupByTags?: ReadonlyArray<string>;
+    readonly tags?: Record<string, string>;
+  }): Effect.Effect<ReadonlyArray<SandboxUsageGroup>, SandboxOpError<"usage">, RuntimeContext>;
+  /** Start a new sandbox from a memory snapshot (`handle.snapshotMemory()`). */
+  restore(
+    snapshot: { readonly snapshotId: string },
+    options?: { readonly name?: string },
+  ): Effect.Effect<
+    SandboxHandle,
+    ErrorOf<typeof restoreSandbox> | SandboxOpError<"setTags">,
+    RuntimeContext
+  >;
+}
+
+/**
+ * Create and drive Modal Sandboxes from any runtime: a Worker, a Lambda, a
+ * Durable Object, or a script.
+ *
+ * Bind it to an App (sandboxes boot from the image you pass to `create`) or
+ * to an Image (it is the default image, and sandboxes go in the image's
+ * App). A sandbox lives at most 24 hours; to keep work across sandboxes, use
+ * a Volume, or snapshot it (`snapshotFilesystem`, `snapshotMemory`) and
+ * start the next one from the snapshot.
+ *
+ * Sandboxes are runtime objects: they aren't in Alchemy state. Stopping the
+ * App (destroying the `Modal.App` resource) terminates every sandbox in it.
+ *
+ * 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:
+ * `sandboxes.list({ tags: { "alchemy::stack": "my-app" } })`, or Modal's
+ * `SandboxList` with `tags`. Your own `tags` merge under the three. A
+ * persistent sandbox takes neither tags nor a name, so it carries no owner;
+ * it lives in the App.
+ *
+ * ### Create a sandbox per request
+ * **Example:** Run a command and terminate
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Warm } from "./Coder.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const sandboxes = yield* Modal.CreateSandbox(Warm);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const sandbox = yield* Effect.acquireRelease(
+ *           sandboxes.create({ timeout: "10 minutes" }),
+ *           (sandbox) => Effect.ignore(sandbox.terminate()),
+ *         );
+ *         const test = yield* sandbox.exec(["pnpm", "test"], { cwd: "/work" });
+ *         return yield* HttpServerResponse.json(test);
+ *       }).pipe(Effect.scoped, Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.CreateSandboxHttp)),
+ * ) {}
+ * ```
+ *
+ * ### One sandbox per session
+ * **Example:** Find it by name, else create it
+ * ```typescript
+ * const sandbox =
+ *   (yield* sandboxes.fromName(`session-${user}`)) ??
+ *   (yield* sandboxes.create({ name: `session-${user}`, idleTimeout: "10 minutes" }));
+ * ```
+ *
+ * ### Secrets the sandbox never sees
+ * **Example:** Inject an API key into outbound requests
+ * ```typescript
+ * // construction phase: read the Secret's id
+ * const openaiId = yield* (yield* OpenAI).secretId;
+ * // in a handler
+ * const openai = { secretId: yield* openaiId };
+ * const sandbox = yield* sandboxes.create({
+ *   outboundPolicy: {
+ *     routes: [
+ *       {
+ *         https: {
+ *           domains: ["api.openai.com"],
+ *           headerReplacements: [{ secret: openai, headers: { Authorization: "Bearer $OPENAI_API_KEY" } }],
+ *         },
+ *       },
+ *       { any: { redirect: "block" } },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * ### A cloud identity, not a key
+ * **Example:** Assume an AWS role with the token Modal signs
+ * ```typescript
+ * const sandbox = yield* sandboxes.create({
+ *   image: "amazon/aws-cli",
+ *   includeOidcIdentityToken: true,
+ * });
+ * // MODAL_IDENTITY_TOKEN is an OIDC token from https://oidc.modal.com
+ * const role = yield* sandbox.exec(
+ *   `aws sts assume-role-with-web-identity --role-arn ${roleArn} --role-session-name sandbox --web-identity-token "$MODAL_IDENTITY_TOKEN"`,
+ * );
+ * ```
+ *
+ * ### Persistent sandboxes
+ * **Example:** A box per user that keeps its files between sessions
+ * ```typescript
+ * const box = yield* sandboxes.createPersistent({ image: "node:22-bookworm" });
+ * const session = yield* box.session();
+ * yield* session.exec("echo hi >> /root/notes.txt");
+ * // later, from any request: resumes the box if it paused
+ * const again = yield* (yield* sandboxes.persistent(box.persistentSandboxId)).session();
+ * ```
+ *
+ * ### Snapshots
+ * **Example:** Save a warmed sandbox and boot the next one from it
+ * ```typescript
+ * yield* sandbox.exec(["pnpm", "install"], { cwd: "/work" });
+ * const image = yield* sandbox.snapshotFilesystem();
+ * const next = yield* sandboxes.create({ image });
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface CreateSandbox extends Binding.Service<
+  CreateSandbox,
+  "Modal.CreateSandbox",
+  (target: App | Image | Sandbox) => Effect.Effect<SandboxesClient>
+> {}
+
+export const CreateSandbox = Binding.Service<CreateSandbox>("Modal.CreateSandbox");

package/src/CreateSandboxHttp.ts

@@ -0,0 +1,160 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { App } from "./App.ts";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { CreateSandbox, type SandboxesClient, type SandboxUsageGroup } from "./CreateSandbox.ts";
+import type { Image } from "./Image.ts";
+import { timestampOf } from "./internal.ts";
+import { type RuntimeOwner, RuntimeOwnerOf, runtimeTags } from "./RuntimeOwner.ts";
+import type { Sandbox } from "./Sandbox.ts";
+import {
+  createPersistentSandbox,
+  createSandbox,
+  listSandboxes,
+  persistentSandboxHandle,
+  restoreSandbox,
+  SandboxOps,
+  sandboxFromName,
+  sandboxHandle,
+  type SandboxTarget,
+} from "./SandboxClient.ts";
+
+const HOUR_MS = 3_600_000;
+
+/** A time rounded to an hour boundary, as Modal's usage query wants it. */
+const hourOf = (value: Date | string | number, round: (n: number) => number): string =>
+  timestampOf(round(new Date(value).getTime() / HOUR_MS) * HOUR_MS);
+
+/** A sandboxes client over a target resolved per call. */
+export const makeSandboxesClient = (
+  target: Effect.Effect<SandboxTarget>,
+  ops: SandboxOps,
+  owner: Effect.Effect<RuntimeOwner | undefined> = Effect.undefined,
+): SandboxesClient => ({
+  appId: Effect.map(target, (t) => t.appId),
+  create: (options) =>
+    Effect.flatMap(Effect.all([target, owner]), ([t, o]) =>
+      createSandbox(ops, t, {
+        ...options,
+        // The owner's tags win over a user tag of the same key.
+        tags: o === undefined ? options?.tags : { ...options?.tags, ...runtimeTags(o) },
+      }),
+    ),
+  fromName: (name) => Effect.flatMap(target, (t) => sandboxFromName(ops, t, name)),
+  fromId: (sandboxId) => Effect.map(target, (t) => sandboxHandle(ops, sandboxId, t)),
+  list: (options) => Effect.flatMap(target, (t) => listSandboxes(ops, t, options)),
+  usage: (query) =>
+    Effect.gen(function* () {
+      const t = yield* target;
+      const groups: Array<SandboxUsageGroup> = [];
+      let pageToken: string | undefined;
+      for (let page = 0; page < 100; page++) {
+        const response = yield* ops.usage({
+          appId: t.appId,
+          // Modal reports usage by whole hours.
+          since: hourOf(query.since, Math.floor),
+          until: query.until === undefined ? undefined : hourOf(query.until, Math.ceil),
+          groupByTags: query.groupByTags ? [...query.groupByTags] : undefined,
+          tags: query.tags,
+          pageToken,
+        });
+        for (const group of response.groups ?? []) {
+          groups.push({
+            tags: Object.fromEntries(
+              Object.entries(group.tags ?? {}).map(([key, value]) => [key, value?.value ?? ""]),
+            ),
+            cost: group.cost ?? 0,
+            costByResource: Object.fromEntries(
+              Object.entries(group.costByResource ?? {}).map(([key, value]) => [key, value ?? 0]),
+            ),
+          });
+        }
+        pageToken = response.nextPageToken || undefined;
+        if (pageToken === undefined) break;
+      }
+      return groups;
+    }),
+  createPersistent: (options) =>
+    Effect.flatMap(target, (t) => createPersistentSandbox(ops, t, options)),
+  persistent: (box) =>
+    Effect.map(target, (t) =>
+      persistentSandboxHandle(ops, typeof box === "string" ? box : box.persistentSandboxId, t),
+    ),
+  restore: (snapshot, options) =>
+    Effect.gen(function* () {
+      const restored = yield* restoreSandbox(ops, yield* target, snapshot, options);
+      const o = yield* owner;
+      if (o !== undefined) yield* restored.setTags(runtimeTags(o));
+      return restored;
+    }),
+});
+
+const isImage = (target: App | Image | Sandbox): target is Image => target.Type === "Modal.Image";
+const isProgram = (target: App | Image | Sandbox): target is Sandbox =>
+  target.Type === "Modal.Sandbox";
+
+/**
+ * {@link CreateSandbox} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the App's environment.
+ *
+ * @layer
+ * @product Sandbox
+ * @provides Modal.CreateSandbox
+ */
+export const CreateSandboxHttp = Layer.effect(
+  CreateSandbox,
+  makeModalBinding({
+    tag: "Modal.CreateSandbox",
+    operations: SandboxOps,
+    role: "contributor",
+    make: Effect.fn(function* (resource: App | Image | Sandbox, ops) {
+      const owner = yield* RuntimeOwnerOf();
+      if (isProgram(resource)) {
+        const imageId = yield* resource.imageId;
+        const appId = yield* resource.appId;
+        const appName = yield* resource.appName;
+        const environment = yield* resource.environment;
+        const secretId = yield* resource.secretId;
+        const command = yield* resource.command;
+        const port = yield* resource.port;
+        const mounts = yield* resource.mounts;
+        const target = Effect.all({
+          imageId,
+          appId,
+          appName,
+          environment,
+          secretId,
+          command,
+          port,
+          mounts,
+        }).pipe(
+          Effect.map((t): SandboxTarget => ({
+            imageId: t.imageId,
+            appId: t.appId,
+            appName: t.appName,
+            environment: t.environment,
+            program: { secretId: t.secretId, command: t.command, port: t.port, mounts: t.mounts },
+          })),
+        );
+        return makeSandboxesClient(target, ops, owner);
+      }
+      if (isImage(resource)) {
+        const imageId = yield* resource.imageId;
+        const appId = yield* resource.appId;
+        const appName = yield* resource.appName;
+        const environment = yield* resource.environment;
+        const target = Effect.all({ imageId, appId, appName, environment }).pipe(
+          Effect.map((t): SandboxTarget => t),
+        );
+        return makeSandboxesClient(target, ops, owner);
+      }
+      const appId = yield* resource.appId;
+      const appName = yield* resource.name;
+      const environment = yield* resource.environment;
+      const target = Effect.all({ appId, appName, environment }).pipe(
+        Effect.map((t): SandboxTarget => t),
+      );
+      return makeSandboxesClient(target, ops, owner);
+    }),
+  }),
+);

package/src/CreateSecret.ts

@@ -0,0 +1,109 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { SecretsOps } from "./CreateSecretHttp.ts";
+import type { Environment } from "./Environment.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+import type { lookupSecret, putSecret } from "./Secret.ts";
+import type { SecretAttributes } from "./Secret.ts";
+
+/** Write, find, list and delete secrets by name in one environment. */
+export interface SecretsClientOf<R> {
+  /**
+   * Create or overwrite the secret named `name` with `env`. Returns its
+   * attributes, to pass as a sandbox `secrets` entry or in an outbound
+   * header replacement.
+   */
+  put(
+    name: string,
+    env: Record<string, string | Redacted.Redacted<string>>,
+  ): Effect.Effect<SecretAttributes, ErrorOf<typeof putSecret>, R>;
+  /** The secret named `name` (its variable names, never its values), or `undefined`. */
+  get(name: string): Effect.Effect<SecretAttributes | undefined, ErrorOf<typeof lookupSecret>, R>;
+  /** Delete the secret named `name` (no-op when missing). */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    | ErrorOf<typeof lookupSecret>
+    | Exclude<OpError<SecretsOps, "delete">, { readonly _tag: "SecretNotFound" }>,
+    R
+  >;
+  /** Names of every secret in the environment. */
+  list(): Effect.Effect<ReadonlyArray<string>, OpError<SecretsOps, "list">, R>;
+}
+
+/** A SecretsClient whose calls run inside a deployed runtime. */
+export type SecretsClient = SecretsClientOf<RuntimeContext>;
+
+/**
+ * Store secrets by name at runtime, such as one per user, and hand them to
+ * that user's sandboxes. With an outbound header replacement the sandbox
+ * never sees the value: Modal adds it to matching requests on the way out.
+ *
+ * Bind it to a `Modal.Environment` to keep these runtime secrets in their
+ * own namespace. They aren't in Alchemy state: deleting the environment
+ * removes them.
+ *
+ * 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. A Modal secret has only a name, so the tags become
+ * its name prefix, `Modal.runtimePrefix({ stack, stage, id })`: list them
+ * with `modal secret list` and delete the ones whose name starts with it.
+ *
+ * ### A user's token, injected at egress
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ * import { HttpServerRequest } from "effect/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Agents, Coder } from "./Coder.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const secrets = yield* Modal.CreateSecret(Agents);
+ *     const sandboxes = yield* Modal.CreateSandbox(Coder);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const user = request.headers["x-user"] ?? "anonymous";
+ *         const github = yield* secrets.put(`github-${user}`, {
+ *           GITHUB_TOKEN: request.headers["x-github-token"] ?? "",
+ *         });
+ *         const sandbox = yield* sandboxes.create({
+ *           outboundPolicy: {
+ *             routes: [
+ *               {
+ *                 https: {
+ *                   domains: ["api.github.com"],
+ *                   headerReplacements: [{ secret: github, headers: { Authorization: "Bearer $GITHUB_TOKEN" } }],
+ *                 },
+ *               },
+ *               { tls: { domains: ["github.com"] } },
+ *               { any: { redirect: "block" } },
+ *             ],
+ *           },
+ *         });
+ *         return HttpServerResponse.text(sandbox.sandboxId);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Modal.CreateSecretHttp, Modal.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Secret
+ */
+export interface CreateSecret extends Binding.Service<
+  CreateSecret,
+  "Modal.CreateSecret",
+  (environment?: Environment) => Effect.Effect<SecretsClient>
+> {}
+
+export const CreateSecret = Binding.Service<CreateSecret>("Modal.CreateSecret");