Skip to content

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/send uses Authorization: Bearer, whereas /v1/panel supports legacy panels that can only embed token inside JSON payloads.
  • Decision: Read the bounded (<= 128 KiB), strict-UTF-8 JSON body prior to tokenMatches, while keeping buildMessage (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 (receiving 401 instead), and providing credentials in both header and body on /v1/panel fails with 400 credentials_ambiguous.

ADR-02: Fail-Closed Source Filtering With Explicit Disable Flag ​

  • Context: Earlier patterns overloaded empty IP_ALLOWLIST or "*" to skip IP checks, blurring accidental misconfiguration with deliberate bypasses.
  • Decision: Empty IP_ALLOWLIST while enforced throws ConfigError (503). Introducing IP_ALLOWLIST_ENABLED=0 still requires CF-Connecting-IP, still parses non-empty allowlist entries for syntax errors, and emits a per-request ip_allowlist_disabled warning 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 .length checks causes lost recipients or oversized multi-byte payloads.
  • Decision: Enforce closed sets (STANDARD_FIELDS, PANEL_FIELDS) returning 400 invalid_field, measure all string caps via TextEncoder UTF-8 bytes, and preserve English error.message strings 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 !== undefined would report 200 even when a secret or CIDR entry is malformed and /v1/send fails with 503.
  • Decision: Both loadConfig and inspectConfig invoke the exact same parsers (readTokens, readSenderDomains, readIpAllowlist, readMaxRecipients), and an optional RATE_LIMITER fails readiness if bound without a valid limit function.
  • Trade-off: Eliminates false-green /healthz probes in production.

Legacy Variable Aliases & Cutover Plan ​

src/config.ts temporarily merges legacy aliases alongside standard variable names during migration:

Legacy Name / FormStandard NameCompatibility & Cutover Guidance
AUTH_TOKEN, WEBHOOK_TOKENAUTH_TOKENSMerged and deduplicated with AUTH_TOKENS; copy active tokens into AUTH_TOKENS first, then remove old secrets
SENDER_DOMAINALLOWED_SENDER_DOMAINSMerged 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 ​

  1. Deploy this Worker alongside the legacy Worker on a staging workers.dev URL with verified Cloudflare sender/destination addresses configured in send_email.
  2. Put both the existing token and newly generated 32+ character tokens into AUTH_TOKENS (comma-separated), then migrate callers onto POST /v1/send (or POST /v1/panel temporarily for headerless legacy panels).
  3. Confirm GET /healthz returns 200 and verify email_sent JSON logs in wrangler tail before retiring the legacy Worker and deleting alias secrets.