The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { Rpc } from "@cloudflare/workers-types"; |
| 2 | import type { Input } from "alchemy/Input"; |
| 3 | import { isResourceOfType } from "alchemy/Resource"; |
| 4 | import type { Worker } from "./Worker.ts"; |
| 5 | import { WorkerTypeId } from "./WorkerRuntime.ts"; |
| 6 | |
| 7 | type WorkerEntrypointTypeId = "Cloudflare.WorkerEntrypoint"; |
| 8 | const WorkerEntrypointTypeId: WorkerEntrypointTypeId = "Cloudflare.WorkerEntrypoint"; |
| 9 | |
| 10 | export interface WorkerEntrypointOptions { |
| 11 | /** |
| 12 | * Named entrypoint on the target Worker — the exported |
| 13 | * `WorkerEntrypoint` class the binding calls. Omitted → the default |
| 14 | * entrypoint (equivalent to binding the Worker directly, but with |
| 15 | * {@link props} support). |
| 16 | */ |
| 17 | entrypoint?: string; |
| 18 | /** |
| 19 | * Properties exposed to the target entrypoint via workerd's |
| 20 | * `ctx.props`. Values accept `Output` references and resolve at deploy |
| 21 | * time. |
| 22 | * |
| 23 | * Local dev (`alchemy dev`) delivers these today. On deployed Workers |
| 24 | * the Cloudflare API's binding schema does not carry `props` yet, so |
| 25 | * they are typed and plumbed but dropped at upload until the distilled |
| 26 | * `workers` service adds the field. |
| 27 | */ |
| 28 | props?: Record<string, Input<unknown>>; |
| 29 | } |
| 30 | |
| 31 | /** |
| 32 | * A service binding to an entrypoint of another Worker or of this Worker — |
| 33 | * the value form accepted in an async Worker's `env`. See |
| 34 | * {@link WorkerEntrypoint}. |
| 35 | */ |
| 36 | export interface WorkerEntrypointBinding< |
| 37 | Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined, |
| 38 | > { |
| 39 | /** Brand discriminating entrypoint bindings in `env` classification. */ |
| 40 | readonly kind: WorkerEntrypointTypeId; |
| 41 | /** The target Worker resource, or `undefined` for this Worker itself. */ |
| 42 | readonly worker: Worker | undefined; |
| 43 | /** Named entrypoint on the target, or `undefined` for the default. */ |
| 44 | readonly entrypoint: string | undefined; |
| 45 | /** `ctx.props` delivered to the target entrypoint. */ |
| 46 | readonly props: Record<string, Input<unknown>> | undefined; |
| 47 | /** Entry-point instance type used by `InferEnv`; absent at runtime. */ |
| 48 | readonly "~alchemy/entrypoint"?: Entrypoint; |
| 49 | } |
| 50 | |
| 51 | /** |
| 52 | * Bind an entrypoint of another Worker or of this Worker. |
| 53 | * |
| 54 | * Binding a Worker directly in `env` (`env: { TARGET: worker }`) targets |
| 55 | * its *default* entrypoint. A Worker that exposes additional |
| 56 | * `WorkerEntrypoint` classes — workerd treats every named class export of |
| 57 | * an entry module as an entrypoint — is bound with `WorkerEntrypoint`, |
| 58 | * which selects the class by name and can deliver `ctx.props` to it. |
| 59 | * |
| 60 | * ### Defining the Target Entrypoint |
| 61 | * Export a class extending Cloudflare's native `WorkerEntrypoint` from |
| 62 | * the target Worker's module. This `Api` class defines the RPC methods |
| 63 | * that callers can invoke through a named service binding. |
| 64 | * |
| 65 | * **Example:** Export the Api class |
| 66 | * ```typescript |
| 67 | * // target/src/worker.ts |
| 68 | * import { WorkerEntrypoint } from "cloudflare:workers"; |
| 69 | * |
| 70 | * export class Api extends WorkerEntrypoint { |
| 71 | * async greet(name: string): Promise<string> { |
| 72 | * return `hello ${name}`; |
| 73 | * } |
| 74 | * } |
| 75 | * |
| 76 | * export default { |
| 77 | * async fetch() { |
| 78 | * return new Response("ok"); |
| 79 | * }, |
| 80 | * }; |
| 81 | * ``` |
| 82 | * |
| 83 | * ### Binding a Named Entrypoint |
| 84 | * Import the exported `Api` class as a type and select its named export |
| 85 | * with `"Api"`. Pass its instance type (`Api`, not `typeof Api`) to get |
| 86 | * Cloudflare's native `Service<Api>` RPC client. Without a type argument, |
| 87 | * the binding is a bare `Fetcher`; the entrypoint name alone cannot |
| 88 | * identify the class's type. |
| 89 | * |
| 90 | * **Example:** Bind and call the exported Api |
| 91 | * ```typescript |
| 92 | * // alchemy.run.ts |
| 93 | * import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 94 | * import type { Api } from "./target/src/worker.ts"; |
| 95 | * |
| 96 | * const target = yield* Cloudflare.Worker("Target", { |
| 97 | * main: "./target/src/worker.ts", |
| 98 | * }); |
| 99 | * |
| 100 | * const caller = yield* Cloudflare.Worker("Caller", { |
| 101 | * main: "./caller/src/worker.ts", |
| 102 | * env: { |
| 103 | * API: Cloudflare.WorkerEntrypoint<Api>(target, "Api"), |
| 104 | * }, |
| 105 | * }); |
| 106 | * ``` |
| 107 | * |
| 108 | * ```typescript |
| 109 | * // caller/src/worker.ts |
| 110 | * import type { CallerEnv } from "../../alchemy.run.ts"; |
| 111 | * |
| 112 | * export default { |
| 113 | * async fetch(request: Request, env: CallerEnv) { |
| 114 | * return new Response(await env.API.greet("alice")); |
| 115 | * }, |
| 116 | * }; |
| 117 | * ``` |
| 118 | * |
| 119 | * ### Binding This Worker's Own Entrypoints |
| 120 | * Leave out the Worker to bind an entrypoint of the Worker that declares |
| 121 | * the binding (Wrangler's `services: [{ binding, service: <this worker>, |
| 122 | * entrypoint }]`). With no name, it binds the default export, the same as |
| 123 | * `Cloudflare.Workers.Self`. |
| 124 | * |
| 125 | * **Example:** Bind this Worker's McpEntrypoint and default export |
| 126 | * ```typescript |
| 127 | * // alchemy.run.ts |
| 128 | * import type { McpEntrypoint } from "./src/worker.ts"; |
| 129 | * |
| 130 | * const api = yield* Cloudflare.Worker("Api", { |
| 131 | * main: "./src/worker.ts", |
| 132 | * env: { |
| 133 | * MCP: Cloudflare.WorkerEntrypoint<McpEntrypoint>("McpEntrypoint"), |
| 134 | * SELF: Cloudflare.WorkerEntrypoint(), |
| 135 | * }, |
| 136 | * }); |
| 137 | * ``` |
| 138 | * |
| 139 | * ```typescript |
| 140 | * // src/worker.ts |
| 141 | * export class McpEntrypoint extends WorkerEntrypoint { |
| 142 | * async fetch() { |
| 143 | * return new Response("mcp"); |
| 144 | * } |
| 145 | * } |
| 146 | * |
| 147 | * export default { |
| 148 | * fetch: (request: Request, env: WorkerEnv) => env.MCP.fetch(request), |
| 149 | * }; |
| 150 | * ``` |
| 151 | * |
| 152 | * ### Delivering ctx.props |
| 153 | * The options form attaches properties the target reads from |
| 154 | * `this.ctx.props` — workerd's per-binding configuration channel. `Output` |
| 155 | * values resolve at deploy time. An Effect Worker reads them with |
| 156 | * `yield* ctx.props` on `Cloudflare.WorkerExecutionContext`. |
| 157 | * |
| 158 | * **Example:** Entrypoint binding with props |
| 159 | * ```typescript |
| 160 | * env: { |
| 161 | * VENDOR: Cloudflare.WorkerEntrypoint(vendorWorker, { |
| 162 | * entrypoint: "Vendor", |
| 163 | * props: { baseUrl: site.url }, |
| 164 | * }), |
| 165 | * } |
| 166 | * ``` |
| 167 | * |
| 168 | * @resource |
| 169 | * @product Workers |
| 170 | * @category Workers & Compute |
| 171 | */ |
| 172 | export interface WorkerEntrypointFunction { |
| 173 | /** An entrypoint of this Worker: its default export, or the named class. */ |
| 174 | <Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined>( |
| 175 | entrypointOrOptions?: string | WorkerEntrypointOptions, |
| 176 | ): WorkerEntrypointBinding<NoInfer<Entrypoint>>; |
| 177 | /** An entrypoint of another Worker: its default export, or the named class. */ |
| 178 | <Entrypoint extends Rpc.WorkerEntrypointBranded | undefined = undefined>( |
| 179 | worker: Worker, |
| 180 | entrypointOrOptions?: string | WorkerEntrypointOptions, |
| 181 | ): WorkerEntrypointBinding<NoInfer<Entrypoint>>; |
| 182 | } |
| 183 | |
| 184 | export const WorkerEntrypoint: WorkerEntrypointFunction = ( |
| 185 | workerOrEntrypoint?: Worker | string | WorkerEntrypointOptions, |
| 186 | entrypointOrOptions?: string | WorkerEntrypointOptions, |
| 187 | ) => { |
| 188 | // A Worker resource carries its `Type`; a bare name or options object |
| 189 | // names an entrypoint of this Worker. A `Worker.ref(...)` is a callable |
| 190 | // Output proxy (`typeof` is "function"), so match on `Type` rather than |
| 191 | // on the value's shape. |
| 192 | const targetsWorker = isResourceOfType(workerOrEntrypoint, WorkerTypeId); |
| 193 | const worker = targetsWorker ? (workerOrEntrypoint as Worker) : undefined; |
| 194 | const entrypoint = targetsWorker |
| 195 | ? entrypointOrOptions |
| 196 | : (workerOrEntrypoint as string | WorkerEntrypointOptions | undefined); |
| 197 | const options = typeof entrypoint === "string" ? { entrypoint } : (entrypoint ?? {}); |
| 198 | return { |
| 199 | kind: WorkerEntrypointTypeId, |
| 200 | worker, |
| 201 | entrypoint: options.entrypoint, |
| 202 | props: options.props, |
| 203 | }; |
| 204 | }; |
| 205 | |
| 206 | /** Structural guard for {@link WorkerEntrypointBinding} `env` values. */ |
| 207 | export const isWorkerEntrypoint = (value: unknown): value is WorkerEntrypointBinding<any> => |
| 208 | typeof value === "object" && |
| 209 | value !== null && |
| 210 | (value as { kind?: unknown }).kind === WorkerEntrypointTypeId; |