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

package/lib/InvokeFunction.d.ts

@@ -0,0 +1,186 @@
+import * as Binding from "alchemy/Binding";
+import type { Input } from "alchemy/Input";
+import type { Rpc } from "alchemy/Rpc";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { downloadBlob, uploadBlob } from "./Blob.ts";
+import type { Function } from "./Function.ts";
+import type { FunctionLookupError } from "./FunctionTarget.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+import type { InvokeOps } from "./InvokeFunctionHttp.ts";
+/** A function deployed outside the Stack (`modal deploy`), by name. */
+export interface FunctionRef {
+    /** Name of the deployed App (`modal deploy` / `modal.App("…")`). */
+    readonly app: string;
+    /** Function name in the App (`"embed"`), or `"Class.method"` for a class method. */
+    readonly function: string;
+    /** Environment the App is deployed in. @default the workspace default */
+    readonly environment?: string;
+    /**
+     * Parameters of a parameterized class (`modal.parameter()` fields), for a
+     * `"Class.method"` target. Modal runs one set of containers per value set.
+     */
+    readonly parameters?: Record<string, string | number | boolean | Uint8Array>;
+}
+/** What a function binding targets: a `Modal.Function` of the Stack, or a deployed function by name. */
+export type FunctionTarget = Function | FunctionRef;
+declare const FunctionCallFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Modal.FunctionCallFailed";
+} & Readonly<A>;
+/** The function raised, or Modal failed the call. */
+export declare class FunctionCallFailed extends FunctionCallFailed_base<{
+    readonly status: string;
+    readonly message: string;
+    readonly traceback?: string;
+}> {
+}
+/** Calling a function: looking it up, sending inputs, reading outputs, and the call's own failure. */
+export type InvokeError = FunctionLookupError | OpError<InvokeOps, "map" | "putInputs" | "getOutputs"> | ErrorOf<typeof uploadBlob | typeof downloadBlob> | FunctionCallFailed | FunctionCallTimeout;
+declare const FunctionCallTimeout_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Modal.FunctionCallTimeout";
+} & Readonly<A>;
+/** The call didn't finish within its timeout. */
+export declare class FunctionCallTimeout extends FunctionCallTimeout_base<{
+    readonly functionCallId: string;
+    readonly message: string;
+}> {
+}
+/** Options for one call. */
+export interface CallOptions {
+    /** How long to wait for the result (seconds, or `"10 minutes"`). @default 300 seconds */
+    readonly timeout?: number | string;
+}
+/** Call one function. Arguments and results travel as CBOR. */
+export interface FunctionClient {
+    /** Call the function and wait for its result. */
+    call<A = unknown>(args?: ReadonlyArray<unknown>, kwargs?: Record<string, unknown>, options?: CallOptions): Effect.Effect<A, InvokeError, RuntimeContext>;
+    /**
+     * Call the function once per input, in parallel across containers, and
+     * return the results in input order. Each input is a list of positional
+     * arguments. Fails with the first failed input.
+     */
+    map<A = unknown>(inputs: ReadonlyArray<ReadonlyArray<unknown>>, options?: CallOptions): Effect.Effect<A[], InvokeError, RuntimeContext>;
+    /** Start a call without waiting; read it later with {@link result}. */
+    spawn(args?: ReadonlyArray<unknown>, kwargs?: Record<string, unknown>): Effect.Effect<{
+        readonly functionCallId: string;
+    }, InvokeError, RuntimeContext>;
+    /** The result of a spawned call, waiting up to `timeout`. */
+    result<A = unknown>(call: {
+        readonly functionCallId: string;
+    }, options?: CallOptions): Effect.Effect<A, InvokeError, RuntimeContext>;
+    /** Cancel a spawned call. */
+    cancel(call: {
+        readonly functionCallId: string;
+    }): Effect.Effect<void, FunctionLookupError | OpError<InvokeOps, "cancel">, RuntimeContext>;
+}
+/**
+ * The RPC methods of a `Modal.Function` program: every function it returns
+ * besides `fetch` and `run`, called through Modal with the same arguments
+ * and results.
+ */
+export type FunctionStub<Shape> = Omit<Shape, "fetch" | "run">;
+/**
+ * Call a Modal Function from any runtime: a Worker, a Lambda, a Durable
+ * Object, another Modal Function. Bind a `Modal.Function` of the Stack, or
+ * a function deployed with `modal deploy` by name.
+ *
+ * A `Modal.Function` program's RPC methods come back as a typed client:
+ * each call goes through Modal (queued, retried and autoscaled like any
+ * Modal call) to the method of that name. Arguments and results are JSON
+ * values, and a typed failure reaches the caller by its `_tag`. A method
+ * that returns a `Stream` arrives whole, once the call finishes. The
+ * binding gives the host its own key for the function, which every call
+ * carries: the program answers only callers bound to it.
+ *
+ * A Python function, or an async program, gets a {@link FunctionClient}
+ * instead: `call`, `map` and `spawn` with CBOR arguments (Modal's
+ * cross-language format). Payloads over 2 MiB go through Modal's blob store.
+ *
+ * ### Call a function
+ * **Example:** RPC methods of a `Modal.Function`
+ * ```typescript
+ * // src/Embed.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import { Inference } from "./Inference.ts";
+ *
+ * export default class Embed extends Modal.Function<Embed>()(
+ *   "Embed",
+ *   { main: import.meta.url, app: Inference },
+ *   Effect.gen(function* () {
+ *     return {
+ *       embed: Effect.fn(function* (text: string) {
+ *         return { tokens: text.split(/\s+/).length };
+ *       }),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * **Example:** Call it 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 Embed from "./Embed.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, compatibility: { flags: ["nodejs_compat"] } },
+ *   Effect.gen(function* () {
+ *     const embed = yield* Modal.InvokeFunction(Embed);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const { tokens } = yield* embed.embed("hello world");
+ *         return yield* HttpServerResponse.json({ tokens });
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.InvokeFunctionHttp)),
+ * ) {}
+ * ```
+ *
+ * **Example:** A Python function deployed with `modal deploy`
+ * ```typescript
+ * const embed = yield* Modal.InvokeFunction({ app: "inference", function: "embed" });
+ * const vector = yield* embed.call<number[]>(["hello world"]);
+ * ```
+ *
+ * **Example:** A method of a parameterized Python class
+ * ```typescript
+ * const model = yield* Modal.InvokeFunction({
+ *   app: "inference",
+ *   function: "Model.generate",
+ *   parameters: { size: "7b" },
+ * });
+ * const text = yield* model.call<string>(["hello"]);
+ * ```
+ *
+ * ### Fan out
+ * **Example:** One call per input, in parallel
+ * ```typescript
+ * const results = yield* embed.map<{ tokens: number }>([["a"], ["b"], ["c"]]);
+ * ```
+ *
+ * ### Fire and forget
+ * **Example:** Spawn, then read the result later
+ * ```typescript
+ * const job = yield* train.spawn([], { epochs: 3 });
+ * const metrics = yield* train.result(job, { timeout: "30 minutes" });
+ * ```
+ *
+ * @binding
+ * @product Function
+ */
+export interface InvokeFunction extends Binding.Service<InvokeFunction, "Modal.InvokeFunction", (target: FunctionTarget) => Effect.Effect<FunctionClient>> {
+}
+/** InvokeFunction's call signatures, typed from the target's program. */
+export interface InvokeFunctionCall {
+    /** A `Modal.Function` of the Stack whose program has RPC methods: its typed client. */
+    <Shape, Req = never>(target: (Function & Rpc<Shape>) | Effect.Effect<Function & Rpc<Shape>, never, Req>): Effect.Effect<FunctionStub<Shape>, never, InvokeFunction | Req>;
+    /** A deployed function by name, or an async program: `call`, `map` and `spawn`. */
+    <Req = never>(target: Input<FunctionTarget> | Effect.Effect<FunctionTarget, never, Req>): Effect.Effect<FunctionClient, never, InvokeFunction | Req>;
+}
+export declare const InvokeFunction: InvokeFunctionCall & InvokeFunction;
+export {};
+//# sourceMappingURL=InvokeFunction.d.ts.map

