Skip to content

Commit c114a6e

Browse files
authored
fix(email): resolve live staging acceptance failures (#332)
Live staging acceptance exposed failures in first-time native setup, hosted recipient confirmation, admission timing, and forwarding from nested plus-tag addresses. This makes those paths work through the current email design and removes the retired internal verification transport. - Preserve an exact owned native routing plan while new subdomain MX records propagate; stop before build/upload instead of losing the plan or failing after upload. - Send recipient confirmations through the native email binding and serve confirmation links through the public gateway. Align hosted identities, account-token verification, and installer permissions. - Batch admission queries, use one bounded direct-send deadline with finalization time reserved, and place the hosted API beside its PostgreSQL origins. Preserve idempotency, quota accounting, and unknown-outcome handling. - Accept nested plus tags consistently while retaining project ownership checks. Update the existing design and affected guidance; remove obsolete handlers, helpers, exports, and tests. Validation: complete `vp run test:all` passed (551 files; 10,429 tests passed, 20 skipped), plus focused PostgreSQL admission checks and repeated GPT-5.6-sol xhigh reviews ending with no actionable findings. Real staging/native mail covered To/CC/BCC, consent, retries, conflicts, quotas, policy modes, replies, forwarding, sender isolation, and sibling-domain preservation. The final forward passed SPF/DKIM/DMARC/ARC and its ledger recorded provider acceptance. The reproduced hosted send improved from a 10-second timeout to a confirmed result in 4.9 seconds. Only staging and disposable fixtures were deployed. The previous staging credential and recipient policy were restored. Standalone customer-account relay rotation still needs its separate live acceptance run; three intentionally interrupted sends remain under the existing 24-hour recovery guard. Production configuration was reviewed but not deployed.
1 parent 09b4887 commit c114a6e

58 files changed

Lines changed: 1963 additions & 1992 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/guide/email.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ await sendEmail({
172172

173173
`ok: false` carries either a top-level `error` or a complete per-recipient `deliveries` list. Platform results include an `operationId` when available, and per-recipient `state` distinguishes rejection, reservation, submission, provider acceptance, failure, cancellation, and an unknown outcome.
174174

175-
Provider submissions have a 30-second wait limit and share a 60-second budget per batch. A submission that times out returns `OUTCOME_UNKNOWN`; the provider may still accept it later.
175+
Provider submissions have a 30-second wait limit. Platform `sendEmail` requests are bounded to 60 seconds, including admission and recording the result; native and inbound handler submissions share a 60-second batch budget. A submission that times out returns `OUTCOME_UNKNOWN`; the provider may still accept it later.
176176

177177
Use an idempotency key for sends you may retry:
178178

@@ -524,7 +524,9 @@ Enter (Yes is the default) applies only the `+` rows that are not ready, then th
524524
outbound sendEmail() from support@mail.acme.com
525525
```
526526

527-
On the second deploy every row reads ready: no prompt, no account call, and wrangler reports `Email Routing rules are up to date.` Answer No, and the deploy continues without email.
527+
On the second deploy every row reads ready: no prompt, no account call, and wrangler reports `Email Routing rules are up to date.` Answer No before any setup has been committed, and the deploy continues without email.
528+
529+
DNS can take a few minutes to become visible to the resolver running the deploy. If `void email setup` has already written the exact `addresses` plan but that resolver still sees no subdomain MX, Void preserves the plan and stops before the build or upload. Run `void email status --platform cloudflare`, then retry the deploy after it sees Cloudflare's MX records.
528530

529531
Two rows live in `wrangler.jsonc` rather than in your account, and a deploy that finds every account row ready reconciles them with a plain file write, no prompt: the `addresses` array is rewritten whenever it is not the current derivation (an entry pruned since, a worker rename, a new handler), and `vars.__VOID_EMAIL_FROM` follows a changed `email.from`. Routing rules are `wrangler deploy`'s own work, so a committed `addresses` entry whose rule does not exist yet — the state right after `void email setup` — still reads ready; the address map marks it `(rule created by this deploy)`.
530532

@@ -571,7 +573,7 @@ How handlers become addresses, with `email.from` on `mail.acme.com` under the zo
571573
| `email/_default.ts` | **none** — a catch-all exists only on an apex | `*@acme.com` (the catch-all) |
572574
| `email/[user].ts`, `email/[user]+[tag].ts` (dynamic local part) | **refused** — a dynamic local part needs a catch-all | `*@acme.com` (the catch-all) |
573575

574-
On a subdomain, `email/_default.ts` gets no rule and never runs: mail to any other `@mail.acme.com` address bounces at Cloudflare. The checklist says so in a `!` row, and the handler is absent from the address map.
576+
On a subdomain, `email/_default.ts` gets no rule of its own, so it cannot make arbitrary `@mail.acme.com` addresses reach the worker. Mail admitted by an explicit rule can still fall through to `_default` when no handler pattern matches—for example, bare `support@mail.acme.com` admitted by the rule for `support+anything@`. Addresses that match no Cloudflare rule bounce before the worker runs. The checklist says so in a `!` row, and the handler is absent from the address map.
575577

576578
Inside the worker, a message reaches your handlers exactly as addressed — `support+T-42@mail.acme.com` matches `email/support+[ticket].ts` with `info.params.ticket === "T-42"` — and `setReject`, `forward` and `replyEmail` act on the real message. `replyEmail` defaults `from` to `message.to`, the address on your zone the mail was delivered to.
577579

@@ -602,9 +604,9 @@ deploy: email on mail.acme.com is not set up, and this shell cannot ask.
602604
Run `void email setup --platform cloudflare` once locally, commit wrangler.jsonc, then redeploy — deploying without email.
603605
```
604606

605-
then deploys **without** email. Pass `--require-email` to fail instead. Automatic resource provisioning is not an escape hatch: it creates D1/KV/R2/Queue/Hyperdrive resources, never a mail setup. To read the rows without deploying or being asked anything, run `void email status --platform cloudflare`.
607+
then deploys **without** email. Pass `--require-email` to fail instead. When setup has already committed the exact subdomain `addresses` plan and only its MX records are not visible yet, every deploy stops and preserves that plan until DNS can be verified. Automatic resource provisioning is not an escape hatch: it creates D1/KV/R2/Queue/Hyperdrive resources, never a mail setup. To read the rows without deploying or being asked anything, run `void email status --platform cloudflare`.
606608

607-
So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then writes `wrangler.jsonc`, without deploying), commit `wrangler.jsonc`, and let CI run `void deploy --platform cloudflare --require-email`. With the binding and `addresses` committed, every row reads ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)).
609+
So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then writes `wrangler.jsonc`, without deploying), commit `wrangler.jsonc`, and let CI run `void deploy --platform cloudflare --require-email`. Once the MX records are visible, the committed binding and `addresses` make every row read ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)).
608610

