AI Translation Notice
This page is a concise English summary synchronized with Chinese architecture walkthrough and repo-docs/walkthroughs/one-real-run.md.
Request Flow & Topology
This page connects the verified Worker request pipeline, the preserved interactive concept canvas, and an end-to-end execution walkthrough of POST /v1/send.
Verified Six-Stage Request Pipeline
src/index.ts orders checks from cheapest framing guards to configuration, edge gating, bounded parsing, constant-time authentication, field validation, and finally upstream delivery:
POST /v1/send or /v1/panel
│
├─► [1] Route & HTTP framing: no query / application/json / no compression ──► 404 / 405 / 400 / 415
│
├─► [2] Config & edge guards: loadConfig() + CF-Connecting-IP + RATE_LIMITER ──► 503 / 403 / 429
│
├─► [3] Bounded body reader: stream <= 128 KiB + strict UTF-8 + plain object ──► 413 / 400
│
├─► [4] Constant-time auth: Bearer header (or /v1/panel token) SHA-256 XOR ──► 401 / 400 credentials_ambiguous
│
├─► [5] Schema & UTF-8 limits: unknown fields / sender domains / dedup ──► 400 invalid_field
│
└─► [6] Platform dispatch: env.EMAIL.send(message) ──► 200 (messageId) / 502 upstream_failedInteractive Concept Topology
Static Topology Canvas Calibration
The embedded Archify HTML canvas below (docs-site/public/diagrams/email-relay-architecture.html) is preserved as a visual overview asset. Some historical text labels inside that static HTML file (e.g., POST /send-email, template renderer, external provider names) do not reflect the actual codebase; treat the pipeline above and the walkthrough below as authoritative.
End-to-End Walkthrough (POST /v1/send)
- Entry & request ID (
src/index.ts): GeneratesrequestId = crypto.randomUUID(), dispatches/healthz,/v1/send, and/v1/panel, and rejects query parameters or unsupported methods (Allowheader added on405). - Framing pre-check (
ensureJsonRequest): Enforcesapplication/jsonmedia type and refuses anyContent-Encodingother than omitted oridentity. - Fail-closed configuration (
src/config.ts):loadConfig(env)parsesAUTH_TOKENS(plus legacy aliases),ALLOWED_SENDER_DOMAINS,IP_ALLOWLIST+IP_ALLOWLIST_ENABLED,MAX_RECIPIENTS, and checksEMAIL.send(plus optionalRATE_LIMITER.limit). Any violation returns503 not_configuredand logsconfiguration_errorwithout exposing secret values. - Source & rate checks (
src/ip.ts,src/index.ts): ReadsCF-Connecting-IP; rejects missing headers or out-of-range IPs viaipInAllowlistwith403, or logsip_allowlist_disabledif allowlisting is explicitly turned off. Optionally awaitsenv.RATE_LIMITER.limit({ key: "ip:" + clientIp })and returns429withRetry-After: 60. - Bounded read & constant-time auth (
src/index.ts): Streams the request body up to128 * 1024bytes, decodes withTextDecoder("utf-8", { fatal: true }), parses plain JSON object, resolves candidate token (Authorization: Beareror/v1/panelfallback without ambiguity), and runstokenMatchesover SHA-256 digests without early return. - Payload normalization &
EMAIL.send(src/validate.ts,src/log.ts):buildMessagerejects unknown keys, validates UTF-8 byte lengths, normalizes sender/recipient objects, checks allowed sender domains onfromandreplyTo, deduplicates recipients case-insensitively, constructs the payload (replyToomitted if absent,cc/bccomitted when empty), callsenv.EMAIL.send(message), logsemail_sentor truncatedemail_send_failed, and wraps the reply with security headers viasrc/respond.ts.
Next: explore source modules and tests in Code Map & Verification.