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

package/src/internal/Deploy.ts

@@ -0,0 +1,309 @@
+import * as BuildPlan from "@alchemy.run/docker/BuildPlan";
+import * as app from "@distilled.cloud/modal/app";
+import * as mount from "@distilled.cloud/modal/mount";
+import * as workspace from "@distilled.cloud/modal/workspace";
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import { type MountCapability, mountInstallLines } from "alchemy/Mount";
+import { sha256, sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Semaphore from "effect/Semaphore";
+import { buildImage, ImageBuildOps, type ImageBuildSpec } from "../ImageBuild.ts";
+import { checkCommands, lowerPlan, MODAL_CAPABILITIES } from "../ImagePlan.ts";
+import { checkModalMounts } from "../Mounts.ts";
+import { ENTRYPOINT_PATH, ENTRYPOINT_SOURCE } from "./Entrypoint.ts";
+
+/*
+ * Deploy-time plumbing shared by `Modal.Function` and `Modal.Server`: the
+ * Python layer and mounts every Modal Function container needs, and
+ * publishing a function into its App.
+ */
+
+/** Modal returned a response without a field the deploy needs. */
+export class ModalDeployUnexpectedResponse extends Data.TaggedError(
+  "Modal.DeployUnexpectedResponse",
+)<{
+  readonly message: string;
+}> {}
+
+/**
+ * The Modal Python client whose container entrypoint runs the function.
+ * Modal publishes it as the global mount `modal-client-mount-<version>`.
+ */
+export const MODAL_CLIENT_VERSION = "1.6.3";
+
+/** Standalone Python builds Modal publishes as global mounts, by image builder version. */
+const PYTHON_STANDALONE: Record<
+  "2026.10" | "2025.06",
+  Record<string, readonly [string, string]>
+> = {
+  "2026.10": {
+    "3.11": ["20261021", "3.11.17"],
+    "3.12": ["20261021", "3.12.15"],
+    "3.13": ["20261021", "3.13.17"],
+    "3.14": ["20261021", "3.14.9"],
+  },
+  "2025.06": {
+    "3.11": ["20230826", "3.11.5"],
+    "3.12": ["20240107", "3.12.1"],
+    "3.13": ["20241008", "3.13.0"],
+    "3.14": ["20251205", "3.14.2"],
+  },
+};
+
+/** The Python version added to a base image without one. */
+export const DEFAULT_PYTHON = "3.12";
+
+/** Port the program listens on when the resource doesn't set one. */
+export const DEFAULT_PORT = 8000;
+
+const lookupMount = (deploymentName: string) =>
+  Effect.gen(function* () {
+    const { mountId } = yield* mount.mountGetOrCreate({
+      deploymentName,
+      namespace: "DEPLOYMENT_NAMESPACE_GLOBAL",
+      objectCreationType: "OBJECT_CREATION_TYPE_UNSPECIFIED",
+    });
+    if (!mountId) {
+      return yield* new ModalDeployUnexpectedResponse({
+        message: `Modal returned no id for mount ${deploymentName}`,
+      });
+    }
+    return mountId;
+  });
+
+/** The mount holding Modal's Python client, which runs the container entrypoint. */
+export const clientMount = /*@__PURE__*/ lookupMount(`modal-client-mount-${MODAL_CLIENT_VERSION}`);
+
+/**
+ * The image builder version builds use: the resource's pin, else the
+ * workspace's setting.
+ */
+const builderVersionOf = Effect.fn(function* (pinned: string | undefined) {
+  if (pinned !== undefined) return pinned;
+  const settings = yield* workspace.workspaceSettings({});
+  return settings.imageBuilderVersion ?? "2025.06";
+});
+
+/**
+ * Upload {@link ENTRYPOINT_SOURCE} as a mount owned by the app. Modal stores
+ * files by content hash, so redeploys reuse it.
+ */
+export const entrypointMount = Effect.fn(function* (appId: string) {
+  const bytes = new TextEncoder().encode(ENTRYPOINT_SOURCE);
+  const hash = yield* sha256(bytes);
+  const data = yield* Effect.sync(() => Buffer.from(bytes).toString("base64"));
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const { exists } = yield* mount.mountPutFile({ sha256Hex: hash, data });
+    if (exists) break;
+  }
+  const { mountId } = yield* mount.mountGetOrCreate({
+    objectCreationType: "OBJECT_CREATION_TYPE_ANONYMOUS_OWNED_BY_APP",
+    appId,
+    files: [
+      { filename: ENTRYPOINT_PATH, sha256Hex: hash, size: String(bytes.length), mode: 0o100644 },
+    ],
+  });
+  if (!mountId) {
+    return yield* new ModalDeployUnexpectedResponse({
+      message: "Modal returned no id for the entrypoint mount",
+    });
+  }
+  return mountId;
+});
+
+/** What a runtime's image is built from. */
+export interface RuntimeImageInput {
+  readonly main: string;
+  readonly image?: string;
+  readonly commands?: ReadonlyArray<string>;
+  readonly handler?: string;
+  readonly build?: Bundle.BundleConfig;
+  readonly isExternal?: boolean;
+  readonly python?: string | false;
+  readonly builderVersion?: string;
+  readonly gpu?: string;
+}
+
+/**
+ * Plan a runtime's image with the shared BuildPlan: the bundled program on
+ * its base image, without the image's `ENTRYPOINT`/`CMD` (Modal starts the
+ * container with its own Python entrypoint, which then runs the program).
+ */
+export const planRuntimeImage = Effect.fn(function* (
+  target: string,
+  input: RuntimeImageInput,
+  port: number,
+  bootstrap: ((importPath: string) => string) | undefined,
+  capabilities: ReadonlyArray<MountCapability> = [],
+) {
+  yield* checkModalMounts(target, capabilities);
+  const plan = yield* BuildPlan.plan(
+    { main: input.main, image: input.image, handler: input.handler, build: input.build },
+    {
+      capabilities: { ...MODAL_CAPABILITIES, target },
+      port,
+      bootstrap,
+      install: mountInstallLines(capabilities),
+    },
+  );
+  const extra = yield* checkCommands(input.commands ?? []);
+  const lowered = yield* lowerPlan(plan, extra);
+  const command = [...(BuildPlan.startCommand(plan) ?? [])];
+  // Lines after `FROM`, minus the start instruction, run on top of the Python layer.
+  const commands = lowered.commands
+    .slice(1)
+    .filter((line) => !/^\s*(ENTRYPOINT|CMD)\b/i.test(line));
+  const python = input.python === undefined ? DEFAULT_PYTHON : input.python;
+  const hash = yield* sha256Object({
+    plan: plan.hash,
+    extra,
+    python,
+    builder: input.builderVersion,
+    gpu: input.gpu,
+  });
+  return {
+    plan,
+    command,
+    hash,
+    warnings: plan.warnings,
+    spec: { ...lowered, commands: [...commands, "ENTRYPOINT []"] } satisfies ImageBuildSpec,
+    python,
+  };
+});
+
+/**
+ * Build a runtime's image: the base, a layer adding standalone Python
+ * (unless `python: false`), then the program.
+ */
+export const buildRuntimeImage = Effect.fn(function* (
+  appId: string,
+  planned: {
+    readonly plan: BuildPlan.BuildPlan;
+    readonly spec: ImageBuildSpec;
+    readonly python: string | false;
+  },
+  options: {
+    readonly builderVersion?: string;
+    readonly gpu?: string;
+    readonly note?: (message: string) => Effect.Effect<void>;
+  },
+) {
+  const builderVersion = yield* builderVersionOf(options.builderVersion);
+  const buildOps = yield* ImageBuildOps;
+  let baseImageId: string | undefined;
+  if (planned.python !== false) {
+    const table =
+      builderVersion >= "2026.10" || builderVersion === "PREVIEW"
+        ? PYTHON_STANDALONE["2026.10"]
+        : PYTHON_STANDALONE["2025.06"];
+    const release = table[planned.python];
+    if (release === undefined) {
+      return yield* new ModalDeployUnexpectedResponse({
+        message: `Python ${planned.python} isn't available for image builder ${builderVersion}; use one of ${Object.keys(table).join(", ")}`,
+      });
+    }
+    const contextMountId = yield* lookupMount(
+      `python-build-standalone.${release[0]}.${release[1]}-gnu`,
+    );
+    baseImageId = yield* buildImage(
+      buildOps,
+      appId,
+      {
+        dockerTag: planned.plan.base,
+        commands: [
+          "COPY /python/. /usr/local",
+          "ENV TERMINFO_DIRS=/etc/terminfo:/lib/terminfo:/usr/share/terminfo:/usr/lib/terminfo",
+        ],
+        contextMountId,
+        registry: undefined,
+        builderVersion,
+      },
+      { note: options.note },
+    );
+  }
+  return yield* buildImage(
+    buildOps,
+    appId,
+    {
+      ...planned.spec,
+      ...(baseImageId !== undefined ? { baseImageId } : { dockerTag: planned.plan.base }),
+      gpu: options.gpu,
+      builderVersion,
+    },
+    { note: options.note },
+  );
+});
+
+/** Serializes publishes per App: each publish replaces the App's whole function map. */
+const appLocks = /*@__PURE__*/ new Map<string, Semaphore.Semaphore>();
+const lockFor = (appId: string) => {
+  let lock = appLocks.get(appId);
+  if (lock === undefined) {
+    lock = Semaphore.makeUnsafe(1);
+    appLocks.set(appId, lock);
+  }
+  return lock;
+};
+
+/**
+ * Publish the App with `tag` pointing at `created` (or removed, when
+ * `created` is `undefined`), keeping every other function and class the
+ * App serves. Modal deploys an App as a whole, so a publish carries the full
+ * map read back from the App's current layout.
+ *
+ * A class function (one with a `classId`) is published as Modal's clients
+ * publish `@app.cls`: its service function under `<tag>.*` and its class
+ * under `<tag>`, where its containers look the class up.
+ */
+/** The service function name of the class `tag`, as Modal's clients name it. */
+export const classTag = (tag: string) => `${tag}.*`;
+
+export const publishFunction = (
+  target: { readonly appId: string; readonly appName: string | undefined },
+  tag: string,
+  created:
+    | {
+        readonly functionId: string;
+        readonly definitionId: string | undefined;
+        readonly classId?: string | undefined;
+      }
+    | undefined,
+) =>
+  Semaphore.withPermits(
+    lockFor(target.appId),
+    1,
+  )(
+    Effect.gen(function* () {
+      const { appLayout } = yield* app.appGetLayout({ appId: target.appId });
+      const functionIds: Record<string, string> = {};
+      for (const [key, value] of Object.entries(appLayout?.functionIds ?? {})) {
+        if (value !== undefined && key !== tag && key !== classTag(tag)) functionIds[key] = value;
+      }
+      if (created !== undefined) {
+        functionIds[created.classId ? classTag(tag) : tag] = created.functionId;
+      }
+      const classIds: Record<string, string> = {};
+      for (const [key, value] of Object.entries(appLayout?.classIds ?? {})) {
+        if (value !== undefined && key !== tag) classIds[key] = value;
+      }
+      if (created?.classId) classIds[tag] = created.classId;
+      const published = new Set(Object.values(functionIds));
+      const definitionIds: Record<string, string> = {};
+      for (const object of appLayout?.objects ?? []) {
+        const definitionId = object.functionHandleMetadata?.definitionId;
+        if (object.objectId && definitionId && published.has(object.objectId)) {
+          definitionIds[object.objectId] = definitionId;
+        }
+      }
+      if (created?.definitionId) definitionIds[created.functionId] = created.definitionId;
+      return yield* app.publishApp({
+        appId: target.appId,
+        name: target.appName,
+        appState: "APP_STATE_DEPLOYED",
+        functionIds,
+        classIds,
+        definitionIds,
+      });
+    }),
+  );

