import type * as cf from "@cloudflare/workers-types";
import type { Input } from "alchemy/Input";
import * as Namespace from "alchemy/Namespace";
import * as RemovalPolicy from "alchemy/RemovalPolicy";
import type { FunctionContext } from "alchemy/Runtime/Function";
import { RuntimeContext } from "alchemy/RuntimeContext";
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 { 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.run/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;
}),
);