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

package/src/CreateSecretHttp.ts

@@ -0,0 +1,83 @@
+import * as secret from "@distilled.cloud/modal/secret";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeOpenModalBinding } from "./BindingHttp.ts";
+import { CreateSecret, type SecretsClientOf } from "./CreateSecret.ts";
+import type { Environment } from "./Environment.ts";
+import { environmentOf, listAll, operations } from "./internal.ts";
+import { ownedName, type RuntimeOwner, RuntimeOwnerOf, unownedName } from "./RuntimeOwner.ts";
+import { lookupSecret, putSecret } from "./Secret.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+export const SecretsOps = operations({
+  getOrCreate: secret.secretGetOrCreate,
+  delete: secret.deleteSecret,
+  list: secret.listSecret,
+});
+
+export type SecretsOps = Effect.Success<typeof SecretsOps>;
+
+/** A secrets client over an environment name resolved per call. */
+export const makeSecretsClient = (
+  environment: Effect.Effect<string | undefined>,
+  ops: SecretsOps,
+  owner: Effect.Effect<RuntimeOwner | undefined> = Effect.undefined,
+): SecretsClientOf<never> => ({
+  put: (name, env) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([e, stamp]) =>
+      putSecret(ops.getOrCreate, ownedName(stamp, name), e, env),
+    ),
+  get: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([e, stamp]) =>
+      lookupSecret(ops.getOrCreate, ownedName(stamp, name), e),
+    ),
+  delete: (name) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const found = yield* lookupSecret(ops.getOrCreate, ownedName(yield* owner, name), env);
+      if (!found) return;
+      yield* ops
+        .delete({ secretId: found.secretId })
+        .pipe(Effect.catchTag("SecretNotFound", () => 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.items ?? [])),
+        (item) => item.createdAt,
+      );
+      return items.flatMap((item) => {
+        const name = item.label ?? item.metadata?.name;
+        const own = name ? unownedName(stamp, name) : undefined;
+        return own ? [own] : [];
+      });
+    }),
+});
+
+/**
+ * {@link CreateSecret} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the environment.
+ *
+ * @layer
+ * @product Secret
+ * @provides Modal.CreateSecret
+ */
+export const CreateSecretHttp = Layer.effect(
+  CreateSecret,
+  makeOpenModalBinding({
+    tag: "Modal.CreateSecret",
+    operations: SecretsOps,
+    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 makeSecretsClient(name, ops, owner);
+    }),
+  }),
+);

package/src/CreateVolume.ts

