import * as workers from "@distilled.cloud/cloudflare/workers";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import * as RpcProvider from "alchemy/Local/RpcProvider";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import {
generateLocalId,
isLiveId,
LOCAL_PROVIDERS_URL,
localRuntimeServices,
} from "../LocalRuntime.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
import { LocalEdge } from "./LocalEdge.ts";
import { routePatternHost, routePatternUrl } from "./RoutePattern.ts";
export interface WorkerRouteProps {
/**
* Zone the route lives in. Stable — routes are scoped to a zone, so
* changing the zone triggers a replacement.
*/
zoneId: string;
/**
* Pattern to match incoming requests against, e.g.
* `api.example.com/*`. The pattern must match a hostname inside the
* zone identified by {@link zoneId}.
*
* Mutable — Cloudflare's PUT endpoint accepts a new pattern in place.
* Declared as plain `string` (not `string`) so the reconciler
* can locate an existing route by pattern after state loss.
*/
pattern: string;
/**
* Name of the Worker script to run when the route matches. Accepts a
* reference to a deployed Worker's `workerName`. When omitted, the
* route disables Workers for matching requests (useful to opt a path
* out of a broader wildcard route).
*
* Mutable — updated in place.
*/
script?: string;
}
export interface WorkerRouteAttributes {
/** Cloudflare-assigned route identifier. */
routeId: string;
/** Zone that owns this route. */
zoneId: string;
/** Pattern the route matches. */
pattern: string;
/** Worker script the route runs, or `undefined` for an opt-out route. */
script: string | undefined;
/**
* Origin serving the route's hostname — `https://<host>` when deployed,
* the local edge listener under `alchemy dev` — or `undefined` for a
* wildcard host.
*/
url?: string;
}
export type WorkerRoute = Resource<
"Cloudflare.Workers.Route",
WorkerRouteProps,
WorkerRouteAttributes,
never,
Providers
>;
/**
* A Workers Route — a zone-level mapping from a URL pattern to a Worker
* script.
*
* Routes are the classic way to serve a Worker on a zone hostname or
* path. The matched hostname must resolve through Cloudflare's proxy,
* so pair the route with a proxied DNS record (an `AAAA 100::`
* placeholder is the conventional choice when the Worker is the only
* origin).
*
* Safety: routes carry no ownership markers, and Cloudflare enforces
* one route per pattern per zone. When there is no prior state, `read`
* scans the zone for an existing route with the same pattern and
* reports it as `Unowned`, so the engine refuses to take it over unless
* `--adopt` (or `adopt(true)`) is set.
*
* Under `alchemy dev` the route is emulated locally instead: requests to a
* custom-domain Worker on the same hostname (or to the route's `url`, a
* local listener for the hostname) are matched against every route and
* forwarded to the target Worker, most specific pattern first.
* ### Routing a hostname to a Worker
* **Example:** Route all requests on a subdomain to a Worker
* ```typescript
* const worker = yield* Cloudflare.Worker("Api", {
* main: "./src/api.ts",
* });
*
* yield* Cloudflare.Workers.WorkerRoute("ApiRoute", {
* zoneId: zone.zoneId,
* pattern: "api.example.com/*",
* script: worker.workerName,
* });
*
* // Workers only run on proxied hostnames — give the host an origin.
* yield* Cloudflare.DNS.Record("ApiPlaceholder", {
* zoneId: zone.zoneId,
* name: "api.example.com",
* type: "AAAA",
* content: "100::",
* proxied: true,
* });
* ```
*
* ### Disabling Workers on a path
* **Example:** Opt a path out of a wildcard route
* ```typescript
* // No `script` — matching requests bypass Workers entirely.
* yield* Cloudflare.Workers.WorkerRoute("AssetsBypass", {
* zoneId: zone.zoneId,
* pattern: "example.com/assets/*",
* });
* ```
*
* @resource
* @product Workers
* @category Workers & Compute
*/
export const WorkerRoute = Resource<WorkerRoute>("Cloudflare.Workers.Route");
export const isWorkerRoute = (value: unknown): value is WorkerRoute =>
Predicate.hasProperty(value, "Type") && value.Type === "Cloudflare.Workers.Route";
export const WorkerRouteProvider = () =>
ProviderLayer.dual(WorkerRoute, {
live: () => WorkerRouteProviderLive(),
local: () => WorkerRouteProviderLocal().pipe(Layer.provide(localRuntimeServices())),
});
/**
* `alchemy dev` emulation: the route is registered with the local edge,
* which matches its pattern in front of the local Workers exactly like
* Cloudflare's zone routing (see `LocalEdge`). No cloud call is made.
*/
export const WorkerRouteProviderLocal = () =>
RpcProvider.effect(
WorkerRoute,
LOCAL_PROVIDERS_URL,
Effect.gen(function* () {
const edge = yield* LocalEdge;
const register = Effect.fn(function* (attrs: WorkerRouteAttributes) {
yield* edge.setRoutes(attrs.routeId, [{ pattern: attrs.pattern, script: attrs.script }]);
const host = routePatternHost(attrs.pattern);
const url = host === undefined ? undefined : yield* edge.url(host);
return { ...attrs, url: url?.origin };
});
return {
stables: ["routeId", "zoneId"],
diff: Effect.fn(function* ({ news, output }) {
if (!output) return undefined;
// A real route id on a local row: replace to mint a local one.
if (isLiveId(output.routeId)) return { action: "replace" } as const;
if (!isResolved(news)) return undefined;
if (output.zoneId !== news.zoneId) return { action: "replace" } as const;
if (output.pattern !== news.pattern || output.script !== news.script) {
return { action: "update" } as const;
}
// Unchanged: re-register so a fresh dev session's edge serves it
// without the plan reporting an update — unless the hostname's
// listener moved (a new session picks a new port).
const registered = yield* register(output);
return registered.url === output.url
? ({ action: "noop" } as const)
: ({ action: "update" } as const);
}),
reconcile: Effect.fn(function* ({ news, output }) {
const attrs: WorkerRouteAttributes = {
routeId:
output?.routeId && !isLiveId(output.routeId) ? output.routeId : generateLocalId(),
zoneId: news.zoneId as string,
pattern: news.pattern,
script: news.script as string | undefined,
};
return yield* register(attrs);
}),
delete: Effect.fn(function* ({ output }) {
yield* edge.removeRoutes(output.routeId);
}),
};
}),
);
export const WorkerRouteProviderLive = () =>
Provider.succeed(WorkerRoute, {
stables: ["routeId", "zoneId"],
diff: Effect.fn(function* ({ olds = {}, news }) {
const o = olds as WorkerRouteProps;
const n = news as WorkerRouteProps;
// zoneId is Input<string>; by diff time both sides are concrete
// strings when statically knowable.
if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ output, olds }) {
// Owned path: refresh by our persisted route id.
if (output?.routeId) {
const observed = yield* observeById(output.zoneId, output.routeId);
if (observed) {
return toAttributes(observed, output.zoneId);
}
}
// Adoption path: no state of our own, but Cloudflare enforces one
// route per pattern per zone, so a `(zoneId, pattern)` match is
// the same logical route. Routes carry no ownership markers, so
// brand it `Unowned` and let the engine gate takeover behind the
// adopt policy.
const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
const pattern = output?.pattern ?? olds?.pattern;
if (zoneId && pattern) {
const observed = yield* findByPattern(zoneId, pattern);
if (observed) {
return Unowned(toAttributes(observed, zoneId));
}
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
const script = news.script as string | undefined;
// 1. Observe by cached id first.
let observed = output?.routeId ? yield* observeById(zoneId, output.routeId) : undefined;
// 2. Fall back to scanning the zone for the pattern. Ownership has
// already been verified upstream — `read` reports existing
// routes as `Unowned` and the engine gates takeover behind the
// adopt policy before reconcile ever runs.
if (!observed) {
observed = yield* findByPattern(zoneId, news.pattern);
}
// 3. Ensure. A duplicate-pattern failure means another actor (or a
// crashed previous reconcile) created the route between our
// observation and now — treat it as a race and converge via PUT.
if (!observed) {
observed = yield* workers.createRoute({ zoneId, pattern: news.pattern, script }).pipe(
Effect.map(normalizeRoute),
Effect.catchTag("InvalidRoute", (originalError) =>
Effect.gen(function* () {
const match = yield* findByPattern(zoneId, news.pattern);
if (!match) {
return yield* originalError;
}
return match;
}),
),
);
}
// 4. Sync — PUT resends the full desired body when the observed
// route drifts from the desired pattern/script.
if (observed.pattern !== news.pattern || observed.script !== script) {
observed = normalizeRoute(
yield* workers.updateRoute({
zoneId,
routeId: observed.id,
pattern: news.pattern,
script,
}),
);
}
// 5. Return.
return toAttributes(observed, zoneId);
}),
delete: Effect.fn(function* ({ output }) {
yield* workers
.deleteRoute({
zoneId: output.zoneId,
routeId: output.routeId,
})
.pipe(Effect.catchTag("RouteNotFound", () => Effect.void));
}),
// Routes are zone-scoped (`/zones/{id}/workers/routes`) with no account-
// wide enumeration API. Fan out over every zone via `listAllZones`,
// exhaustively paginate `listRoutes` per zone, and hydrate each into the
// same Attributes shape `read` returns. Zones the scoped token can't
// reach (Forbidden) or that reject the route (InvalidRoute) are skipped
// with a typed catch rather than failing the whole enumeration.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
workers.listRoutes.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((route) => toAttributes(normalizeRoute(route), zone.id)),
),
),
Effect.catchTag(["InvalidRoute", "Forbidden"], () =>
Effect.succeed([] as WorkerRouteAttributes[]),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
interface ObservedRoute {
readonly id: string;
readonly pattern: string;
readonly script: string | undefined;
}
/**
* Distilled types `script` as `string | null | undefined`; an opt-out
* route comes back as `null` (or empty string from older API versions).
* Normalize both to `undefined` so drift comparison is stable.
*/
const normalizeRoute = (raw: {
id: string;
pattern: string;
script?: string | null;
}): ObservedRoute => ({
id: raw.id,
pattern: raw.pattern,
script: raw.script == null || raw.script === "" ? undefined : raw.script,
});
const toAttributes = (observed: ObservedRoute, zoneId: string): WorkerRouteAttributes => ({
routeId: observed.id,
zoneId,
pattern: observed.pattern,
script: observed.script,
url: routePatternUrl(observed.pattern),
});
const observeById = (zoneId: string, routeId: string) =>
workers.getRoute({ zoneId, routeId }).pipe(
Effect.map(normalizeRoute),
// A missing route surfaces as a 404 whose CF error code varies —
// `RouteNotFound` (10009 or a bare 404 envelope) or `WorkerNotFound`
// (10007, how some API versions tag a GET on a missing route). Both
// are in `getRoute`'s typed union; swallow them so the reconciler
// falls through to the find-by-pattern path.
Effect.catchTag(["RouteNotFound", "WorkerNotFound"], () => Effect.undefined),
);
/**
* Locate an existing route by `(zoneId, pattern)`. Cloudflare enforces
* pattern uniqueness within a zone, so a match identifies the route.
*/
const findByPattern = (zoneId: string, pattern: string) =>
workers.listRoutes.items({ zoneId }).pipe(
Stream.filter((r) => r.pattern === pattern),
Stream.runCollect,
Effect.map((chunk) => {
const found = Array.from(chunk)[0];
return found === undefined ? undefined : normalizeRoute(found);
}),
);