package/lib/InvokeFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvokeFunction.d.ts","sources":["../src/InvokeFunction.ts"],"names":[],"mappings":"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"}

package/lib/InvokeFunction.js

@@ -0,0 +1,10 @@
+import * as Binding from "alchemy/Binding";
+import * as Data from "effect/Data";
+/** The function raised, or Modal failed the call. */
+export class FunctionCallFailed extends Data.TaggedError("Modal.FunctionCallFailed") {
+}
+/** The call didn't finish within its timeout. */
+export class FunctionCallTimeout extends Data.TaggedError("Modal.FunctionCallTimeout") {
+}
+export const InvokeFunction = Binding.Service("Modal.InvokeFunction");
+//# sourceMappingURL=InvokeFunction.js.map

package/lib/InvokeFunction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvokeFunction.js","sources":["../src/InvokeFunction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAI3C,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AA0BpC,qDAAqD;AACrD,MAAM,OAAO,kBAAmB,SAAQ,IAAI,CAAC,WAAW,CAAC,0BAA0B,CAIjF;CAAG;AAUL,iDAAiD;AACjD,MAAM,OAAO,mBAAoB,SAAQ,IAAI,CAAC,WAAW,CAAC,2BAA2B,CAGnF;CAAG;AA+JL,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAC3C,sBAAsB,CAC2B,CAAC"}