@@ -0,0 +1,96 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { VolumesOps } from "./CreateVolumeHttp.ts";
+import type { Environment } from "./Environment.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+import type { ensureVolume, lookupVolume } from "./Volume.ts";
+import type { VolumeAttributes } from "./Volume.ts";
+import type { ReadWriteVolumeClient } from "./VolumeClient.ts";
+
+/** A volume created or found at runtime: its attributes plus a read-write client. */
+export interface VolumeHandle extends ReadWriteVolumeClient {
+  readonly volumeId: Effect.Effect<string>;
+  readonly name: string;
+  /** The attributes, to pass where a `Modal.Volume` is accepted (e.g. sandbox mounts). */
+  readonly attributes: VolumeAttributes;
+}
+
+/** Get, create, list and delete volumes by name in one environment. */
+export interface VolumesClientOf<R> {
+  /** The volume named `name`, created when missing (Modal's own get-or-create). */
+  getOrCreate(name: string): Effect.Effect<VolumeHandle, ErrorOf<typeof ensureVolume>, R>;
+  /** The volume named `name`, or `undefined`. */
+  get(name: string): Effect.Effect<VolumeHandle | undefined, ErrorOf<typeof lookupVolume>, R>;
+  /** Delete the volume named `name` (no-op when missing). */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    | ErrorOf<typeof lookupVolume>
+    | Exclude<OpError<VolumesOps, "delete">, { readonly _tag: "VolumeNotFound" }>,
+    R
+  >;
+  /** Names of every volume in the environment. */
+  list(): Effect.Effect<ReadonlyArray<string>, OpError<VolumesOps, "list">, R>;
+}
+
+/** A VolumesClient whose calls run inside a deployed runtime. */
+export type VolumesClient = VolumesClientOf<RuntimeContext>;
+
+/**
+ * Create volumes 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 volume has only a name, so the tags become
+ * its name prefix, `Modal.runtimePrefix({ stack, stage, id })`: list them
+ * with `modal volume list` and delete the ones whose name starts with it.
+ *
+ * ### One volume 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 volumes = yield* Modal.CreateVolume(Agents);
+ *     const sandboxes = yield* Modal.CreateSandbox(Coder);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const user = request.headers["x-user"] ?? "anonymous";
+ *         const home = yield* volumes.getOrCreate(`user-${user}`);
+ *         yield* home.writeFile("/notes.md", "hello");
+ *         const sandbox = yield* sandboxes.create({ mounts: [{ volume: home, path: "/home/user" }] });
+ *         return HttpServerResponse.text("ok");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Modal.CreateVolumeHttp, Modal.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface CreateVolume extends Binding.Service<
+  CreateVolume,
+  "Modal.CreateVolume",
+  (environment?: Environment) => Effect.Effect<VolumesClient>
+> {}
+
+export const CreateVolume = Binding.Service<CreateVolume>("Modal.CreateVolume");

package/src/CreateVolumeHttp.ts

@@ -0,0 +1,93 @@
+import * as volume from "@distilled.cloud/modal/volume";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeOpenModalBinding } from "./BindingHttp.ts";
+import { CreateVolume, type VolumeHandle, type VolumesClientOf } from "./CreateVolume.ts";
+import type { Environment } from "./Environment.ts";
+import { environmentOf, listAll, operations } from "./internal.ts";
+import { ownedName, type RuntimeOwner, RuntimeOwnerOf, unownedName } from "./RuntimeOwner.ts";
+import { ensureVolume, lookupVolume, type VolumeAttributes } from "./Volume.ts";
+import { makeReadWriteVolumeClient } from "./VolumeClient.ts";
+import { VolumeFileOps } from "./VolumeFiles.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+export const VolumesOps = operations({
+  getOrCreate: volume.volumeGetOrCreate,
+  delete: volume.deleteVolume,
+  list: volume.listVolume,
+  client: VolumeFileOps,
+});
+
+export type VolumesOps = Effect.Success<typeof VolumesOps>;
+
+const handleOf = (attributes: VolumeAttributes, ops: VolumesOps, name: string): VolumeHandle => ({
+  ...makeReadWriteVolumeClient(Effect.succeed(attributes.volumeId), ops.client),
+  volumeId: Effect.succeed(attributes.volumeId),
+  name,
+  attributes,
+});
+
+/** A volumes client over an environment name resolved per call. */
+export const makeVolumesClient = (
+  environment: Effect.Effect<string | undefined>,
+  ops: VolumesOps,
+  owner: Effect.Effect<RuntimeOwner | undefined> = Effect.undefined,
+): VolumesClientOf<never> => ({
+  getOrCreate: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      ensureVolume(ops.getOrCreate, ownedName(stamp, name), env),
+    ).pipe(Effect.map((attributes) => handleOf(attributes, ops, name))),
+  get: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      lookupVolume(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* lookupVolume(ops.getOrCreate, ownedName(yield* owner, name), env);
+      if (!found) return;
+      yield* ops
+        .delete({ volumeId: found.volumeId, environmentName: environmentOf(env) })
+        .pipe(Effect.catchTag("VolumeNotFound", () => 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.items ?? [])),
+        (item) => item.createdAt,
+      );
+      return items.flatMap((item) => {
+        const name = item.label ?? item.metadata?.name;
+        const own = name ? unownedName(stamp, name) : undefined;
+        return own ? [own] : [];
+      });
+    }),
+});
+
+/**
+ * {@link CreateVolume} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the environment.
+ *
+ * @layer
+ * @product Volume
+ * @provides Modal.CreateVolume
+ */
+export const CreateVolumeHttp = Layer.effect(
+  CreateVolume,
+  makeOpenModalBinding({
+    tag: "Modal.CreateVolume",
+    operations: VolumesOps,
+    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 makeVolumesClient(name, ops, owner);
+    }),
+  }),
+);

package/src/Credentials.ts