package/src/internal/Entrypoint.ts

@@ -0,0 +1,198 @@
+/**
+ * The Python module a `Modal.Function` or `Modal.Server` container imports.
+ *
+ * Modal boots every Function container with its Python entrypoint, which
+ * imports the function's module and looks the function up by name. This
+ * module is that function: it starts the bundled program (`ALCHEMY_COMMAND`,
+ * from the function's env secret) once per container and hands it work as
+ * HTTP on `PORT`:
+ *
+ * - `Rpc` (a class function) has one method per RPC method of the program
+ *   (`ALCHEMY_MODAL_RPC_METHODS`, from the function's env secret); a call is
+ *   sent to the program's `POST /__rpc__/<method>` with the positional
+ *   arguments as a JSON array and the caller's key (the
+ *   `__alchemy_rpc_key__` keyword argument) as `x-alchemy-rpc-key`, and
+ *   returns the JSON result (a value, or an
+ *   error envelope the caller fails with). A streamed result is read to its
+ *   end and returned as its list of values;
+ * - `call` and `schedule` forward each input as `POST /__modal/call` or
+ *   `POST /__modal/schedule` with a JSON body `{ "args": [...], "kwargs":
+ *   {...} }`, and return the JSON response (an async program's calls, and
+ *   schedule ticks);
+ * - `web` (a `WEBHOOK_TYPE_WEB_SERVER` function) starts the program, then
+ *   Modal proxies its `*.modal.run` URL to `PORT`;
+ * - `Server` (`is_server`) starts the program in `@modal.enter`, then Modal
+ *   routes the Server's URL to `PORT`.
+ *
+ * It's uploaded as a Mount (`/root/alchemy_modal.py`); the module name and
+ * its function names are part of every function definition, so changing
+ * them redeploys every function.
+ */
+export const ENTRYPOINT_MODULE = "alchemy_modal";
+
+export const ENTRYPOINT_PATH = `/root/${ENTRYPOINT_MODULE}.py`;
+
+/** Function implementations in {@link ENTRYPOINT_SOURCE}. */
+export const ENTRYPOINT = {
+  call: "call",
+  schedule: "schedule",
+  web: "web",
+  server: "Server",
+  rpc: "Rpc",
+} as const;
+
+/** Env var listing a program's RPC methods (a JSON array), set at plan. */
+export const RPC_METHODS_ENV = "ALCHEMY_MODAL_RPC_METHODS";
+
+/**
+ * Env var that turns on the program's `/__rpc__/*` routes. Set only where
+ * Modal authenticates every request: a class function's calls and a Server
+ * behind proxy auth. A public web endpoint never serves RPC.
+ */
+export const RPC_SERVE_ENV = "ALCHEMY_MODAL_SERVE_RPC";
+
+/** A streamed RPC result, as {@link ENTRYPOINT_SOURCE} returns it: its values in order. */
+export const RPC_STREAM_KEY = "~alchemy/modal/rpc-stream";
+
+export const ENTRYPOINT_SOURCE = `"""Alchemy's entrypoint for a JavaScript program on Modal (generated, do not edit)."""
+
+import base64
+import http.client
+import json
+import os
+import socket
+import subprocess
+import threading
+import time
+
+import modal
+
+_PORT = int(os.environ.get("PORT", "8000"))
+_lock = threading.Lock()
+_process = None
+
+
+def _start():
+    global _process
+    with _lock:
+        if _process is None or _process.poll() is not None:
+            _process = subprocess.Popen(json.loads(os.environ["ALCHEMY_COMMAND"]))
+        return _process
+
+
+def _wait_until_listening(process, timeout=600.0):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            raise RuntimeError(f"The program exited with code {process.returncode} before listening on port {_PORT}")
+        try:
+            socket.create_connection(("127.0.0.1", _PORT), timeout=1).close()
+            return
+        except OSError:
+            time.sleep(0.05)
+    raise TimeoutError(f"The program didn't listen on port {_PORT} within {timeout:.0f} seconds")
+
+
+def _json_default(value):
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return base64.b64encode(bytes(value)).decode("ascii")
+    raise TypeError(f"{type(value).__name__} isn't JSON-serializable")
+
+
+def _forward(path, args, kwargs):
+    _wait_until_listening(_start())
+    body = json.dumps({"args": list(args), "kwargs": kwargs}, default=_json_default).encode()
+    headers = {"content-type": "application/json"}
+    try:
+        call_id = modal.current_function_call_id()
+        if call_id:
+            headers["x-modal-function-call-id"] = call_id
+    except Exception:
+        pass
+    connection = http.client.HTTPConnection("127.0.0.1", _PORT)
+    try:
+        connection.request("POST", path, body=body, headers=headers)
+        response = connection.getresponse()
+        data = response.read()
+    finally:
+        connection.close()
+    if response.status >= 400:
+        raise RuntimeError(f"{path} returned {response.status}: {data.decode(errors='replace')}")
+    if not data:
+        return None
+    if response.getheader("content-type", "").startswith("application/json"):
+        return json.loads(data)
+    return data.decode(errors="replace")
+
+
+def _post(path, body, headers=None):
+    _wait_until_listening(_start())
+    connection = http.client.HTTPConnection("127.0.0.1", _PORT)
+    try:
+        connection.request("POST", path, body=body, headers={"content-type": "application/json", **(headers or {})})
+        response = connection.getresponse()
+        return response, response.read()
+    finally:
+        connection.close()
+
+
+def _rpc(name):
+    def method(self, *args, **kwargs):
+        key = kwargs.pop("__alchemy_rpc_key__", None)
+        if kwargs:
+            raise TypeError(f"RPC method {name} takes positional arguments only")
+        body = json.dumps(list(args), default=_json_default).encode()
+        headers = {"x-alchemy-rpc-key": key} if isinstance(key, str) else {}
+        response, data = _post("/__rpc__/" + name, body, headers)
+        if response.status >= 400:
+            raise RuntimeError(f"RPC method {name} returned {response.status}: {data.decode(errors='replace')}")
+        if response.getheader("x-alchemy-rpc-stream") is not None:
+            lines = [json.loads(line) for line in data.decode().splitlines() if line]
+            return {"~alchemy/modal/rpc-stream": lines}
+        return json.loads(data) if data else None
+
+    method.__name__ = name
+    return modal.method()(method)
+
+
+def _rpc_enter(self):
+    _wait_until_listening(_start())
+
+
+Rpc = type(
+    "Rpc",
+    (),
+    {
+        "start": modal.enter()(_rpc_enter),
+        **{name: _rpc(name) for name in json.loads(os.environ.get("ALCHEMY_MODAL_RPC_METHODS") or "[]")},
+    },
+)
+
+
+def call(*args, **kwargs):
+    return _forward("/__modal/call", args, kwargs)
+
+
+def schedule(*args, **kwargs):
+    return _forward("/__modal/schedule", args, kwargs)
+
+
+def web():
+    _start()
+
+
+class Server:
+    @modal.enter()
+    def start(self):
+        _wait_until_listening(_start())
+
+    @modal.exit()
+    def stop(self):
+        process = _process
+        if process is not None and process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=20)
+            except subprocess.TimeoutExpired:
+                process.kill()
+`;