package/lib/InvokeFunctionHttp.d.ts

@@ -0,0 +1,39 @@
+import * as functions from "@distilled.cloud/modal/functions";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { type ResolvedFunction } from "./FunctionTarget.ts";
+import { InvokeFunction, type FunctionClient } from "./InvokeFunction.ts";
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+declare const InvokeOps: Effect.Effect<{
+    readonly map: (input: functions.FunctionMapRequest) => Effect.Effect<functions.FunctionMapResponse, functions.FunctionMapError, never>;
+    readonly putInputs: (input: functions.FunctionPutInputsRequest) => Effect.Effect<functions.FunctionPutInputsResponse, functions.ModalOpError, never>;
+    readonly getOutputs: (input: functions.GetFunctionOutputsRequest) => Effect.Effect<functions.GetFunctionOutputsResponse, functions.GetFunctionOutputsError, never>;
+    readonly cancel: (input: functions.CancelFunctionCallRequest) => Effect.Effect<functions.CancelFunctionCallResponse, functions.CancelFunctionCallError, never>;
+    readonly blobs: {
+        readonly create: (input: import("@distilled.cloud/modal/blob").CreateBlobRequest) => Effect.Effect<import("@distilled.cloud/modal/blob").CreateBlobResponse, functions.ModalOpError, never>;
+        readonly get: (input: import("@distilled.cloud/modal/blob").GetBlobRequest) => Effect.Effect<import("@distilled.cloud/modal/blob").GetBlobResponse, functions.ModalOpError, never>;
+        readonly http: import("effect/http/HttpClient").HttpClient;
+    };
+}, never, import("./internal.ts").OperationServices>;
+export type InvokeOps = Effect.Success<typeof InvokeOps>;
+/** A client for a resolved function. */
+export declare const makeFunctionClient: (resolved: ResolvedFunction, ops: InvokeOps) => FunctionClient;
+/**
+ * The typed client of a `Modal.Function` program's RPC methods. Each method
+ * is a call to the function's method of that name; its result is the
+ * program's JSON answer, a failure envelope the call fails with, or a
+ * stream's values. A Function without methods (an async program) keeps
+ * the {@link FunctionClient} operations.
+ */
+export declare const makeRpcClient: (resolved: ResolvedFunction, ops: InvokeOps, methods: Effect.Effect<ReadonlyArray<string> | undefined>, key: Effect.Effect<string | undefined>) => Record<string, unknown>;
+/**
+ * {@link InvokeFunction} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the function's environment.
+ *
+ * @layer
+ * @product Function
+ * @provides Modal.InvokeFunction
+ */
+export declare const InvokeFunctionHttp: Layer.Layer<InvokeFunction, never, never>;
+export {};
+//# sourceMappingURL=InvokeFunctionHttp.d.ts.map

