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

package/src/WriteApp.ts

@@ -0,0 +1,43 @@
+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 { OpError } from "./internal.ts";
+import type { WriteAppOps } from "./WriteAppHttp.ts";
+
+/** Change an App's deployment. */
+export interface AppWriter {
+  /** Redeploy an earlier version (the previous one by default). */
+  rollback(options?: {
+    readonly version?: number;
+  }): Effect.Effect<void, OpError<WriteAppOps, "rollback">, RuntimeContext>;
+  /** Restart every container on the current version, draining the old ones. */
+  rollover(): Effect.Effect<void, OpError<WriteAppOps, "rollover">, RuntimeContext>;
+  /** Put a staged version into production. */
+  promote(version: number): Effect.Effect<void, OpError<WriteAppOps, "promote">, RuntimeContext>;
+  /** Stop the App: its functions stop serving and its sandboxes terminate. */
+  stop(): Effect.Effect<void, OpError<WriteAppOps, "stop">, RuntimeContext>;
+}
+
+/**
+ * Operate a Modal App from any runtime: roll back a bad version, roll the
+ * containers over, promote a staged version, or stop it. The next deploy of
+ * the Stack publishes its declared version again.
+ *
+ * ### Roll back
+ * **Example:** From an incident webhook
+ * ```typescript
+ * const backend = yield* Modal.WriteApp(Backend);
+ * yield* backend.rollback();
+ * ```
+ *
+ * @binding
+ * @product App
+ */
+export interface WriteApp extends Binding.Service<
+  WriteApp,
+  "Modal.WriteApp",
+  (app: App) => Effect.Effect<AppWriter>
+> {}
+
+export const WriteApp = Binding.Service<WriteApp>("Modal.WriteApp");

package/src/WriteAppHttp.ts

@@ -0,0 +1,51 @@
+import * as app from "@distilled.cloud/modal/app";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { App } from "./App.ts";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { operations } from "./internal.ts";
+import { WriteApp, type AppWriter } from "./WriteApp.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+const WriteAppOps = operations({
+  rollback: app.appRollback,
+  rollover: app.appRollover,
+  promote: app.promoteApp,
+  stop: app.stopApp,
+});
+
+export type WriteAppOps = Effect.Success<typeof WriteAppOps>;
+
+/**
+ * {@link WriteApp} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the App's environment.
+ *
+ * @layer
+ * @product App
+ * @provides Modal.WriteApp
+ */
+export const WriteAppHttp = Layer.effect(
+  WriteApp,
+  makeModalBinding({
+    tag: "Modal.WriteApp",
+    operations: WriteAppOps,
+    role: "contributor",
+    make: Effect.fn(function* (target: App, ops) {
+      const appId = yield* target.appId;
+      return {
+        rollback: (options = {}) =>
+          Effect.flatMap(appId, (id) => ops.rollback({ appId: id, version: options.version })).pipe(
+            Effect.asVoid,
+          ),
+        rollover: () =>
+          Effect.flatMap(appId, (id) => ops.rollover({ appId: id })).pipe(Effect.asVoid),
+        promote: (version) =>
+          Effect.flatMap(appId, (id) => ops.promote({ appId: id, version })).pipe(Effect.asVoid),
+        stop: () =>
+          Effect.flatMap(appId, (id) =>
+            ops.stop({ appId: id, source: "APP_STOP_SOURCE_CLI" }),
+          ).pipe(Effect.asVoid),
+      } satisfies AppWriter;
+    }),
+  }),
+);

package/src/WriteDict.ts

@@ -0,0 +1,44 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Dict } from "./Dict.ts";
+import type { WriteDictClient } from "./DictClient.ts";
+
+export type { WriteDictClient } from "./DictClient.ts";
+
+/**
+ * Write a Modal Dict from any runtime: put, update, pop and clear. Keys and values are JSON.
+ *
+ * ### Bind a dict
+ * **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 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 dict = yield* Modal.WriteDict(Results);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* dict.put("last-run", { ok: true });
+ *         return HttpServerResponse.text("saved");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.WriteDictHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Dict
+ */
+export interface WriteDict extends Binding.Service<
+  WriteDict,
+  "Modal.WriteDict",
+  (dict: Dict) => Effect.Effect<WriteDictClient>
+> {}
+
+export const WriteDict = Binding.Service<WriteDict>("Modal.WriteDict");

