Skip to content

请求链路与交互架构图 ​

本页先展示代码核实后的请求处理管线与保留的交互式拓扑画布,再直接同步仓库源码指南中的一次真实请求走读,让你从输入到 EMAIL.send 绑定建立端到端的运行心智模型。

真实请求流转全景 ​

Worker 入口在 src/index.ts 中严格按「低开销预检 → 服务端配置与边缘守门 → 有界体读入与常数时间鉴权 → 字段校验 → 平台发送」的顺序处理请求,确保每一步拒绝都指向明确的责任归属:

text
POST /v1/send 或 /v1/panel
  │
  ├─► [1] 路由与协议外框:无 query / application/json / 非压缩        ──► 404 / 405 / 400 / 415
  │
  ├─► [2] 配置与边缘守门:loadConfig() + CF-Connecting-IP + RATE_LIMITER ──► 503 / 403 / 429
  │
  ├─► [3] 有界体读入:流式 <= 128 KiB + 严格 UTF-8 + JSON 普通对象       ──► 413 / 400
  │
  ├─► [4] 常数时间鉴权:Bearer 头 (或 /v1/panel body.token) 全令牌异或  ──► 401 / 400 credentials_ambiguous
  │
  ├─► [5] 字段与字节归一化:未知字段 / 域名 / 收件人去重 / UTF-8 上限    ──► 400 invalid_field
  │
  └─► [6] 平台发信:env.EMAIL.send(message)                            ──► 200 (messageId) / 502 upstream_failed

交互式概念拓扑画布 ​

静态拓扑资产对齐说明

以下嵌入的是仓库中保留的 Archify 静态拓扑图(docs-site/public/diagrams/email-relay-architecture.html),可用于缩放浏览概念分层;但其中部分历史标注(例如 POST /send-email、模板渲染、Resend/MailChannels)并不代表当前代码实现。当前真实路由、绑定与模块关系以上方流转图及下方源码走读为准。

邮件中继服务概念拓扑画布(支持平移、缩放与节点探查)

沿一次真实发信请求走到底 ​

设想一条持续集成构建失败告警场景:调用方携带承载发信凭据的授权请求头,向标准发送端点提交一份包含发件人、收件人与正文内容的请求,期望服务将其转发给平台底层邮件绑定并返回受理回执。

这条路径的难点在于必须把调用方写错、服务端配置失效与上游发信拒收三类故障严格拆开:既不能在未确认请求者身份前就暴露字段级校验细节,也不能在服务端漏配白名单或发件域时放行请求或误报健康探针绿灯。成功走通时,服务返回带有唯一追踪标识、平台消息编号与规范化收件人清单的 JSON 响应,同时写出一条不含任何令牌与邮件正文的审计日志。

Step 1: 路由分流与廉价前置检查 ​

请求进入后,入口先按路径与请求方法分流:体检探针路径只放行读取或头部探测方法,发送路径限定使用 POST,兼容面板的旧接口单独分往面板路径,其余路径或方法直接返回 404 或 405。进入发送处理前,系统先以极低成本挡掉不符合传输协议外形的请求:携带查询参数、媒体类型不是 JSON 或带非直传压缩编码的报文,会直接以 400 或 415 拒绝,不消耗后续读取报文体的开销。

这一步由请求编排入口(仓库文件:src/index.ts)中的 fetch 与 assertJsonRequest 承担。对于体检路径,详情见配置解析、过渡别名与健康体检。

Step 2: 读取配置、核验来源 IP 与可选限流 ​

通过外层协议检查后,服务一次性解析整份环境变量与绑定配置,并据此判定来源准入与限流。只要令牌、发件域、收件人上限或 IP 白名单中任何一项缺失或格式写坏,服务立刻抛出服务端配置异常并对外返回 503,而不会在响应里回显写错的配置值。

json
{
  "from": "noreply@example.com",
  "to": "ops@example.org",
  "subject": "构建失败",
  "text": "构建任务第 42 号异常退出,请查看控制台日志。"
}

来源检查把「缺少边缘来源头」与「来源不在允许名单」都拦在 403,即使通过总开关关掉白名单拦截,请求依然必须带有边缘写入的客户端地址头,且每次放行都会记录一条告警日志留痕。之后若部署侧绑定了限流器,则按客户端 IP 扣减配额,超限时返回 429 与重试等待秒数;若限流器绑定存在但方法不可用或调用异常,则视为服务端配置损坏返回 503。来源算法与切换规则详见来源限制、限流与多令牌轮换机制。

