alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Cloudflare/Website/Vocs.ts

@@ -0,0 +1,195 @@
+import * as Effect from "effect/Effect";
+import type { MemoOptions } from "../../Command/Memo.ts";
+import type { InputProps } from "../../Input.ts";
+import { effectClass } from "../../Util/effect.ts";
+import type { Providers } from "../Providers.ts";
+import type { AssetsConfig } from "../Workers/Assets.ts";
+import {
+  Worker,
+  type NormalizedBindings,
+  type WorkerAssetsConfig,
+  type WorkerBindingProps,
+  type WorkerProps,
+} from "../Workers/Worker.ts";
+
+const VOCS_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/vocs/source";
+
+export interface VocsProps<
+  Bindings extends WorkerBindingProps = {},
+> extends Omit<
+  WorkerProps<Bindings>,
+  "vite" | "main" | "assets" | "source" | "script" | "bundle"
+> {
+  /**
+   * Root directory of the Vocs project.
+   * @default process.cwd()
+   */
+  rootDir?: string;
+  /**
+   * Vocs build output directory, relative to {@link rootDir}. Set this when
+   * `vocs.config.*` customizes `outDir` so generated output stays outside the
+   * rebuild hash.
+   * @default "dist"
+   */
+  outDir?: string;
+  /**
+   * Controls which files feed the content hash that decides whether Vocs
+   * rebuilds. By default every non-gitignored file under {@link rootDir} is
+   * hashed, plus the nearest package-manager lockfile.
+   */
+  memo?: MemoOptions;
+  /**
+   * Static asset routing configuration. Vocs links prerendered pages without
+   * trailing slashes, so extensionless routing is enabled by default.
+   * @default { htmlHandling: "drop-trailing-slash" }
+   */
+  assets?: AssetsConfig;
+}
+
+/**
+ * A Cloudflare Worker deployed from a [Vocs](https://vocs.dev) documentation project.
+ *
+ * Vocs' `vocs.config.*` loads natively. Alchemy runs Vocs' Waku/RSC build,
+ * deploys its server environments as a Worker, and publishes the client and
+ * prerendered output as static assets. No Vite or Wrangler config is required.
+ *
+ * Requires `@alchemy.run/frontend-frameworks`, `vocs`, and Vocs' Waku peer
+ * dependencies in the project.
+ *
+ * Input files are content-hashed (respecting `.gitignore` by default), so an
+ * unchanged project skips its build and deployment. Vocs' server runtime uses
+ * Node APIs, so `nodejs_compat` is included in the Worker's compatibility
+ * flags automatically.
+ *
+ * ### Deploying a Vocs Site
+ * A single resource builds the documentation project and deploys its server
+ * runtime, prerendered pages, generated files, and public assets.
+ *
+ * **Example:** Vocs documentation site
+ * ```typescript
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ * });
+ * ```
+ *
+ * ### Bindings
+ * Pass Cloudflare resources through `env` like any other Worker. Server-side
+ * Vocs and MDX code can access them from `cloudflare:workers`.
+ *
+ * **Example:** Vocs with a KV namespace
+ * ```typescript
+ * const searchCache = yield* Cloudflare.KV.Namespace("SearchCache");
+ *
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   env: {
+ *     SEARCH_CACHE: searchCache,
+ *   },
+ * });
+ * ```
+ *
+ * ### Custom Build Output
+ * Vocs configuration continues to own the output directory. When
+ * `vocs.config.*` changes `outDir`, mirror that value on the resource so the
+ * generated directory is excluded from the rebuild hash and read correctly.
+ *
+ * **Example:** Custom output directory
+ * ```typescript
+ * // vocs.config.ts: defineConfig({ outDir: "build" })
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   outDir: "build",
+ * });
+ * ```
+ *
+ * ### Custom Rebuild Scope
+ * Use `memo` to narrow the files that trigger a rebuild in large projects.
+ *
+ * **Example:** Narrowing the memo scope
+ * ```typescript
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   memo: {
+ *     include: ["src/**", "public/**", "vocs.config.ts", "package.json"],
+ *   },
+ * });
+ * ```
+ *
+ * ### Class Form
+ * Calling `Vocs` without arguments returns a constructor for declaring the
+ * deployed Worker as a named class.
+ *
+ * **Example:** Declaring a Vocs Worker class
+ * ```typescript
+ * class Docs extends Cloudflare.Website.Vocs<Docs>()("Docs", {
+ *   rootDir: "./docs",
+ * }) {}
+ *
+ * const docs = yield* Docs;
+ * ```
+ *
+ * @resource
+ * @product Website
+ * @category Workers & Compute
+ */
+export const Vocs: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff?:
+        | InputProps<VocsProps<Bindings>>
+        | Effect.Effect<InputProps<VocsProps<Bindings>>, never, Req>,
+    ): Effect.Effect<Self, never, Req | Providers> & {
+      new (): Worker<{
+        [
+          binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>
+        ]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+      }>;
+    };
+  };
+  <const Bindings extends WorkerBindingProps = {}, Req = never>(
+    id: string,
+    propsEff?:
+      | InputProps<VocsProps<Bindings>>
+      | Effect.Effect<InputProps<VocsProps<Bindings>>, never, Req>,
+  ): Effect.Effect<
+    Worker<{
+      [
+        binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>
+      ]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+    }>,
+    never,
+    Req | Providers
+  >;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(Vocs(id, propsEff))
+    : Worker(
+        id,
+        Effect.map(
+          Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
+          (props) => ({
+            ...props,
+            compatibility: {
+              ...props?.compatibility,
+              flags: props?.compatibility?.flags?.includes("nodejs_compat")
+                ? props.compatibility.flags
+                : [...(props?.compatibility?.flags ?? []), "nodejs_compat"],
+            },
+            assets: {
+              htmlHandling: "drop-trailing-slash" as const,
+              ...props?.assets,
+            },
+            main: undefined!,
+            source: {
+              provider: VOCS_SOURCE_PROVIDER,
+              devMode: "server",
+              options: {
+                rootDir: props?.rootDir,
+                outDir: props?.outDir,
+                memo: props?.memo,
+              },
+            },
+          }),
+        ),
+      )) as any;