@@ -0,0 +1,74 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import { withAuthToken } from "@distilled.cloud/modal/AuthToken";
+import { Credentials, DEFAULT_API_BASE_URL } from "@distilled.cloud/modal/Credentials";
+import { lazyCredentials } from "alchemy/Auth/Resolve";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { MODAL_AUTH_PROVIDER_NAME, type ModalResolvedCredentials } from "./AuthProvider.ts";
+import { ModalTransport } from "./internal/Transport.ts";
+
+export { withAuthToken } from "@distilled.cloud/modal/AuthToken";
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/modal/Credentials";
+
+/**
+ * Build Modal `Credentials` that resolve through the Alchemy AuthProvider:
+ * `MODAL_TOKEN_ID` / `MODAL_TOKEN_SECRET` when set, otherwise the selected
+ * profile. Resolution is deferred until the first API call, so building the
+ * provider layers never needs a profile.
+ */
+export const fromAuthProvider = () =>
+  withAuthTokens(
+    Layer.effect(
+      Credentials,
+      lazyCredentials<ModalResolvedCredentials, ConfigError>()(
+        MODAL_AUTH_PROVIDER_NAME,
+        (creds) => ({
+          tokenId: creds.tokenId,
+          tokenSecret: creds.tokenSecret,
+          apiBaseUrl: creds.apiBaseUrl,
+        }),
+      ),
+    ),
+  );
+
+/**
+ * Add Modal's short-lived auth token (the `x-modal-auth-token` JWT its V2
+ * sandbox RPCs and input plane need) to a token pair's `Credentials`.
+ */
+export const withAuthTokens = <E, R>(
+  credentials: Layer.Layer<Credentials, E, R>,
+): Layer.Layer<Credentials, E, R> =>
+  withAuthToken.pipe(Layer.provide(Layer.mergeAll(credentials, ModalTransport)));
+
+/**
+ * Build Modal `Credentials` from an explicit token pair, e.g. in a test or a
+ * script that already holds one.
+ *
+ * @example
+ * ```ts
+ * Effect.provide(Modal.fromToken({ tokenId: "ak-…", tokenSecret: "as-…" }))
+ * ```
+ */
+export const fromToken = (input: {
+  tokenId: string | Redacted.Redacted<string>;
+  tokenSecret: string | Redacted.Redacted<string>;
+  apiBaseUrl?: string;
+}): Layer.Layer<Credentials> =>
+  withAuthTokens(
+    Layer.succeed(
+      Credentials,
+      Effect.succeed({
+        tokenId: typeof input.tokenId === "string" ? Redacted.make(input.tokenId) : input.tokenId,
+        tokenSecret:
+          typeof input.tokenSecret === "string"
+            ? Redacted.make(input.tokenSecret)
+            : input.tokenSecret,
+        apiBaseUrl: input.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+      }),
+    ),
+  );

package/src/Dict.ts

