Skip to content

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 PathResponsibilityKey Symbols
src/index.tsWorker default entry, routing (/v1/send, /v1/panel, /healthz), rate limit, bounded body read, SHA-256 XOR auth, EMAIL.send dispatchdefault { fetch }, readJsonBody, tokenMatches, sha256
src/config.tsConfig parsing, fail-closed loadConfig, /healthz inspectConfig, transitional alias resolutionloadConfig, inspectConfig, parseIpEntry, TOKEN_PATTERN
src/ip.tsIPv4/IPv6 parsing (bigint), CIDR mask comparison, normalizeClientIpparseIpAddress, ipInAllowlist, normalizeClientIp
src/validate.tsStrict STANDARD_FIELDS / PANEL_FIELDS validation, UTF-8 byte caps, address & domain normalization, recipient deduplicationbuildMessage, isAllowedSenderDomain, normalizeAddress, collectRecipients
src/errors.tsTyped domain errors (HttpError, FieldError, ConfigError) mapped cleanly to status codesHttpError, FieldError, ConfigError
src/respond.tsJSON envelopes, /healthz empty-body HEAD handling, and security headers (nosniff, no-store, CSP)jsonSuccess, jsonError, jsonHealth
src/log.tsStructured single-line JSON log emitter that never prints tokens or message contentslogInfo, logWarn, logError
test/*.test.ts86 mocked Vitest assertions covering config, IPv4/IPv6 CIDR matching, validation limits, and full fetch handlersconfig.test.ts, ip.test.ts, validate.test.ts, handler.test.ts

Deployment & Docs Assets ​

  • wrangler.jsonc: Public Worker template (name, compatibility_date, send_email binding EMAIL, default vars). Copy to gitignored wrangler.local.jsonc for private addresses and domains.
  • .dev.vars.example: Template for local secrets (AUTH_TOKENS, IP_ALLOWLIST, commented IP_ALLOWLIST_ENABLED). Copy to gitignored .dev.vars.
  • repo-docs/: Source-grounded Chinese architecture guide validated with validate_repo_docs.py.
  • docs-site/: Bilingual VitePress documentation site backed by docs-site/public/diagrams/email-relay-architecture.html.

Contributor Verification Workflow ​

  1. Modifying routing or auth (src/index.ts): Keep only export default, then run pnpm run check && pnpm test && pnpm run dev to catch any invalid named exports at Worker startup.
  2. Modifying config or readiness (src/config.ts): Keep loadConfig and inspectConfig backed by the same reader helpers and run pnpm test -- test/config.test.ts.
  3. Modifying payload validation (src/validate.ts): Add matching positive and boundary cases in test/validate.test.ts and test/handler.test.ts.
  4. Before committing: Ensure git hooks (tools/repo_maintenance_guard.py) pass, follow Conventional Commits, and verify .dev.vars and wrangler.local.jsonc are absent from git status.

Next: review design trade-offs and legacy alias migration in Decisions & Alias Migration.