package/src/Cloudflare/Website/Waku.ts

@@ -50,28 +50,6 @@ export interface WakuProps<
    * directory.
    */
   rootDir?: string;
-  /**
-   * Waku source directory, relative to {@link rootDir}. Setting this
-   * overrides a `srcDir` in the project's `waku.config.*`.
-   * @default the project's `waku.config.*` value, or waku's own default (`"src"`)
-   */
-  srcDir?: string;
-  /**
-   * Waku build output directory, relative to {@link rootDir}. The server
-   * bundle is read from `<distDir>/server` and the client assets from
-   * `<distDir>/public`. Setting this overrides a `distDir` in the
-   * project's `waku.config.*` — if your config file customizes `distDir`,
-   * mirror it here (or exclude it via `memo`) so the build output doesn't
-   * pollute the rebuild hash.
-   * @default the project's `waku.config.*` value, or waku's own default (`"dist"`)
-   */
-  distDir?: string;
-  /**
-   * Base path the app is served under. Setting this overrides a
-   * `basePath` in the project's `waku.config.*`.
-   * @default the project's `waku.config.*` value, or waku's own default (`"/"`)
-   */
-  basePath?: string;
   /**
    * Controls which files feed the content hash that decides whether a
    * rebuild is needed. By default every non-gitignored file under
@@ -91,6 +69,31 @@ export interface WakuProps<
    * @default { htmlHandling: "drop-trailing-slash" }
    */
   assets?: AssetsConfig;