package/src/internal/Rpc.ts

@@ -0,0 +1,59 @@
+import { safeHttpEffect } from "alchemy/Http";
+import * as Output from "alchemy/Output";
+import { serveRpc } from "alchemy/Rpc";
+import { createHostRuntimeContext, type HostRuntimeContext } from "alchemy/Runtime/Process";
+import * as Effect from "effect/Effect";
+import { RPC_METHODS_ENV, RPC_SERVE_ENV } from "./Entrypoint.ts";
+import { parseCallers, requireRpcCaller, RPC_CALLERS_ENV } from "./RpcAuth.ts";
+
+/** The RPC methods of a program's shape: every function besides `fetch` and `run`. */
+export const rpcMethodsOf = (shape: Record<string, unknown> | undefined) =>
+  Object.fromEntries(
+    Object.entries(shape ?? {}).filter(
+      ([key, value]) => key !== "fetch" && key !== "run" && typeof value === "function",
+    ),
+  );
+
+/** The method names a function's env records (see {@link RPC_METHODS_ENV}). */
+export const rpcMethodNamesOf = (env: Record<string, unknown> | undefined): string[] => {
+  const value = env?.[RPC_METHODS_ENV];
+  if (typeof value !== "string") return [];
+  try {
+    const names = JSON.parse(value) as unknown;
+    return Array.isArray(names) ? names.filter((name) => typeof name === "string") : [];
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * The runtime context of a `Modal.Function` or `Modal.Server` program. At
+ * plan it records the program's RPC methods in its env, so the Function's
+ * definition can name them. At run time it serves them on `/__rpc__/*`
+ * next to `fetch`, but only where the provider set {@link RPC_SERVE_ENV}
+ * (where Modal authenticates every request), and only to callers holding a
+ * key a binding issued (see `RpcAuth.ts`).
+ */
+export const createModalRuntimeContext =
+  (type: string) =>
+  (id: string): HostRuntimeContext => {
+    const base = createHostRuntimeContext(type)(id);
+    const serveBase = base.serve;
+    const serve: HostRuntimeContext["serve"] = (handler, options) =>
+      Effect.gen(function* () {
+        const methods = rpcMethodsOf(options?.shape);
+        const names = Object.keys(methods).sort();
+        if (!globalThis.__ALCHEMY_RUNTIME__ && names.length > 0) {
+          yield* base.set(RPC_METHODS_ENV, Output.literal(names));
+        }
+        const enabled = (yield* base.get<unknown>(RPC_SERVE_ENV)) !== undefined;
+        if (!enabled || names.length === 0) return yield* serveBase(handler, options);
+        const fallback = safeHttpEffect(handler);
+        const callers = parseCallers(yield* base.get<unknown>(RPC_CALLERS_ENV));
+        return yield* serveBase(
+          requireRpcCaller(callers, serveRpc(methods, fallback), fallback),
+          options,
+        );
+      }) as Effect.Effect<void, never, any>;
+    return Object.assign(base, { serve });
+  };

package/src/internal/RpcAuth.ts

@@ -0,0 +1,132 @@
+import * as Binding from "alchemy/Binding";
+import * as Output from "alchemy/Output";
+import { Random } from "alchemy/Random";
+import { rpcMethodOf } from "alchemy/Rpc";
+import { CurrentRuntimeContext, sanitizeKey } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import { HttpServerRequest } from "effect/http/HttpServerRequest";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import * as Redacted from "effect/Redacted";
+
+/*
+ * Who may call a program's RPC methods. Every binding that calls them
+ * (`Modal.InvokeFunction`, `Modal.FetchServer`) gets its own random key: the
+ * caller keeps the key, the target keeps only its SHA-256, and each RPC call
+ * carries the key. A key opens one target for one caller, so a target can't
+ * replay what it receives to another target. Modal's own access control
+ * (proxy auth, environment roles) still applies underneath.
+ */
+
+/** Env var on the target: the SHA-256 (hex) of each caller's key, as a JSON array. */
+export const RPC_CALLERS_ENV = "ALCHEMY_MODAL_RPC_CALLERS";
+
+/** Request header a Server's RPC call carries its key in. */
+export const RPC_KEY_HEADER = "x-alchemy-rpc-key";
+
+/** Keyword argument a Function's RPC call carries its key in (the entrypoint forwards it as {@link RPC_KEY_HEADER}). */
+export const RPC_KEY_KWARG = "__alchemy_rpc_key__";
+
+/** Env var on the caller holding its key for the target `targetId`. */
+export const rpcKeyEnv = (targetId: string) => sanitizeKey(`ALCHEMY_MODAL_RPC_KEY_${targetId}`);
+
+/** What a caller's binding attaches to the target. */
+export interface RpcCallerBinding {
+  /** SHA-256 (hex) of the caller's key. */
+  readonly rpcCallers?: ReadonlyArray<string>;
+}
+
+/** SHA-256 of `text`, as hex. */
+export const sha256Hex = (text: string) =>
+  Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))).pipe(
+    Effect.map((digest) =>
+      Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(""),
+    ),
+  );
+
+/** The caller key hashes a target's bindings recorded, sorted. */
+export const rpcCallersOf = (
+  bindings: ReadonlyArray<{ readonly data: RpcCallerBinding }>,
+): string[] => [...new Set(bindings.flatMap((binding) => binding.data.rpcCallers ?? []))].sort();
+
+type BindTarget = {
+  readonly LogicalId: string;
+  bind: (...args: unknown[]) => (data: RpcCallerBinding) => Effect.Effect<void>;
+};
+
+/**
+ * The caller half of an RPC binding. Yield it while the binding's layer is
+ * built; call the result with the target in the binding. At deploy it mints
+ * the key for this caller and target (`<host><target>RpcKey`), binds it into
+ * the host's env, and records its hash on the target. At run time it reads
+ * the key back, or `undefined` when the caller has none (a script).
+ */
+export const RpcCaller = Effect.gen(function* () {
+  // Deploy only: a host bundle never creates the key.
+  const Key = globalThis.__ALCHEMY_RUNTIME__ ? undefined : yield* Random;
+  return Effect.fn(function* (target: { readonly LogicalId: string }) {
+    // The host binding the target, read per call: one binding layer serves
+    // every host in the Stack, so a host captured when the layer was built
+    // would be the first one to build it.
+    const runtime = yield* CurrentRuntimeContext;
+    const env = rpcKeyEnv(target.LogicalId);
+    if (!globalThis.__ALCHEMY_RUNTIME__ && Key !== undefined && runtime !== undefined) {
+      const host = yield* Binding.Host;
+      if (host !== undefined) {
+        const key = yield* Key(`${host.LogicalId}${target.LogicalId}RpcKey`, {});
+        yield* runtime.set(env, key.text);
+        yield* (target as unknown as BindTarget).bind`Modal.RpcCaller(${host})`({
+          rpcCallers: [
+            key.text.pipe(
+              Output.mapEffect((text) => text.pipe(Redacted.value, sha256Hex)),
+            ) as unknown as string,
+          ],
+        });
+      }
+    }
+    return Effect.gen(function* () {
+      if (runtime === undefined) return undefined;
+      const value = yield* runtime.get<string | Redacted.Redacted<string>>(env);
+      return value === undefined
+        ? undefined
+        : Redacted.isRedacted(value)
+          ? Redacted.value(value)
+          : value;
+    });
+  });
+});
+
+/**
+ * Serve `rpc` only to callers whose key's hash is in {@link RPC_CALLERS_ENV};
+ * every other request goes to `fallback`. A call without a key, or with one
+ * no binding issued, gets `401`.
+ */
+export const requireRpcCaller = <A, E, R, A2, E2, R2>(
+  callers: ReadonlySet<string>,
+  rpc: Effect.Effect<A, E, R>,
+  fallback: Effect.Effect<A2, E2, R2>,
+) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest;
+    if (rpcMethodOf(request) === undefined) return yield* fallback;
+    const key = request.headers[RPC_KEY_HEADER];
+    if (typeof key !== "string" || key.length === 0 || !callers.has(yield* sha256Hex(key))) {
+      return HttpServerResponse.text("Unauthorized: this caller has no binding to the program", {
+        status: 401,
+      });
+    }
+    return yield* rpc;
+  });
+
+/** The caller key hashes in a target's env (see {@link RPC_CALLERS_ENV}). */
+export const parseCallers = (value: unknown): ReadonlySet<string> => {
+  const list = typeof value === "string" ? safeParse(value) : value;
+  return new Set(Array.isArray(list) ? list.filter((item) => typeof item === "string") : []);
+};
+
+const safeParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};