package/src/WriteDictHttp.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import type { Dict } from "./Dict.ts";
+import { DictOps, makeWriteDictClient } from "./DictClient.ts";
+import { WriteDict } from "./WriteDict.ts";
+
+/**
+ * {@link WriteDict} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the dict's environment.
+ *
+ * @layer
+ * @product Dict
+ * @provides Modal.WriteDict
+ */
+export const WriteDictHttp = Layer.effect(
+  WriteDict,
+  makeModalBinding({
+    tag: "Modal.WriteDict",
+    operations: DictOps,
+    role: "contributor",
+    make: Effect.fn(function* (dict: Dict, ops) {
+      const dictId = yield* dict.dictId;
+      return makeWriteDictClient(dictId, ops);
+    }),
+  }),
+);

package/src/WriteQueue.ts

@@ -0,0 +1,44 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Queue } from "./Queue.ts";
+import type { WriteQueueClient } from "./QueueClient.ts";
+
+export type { WriteQueueClient } from "./QueueClient.ts";
+
+/**
+ * Put items into a Modal Queue from any runtime. Items are JSON, so a Python consumer reads them with `json.loads`.
+ *
+ * ### Bind a queue
+ * **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 HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Jobs } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const queue = yield* Modal.WriteQueue(Jobs);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* queue.put({ repo: "alchemy-run/alchemy", command: "pnpm test" });
+ *         return HttpServerResponse.text("queued");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.WriteQueueHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Queue
+ */
+export interface WriteQueue extends Binding.Service<
+  WriteQueue,
+  "Modal.WriteQueue",
+  (queue: Queue) => Effect.Effect<WriteQueueClient>
+> {}
+
+export const WriteQueue = Binding.Service<WriteQueue>("Modal.WriteQueue");

package/src/WriteQueueHttp.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import type { Queue } from "./Queue.ts";
+import { QueueOps, makeWriteQueueClient } from "./QueueClient.ts";
+import { WriteQueue } from "./WriteQueue.ts";
+
+/**
+ * {@link WriteQueue} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the queue's environment.
+ *
+ * @layer
+ * @product Queue
+ * @provides Modal.WriteQueue
+ */
+export const WriteQueueHttp = Layer.effect(
+  WriteQueue,
+  makeModalBinding({
+    tag: "Modal.WriteQueue",
+    operations: QueueOps,
+    role: "contributor",
+    make: Effect.fn(function* (queue: Queue, ops) {
+      const queueId = yield* queue.queueId;
+      return makeWriteQueueClient(queueId, ops);
+    }),
+  }),
+);

package/src/WriteSecret.ts

@@ -0,0 +1,60 @@
+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 { OpError } from "./internal.ts";
+import type { Secret } from "./Secret.ts";
+import type { WriteSecretOps } from "./WriteSecretHttp.ts";
+
+/** Replace one secret's variables. */
+export interface WriteSecretClient {
+  readonly secretId: Effect.Effect<string>;
+  /**
+   * Replace the secret's whole variable set. Sandboxes and functions started
+   * afterwards see the new values; running ones keep theirs.
+   */
+  put(
+    env: Record<string, string | Redacted.Redacted<string>>,
+  ): Effect.Effect<void, OpError<WriteSecretOps, "getInfo" | "update">, RuntimeContext>;
+}
+
+/**
+ * Rotate a Modal Secret from any runtime. Modal never returns secret
+ * values, so there is no read binding: attach the secret to a sandbox
+ * instead, or inject it with an outbound header replacement.
+ *
+ * ### Rotate a secret
+ * **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 Redacted from "effect/Redacted";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { OpenAI } from "./Storage.ts";
+ *
+ * export default class Rotate extends Cloudflare.Worker<Rotate>()(
+ *   "Rotate",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const openai = yield* Modal.WriteSecret(OpenAI);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* openai.put({ OPENAI_API_KEY: Redacted.make("sk-new") });
+ *         return HttpServerResponse.text("rotated");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.WriteSecretHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Secret
+ */
+export interface WriteSecret extends Binding.Service<
+  WriteSecret,
+  "Modal.WriteSecret",
+  (secret: Secret) => Effect.Effect<WriteSecretClient>
+> {}
+
+export const WriteSecret = Binding.Service<WriteSecret>("Modal.WriteSecret");

