AI Translation Notice
This page is synchronized with the Chinese Decisions & Migration guide. Refer to the Chinese edition as the primary authority in case of discrepancy.
Decisions & Alias Migration
This page records the key architectural trade-offs made in the codebase and how to migrate safely from legacy Worker configurations and environment variable aliases.
Architecture Decision Records (ADR)
ADR-01: Bounded JSON Read Before Auth, Business Validation Strictly After Auth
- Context:
/v1/sendusesAuthorization: Bearer, whereas/v1/panelsupports legacy panels that can only embedtokeninside JSON payloads. - Decision: Read the bounded (
<= 128 KiB), strict-UTF-8 JSON body prior totokenMatches, while keepingbuildMessage(field allowlists, sender domain checks, recipient limits) strictly after authentication succeeds. - Trade-off: Unauthenticated requests cannot probe allowed domains or field rules via
400 invalid_field(receiving401instead), and providing credentials in both header and body on/v1/panelfails with400 credentials_ambiguous.
ADR-02: Fail-Closed Source Filtering With Explicit Disable Flag
- Context: Earlier patterns overloaded empty
IP_ALLOWLISTor"*"to skip IP checks, blurring accidental misconfiguration with deliberate bypasses. - Decision: Empty
IP_ALLOWLISTwhile enforced throwsConfigError(503). IntroducingIP_ALLOWLIST_ENABLED=0still requiresCF-Connecting-IP, still parses non-empty allowlist entries for syntax errors, and emits a per-requestip_allowlist_disabledwarning log. - Trade-off: Slightly higher log volume on bypassed requests in exchange for isolated per-request auditability (no shared Worker isolate state) and zero silent fail-open gaps.
ADR-03: Strict Unknown-Field Rejection & UTF-8 Byte Accounting
- Context: Silent ignoring of misspelled keys (
ccs) or UTF-16.lengthchecks causes lost recipients or oversized multi-byte payloads. - Decision: Enforce closed sets (
STANDARD_FIELDS,PANEL_FIELDS) returning400 invalid_field, measure all string caps viaTextEncoderUTF-8 bytes, and preserve Englisherror.messagestrings as a stable client contract. - Trade-off: Zero tolerance for typoed keys yields immediate integration feedback and predictable memory envelopes.
ADR-04: Shared Parsers Between Request Path & /healthz
- Context: Readiness probes checking only
!== undefinedwould report200even when a secret or CIDR entry is malformed and/v1/sendfails with503. - Decision: Both
loadConfigandinspectConfiginvoke the exact same parsers (readTokens,readSenderDomains,readIpAllowlist,readMaxRecipients), and an optionalRATE_LIMITERfails readiness if bound without a validlimitfunction. - Trade-off: Eliminates false-green
/healthzprobes in production.
Legacy Variable Aliases & Cutover Plan
src/config.ts temporarily merges legacy aliases alongside standard variable names during migration:
| Legacy Name / Form | Standard Name | Compatibility & Cutover Guidance |
|---|---|---|
AUTH_TOKEN, WEBHOOK_TOKEN | AUTH_TOKENS | Merged and deduplicated with AUTH_TOKENS; copy active tokens into AUTH_TOKENS first, then remove old secrets |
SENDER_DOMAIN | ALLOWED_SENDER_DOMAINS | Merged and normalized; remember bare domains and wildcards must both be listed (example.com,*.example.com) |
IP_ALLOWLIST="*" | IP_ALLOWLIST_ENABLED="0" | Still disables IP filtering unless combined with IP_ALLOWLIST_ENABLED=1 (rejected with 503); switch to IP_ALLOWLIST_ENABLED="0" to preserve allowlist entries |
Zero-Downtime Worker Cutover Steps
- Deploy this Worker alongside the legacy Worker on a staging
workers.devURL with verified Cloudflare sender/destination addresses configured insend_email. - Put both the existing token and newly generated 32+ character tokens into
AUTH_TOKENS(comma-separated), then migrate callers ontoPOST /v1/send(orPOST /v1/paneltemporarily for headerless legacy panels). - Confirm
GET /healthzreturns200and verifyemail_sentJSON logs inwrangler tailbefore retiring the legacy Worker and deleting alias secrets.