package/lib/InvokeFunctionHttp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvokeFunctionHttp.d.ts","sources":["../src/InvokeFunctionHttp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,kCAAkC,CAAC;AAO9D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,EAAsC,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAIhG,OAAO,EAGL,cAAc,EAEd,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,oFAAoF;AACpF,QAAA,MAAM,SAAS;;;;;;;;;;oDAMb,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,SAAS,CAAC,CAAC;AA6DzD,wCAAwC;AACxC,eAAO,MAAM,kBAAkB,aAAc,gBAAgB,OAAO,SAAS,KAAG,cAgH/E,CAAC;AAQF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,aACd,gBAAgB,OACrB,SAAS,WACL,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,OACpD,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,KACrC,MAAM,CAAC,MAAM,EAAE,OAAO,CAsDxB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,2CAuB9B,CAAC"}

package/lib/InvokeFunctionHttp.js

@@ -0,0 +1,210 @@
+import * as functions from "@distilled.cloud/modal/functions";
+import { asEffectOrStream, decodeRpcResponseStream, decodeRpcResult, RpcCallError, } from "alchemy/Rpc";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { BlobOps, downloadBlob, MAX_INLINE_BYTES, uploadBlob } from "./Blob.js";
+import { decodeCbor, encodeCbor } from "./Cbor.js";
+import { isFunctionRef, makeFunctionBinding } from "./FunctionTarget.js";
+import { operations, seconds } from "./internal.js";
+import { RPC_STREAM_KEY } from "./internal/Entrypoint.js";
+import { RPC_KEY_KWARG, RpcCaller } from "./internal/RpcAuth.js";
+import { FunctionCallFailed, FunctionCallTimeout, InvokeFunction, } from "./InvokeFunction.js";
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+const InvokeOps = operations({
+    map: functions.functionMap,
+    putInputs: functions.functionPutInputs,
+    getOutputs: functions.getFunctionOutputs,
+    cancel: functions.cancelFunctionCall,
+    blobs: BlobOps,
+});
+/** One input: CBOR `[args, kwargs]`, inline or (over 2 MiB) as a blob. */
+const encodeInput = Effect.fn(function* (blobs, args, kwargs, method) {
+    const bytes = yield* Effect.try({
+        try: () => encodeCbor([args, kwargs]),
+        catch: (cause) => new FunctionCallFailed({
+            status: "INVALID_ARGUMENTS",
+            message: `Arguments aren't CBOR-encodable: ${String(cause)}`,
+        }),
+    });
+    const payload = bytes.length > MAX_INLINE_BYTES
+        ? { argsBlobId: yield* uploadBlob(blobs, bytes) }
+        : { args: yield* Effect.sync(() => Buffer.from(bytes).toString("base64")) };
+    return {
+        ...payload,
+        dataFormat: "DATA_FORMAT_CBOR",
+        methodName: method,
+    };
+});
+/** The value of a finished output, or its failure. */
+const decodeOutput = Effect.fn(function* (blobs, functionCallId, output) {
+    const result = output.result;
+    if (result?.status !== "GENERIC_STATUS_SUCCESS") {
+        return yield* new FunctionCallFailed({
+            status: result?.status ?? "GENERIC_STATUS_UNSPECIFIED",
+            message: result?.exception || `Function call ${functionCallId} failed`,
+            traceback: result?.traceback,
+        });
+    }
+    const bytes = result.dataBlobId
+        ? yield* downloadBlob(blobs, result.dataBlobId)
+        : result.data
+            ? yield* Effect.sync(() => new Uint8Array(Buffer.from(result.data, "base64")))
+            : undefined;
+    if (bytes === undefined)
+        return null;
+    return yield* Effect.try({
+        try: () => decodeCbor(bytes),
+        catch: (cause) => new FunctionCallFailed({
+            status: "INVALID_RESULT",
+            message: `The result isn't CBOR (return plain values, or set the function's serialization): ${String(cause)}`,
+        }),
+    });
+});
+/** Inputs per `FunctionPutInputs` request. */
+const BATCH = 49;
+/** A client for a resolved function. */
+export const makeFunctionClient = (resolved, ops) => {
+    const { functionId, method } = resolved;
+    /** Collect `count` outputs of a call, by input index. */
+    const collect = Effect.fn(function* (functionCallId, count, timeout) {
+        const budget = seconds(timeout) ?? 300;
+        const rounds = Math.max(1, Math.ceil(budget / 55));
+        const values = new Map();
+        let lastEntryId = "0-0";
+        for (let round = 0; round < rounds && values.size < count; round++) {
+            const response = yield* ops.getOutputs({
+                functionCallId,
+                maxValues: Math.min(1000, count - values.size),
+                timeout: Math.min(55, budget),
+                lastEntryId,
+                // A map's outputs stay until all are read; a single output is popped.
+                clearOnSuccess: count === 1,
+            });
+            if (response.lastEntryId)
+                lastEntryId = response.lastEntryId;
+            for (const output of response.outputs ?? []) {
+                if (!output.result)
+                    continue;
+                values.set(output.idx ?? 0, yield* decodeOutput(ops.blobs, functionCallId, output));
+            }
+        }
+        if (values.size < count) {
+            return yield* new FunctionCallTimeout({
+                functionCallId,
+                message: `Function call ${functionCallId} didn't finish within ${budget} seconds`,
+            });
+        }
+        return Array.from({ length: count }, (_, idx) => values.get(idx));
+    });
+    /**
+     * Start a function call the way Modal's clients do: a unary call sends its
+     * input with `FunctionMap` (or with `FunctionPutInputs` when Modal doesn't
+     * take it there); a map creates the call, then sends every input with
+     * `FunctionPutInputs`.
+     */
+    const start = Effect.fn(function* (inputs, type, invocation) {
+        const id = yield* functionId;
+        const items = yield* Effect.forEach(inputs, ([args, kwargs], idx) => Effect.map(encodeInput(ops.blobs, args, kwargs, method), (input) => ({ idx, input })));
+        const unary = type === "FUNCTION_CALL_TYPE_UNARY";
+        const response = yield* ops.map({
+            functionId: id,
+            functionCallType: type,
+            functionCallInvocationType: invocation,
+            returnExceptions: false,
+            pipelinedInputs: unary ? items : undefined,
+        });
+        const functionCallId = response.functionCallId ?? "";
+        const sent = unary && (response.pipelinedInputs ?? []).length > 0 ? items.length : 0;
+        for (let offset = sent; offset < items.length; offset += BATCH) {
+            yield* ops.putInputs({
+                functionId: id,
+                functionCallId,
+                inputs: items.slice(offset, offset + BATCH),
+            });
+        }
+        return functionCallId;
+    });
+    return {
+        call: (args = [], kwargs = {}, options = {}) => start([[args, kwargs]], "FUNCTION_CALL_TYPE_UNARY", "FUNCTION_CALL_INVOCATION_TYPE_SYNC").pipe(Effect.flatMap((id) => collect(id, 1, options.timeout)), 
+        // CBOR results are untyped; the caller names the shape it expects.
+        Effect.map(([value]) => value)),
+        map: (inputs, options = {}) => inputs.length === 0
+            ? Effect.succeed([])
+            : start(inputs.map((args) => [args, {}]), "FUNCTION_CALL_TYPE_MAP", "FUNCTION_CALL_INVOCATION_TYPE_SYNC").pipe(Effect.flatMap((id) => collect(id, inputs.length, options.timeout)), Effect.map((values) => values)),
+        spawn: (args = [], kwargs = {}) => start([[args, kwargs]], "FUNCTION_CALL_TYPE_UNARY", "FUNCTION_CALL_INVOCATION_TYPE_ASYNC").pipe(Effect.map((functionCallId) => ({ functionCallId }))),
+        result: (call, options = {}) => collect(call.functionCallId, 1, options.timeout).pipe(Effect.map(([value]) => value)),
+        cancel: (call) => ops.cancel({ functionCallId: call.functionCallId }).pipe(Effect.catchTag("FunctionCallNotFound", () => Effect.void), Effect.asVoid),
+    };
+};
+/** Whether a call's result is a streamed RPC result (see `RPC_STREAM_KEY`). */
+const isStreamResult = (value) => typeof value === "object" &&
+    value !== null &&
+    Array.isArray(value[RPC_STREAM_KEY]);
+/**
+ * The typed client of a `Modal.Function` program's RPC methods. Each method
+ * is a call to the function's method of that name; its result is the
+ * program's JSON answer, a failure envelope the call fails with, or a
+ * stream's values. A Function without methods (an async program) keeps
+ * the {@link FunctionClient} operations.
+ */
+export const makeRpcClient = (resolved, ops, methods, key) => {
+    const client = makeFunctionClient(resolved, ops);
+    const callMethod = (name, args) => key.pipe(Effect.flatMap((value) => makeFunctionClient({ ...resolved, method: name }, ops).call(args, 
+    // The binding's key: the program serves only callers it issued keys to.
+    value === undefined ? {} : { [RPC_KEY_KWARG]: value })), Effect.flatMap((value) => isStreamResult(value)
+        ? // The stream's values, re-encoded as the NDJSON the RPC codec
+            // decodes (byte chunks and a trailing failure marker included).
+            Effect.succeed(Stream.fromIterable(value[RPC_STREAM_KEY]).pipe(Stream.map((item) => `${JSON.stringify(item)}\n`), Stream.encodeText, decodeRpcResponseStream))
+        : decodeRpcResult(value)));
+    return new Proxy({}, {
+        get: (_, prop) => {
+            // Never thenable, and no symbol members.
+            if (typeof prop !== "string" || prop === "then")
+                return undefined;
+            const call = (args) => Effect.gen(function* () {
+                const names = (yield* methods) ?? [];
+                if (names.includes(prop))
+                    return yield* callMethod(prop, args);
+                const operation = client[prop];
+                if (typeof operation === "function") {
+                    return yield* operation(...args);
+                }
+                return yield* new RpcCallError({
+                    method: prop,
+                    cause: `The function has no RPC method ${prop}`,
+                });
+            });
+            return (...args) => asEffectOrStream(
+            // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the stub's declared method types carry `RuntimeContext`, which the caller's runtime provides
+            call(args));
+        },
+    });
+};
+/**
+ * {@link InvokeFunction} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the function's environment.
+ *
+ * @layer
+ * @product Function
+ * @provides Modal.InvokeFunction
+ */
+export const InvokeFunctionHttp = Layer.effect(InvokeFunction, Effect.gen(function* () {
+    const caller = yield* RpcCaller;
+    return yield* makeFunctionBinding({
+        tag: "Modal.InvokeFunction",
+        operations: InvokeOps,
+        role: "contributor",
+        make: Effect.fn(function* (resolved, ops, target) {
+            if (isFunctionRef(target))
+                return makeFunctionClient(resolved, ops);
+            // This host's key for the Function's RPC methods (minted at deploy).
+            const key = yield* caller(target);
+            // The program's methods, recorded at deploy (an attribute of the Function).
+            const methods = yield* target.methods;
+            // Typed by `InvokeFunction`'s call signatures from the target's program.
+            return makeRpcClient(resolved, ops, methods, key);
+        }),
+    });
+}));
+//# sourceMappingURL=InvokeFunctionHttp.js.map