@@ -0,0 +1,245 @@
+import * as dict from "@distilled.cloud/modal/dict";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import {
+  type EnvironmentInput,
+  envNameOf,
+  environmentNames,
+  environmentOf,
+  isGeneratedName,
+  listAll,
+  objectName,
+} from "./internal.ts";
+import { declarable } from "./internal/Declared.ts";
+import type { Providers } from "./Providers.ts";
+import { isRuntimeName } from "./RuntimeOwner.ts";
+
+export class DictUnexpectedResponse extends Data.TaggedError("Modal.DictUnexpectedResponse")<{
+  readonly message: string;
+}> {}
+
+export interface DictProps {
+  /**
+   * Dict name, unique per environment. If omitted, a unique name is
+   * generated from the stack, stage and logical ID. Changing it replaces the
+   * dict (Modal can't rename dicts).
+   */
+  name?: string;
+  /**
+   * Environment the dict lives in. Changing it replaces the dict.
+   * @default the workspace's default environment
+   */
+  environment?: EnvironmentInput;
+}
+
+export interface DictAttributes {
+  /** Dict ID (`di-…`). */
+  dictId: string;
+  /** Dict name. */
+  name: string;
+  /** Environment name, or `undefined` for the workspace default. */
+  environment: string | undefined;
+}
+
+/**
+ * A Modal Dict: a distributed key-value store shared by every container,
+ * Sandbox and client in the workspace. Entries expire 7 days after their
+ * last write.
+ *
+ * Bind it with {@link ReadDict}, {@link WriteDict} or {@link ReadWriteDict}
+ * to use it from a Worker, Lambda or any other runtime. Values travel as
+ * bytes: the bindings encode them as JSON by default.
+ *
+ * Modal dicts have no tags. Ownership is inferred from Alchemy state: a
+ * dict found under an explicit `name` without prior state is reported as
+ * unowned.
+ *
+ * ### Creating a Dict
+ * **Example:** A dict with a generated name
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Results = Modal.Dict("Results", {});
+ * ```
+ *
+ * **Example:** A named dict in an environment
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Agents = Modal.Environment("Agents", {});
+ * export const Sessions = Modal.Dict("Sessions", { name: "sessions", environment: Agents });
+ * ```
+ *
+ * ### Reading and writing from a Worker
+ * **Example:** Bind read and write access
+ * ```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 { Results } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const results = yield* Modal.ReadWriteDict(Results);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* results.put("last-run", { ok: true });
+ *         const last = yield* results.get("last-run");
+ *         return yield* HttpServerResponse.json(last ?? null);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ReadWriteDictHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Looking up an existing dict
+ * `Dict.lookup` references a dict Alchemy doesn't manage (created with
+ * the Modal CLI or by another stack). It is read during plan/deploy, never
+ * created, updated or deleted.
+ *
+ * **Example:** Reference an existing dict
+ * ```typescript
+ * const cache = Modal.Dict.lookup({ name: "cache" });
+ * ```
+ *
+ * @resource
+ * @product Dict
+ */
+export const Dict = declarable<Dict>()(Resource<Dict>("Modal.Dict"));
+
+export type Dict = Resource<"Modal.Dict", DictProps, DictAttributes, never, Providers, DictLookup>;
+
+/**
+ * Props for {@link Dict.lookup}: find a dict this stack
+ * doesn't manage by its name.
+ */
+export interface DictLookup {
+  /** Dict name. */
+  name: string;
+  /**
+   * Modal environment the object lives in.
+   * @default the workspace's default environment
+   */
+  environment?: string;
+}
+
+/** A dict by name, or `undefined` when missing. */
+export const lookupDict = Effect.fn(function* (
+  getOrCreate: Effect.Success<typeof dict.dictGetOrCreate>,
+  name: string,
+  env: string | undefined,
+) {
+  const found = yield* getOrCreate({
+    deploymentName: name,
+    environmentName: environmentOf(env),
+    objectCreationType: "OBJECT_CREATION_TYPE_UNSPECIFIED",
+  }).pipe(Effect.catchTag("DictNotFound", () => Effect.undefined));
+  if (!found?.dictId) return undefined;
+  return { dictId: found.dictId, name, environment: env } satisfies DictAttributes;
+});
+
+/**
+ * Get a dict by name, creating it when missing: the one implementation behind
+ * {@link Dict}'s reconcile and the runtime {@link CreateDict} client.
+ */
+export const ensureDict = Effect.fn(function* (
+  getOrCreate: Effect.Success<typeof dict.dictGetOrCreate>,
+  name: string,
+  env: string | undefined,
+) {
+  const created = yield* getOrCreate({
+    deploymentName: name,
+    environmentName: environmentOf(env),
+    objectCreationType: "OBJECT_CREATION_TYPE_CREATE_IF_MISSING",
+  });
+  if (!created.dictId) {
+    return yield* new DictUnexpectedResponse({ message: `Modal returned no id for dict ${name}` });
+  }
+  return { dictId: created.dictId, name, environment: env } satisfies DictAttributes;
+});
+
+export const DictProvider = () =>
+  Provider.effect(
+    Dict,
+    Effect.gen(function* () {
+      const observe = Effect.fn(function* (
+        dictId: string | undefined,
+        name: string,
+        env: string | undefined,
+      ) {
+        if (dictId !== undefined) {
+          const byId = yield* dict
+            .dictGetById({ dictId })
+            .pipe(Effect.catchTag("DictNotFound", () => Effect.undefined));
+          if (byId?.dictId) {
+            return {
+              dictId: byId.dictId,
+              name: byId.metadata?.name ?? name,
+              environment: env,
+            } satisfies DictAttributes;
+          }
+        }
+        return yield* lookupDict(yield* dict.dictGetOrCreate, name, env);
+      });
+
+      return {
+        stables: ["dictId", "name", "environment"],
+        diff: Effect.fn(function* ({ id, news, olds, output }) {
+          if (!isResolved(news)) return undefined;
+          if (envNameOf(news.environment) !== envNameOf(olds?.environment))
+            return { action: "replace" } as const;
+          const name = yield* objectName(id, news.name);
+          if (output !== undefined && name !== output.name) return { action: "replace" } as const;
+          return undefined;
+        }),
+        lookup: Effect.fn(function* ({ name, environment }) {
+          return yield* observe(undefined, name, environment);
+        }),
+
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.name ?? (yield* objectName(id, olds?.name));
+          const observed = yield* observe(output?.dictId, name, envNameOf(olds?.environment));
+          if (!observed) return undefined;
+          return output !== undefined || olds?.name === undefined ? observed : Unowned(observed);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = output?.name ?? (yield* objectName(id, news.name));
+          const current = yield* observe(output?.dictId, name, envNameOf(news.environment));
+          if (current) return current;
+          yield* session.note(`Creating dict ${name}...`);
+          return yield* ensureDict(yield* dict.dictGetOrCreate, name, envNameOf(news.environment));
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* dict
+            .deleteDict({ dictId: output.dictId })
+            .pipe(Effect.catchTag("DictNotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const envs = yield* environmentNames;
+          const all: DictAttributes[] = [];
+          for (const env of envs) {
+            const items = yield* listAll(
+              (pagination) =>
+                dict
+                  .listDict({ environmentName: env, pagination })
+                  .pipe(Effect.map((response) => response.dicts ?? [])),
+              (item) => item.createdAt,
+            );
+            for (const item of items) {
+              if (!item.dictId || !(isGeneratedName(item.name) || isRuntimeName(item.name)))
+                continue;
+              all.push({ dictId: item.dictId, name: item.name ?? "", environment: env });
+            }
+          }
+          return all;
+        }),
+      };
+    }),
+  );