AI Translation Notice
This page is synchronized with the Chinese configuration reference. Refer to the Chinese version as the primary authority in case of discrepancy.
Config Matrix, /healthz & FAQ
This guide documents all bindings, plain vars, and encrypted secrets validated by src/config.ts, how /healthz mirrors fail-closed runtime validation, and how to diagnose deployment errors.
Bindings & Environment Matrix
Place non-secret settings in wrangler.jsonc (or wrangler.local.jsonc) under vars, and inject secrets via .dev.vars locally or wrangler secret put in production:
| Binding / Variable | Type & Secret Tier | Validation & Default Behavior | Transitional Aliases |
|---|---|---|---|
EMAIL | send_email binding | Required; must expose callable EMAIL.send(...) | None |
RATE_LIMITER | ratelimits binding (optional) | No rate limiting when absent; if configured, must expose callable limit(...) or service returns 503 | None |
AUTH_TOKENS | Secret (comma-separated) | At least 1 token, deduplicated; each entry must match [A-Za-z0-9._~+/=-]{32,512} | AUTH_TOKEN, WEBHOOK_TOKEN |
ALLOWED_SENDER_DOMAINS | Plain vars (comma-separated) | At least 1 valid domain; *.example.com matches subdomains only, never bare example.com | SENDER_DOMAIN |
IP_ALLOWLIST | Secret (comma-separated) | Accepts IPv4, IPv6, or CIDR (/32 or /128 implied when prefix omitted); empty while enforced triggers 503 | * (legacy disable marker) |
IP_ALLOWLIST_ENABLED | Plain vars boolean | Empty defaults to enabled; accepts 1/true/yes/on and 0/false/no/off (case-insensitive) | None |
MAX_RECIPIENTS | Plain vars integer | Defaults to 10; must be an integer between 1 and 50 covering total to + cc + bcc | None |
Existing Allowlist Entries Are Still Parsed When Disabled
Even when IP_ALLOWLIST_ENABLED=0, any non-empty IP_ALLOWLIST entries are still parsed strictly so latent CIDR typos are caught immediately rather than when re-enabling protection. Combining IP_ALLOWLIST="*" with IP_ALLOWLIST_ENABLED=1 is rejected with 503.
Dynamic CI Runner IP Options
Cloud-hosted CI runners frequently change egress IP addresses across builds; allowlisting broad cloud IP ranges effectively disables source filtering and still yields intermittent 403 failures. Choose one of two patterns:
- Disable allowlist checks while retaining token auth and rate limiting: Set
IP_ALLOWLIST_ENABLED=0and configureRATE_LIMITER. Requests still require Cloudflare's edgeCF-Connecting-IPheader and emit a per-requestip_allowlist_disabledwarning log for audit visibility. - Route CI traffic through a static-egress proxy: Forward outbound webhook/email requests through an internal proxy with a fixed public IP and keep that static IP in
IP_ALLOWLIST.
/healthz Seven-Check Readiness Semantics
GET /healthz and HEAD /healthz (supporting curl -I) invoke inspectConfig(env), sharing the exact same parsers as loadConfig(env). Any missing or malformed mandatory configuration, or a broken optional RATE_LIMITER, fails closed with 503 not_configured. Only booleans are returned—raw config values are never echoed.
checks Key | Condition for true | Causes 503 When false? |
|---|---|---|
config | All four groups (tokens, sender domains, IP config, MAX_RECIPIENTS) parsed cleanly | Yes |
authTokens | At least 1 valid token resolved (including aliases) | Yes |
senderDomains | At least 1 valid sender domain resolved (including alias) | Yes |
ipAllowlist | Valid IP configuration (non-empty and valid when enforced; empty allowed or valid when disabled) | Yes |
ipAllowlistEnforced | Source IP allowlist check is actively enforced (false if explicitly disabled or invalid) | No (intentional disable is healthy) |
emailBinding | EMAIL binding exists with a callable send function | Yes |
rateLimiter | RATE_LIMITER is bound and exposes a callable limit function (false when unbound) | No when unbound (bound-but-broken sets ready=false) |
Deployment & Operations Troubleshooting FAQ
| Symptom | Common Root Cause | How to Inspect | Resolution |
|---|---|---|---|
Both /healthz and /v1/send return 503 not_configured | Missing AUTH_TOKENS or ALLOWED_SENDER_DOMAINS, empty IP_ALLOWLIST while enabled, or malformed IP/CIDR entry (e.g., /99 or %eth0 zone id) | Check which field is false in GET /healthz error.details.checks, or view configuration_error in wrangler tail | Upload valid secrets with wrangler secret put, or set IP_ALLOWLIST_ENABLED=0 explicitly if intentionally disabling IP checks |
Request fails with 502 upstream_failed | Sender/recipient passes domain policy yet is absent or unverified in wrangler.jsonc send_email binding, or running locally in wrangler dev | Inspect truncated error.details.providerCode and send_email lists in Wrangler config | Verify addresses in Cloudflare Email Service and sync allowed_sender_addresses / allowed_destination_addresses (expected in local wrangler dev) |
IP_ALLOWLIST_ENABLED=0 still returns 403 forbidden | Request bypassed Cloudflare edge proxy or local mock test omitted CF-Connecting-IP | Confirm whether CF-Connecting-IP header reaches the Worker | Route production calls via Cloudflare Workers; ensure local harness supplies CF-Connecting-IP |
Calls from Windows terminal return 400 invalid_request (must be valid UTF-8) | Windows shell sent non-UTF-8 inline command bytes | Inspect error.message for UTF-8 error text | Save JSON payload as a UTF-8 file and pass curl --data-binary @payload.json |
pnpm run dev crashes with Incorrect type for map entry | A named export was added to src/index.ts alongside default | Inspect exports in src/index.ts | Move shared helpers/constants to other modules and keep only export default { fetch } in src/index.ts |
Next: review HTTP routes, token hashing, and schema rules in HTTP Contracts, Security & FAQ.