package/src/WriteSecretHttp.ts

@@ -0,0 +1,56 @@
+import * as secret from "@distilled.cloud/modal/secret";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { operations } from "./internal.ts";
+import type { Secret } from "./Secret.ts";
+import { WriteSecret, type WriteSecretClient } from "./WriteSecret.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+const WriteSecretOps = operations({ getInfo: secret.secretGetInfo, update: secret.updateSecret });
+
+export type WriteSecretOps = Effect.Success<typeof WriteSecretOps>;
+
+/** A write client over a secret id. */
+export const makeWriteSecretClient = (
+  secretId: Effect.Effect<string>,
+  ops: WriteSecretOps,
+): WriteSecretClient => ({
+  secretId,
+  put: (env) =>
+    Effect.gen(function* () {
+      const id = yield* secretId;
+      const { metadata } = yield* ops.getInfo({ secretId: id });
+      const values = Object.entries(env).map(([key, value]) => ({
+        key,
+        value: Redacted.isRedacted(value) ? Redacted.value(value) : value,
+      }));
+      const removed = (metadata?.keys ?? []).filter((key) => !(key in env));
+      yield* ops.update({
+        secretId: id,
+        updates: [...values, ...removed.map((key) => ({ key }))],
+      });
+    }),
+});
+
+/**
+ * {@link WriteSecret} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the secret's environment.
+ *
+ * @layer
+ * @product Secret
+ * @provides Modal.WriteSecret
+ */
+export const WriteSecretHttp = Layer.effect(
+  WriteSecret,
+  makeModalBinding({
+    tag: "Modal.WriteSecret",
+    operations: WriteSecretOps,
+    role: "contributor",
+    make: Effect.fn(function* (resource: Secret, ops) {
+      const secretId = yield* resource.secretId;
+      return makeWriteSecretClient(secretId, ops);
+    }),
+  }),
+);

package/src/WriteVolume.ts

@@ -0,0 +1,44 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Volume } from "./Volume.ts";
+import type { WriteVolumeClient } from "./VolumeClient.ts";
+
+export type { WriteVolumeClient } from "./VolumeClient.ts";
+
+/**
+ * Write a Modal Volume's files from any runtime without mounting it: upload, remove and copy files over Modal's volume API. Sandboxes that mount the volume see the changes after they reload it.
+ *
+ * ### Bind a volume
+ * **Example:** Write 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 HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Workspace } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const volume = yield* Modal.WriteVolume(Workspace);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* volume.writeFile("/inbox/task.json", JSON.stringify({ repo: "alchemy" }));
+ *         return HttpServerResponse.text("written");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.WriteVolumeHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface WriteVolume extends Binding.Service<
+  WriteVolume,
+  "Modal.WriteVolume",
+  (volume: Volume) => Effect.Effect<WriteVolumeClient>
+> {}
+
+export const WriteVolume = Binding.Service<WriteVolume>("Modal.WriteVolume");

package/src/WriteVolumeHttp.ts

@@ -0,0 +1,28 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import type { Volume } from "./Volume.ts";
+import { makeWriteVolumeClient } from "./VolumeClient.ts";
+import { VolumeFileOps } from "./VolumeFiles.ts";
+import { WriteVolume } from "./WriteVolume.ts";
+
+/**
+ * {@link WriteVolume} over Modal's volume API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the volume's environment.
+ *
+ * @layer
+ * @product Volume
+ * @provides Modal.WriteVolume
+ */
+export const WriteVolumeHttp = Layer.effect(
+  WriteVolume,
+  makeModalBinding({
+    tag: "Modal.WriteVolume",
+    operations: VolumeFileOps,
+    role: "contributor",
+    make: Effect.fn(function* (volume: Volume, ops) {
+      const volumeId = yield* volume.volumeId;
+      return makeWriteVolumeClient(volumeId, ops);
+    }),
+  }),
+);