609611
### If the subdomain step is refused
610612

‎docs/guide/self-hosted-platform.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ Use the following permissions for the core platform. Cloudflare may label write
134134

135135
The management token also needs **Zone Edit** with authority to create zones if you ask Void to create the zone. If it already exists, use the selected zone with Zone Read and DNS Edit. Nested application domains additionally need **SSL and Certificates: Read** on the management token. A custom runtime that enables custom project domains needs **SSL and Certificates: Edit** on the runtime token; the core runtime does not enable that feature.
136136

137-
Enabling email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) on the runtime token. That needs **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail, and **Email Sending: Edit** on the account; the token link preselects them when email is enabled. Email Sending onboarding itself needs Workers Paid on the account.
137+
Enabling email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) and lets projects register destination addresses through the runtime token. That needs **Email Routing Addresses: Edit** and **Email Sending: Edit** on the account, plus **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail; the token link preselects them when email is enabled. Email Sending onboarding itself needs Workers Paid on the account.
138138

139139
To enable email, set `VOID_EMAIL_SENDER_DOMAIN` to the shared sender domain and `VOID_EMAIL_SHARED_ZONE_ID` to its Cloudflare zone ID when installing or upgrading. Void records both values for later upgrades and rejects attempts to replace them during an ordinary upgrade. The mail zone can differ from the application zone, but it must belong to the selected platform Cloudflare account; without an explicit mail-zone identity, shared inbound delivery stays unavailable. The dedicated email gateway is deployed in the platform account. Each customer zone uses its own ingress Worker to forward mail to that gateway.
140140

