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

main
ts 376 lines 13.7 KB
Raw
1 import * as workers from "@distilled.cloud/cloudflare/workers";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
5 import * as RpcProvider from "alchemy/Local/RpcProvider";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import * as Effect from "effect/Effect";
9 import * as Layer from "effect/Layer";
10 import * as Predicate from "effect/Predicate";
11 import * as Stream from "effect/Stream";
12 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
13 import {
14 generateLocalId,
15 isLiveId,
16 LOCAL_PROVIDERS_URL,
17 localRuntimeServices,
18 } from "../LocalRuntime.ts";
19 import type { Providers } from "../Providers.ts";
20 import { listAllZones } from "../Zone/lookup.ts";
21 import { LocalEdge } from "./LocalEdge.ts";
22 import { routePatternHost, routePatternUrl } from "./RoutePattern.ts";
23
24 export interface WorkerRouteProps {
25 /**
26 * Zone the route lives in. Stable — routes are scoped to a zone, so
27 * changing the zone triggers a replacement.
28 */
29 zoneId: string;
30 /**
31 * Pattern to match incoming requests against, e.g.
32 * `api.example.com/*`. The pattern must match a hostname inside the
33 * zone identified by {@link zoneId}.
34 *
35 * Mutable — Cloudflare's PUT endpoint accepts a new pattern in place.
36 * Declared as plain `string` (not `string`) so the reconciler
37 * can locate an existing route by pattern after state loss.
38 */
39 pattern: string;
40 /**
41 * Name of the Worker script to run when the route matches. Accepts a
42 * reference to a deployed Worker's `workerName`. When omitted, the
43 * route disables Workers for matching requests (useful to opt a path
44 * out of a broader wildcard route).
45 *
46 * Mutable — updated in place.
47 */
48 script?: string;
49 }
50
51 export interface WorkerRouteAttributes {
52 /** Cloudflare-assigned route identifier. */
53 routeId: string;
54 /** Zone that owns this route. */
55 zoneId: string;
56 /** Pattern the route matches. */
57 pattern: string;
58 /** Worker script the route runs, or `undefined` for an opt-out route. */
59 script: string | undefined;
60 /**
61 * Origin serving the route's hostname — `https://<host>` when deployed,
62 * the local edge listener under `alchemy dev` — or `undefined` for a
63 * wildcard host.
64 */
65 url?: string;
66 }
67
68 export type WorkerRoute = Resource<
69 "Cloudflare.Workers.Route",
70 WorkerRouteProps,
71 WorkerRouteAttributes,
72 never,
73 Providers
74 >;
75
76 /**
77 * A Workers Route — a zone-level mapping from a URL pattern to a Worker
78 * script.
79 *
80 * Routes are the classic way to serve a Worker on a zone hostname or
81 * path. The matched hostname must resolve through Cloudflare's proxy,
82 * so pair the route with a proxied DNS record (an `AAAA 100::`
83 * placeholder is the conventional choice when the Worker is the only
84 * origin).
85 *
86 * Safety: routes carry no ownership markers, and Cloudflare enforces
87 * one route per pattern per zone. When there is no prior state, `read`
88 * scans the zone for an existing route with the same pattern and
89 * reports it as `Unowned`, so the engine refuses to take it over unless
90 * `--adopt` (or `adopt(true)`) is set.
91 *
92 * Under `alchemy dev` the route is emulated locally instead: requests to a
93 * custom-domain Worker on the same hostname (or to the route's `url`, a
94 * local listener for the hostname) are matched against every route and
95 * forwarded to the target Worker, most specific pattern first.
96 * ### Routing a hostname to a Worker
97 * **Example:** Route all requests on a subdomain to a Worker
98 * ```typescript
99 * const worker = yield* Cloudflare.Worker("Api", {
100 * main: "./src/api.ts",
101 * });
102 *
103 * yield* Cloudflare.Workers.WorkerRoute("ApiRoute", {
104 * zoneId: zone.zoneId,
105 * pattern: "api.example.com/*",
106 * script: worker.workerName,
107 * });
108 *
109 * // Workers only run on proxied hostnames — give the host an origin.
110 * yield* Cloudflare.DNS.Record("ApiPlaceholder", {
111 * zoneId: zone.zoneId,
112 * name: "api.example.com",
113 * type: "AAAA",
114 * content: "100::",
115 * proxied: true,
116 * });
117 * ```
118 *
119 * ### Disabling Workers on a path
120 * **Example:** Opt a path out of a wildcard route
121 * ```typescript
122 * // No `script` — matching requests bypass Workers entirely.
123 * yield* Cloudflare.Workers.WorkerRoute("AssetsBypass", {
124 * zoneId: zone.zoneId,
125 * pattern: "example.com/assets/*",
126 * });
127 * ```
128 *
129 * @resource
130 * @product Workers
131 * @category Workers & Compute
132 */
133 export const WorkerRoute = Resource<WorkerRoute>("Cloudflare.Workers.Route");
134
135 export const isWorkerRoute = (value: unknown): value is WorkerRoute =>
136 Predicate.hasProperty(value, "Type") && value.Type === "Cloudflare.Workers.Route";
137
138 export const WorkerRouteProvider = () =>
139 ProviderLayer.dual(WorkerRoute, {
140 live: () => WorkerRouteProviderLive(),
141 local: () => WorkerRouteProviderLocal().pipe(Layer.provide(localRuntimeServices())),
142 });
143
144 /**
145 * `alchemy dev` emulation: the route is registered with the local edge,
146 * which matches its pattern in front of the local Workers exactly like
147 * Cloudflare's zone routing (see `LocalEdge`). No cloud call is made.
148 */
149 export const WorkerRouteProviderLocal = () =>
150 RpcProvider.effect(
151 WorkerRoute,
152 LOCAL_PROVIDERS_URL,
153 Effect.gen(function* () {
154 const edge = yield* LocalEdge;
155 const register = Effect.fn(function* (attrs: WorkerRouteAttributes) {
156 yield* edge.setRoutes(attrs.routeId, [{ pattern: attrs.pattern, script: attrs.script }]);
157 const host = routePatternHost(attrs.pattern);
158 const url = host === undefined ? undefined : yield* edge.url(host);
159 return { ...attrs, url: url?.origin };
160 });
161 return {
162 stables: ["routeId", "zoneId"],
163 diff: Effect.fn(function* ({ news, output }) {
164 if (!output) return undefined;
165 // A real route id on a local row: replace to mint a local one.
166 if (isLiveId(output.routeId)) return { action: "replace" } as const;
167 if (!isResolved(news)) return undefined;
168 if (output.zoneId !== news.zoneId) return { action: "replace" } as const;
169 if (output.pattern !== news.pattern || output.script !== news.script) {
170 return { action: "update" } as const;
171 }
172 // Unchanged: re-register so a fresh dev session's edge serves it
173 // without the plan reporting an update — unless the hostname's
174 // listener moved (a new session picks a new port).
175 const registered = yield* register(output);
176 return registered.url === output.url
177 ? ({ action: "noop" } as const)
178 : ({ action: "update" } as const);
179 }),
180 reconcile: Effect.fn(function* ({ news, output }) {
181 const attrs: WorkerRouteAttributes = {
182 routeId:
183 output?.routeId && !isLiveId(output.routeId) ? output.routeId : generateLocalId(),
184 zoneId: news.zoneId as string,
185 pattern: news.pattern,
186 script: news.script as string | undefined,
187 };
188 return yield* register(attrs);
189 }),
190 delete: Effect.fn(function* ({ output }) {
191 yield* edge.removeRoutes(output.routeId);
192 }),
193 };
194 }),
195 );
196
197 export const WorkerRouteProviderLive = () =>
198 Provider.succeed(WorkerRoute, {
199 stables: ["routeId", "zoneId"],
200
201 diff: Effect.fn(function* ({ olds = {}, news }) {
202 const o = olds as WorkerRouteProps;
203 const n = news as WorkerRouteProps;
204 // zoneId is Input<string>; by diff time both sides are concrete
205 // strings when statically knowable.
206 if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
207 return { action: "replace" } as const;
208 }
209 }),
210
211 read: Effect.fn(function* ({ output, olds }) {
212 // Owned path: refresh by our persisted route id.
213 if (output?.routeId) {
214 const observed = yield* observeById(output.zoneId, output.routeId);
215 if (observed) {
216 return toAttributes(observed, output.zoneId);
217 }
218 }
219 // Adoption path: no state of our own, but Cloudflare enforces one
220 // route per pattern per zone, so a `(zoneId, pattern)` match is
221 // the same logical route. Routes carry no ownership markers, so
222 // brand it `Unowned` and let the engine gate takeover behind the
223 // adopt policy.
224 const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
225 const pattern = output?.pattern ?? olds?.pattern;
226 if (zoneId && pattern) {
227 const observed = yield* findByPattern(zoneId, pattern);
228 if (observed) {
229 return Unowned(toAttributes(observed, zoneId));
230 }
231 }
232 return undefined;
233 }),
234
235 reconcile: Effect.fn(function* ({ news, output }) {
236 // Inputs have been resolved to concrete strings by Plan.
237 const zoneId = news.zoneId as string;
238 const script = news.script as string | undefined;
239
240 // 1. Observe by cached id first.
241 let observed = output?.routeId ? yield* observeById(zoneId, output.routeId) : undefined;
242
243 // 2. Fall back to scanning the zone for the pattern. Ownership has
244 // already been verified upstream — `read` reports existing
245 // routes as `Unowned` and the engine gates takeover behind the
246 // adopt policy before reconcile ever runs.
247 if (!observed) {
248 observed = yield* findByPattern(zoneId, news.pattern);
249 }
250
251 // 3. Ensure. A duplicate-pattern failure means another actor (or a
252 // crashed previous reconcile) created the route between our
253 // observation and now — treat it as a race and converge via PUT.
254 if (!observed) {
255 observed = yield* workers.createRoute({ zoneId, pattern: news.pattern, script }).pipe(
256 Effect.map(normalizeRoute),
257 Effect.catchTag("InvalidRoute", (originalError) =>
258 Effect.gen(function* () {
259 const match = yield* findByPattern(zoneId, news.pattern);
260 if (!match) {
261 return yield* originalError;
262 }
263 return match;
264 }),
265 ),
266 );
267 }
268
269 // 4. Sync — PUT resends the full desired body when the observed
270 // route drifts from the desired pattern/script.
271 if (observed.pattern !== news.pattern || observed.script !== script) {
272 observed = normalizeRoute(
273 yield* workers.updateRoute({
274 zoneId,
275 routeId: observed.id,
276 pattern: news.pattern,
277 script,
278 }),
279 );
280 }
281
282 // 5. Return.
283 return toAttributes(observed, zoneId);
284 }),
285
286 delete: Effect.fn(function* ({ output }) {
287 yield* workers
288 .deleteRoute({
289 zoneId: output.zoneId,
290 routeId: output.routeId,
291 })
292 .pipe(Effect.catchTag("RouteNotFound", () => Effect.void));
293 }),
294
295 // Routes are zone-scoped (`/zones/{id}/workers/routes`) with no account-
296 // wide enumeration API. Fan out over every zone via `listAllZones`,
297 // exhaustively paginate `listRoutes` per zone, and hydrate each into the
298 // same Attributes shape `read` returns. Zones the scoped token can't
299 // reach (Forbidden) or that reject the route (InvalidRoute) are skipped
300 // with a typed catch rather than failing the whole enumeration.
301 list: Effect.fn(function* () {
302 const { accountId } = yield* yield* CloudflareEnvironment;
303 const zones = yield* listAllZones(accountId);
304 const rows = yield* Effect.forEach(
305 zones,
306 (zone) =>
307 workers.listRoutes.pages({ zoneId: zone.id }).pipe(
308 Stream.runCollect,
309 Effect.map((chunk) =>
310 Array.from(chunk).flatMap((page) =>
311 (page.result ?? []).map((route) => toAttributes(normalizeRoute(route), zone.id)),
312 ),
313 ),
314 Effect.catchTag(["InvalidRoute", "Forbidden"], () =>
315 Effect.succeed([] as WorkerRouteAttributes[]),
316 ),
317 ),
318 { concurrency: 10 },
319 );
320 return rows.flat();
321 }),
322 });
323
324 interface ObservedRoute {
325 readonly id: string;
326 readonly pattern: string;
327 readonly script: string | undefined;
328 }
329
330 /**
331 * Distilled types `script` as `string | null | undefined`; an opt-out
332 * route comes back as `null` (or empty string from older API versions).
333 * Normalize both to `undefined` so drift comparison is stable.
334 */
335 const normalizeRoute = (raw: {
336 id: string;
337 pattern: string;
338 script?: string | null;
339 }): ObservedRoute => ({
340 id: raw.id,
341 pattern: raw.pattern,
342 script: raw.script == null || raw.script === "" ? undefined : raw.script,
343 });
344
345 const toAttributes = (observed: ObservedRoute, zoneId: string): WorkerRouteAttributes => ({
346 routeId: observed.id,
347 zoneId,
348 pattern: observed.pattern,
349 script: observed.script,
350 url: routePatternUrl(observed.pattern),
351 });
352
353 const observeById = (zoneId: string, routeId: string) =>
354 workers.getRoute({ zoneId, routeId }).pipe(
355 Effect.map(normalizeRoute),
356 // A missing route surfaces as a 404 whose CF error code varies —
357 // `RouteNotFound` (10009 or a bare 404 envelope) or `WorkerNotFound`
358 // (10007, how some API versions tag a GET on a missing route). Both
359 // are in `getRoute`'s typed union; swallow them so the reconciler
360 // falls through to the find-by-pattern path.
361 Effect.catchTag(["RouteNotFound", "WorkerNotFound"], () => Effect.undefined),
362 );
363
364 /**
365 * Locate an existing route by `(zoneId, pattern)`. Cloudflare enforces
366 * pattern uniqueness within a zone, so a match identifies the route.
367 */
368 const findByPattern = (zoneId: string, pattern: string) =>
369 workers.listRoutes.items({ zoneId }).pipe(
370 Stream.filter((r) => r.pattern === pattern),
371 Stream.runCollect,
372 Effect.map((chunk) => {
373 const found = Array.from(chunk)[0];
374 return found === undefined ? undefined : normalizeRoute(found);
375 }),
376 );