package/src/globals.d.ts

@@ -0,0 +1,2 @@
+// `globalThis.__ALCHEMY_RUNTIME__`, declared by alchemy's Phase module.
+import type {} from "alchemy/Phase";

package/src/index.ts

@@ -0,0 +1,85 @@
+export * from "./App.ts";
+export * from "./AuthProvider.ts";
+export * from "./ConnectSandbox.ts";
+export * from "./Container.ts";
+export * from "./CreateDict.ts";
+export * from "./CreateDictHttp.ts";
+export * from "./CreateImage.ts";
+export * from "./CreateImageHttp.ts";
+export * from "./CreateQueue.ts";
+export * from "./CreateQueueHttp.ts";
+export * from "./CreateSandbox.ts";
+export * from "./CreateSandboxHttp.ts";
+export * from "./CreateSecret.ts";
+export * from "./CreateSecretHttp.ts";
+export * from "./CreateVolume.ts";
+export * from "./CreateVolumeHttp.ts";
+export * from "./Dict.ts";
+export * from "./Domain.ts";
+export * from "./Endpoint.ts";
+export * from "./Environment.ts";
+export * from "./FetchServer.ts";
+export * from "./FetchServerHttp.ts";
+export * from "./Function.ts";
+export * from "./FunctionAutoscaler.ts";
+export * from "./Image.ts";
+export * from "./ImageBuild.ts";
+export * from "./InvokeFunction.ts";
+export * from "./InvokeFunctionHttp.ts";
+export * from "./Providers.ts";
+export * from "./PersistentSandbox.ts";
+export * from "./MountBucket.ts";
+export * from "./Mounts.ts";
+export * from "./MountVolume.ts";
+export * from "./Proxy.ts";
+export * from "./RuntimeOwner.ts";
+export * from "./Queue.ts";
+export * from "./ReadApp.ts";
+export * from "./ReadAppHttp.ts";
+export * from "./ReadDict.ts";
+export * from "./ReadDictHttp.ts";
+export * from "./ReadFunction.ts";
+export * from "./ReadFunctionHttp.ts";
+export * from "./ReadQueue.ts";
+export * from "./ReadQueueHttp.ts";
+export * from "./ReadServer.ts";
+export * from "./ReadServerHttp.ts";
+export * from "./ReadVolume.ts";
+export * from "./ReadVolumeHttp.ts";
+export * from "./ReadWriteDict.ts";
+export * from "./ReadWriteDictHttp.ts";
+export * from "./ReadWriteQueue.ts";
+export * from "./ReadWriteQueueHttp.ts";
+export * from "./ReadWriteVolume.ts";
+export * from "./ReadWriteVolumeHttp.ts";
+export * from "./Sandbox.ts";
+export * from "./SandboxClient.ts";
+export * from "./ScaleFunction.ts";
+export * from "./ScaleFunctionHttp.ts";
+export * from "./Secret.ts";
+export * from "./Server.ts";
+export * from "./ServiceUser.ts";
+export * from "./Volume.ts";
+export * from "./VolumeFiles.ts";
+export * from "./WebhookToken.ts";
+export * from "./WorkspaceSettings.ts";
+export * from "./WriteApp.ts";
+export * from "./WriteAppHttp.ts";
+export * from "./WriteDict.ts";
+export * from "./WriteDictHttp.ts";
+export * from "./WriteQueue.ts";
+export * from "./WriteQueueHttp.ts";
+export * from "./WriteSecret.ts";
+export * from "./WriteSecretHttp.ts";
+export * from "./WriteVolume.ts";
+export * from "./WriteVolumeHttp.ts";
+export type { InferEnv } from "./InferEnv.ts";
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+  fromAuthProvider,
+  fromToken,
+} from "./Credentials.ts";
+export { DeployerHostIdentity, HostIdentity } from "./ModalBindings.ts";
+export type { DictHandle, DictsClient } from "./CreateDict.ts";

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: `app: Backend`
+ * instead of `app: yield* Backend`, 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: `Modal.Image("Node", { app: Backend })`.
+ * 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;