‎docs/reference/cli.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -912,7 +912,7 @@ Provisioning reuses known resource IDs and writes newly resolved IDs into `wrang
912912

913913
Existing remote secrets are preserved. Void also preserves or creates `BETTER_AUTH_SECRET` for auth apps.
914914

915-
**Email.** When the app uses email (`sendEmail()` or `email/` handlers) and `void.json` has `email.from`, the deploy reads the state of that address's zone before the build — session scopes, zone, MX records, Email Routing, subaddressing, routing rules, Email Sending, and what `wrangler.jsonc` holds — prints a checklist of what it would change in your account, and asks once (default Yes). On Yes it enables what is missing, writes `send_email: [{ "name": "SEND_EMAIL" }]`, the `__VOID_EMAIL_FROM` var and the `addresses` array into `wrangler.jsonc`, and lets wrangler create the routing rules when the activated version's triggers are synchronized; the deploy ends with the address map. A deploy with nothing left to set up asks nothing. Without `email.from` the deploy prints `add "email": { "from": "you@mail.acme.com" } to void.json` and continues without email. Non-interactive runs (CI, or stdin/stdout not a terminal) never prompt: they print the checklist plus `Run void email setup --platform cloudflare once locally, commit wrangler.jsonc, then redeploy` and deploy without email (or with the setup `wrangler.jsonc` already carries, when the binding is committed; a committed `addresses` array whose routing is off is removed first, since wrangler's plan on it would fail after the upload) — unless `--require-email` is passed, which fails instead. A deploy whose account rows all read ready reconciles the two config rows — `addresses` against the current derivation and `vars.__VOID_EMAIL_FROM` against `email.from` — with a plain file write and no prompt. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account) for the whole flow, including the subdomain-vs-apex rule and what stays manual.
915+
**Email.** When the app uses email (`sendEmail()` or `email/` handlers) and `void.json` has `email.from`, the deploy reads the state of that address's zone before the build — session scopes, zone, MX records, Email Routing, subaddressing, routing rules, Email Sending, and what `wrangler.jsonc` holds — prints a checklist of what it would change in your account, and asks once (default Yes). On Yes it enables what is missing, writes `send_email: [{ "name": "SEND_EMAIL" }]`, the `__VOID_EMAIL_FROM` var and the `addresses` array into `wrangler.jsonc`, and lets wrangler create the routing rules when the activated version's triggers are synchronized; the deploy ends with the address map. A deploy with nothing left to set up asks nothing. Without `email.from` the deploy prints `add "email": { "from": "you@mail.acme.com" } to void.json` and continues without email. Non-interactive runs (CI, or stdin/stdout not a terminal) never prompt: they print the checklist plus `Run void email setup --platform cloudflare once locally, commit wrangler.jsonc, then redeploy` and deploy without email (or with the setup `wrangler.jsonc` already carries, when the binding is committed) — unless `--require-email` is passed, which fails instead. If setup has committed the exact subdomain `addresses` plan but the deploy's resolver still sees no MX records, Void preserves the plan and stops before build or upload until DNS can be verified. A deploy whose account rows all read ready reconciles the two config rows — `addresses` against the current derivation and `vars.__VOID_EMAIL_FROM` against `email.from` — with a plain file write and no prompt. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account) for the whole flow, including the subdomain-vs-apex rule and what stays manual.
916916

917917
See the [Cloudflare guide](../integrations/cloudflare.md#deploy-to-your-own-cloudflare-account) for the complete deployment sequence, first-deploy exceptions, secret precedence, and recovery behavior.
918918

‎packages/platform/src/worker-config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ export function createPlatformWorkerConfigs(input: {
108108
placement: { mode: 'smart' },
109109
hyperdrive: [{ binding: 'HYPERDRIVE', id: resources.hyperdrive }],
110110
kv_namespaces: kv,
111+
...(deployment.capabilities.email ? { send_email: [{ name: 'EMAIL' }] } : {}),
111112
r2_buckets: r2,
112113
dispatch_namespaces: dispatchNamespace,
113114
durable_objects: {

‎packages/platform/test/unit/worker-config.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ describe('platform usage queue bindings', () => {
4545
application: { baseDomain: 'apps.example.com', zoneName: 'example.com' },
4646
emailSharedZoneId: 'mail-zone-id',
4747
emailSenderDomain: 'mail.example.org',
48+
authentication: { accessProtection: true },
4849
capabilities: { email: true },
4950
displayName: 'Example',
5051
installationSlug: 'example',
@@ -85,8 +86,12 @@ describe('platform usage queue bindings', () => {
8586
expect(configs.api.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org');
8687
expect(configs.proxy.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org');
8788
expect(configs.emailGateway.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org');
89+
expect(configs.api).toHaveProperty('send_email', [{ name: 'EMAIL' }]);
8890
expect(configs.emailGateway).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]);
8991
expect(configs.proxy).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]);
92+
expect(configs.api.workers_dev).toBe(false);
93+
expect(configs.proxy.workers_dev).toBe(false);
94+
expect(configs.emailGateway.workers_dev).toBe(true);
9095
expect(configs.api.compatibility_flags).toContain('global_fetch_strictly_public');
9196
expect(configs.api.vars).toHaveProperty(
9297
'EMAIL_GATEWAY_ORIGIN',
@@ -167,6 +172,7 @@ describe('platform usage queue bindings', () => {
167172
expect(configs.proxy.services).toEqual([
168173
{ binding: 'API', service: deployment.resources.apiWorker },
169174
]);
175+
expect(configs.api).not.toHaveProperty('send_email');
170176
expect(configs.proxy).not.toHaveProperty('send_email');
171177
expect(configs.emailGateway).not.toHaveProperty('send_email');
172178
expect(Object.keys(configs).sort()).toEqual([

0 commit comments

Comments
 (0)