package/lib/InvokeFunctionHttp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvokeFunctionHttp.js","sources":["../src/InvokeFunctionHttp.ts"],"names":[],"mappings":"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"}

package/lib/ModalBindings.d.ts

@@ -0,0 +1,138 @@
+import type { Input } from "alchemy/Input";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Stream from "effect/Stream";
+import type { OperationServices } from "./internal.ts";
+/**
+ * How a Modal binding reaches Modal from its host.
+ *
+ * Modal grants access per environment, as a `viewer` or a `contributor`. So:
+ *
+ * - a Modal Function or Server: nothing is bound. It calls Modal as its own
+ *   container, over the API socket Modal gives every container
+ *   (`fromContainer`), the way Modal's Python client does there. No
+ *   credential is stored. A host with `restrictModalAccess` has no such
+ *   access, so it gets a service user like any other host;
+ * - any other host (a Cloudflare Worker, a Lambda, a Modal Sandbox):
+ *   {@link Bind} creates a scoped `Modal.ServiceUser` for the
+ *   host (`<host>ModalIdentity`), grants it the role each binding asks for
+ *   on the bound resource's environment, and binds its token pair into the
+ *   host's env (`MODAL_TOKEN_ID`, and `MODAL_TOKEN_SECRET` kept `Redacted`);
+ * - no host (a script or a deploy-time Action): nothing is bound, and calls
+ *   use the deployer's credentials.
+ *
+ * Modal's Starter plan has no service users. There, provide
+ * {@link DeployerHostIdentity} to bind the deployer's own token pair into
+ * each host instead: hosts then act with the deployer's workspace-wide
+ * access, not the roles their bindings ask for.
+ *
+ * Import it as a namespace. A binding resolves its operations with
+ * {@link withCredentials} and gets its `bind` from {@link Bind} when its layer
+ * is built, then binds behind its own `__ALCHEMY_RUNTIME__` guard:
+ *
+ * ```ts
+ * Effect.gen(function* () {
+ *   const put = yield* ModalBindings.withCredentials(modalQueue.putQueue);
+ *   const bind = yield* ModalBindings.Bind;
+ *   return Effect.fn(function* (queue: Queue) {
+ *     if (!globalThis.__ALCHEMY_RUNTIME__) {
+ *       yield* bind`Modal.WriteQueue(${queue})`({
+ *         roles: [{ environment: queue.environment, role: "contributor" }],
+ *       });
+ *     }
+ *     const queueId = yield* queue.queueId;
+ *     return (value) => put({ queueId: yield* queueId, values: [...] });
+ *   });
+ * })
+ * ```
+ */
+export declare const TOKEN_ENV: {
+    readonly id: "MODAL_TOKEN_ID";
+    readonly secret: "MODAL_TOKEN_SECRET";
+    readonly serverUrl: "ALCHEMY_MODAL_SERVER_URL";
+};
+/**
+ * The identity {@link Bind} gives a binding's host:
+ *
+ * - `"service-user"`: a scoped `Modal.ServiceUser` per host with only the
+ *   roles its bindings ask for (needs Modal's Team or Enterprise plan);
+ * - `"deployer"`: the deployer's own token pair, with its workspace-wide
+ *   access (for the Starter plan, which has no service users).
+ *
+ * Set it with {@link DeployerHostIdentity}.
+ */
+export declare const HostIdentity: Context.Reference<"deployer" | "service-user">;
+/**
+ * Bind the deployer's own Modal token into binding hosts instead of a
+ * scoped service user per host. Use it on Modal's Starter plan, which has
+ * no service users; hosts then have the deployer's workspace-wide access.
+ *
+ * @example
+ * ```ts
+ * export default Alchemy.Stack(
+ *   "App",
+ *   { providers: Layer.mergeAll(Cloudflare.providers(), Modal.providers(), Modal.DeployerHostIdentity) },
+ *   Effect.gen(function* () { ... }),
+ * );
+ * ```
+ */
+export declare const DeployerHostIdentity: Layer.Layer<never>;
+/** A role a binding needs in one environment. */
+export interface EnvironmentGrant {
+    /** The environment's name; `undefined` is the workspace default. */
+    readonly environment: Input<string | undefined>;
+    readonly role: "viewer" | "contributor";
+}
+/** What a Modal binding attaches to its host. */
+export interface HostBinding {
+    /** Environment roles the host's identity needs. */
+    readonly roles?: ReadonlyArray<EnvironmentGrant>;
+    /** Env vars the binding reads at runtime. */
+    readonly env?: Record<string, unknown>;
+}
+/** The signature {@link Bind} yields. */
+export type BindHost = (label: TemplateStringsArray, ...args: unknown[]) => (data?: HostBinding) => Effect.Effect<void>;
+/**
+ * The `bind` for a binding's layer: yield it while the layer is built, then
+ * call it from the returned function behind a literal
+ * `if (!globalThis.__ALCHEMY_RUNTIME__)` so the bundler drops it. On a host it
+ * grants `data.roles` to the host's service user and binds that user's token
+ * pair (and `data.env`) into the host's env; with no host it does nothing.
+ */
+export declare const Bind: Effect.Effect<BindHost>;
+/**
+ * Resolve a distilled operation (or several, with `Effect.all`) once when
+ * the binding's layer is built: with the token pair {@link Bind} bound into
+ * the host, or the deployer's credentials when there is none.
+ *
+ * @example
+ * ```ts
+ * const ops = yield* ModalBindings.withCredentials(
+ *   operations({ getFile: volume.volumeGetFile2, putFiles: volume.volumePutFiles2 }),
+ * );
+ * ```
+ */
+export declare const withCredentials: <Op>(operation: Effect.Effect<Op, never, OperationServices>) => Effect.Effect<Op>;
+/**
+ * Resolve a task command router operation for one sandbox: the router runs
+ * per task, at a URL with its own JWT (from `sandboxGetCommandRouterAccess`).
+ * The router credentials are applied on every call, because a resolved
+ * operation runs with its caller's `Credentials` (the control plane's) over
+ * the ones it captured. `withTaskCommandRouter` also supplies the HTTP/2
+ * client the router requires.
+ */
+export declare const withRouter: <I, O, E>(operation: (input: I) => Effect.Effect<O, E, OperationServices>) => (access: RouterAccess) => Effect.Effect<(input: I) => Effect.Effect<O, E>>;
+/**
+ * {@link withRouter} for a server-streaming router operation: its `.stream`,
+ * which emits each message as the router sends it.
+ */
+export declare const streamRouter: <I, A, E>(operation: {
+    readonly stream: (input: I) => Stream.Stream<A, E, OperationServices>;
+}) => (access: RouterAccess) => Effect.Effect<(input: I) => Stream.Stream<A, E>>;
+/** A task's command router: its URL and JWT, from `sandboxGetCommandRouterAccess`. */
+export interface RouterAccess {
+    readonly url: string;
+    readonly jwt: string;
+}
+//# sourceMappingURL=ModalBindings.d.ts.map

package/lib/ModalBindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModalBindings.d.ts","sources":["../src/ModalBindings.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,SAAS;aACpB,EAAE,EAAE,gBAAgB;aACpB,MAAM,EAAE,oBAAoB;aAG5B,SAAS,EAAE,0BAA0B;CAC7B,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gDAEvB,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAA2C,CAAC;AAEhG,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;CACzC;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACjD,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,yCAAyC;AACzC,MAAM,MAAM,QAAQ,GAAG,CACrB,KAAK,EAAE,oBAAoB,EAC3B,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,CAAC,IAAI,CAAC,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAYjD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CA2CvC,CAAC;AAuEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,EAAE,EAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,iBAAiB,CAAC,KACnD,MAAM,CAAC,MAAM,CAAC,EAAE,CAKnB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACpB,CAAC,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,cAChE,YAAY,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CACa,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,EAAE,CAAC,EAAE,CAAC,aAAa;IAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAA;CAAE,cACrF,YAAY,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CACsB,CAAC;AAEhG,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB"}