Skip to content

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:

text
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_failed

Interactive 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.

Email Relay Conceptual Topology (Pan, Zoom & Search)
Open Fullscreen ↗

End-to-End Walkthrough (POST /v1/send) ​

  1. Entry & request ID (src/index.ts): Generates requestId = crypto.randomUUID(), dispatches /healthz, /v1/send, and /v1/panel, and rejects query parameters or unsupported methods (Allow header added on 405).
  2. Framing pre-check (ensureJsonRequest): Enforces application/json media type and refuses any Content-Encoding other than omitted or identity.
  3. Fail-closed configuration (src/config.ts): loadConfig(env) parses AUTH_TOKENS (plus legacy aliases), ALLOWED_SENDER_DOMAINS, IP_ALLOWLIST + IP_ALLOWLIST_ENABLED, MAX_RECIPIENTS, and checks EMAIL.send (plus optional RATE_LIMITER.limit). Any violation returns 503 not_configured and logs configuration_error without exposing secret values.
  4. Source & rate checks (src/ip.ts, src/index.ts): Reads CF-Connecting-IP; rejects missing headers or out-of-range IPs via ipInAllowlist with 403, or logs ip_allowlist_disabled if allowlisting is explicitly turned off. Optionally awaits env.RATE_LIMITER.limit({ key: "ip:" + clientIp }) and returns 429 with Retry-After: 60.
  5. Bounded read & constant-time auth (src/index.ts): Streams the request body up to 128 * 1024 bytes, decodes with TextDecoder("utf-8", { fatal: true }), parses plain JSON object, resolves candidate token (Authorization: Bearer or /v1/panel fallback without ambiguity), and runs tokenMatches over SHA-256 digests without early return.
  6. Payload normalization & EMAIL.send (src/validate.ts, src/log.ts): buildMessage rejects unknown keys, validates UTF-8 byte lengths, normalizes sender/recipient objects, checks allowed sender domains on from and replyTo, deduplicates recipients case-insensitively, constructs the payload (replyTo omitted if absent, cc/bcc omitted when empty), calls env.EMAIL.send(message), logs email_sent or truncated email_send_failed, and wraps the reply with security headers via src/respond.ts.

Next: explore source modules and tests in Code Map & Verification.