The best way to control Claude Code, Codex and more from any computer or phone

main
ts 210 lines 7.44 KB
Raw
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;