AI Translation Notice
This page is a synchronized English overview of Chinese Code Map and repo-docs/code-map.md.
Code Map & Verification
All Worker runtime code lives under src/ with zero external runtime dependencies beyond the Cloudflare Workers runtime APIs and Web Crypto (crypto.subtle).
Source & Test Layout
| File Path | Responsibility | Key Symbols |
|---|---|---|
src/index.ts | Worker default entry, routing (/v1/send, /v1/panel, /healthz), rate limit, bounded body read, SHA-256 XOR auth, EMAIL.send dispatch | default { fetch }, readJsonBody, tokenMatches, sha256 |
src/config.ts | Config parsing, fail-closed loadConfig, /healthz inspectConfig, transitional alias resolution | loadConfig, inspectConfig, parseIpEntry, TOKEN_PATTERN |
src/ip.ts | IPv4/IPv6 parsing (bigint), CIDR mask comparison, normalizeClientIp | parseIpAddress, ipInAllowlist, normalizeClientIp |
src/validate.ts | Strict STANDARD_FIELDS / PANEL_FIELDS validation, UTF-8 byte caps, address & domain normalization, recipient deduplication | buildMessage, isAllowedSenderDomain, normalizeAddress, collectRecipients |
src/errors.ts | Typed domain errors (HttpError, FieldError, ConfigError) mapped cleanly to status codes | HttpError, FieldError, ConfigError |
src/respond.ts | JSON envelopes, /healthz empty-body HEAD handling, and security headers (nosniff, no-store, CSP) | jsonSuccess, jsonError, jsonHealth |
src/log.ts | Structured single-line JSON log emitter that never prints tokens or message contents | logInfo, logWarn, logError |
test/*.test.ts | 86 mocked Vitest assertions covering config, IPv4/IPv6 CIDR matching, validation limits, and full fetch handlers | config.test.ts, ip.test.ts, validate.test.ts, handler.test.ts |
Deployment & Docs Assets
wrangler.jsonc: Public Worker template (name,compatibility_date,send_emailbindingEMAIL, defaultvars). Copy to gitignoredwrangler.local.jsoncfor private addresses and domains..dev.vars.example: Template for local secrets (AUTH_TOKENS,IP_ALLOWLIST, commentedIP_ALLOWLIST_ENABLED). Copy to gitignored.dev.vars.repo-docs/: Source-grounded Chinese architecture guide validated withvalidate_repo_docs.py.docs-site/: Bilingual VitePress documentation site backed bydocs-site/public/diagrams/email-relay-architecture.html.
Contributor Verification Workflow
- Modifying routing or auth (
src/index.ts): Keep onlyexport default, then runpnpm run check && pnpm test && pnpm run devto catch any invalid named exports at Worker startup. - Modifying config or readiness (
src/config.ts): KeeploadConfigandinspectConfigbacked by the same reader helpers and runpnpm test -- test/config.test.ts. - Modifying payload validation (
src/validate.ts): Add matching positive and boundary cases intest/validate.test.tsandtest/handler.test.ts. - Before committing: Ensure git hooks (
tools/repo_maintenance_guard.py) pass, follow Conventional Commits, and verify.dev.varsandwrangler.local.jsoncare absent fromgit status.
Next: review design trade-offs and legacy alias migration in Decisions & Alias Migration.