Step 3: 读入有界 JSON 并完成常数时间鉴权 ​

确认来源与配额后,处理流逐块读取请求体,累加字节计数并在超过 128 KiB 时立刻取消流读取、返回 413;随后使用严格 UTF-8 解码器转文本并解析为 JSON 普通对象,非法字节、语法错误或数组/原始值根节点统一返回 400。之所以在鉴权前先读入请求体,是因为兼容旧面板的路线无法设置请求头,只能把令牌放在报文体里。

读取对象后,鉴权层按路由读取凭据:标准路线只认请求头里的 Bearer 凭据(方案名大小写不敏感),面板路线在请求头未带有效 Bearer 时允许读取报文体令牌;若面板路线同时提供两处有效形态凭据,直接返回 400 凭据二义错误而不猜测优先级。最终候选取向会与已配置的所有合法令牌逐个计算摘要并做逐字节异或比对,确保轮换期新旧多把令牌都能命中且耗时不泄漏命中的是第几把;未通过一律返回 401,此时尚不检验邮件业务字段。

Step 4: 校验邮件字段并交付发信绑定 ​

只有穿过鉴权的合法调用方才会进入业务字段归一化:系统拒绝任何协议外未知字段,校验 from 与 replyTo 的域名是否在允许发件域内,在 to、cc、bcc 三者间共享收件人数预算并做不区分大小写的跨字段去重,同时严格按 UTF-8 字节数截断主题、显示名与正文上限,禁止控制字符及可能伪造显示名的定界字符。

mermaid
flowchart LR
    REQ["POST /v1/send 或 /v1/panel"] --> PRE["协议外框检查: 无 query / JSON / <=128 KiB"]
    PRE --> IP["加载配置与来源限流: 503 / 403 / 429"]
    IP --> AUTH["常数时间多令牌鉴权: 401 / 400"]
    AUTH --> VAL["字段与字节归一化: 400 invalid_field"]
    VAL --> SEND["调用 EMAIL.send 绑定"]
    SEND -->|"成功"| OK["200 + messageId + accepted"]
    SEND -->|"上游拒收"| ERR["502 upstream_failed + providerCode"]

图中展示了请求从传输预检到发信绑定的不可逆串联关系。值得注意的是,服务刻意不忽略未知字段,也不支持附件或自定义邮件头,避免调用方拼错字段却误以为生效。规则细节与两套报文字段对照见报文校验、字节上限与地址归一化,核心实现位于字段校验与归一化模块(仓库文件:src/validate.ts)。

运行结果分支HTTP 状态码与错误码返回给调用方的关键信息服务端日志行为
凭据缺失或错误401(unauthorized)WWW-Authenticate: Bearer 头,不泄露字段错误不记录错误令牌原文
环境变量或绑定缺失/损坏503(not_configured)仅提示服务端未正确配置,不回显具体坏值configuration_error 记录脱敏原因
字段拼错、超字节或未知字段400(invalid_field)error.field 精确指明出错字段名或下标不记录正文或完整请求体
平台发信绑定拒绝502(upstream_failed)仅带截断后的 providerCode,不透传上游原文email_send_failed 记录 providerCode
平台绑定接受请求200返回 messageId 与规范化 accepted 列表email_sent 记录路由、收件人数与 messageId

Step 5: 用离线单测与本地仿真验证全链路 ​

通过 fetch 入口注入模拟 EMAIL 绑定与模拟 RATE_LIMITER,单元测试可以在无账号、无外网环境下覆盖从预检拒绝、白名单放行、多令牌轮换到上游 502 异常的完整分支;需要修改代码或核对本地运行时入口导出约束(入口文件只能存在 default 导出,具名常量会导致 Workers 运行时启动失败)时,可执行以下命令:

sh
pnpm run check
pnpm test

单测实现位于处理器管线回归测试(仓库文件:test/handler.test.ts)与配置就绪回归测试(仓库文件:test/config.test.ts)。若需进一步按职责定位源码或审核各条结论的依据,可前往按职责寻找源码与测试入口与两遍源码证据账本。

证据状态:除特别标注外,本页基于当前源码已确认。


需要快速定位 src/ 与 test/ 下的各源文件及改动入口,请继续阅读 源码地图与开发验证 或 架构决策与兼容迁移。