+  /**
+   * Waku config overrides merged over the project's `waku.config.*`
+   * (per-key; deploy-time values win). For values that vary by stage or
+   * come from other resources — static config belongs in `waku.config.*`.
+   */
+  waku?: {
+    /**
+     * Waku `srcDir` (relative to {@link rootDir}).
+     * @default "src"
+     */
+    srcDir?: string;
+    /**
+     * Waku `distDir` (relative to {@link rootDir}). If `waku.config.*`
+     * customizes `distDir`, mirror it here (or add it to `memo.exclude`)
+     * so the build output stays excluded from the rebuild-deciding input
+     * hash.
+     * @default "dist"
+     */
+    distDir?: string;
+    /**
+     * Waku `basePath`.
+     * @default "/"
+     */
+    basePath?: string;
+  };
 }
 
 /**
@@ -98,8 +101,9 @@ export interface WakuProps<
  *
  * `Waku` builds the project programmatically — no `waku.config.ts` edits,
  * no Wrangler configuration, and no build command required. A project's
- * `waku.config.*` loads natively (same as waku's CLI) as the base config,
- * with `srcDir`/`distDir`/`basePath` from this resource winning per key;
+ * `waku.config.*` loads natively (same as waku's CLI) and is where all
+ * Waku configuration (`srcDir`, `distDir`, `basePath`, ...) lives; the
+ * `waku` prop overrides it per key at deploy time.
  * `unstable_adapter` is owned by Alchemy and must not be set. Note that a
  * standalone `vite.config.ts` is NOT loaded (same as waku's CLI) — Vite
  * config belongs in `waku.config.*`'s `vite` field. The RSC server
@@ -135,6 +139,20 @@ export interface WakuProps<
  * });
  * ```
  *
+ * ### Waku Config Overrides
+ * Waku configuration lives in your `waku.config.*`. The `waku` prop
+ * overrides it per key at deploy time — for values that vary by stage
+ * or come from other resources.
+ *
+ * **Example:** Stage-dependent base path
+ * ```typescript
+ * const site = yield* Cloudflare.Website.Waku("Site", {
+ *   waku: {
+ *     basePath: "/docs/",
+ *   },
+ * });
+ * ```
+ *
  * ### Bindings
  * Pass resources through `env` like any other Worker. Server components
  * and API routes read them from the `cloudflare:workers` env at request
@@ -274,9 +292,11 @@ export const Waku: {
                 // `virtual:waku/server-entry`); resolved against `rootDir`
                 // by the source provider.
                 main: props?.main,
-                srcDir: props?.srcDir,
-                distDir: props?.distDir,
-                basePath: props?.basePath,
+                // Deploy-time waku config overrides, merged over the
+                // project's `waku.config.*` by the source provider.
+                srcDir: props?.waku?.srcDir,
+                distDir: props?.waku?.distDir,
+                basePath: props?.waku?.basePath,
                 memo: props?.memo,
               },
             },

package/src/Cloudflare/Website/index.ts

@@ -6,4 +6,5 @@ export * from "./Octane.ts";
 export * from "./StaticSite.ts";
 export * from "./SvelteKit.ts";
 export * from "./Vite.ts";
+export * from "./Vocs.ts";
 export * from "./Waku.ts";

package/src/Cloudflare/Workers/Assets.ts

@@ -1,4 +1,5 @@
 import * as workers from "@distilled.cloud/cloudflare/workers";
+import * as wfp from "@distilled.cloud/cloudflare/workers-for-platforms";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -428,10 +429,10 @@ export const uploadAssets = Effect.fn(function* (
   workerName: string,
   assets: AssetReadResult,
   { note }: ScopedPlanStatusSession,
+  dispatchNamespace?: string,
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const createScriptAssetUpload = yield* workers.createScriptAssetUpload;
   const createAssetUpload = yield* workers.createAssetUpload;
 
   // Manifest keys are the paths Cloudflare *serves*, so they carry the
@@ -463,11 +464,18 @@ export const uploadAssets = Effect.fn(function* (
   // the completion JWT directly.
   const runSession = Effect.fn(function* () {
     yield* note("Checking assets...");
-    const session = yield* createScriptAssetUpload({
-      accountId,
-      scriptName: workerName,
-      manifest: assets.manifest,
-    });
+    const session = dispatchNamespace
+      ? yield* wfp.createDispatchNamespaceScriptAssetUpload({
+          accountId,
+          dispatchNamespace,
+          scriptName: workerName,
+          manifest: assets.manifest,
+        })
+      : yield* workers.createScriptAssetUpload({
+          accountId,
+          scriptName: workerName,
+          manifest: assets.manifest,
+        });
     if (!session.buckets?.length) {
       if (!session.jwt) {
         return yield* new AssetUploadSessionError({

package/src/Cloudflare/Workers/EmailEventSource.ts

@@ -0,0 +1,348 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { Input } from "../../Input.ts";
+import * as Namespace from "../../Namespace.ts";
+import * as RemovalPolicy from "../../RemovalPolicy.ts";
+import { RuntimeContext } from "../../RuntimeContext.ts";
+import type { FunctionContext } from "../../Serverless/Function.ts";
+import { CatchAll } from "../Email/CatchAll.ts";
+import { Routing } from "../Email/Routing.ts";
+import { Rule, type Matcher } from "../Email/Rule.ts";
+import type { Reference } from "../Zone/lookup.ts";
+import { isWorkerEvent, Worker } from "./Worker.ts";
+
+/**
+ * Effect-native wrapper around Cloudflare's
+ * [`ForwardableEmailMessage`](https://developers.cloudflare.com/email-routing/email-workers/runtime-api/#forwardableemailmessage).
+ *
+ * Follows the same shape as the other Cloudflare bindings (R2, KV, …):
+ *
+ * - `raw` is the underlying `cf.ForwardableEmailMessage` — an escape
+ *   hatch for any field or future API not yet wrapped.
+ * - Ergonomic fields (`from`, `to`, `headers`, `body`, `bodySize`) are
+ *   forwarded verbatim.
+ * - Action methods (`forward`, `reply`, `setReject`) return `Effect`s
+ *   instead of `Promise`/`void`.
+ */
+export interface ForwardableEmailMessage {
+  /** Underlying Cloudflare message — escape hatch for unwrapped APIs. */
+  readonly raw: cf.ForwardableEmailMessage;
+  /** Envelope From address. */
+  readonly from: string;
+  /** Envelope To address. */
+  readonly to: string;
+  /** RFC 5322 headers. */
+  readonly headers: cf.Headers;
+  /** Raw message body stream (RFC 5322 wire bytes). */
+  readonly body: cf.ReadableStream<Uint8Array>;
+  /** Size of the raw message body in bytes. */
+  readonly bodySize: number;
+  /**
+   * Reject this message back to the connecting client with a permanent
+   * SMTP error and the given reason.
+   */
+  setReject(reason: string): Effect.Effect<void>;
+  /**
+   * Forward this message to a verified destination address on the
+   * account. Fails with `EmailError` if Cloudflare rejects the forward
+   * (e.g. unverified destination).
+   */
+  forward(
+    rcptTo: string,
+    headers?: cf.Headers,
+  ): Effect.Effect<void, EmailError>;
+  /**
+   * Reply to the sender with a new outbound message. Fails with
+   * `EmailError` if Cloudflare rejects the reply.
+   */
+  reply(message: cf.EmailMessage): Effect.Effect<void, EmailError>;
+}
+
+export class EmailError extends Data.TaggedError("EmailError")<{
+  action: "forward" | "reply";
+  message: string;
+  cause: unknown;
+}> {}
+
+const wrap = (raw: cf.ForwardableEmailMessage): ForwardableEmailMessage => ({
+  raw,
+  from: raw.from,
+  to: raw.to,
+  headers: raw.headers,
+  body: raw.raw,
+  bodySize: raw.rawSize,
+  setReject: (reason) => Effect.sync(() => raw.setReject(reason)),
+  forward: (rcptTo, headers) =>
+    Effect.tryPromise({
+      try: () => raw.forward(rcptTo, headers),
+      catch: (cause) =>
+        new EmailError({
+          action: "forward",
+          message: `Cloudflare email forward failed: ${formatCause(cause)}`,
+          cause,
+        }),
+    }),
+  reply: (msg) =>
+    Effect.tryPromise({
+      try: () => raw.reply(msg),
+      catch: (cause) =>
+        new EmailError({
+          action: "reply",
+          message: `Cloudflare email reply failed: ${formatCause(cause)}`,
+          cause,
+        }),
+    }),
+});
+
+/**
+ * Whether a subscription's matchers describe the zone's catch-all — either
+ * omitted entirely (the documented default) or a lone `{ type: "all" }`.
+ * Cloudflare models that as a per-zone singleton behind `/rules/catch_all`,
+ * so it maps to `Email.CatchAll` rather than `Email.Rule`.
+ */
+const isCatchAll = (matchers: Matcher[] | undefined): boolean =>
+  matchers === undefined ||
+  (matchers.length === 1 && matchers[0]?.type === "all");
+
+const formatCause = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+/**
+ * Settings for {@link email} — both halves of the consumer in one place.
+ * `zone` opts in to the deploy-time setup: an `Email.Routing` toggle on the
+ * zone plus the routing resource that hands matched mail to the host
+ * Worker. Omit `zone` to manage routing yourself.
+ *
+ * Which routing resource depends on {@link EmailSubscribeProps.matchers}:
+ * a catch-all subscription yields `Email.CatchAll` (Cloudflare models the
+ * zone catch-all as a singleton behind its own endpoint), anything more
+ * specific yields `Email.Rule`.
+ */
+export interface EmailSubscribeProps {
+  /**
+   * Zone to enable email routing on and attach the routing resource to.
+   * Accepts a zone id, a zone name (`example.com`), or a
+   * `{ zoneId, name? }` object (a `Cloudflare.Zone` resource works).
+   * Required to auto-create routing resources; omit if you're managing
+   * `Email.Routing` and `Email.Rule`/`Email.CatchAll` yourself.
+   */
+  zone?: Input<Reference>;
+  /**
+   * Which envelopes Cloudflare delivers to this Worker. Ignored when
+   * `zone` is omitted.
+   *
+   * Omitting this (or passing a lone `{ type: "all" }`) subscribes to the
+   * zone's catch-all, provisioned as `Email.CatchAll`. There is exactly one
+   * catch-all per zone, so a second Worker subscribing to it takes the
+   * zone's mail from the first.
+   *
+   * @default [{ type: "all" }]
+   */
+  matchers?: Matcher[];
+  /**
+   * Display name for the auto-created `Email.Rule` / `Email.CatchAll`.
+   *
+   * @default the host worker's logical id
+   */
+  ruleName?: string;
+  /**
+   * Priority of the auto-created `Email.Rule`. Lower numbers run first.
+   * Ignored for a catch-all subscription — the catch-all is always
+   * evaluated last.
+   *
+   * @default 0
+   */
+  priority?: number;
+  /**
+   * Whether the auto-created `Email.Rule` / `Email.CatchAll` is enabled.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Subscribe to Cloudflare Email Worker events with an Effect handler.
+ *
+ * Wires both halves of the consumer in one call:
+ *
+ * - **Runtime**: registers an `email` event listener on the Worker.
+ *   The handler receives a {@link ForwardableEmailMessage} whose
+ *   action methods (`forward`, `reply`, `setReject`) return `Effect`s.
+ * - **Deploy-time** (when `zone` is set): yields a
+ *   `Cloudflare.Email.Routing` toggle on the zone plus the routing
+ *   resource whose `actions: [{ type: "worker", … }]` targets this
+ *   Worker — `Cloudflare.Email.CatchAll` for a catch-all subscription,
+ *   `Cloudflare.Email.Rule` for anything more specific. No manual
+ *   wiring needed in `alchemy.run.ts`.
+ *
+ * Requires `EmailEventSourceLive` provided on the Worker's Effect.
+ *
+ * **Failure semantics**: a failing handler is logged and the failure is
+ * re-raised. Cloudflare turns that into a temporary SMTP failure, so the
+ * sending server keeps the message and retries later — mail is never
+ * accepted and then silently dropped. Handle the failures you consider
+ * final inside the handler (`Effect.retry`, `Effect.catchTag`, or
+ * `message.setReject(...)` to bounce permanently); anything you let
+ * escape becomes a retryable delivery failure.
+ *
+ * ### Subscribing to Inbound Mail
+ * **Example:** Catch-all on a zone — auto-creates routing + catch-all
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Cloudflare.Worker(
+ *   "Inbox",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* Cloudflare.email({ zone: "example.com" }).subscribe(
+ *       (message) => message.forward("ops@example.com"),
+ *     );
+ *     return {};
+ *   }).pipe(Effect.provide(Cloudflare.EmailEventSourceLive)),
+ * );
+ * ```
+ *
+ * **Example:** Match a specific address
+ * ```typescript
+ * yield* Cloudflare.email({
+ *   zone: "example.com",
+ *   matchers: [{ type: "literal", field: "to", value: "hello@example.com" }],
+ * }).subscribe((message) => message.forward("ops@example.com"));
+ * ```
+ *
+ * **Example:** Reject (bounce) a message
+ * ```typescript
+ * yield* Cloudflare.email({ zone: "example.com" }).subscribe((message) =>
+ *   message.setReject("Mailbox closed"),
+ * );
+ * ```
+ *
+ * **Example:** Bring-your-own routing — no `zone`, no auto-create
+ * ```typescript
+ * // Manage `Email.Routing` / `Email.Rule` yourself in alchemy.run.ts.
+ * yield* Cloudflare.email().subscribe((message) =>
+ *   Effect.log(`from ${message.from}`),
+ * );
+ * ```
+ *
+ * @see https://developers.cloudflare.com/email-routing/email-workers/
+ *
+ * @binding
+ * @product Workers
+ * @category Workers & Compute
+ */
+export const email = (props: EmailSubscribeProps = {}) => ({
+  subscribe: <E = never, Req = never>(
+    process: (message: ForwardableEmailMessage) => Effect.Effect<void, E, Req>,
+  ) => EmailEventSource.use((source) => source(props, process)),
+});
+
+export type EmailEventSourceService = <E = never, Req = never>(
+  props: EmailSubscribeProps,
+  process: (message: ForwardableEmailMessage) => Effect.Effect<void, E, Req>,
+) => Effect.Effect<void, never, never>;
+
+export class EmailEventSource extends Context.Service<
+  EmailEventSource,
+  EmailEventSourceService
+>()("Cloudflare.Workers.EmailEventSource") {}
+
+export const EmailEventSourceLive = Layer.effect(
+  EmailEventSource,
+  Effect.gen(function* () {
+    const host = yield* Worker;
+    return Effect.fn(function* <E, Req>(
+      props: EmailSubscribeProps,
+      process: (
+        message: ForwardableEmailMessage,
+      ) => Effect.Effect<void, E, Req>,
+    ) {
+      // Deploy-time: provision the Email.Routing toggle plus the routing
+      // resource that hands matched mail to this Worker. Skipped once
+      // running inside the deployed Worker (the global guard) and when
+      // `zone` is omitted (bring-your-own routing). Namespaced under the
+      // host so logical identity is stable per Worker.
+      if (!globalThis.__ALCHEMY_RUNTIME__ && props.zone !== undefined) {
+        const zone = props.zone;
+        const matchers = props.matchers;
+        yield* Namespace.push(
+          host.LogicalId,
+          Effect.gen(function* () {
+            // Routing is a per-zone singleton shared with other rules on
+            // the zone, so destroying this Worker must not disable it.
+            yield* Routing("EmailRouting", {
+              zone,
+              enabled: true,
+            }).pipe(RemovalPolicy.retain());
+
+            const action = {
+              type: "worker" as const,
+              value: [host.workerName],
+            };
+
+            // Catch-all is a per-zone SINGLETON living behind
+            // `/rules/catch_all`, not an ordinary rule. Cloudflare surfaces
+            // it in `listRules` but rejects mutating it through the rule
+            // endpoint ("Invalid rule operation"), so creating it as an
+            // `Email.Rule` would produce a row the engine cannot delete.
+            // Route an all-matcher subscription to `Email.CatchAll`
+            // instead — the resource that owns that endpoint.
+            if (isCatchAll(matchers)) {
+              yield* CatchAll("EmailCatchAll", {
+                zone,
+                name: props.ruleName ?? host.LogicalId,
+                enabled: props.enabled ?? true,
+                actions: [action],
+              });
+              return;
+            }
+
+            yield* Rule("EmailRule", {
+              zone,
+              name: props.ruleName ?? host.LogicalId,
+              enabled: props.enabled ?? true,
+              priority: props.priority ?? 0,
+              matchers: matchers!,
+              actions: [action],
+            });
+          }),
+        );
+      }
+
+      // Resolve the runtime context per-call rather than at layer
+      // construction (mirrors `Queues.EventSourceLive`).
+      const ctx = (yield* RuntimeContext) as unknown as FunctionContext;
+      yield* ctx.listen<void, Req>((event) => {
+        if (!isWorkerEvent(event) || event.type !== "email") return;
+
+        const message = wrap(event.input as cf.ForwardableEmailMessage);
+        // Log, then let the failure propagate. Cloudflare turns an
+        // exception out of the `email` handler into a temporary SMTP
+        // failure, so the sending server keeps the message and retries.
+        // Swallowing it here would instead ACCEPT the envelope and then
+        // drop it: a transient dependency outage would silently destroy
+        // mail with nothing left to retry from.
+        return process(message).pipe(
+          Effect.tapCause((cause) =>
+            Effect.sync(() => {
+              console.error(
+                `[EmailEventSource] handler failed for message to ` +
+                  `"${message.to}": ${Cause.pretty(cause)}`,
+              );
+            }),
+          ),
+          // The listener contract is `E = never`, so surface the failure as
+          // a defect rather than discarding it: the invocation fails, which
+          // is what Cloudflare turns into the temporary SMTP failure.
+          Effect.orDie,
+        );
+      });
+    }) as EmailEventSourceService;
+  }),
+);