Repository navigation
Commit 5cdaf9a
fix(plugin-email): a malformed recipient address answers 400 VALIDATION_FAILED, not 500 (#29250)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9RaqxGhqh8FisCVMZz6zHXb)_
Fixes #29152
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:发邮件接口收到格式错误的收件人地址(`to` / `cc` / `bcc` / `replyTo`,含空
`to`、列表里一个坏地址、显示名不是字符串)时,现在回 400 `VALIDATION_FAILED` 并点名哪个字段哪个地址,不再回 500
`EMAIL_SEND_FAILED`。
- 为什么改:调用方自己能改正的输入不该报 500(18.3.0 发版清单 email-template-render 验收第 7 条);500
会让集成方和自动化作者以为是服务器坏了。
- 风险与回滚:只改 plugin-email
的收件人校验报错分类,接受哪些地址的判据一字未改;配置错误的发件人(`OS_EMAIL_FROM` / 邮件设置)仍按服务端故障回
500;被拒的发送照旧写一条 `failed` 的 sys_email 记录。回滚即 revert 本 PR。
- 先看:`packages/plugins/plugin-email/src/email-service.ts` 的
`formatCallerAddress`(新增的拒收分类);`packages/rest/src/email-send-door-bounds.test.ts`
新的一组线上钉子。
- 两分钟验证:`pnpm --filter @objectstack/plugin-email exec vitest run
src/email-service.test.ts` 与 `pnpm --filter @objectstack/rest exec
vitest run src/email-send-door-bounds.test.ts`,预期全绿。
- 需要你做的:无,席位落地。
## What changes
- `normalizeMessage` (`@objectstack/plugin-email`) judges every
CALLER-supplied address (`to`, `cc`, `bcc`, `replyTo`) through a new
`formatCallerAddress`. Same acceptance as before (`isSendableAddress`,
which shares `EMAIL_REGEX` with `formatAddress`); a refusal is now
`VALIDATION_FAILED: invalid recipient address in FIELD: ADDRESS`
(`invalid reply-to address` for `replyTo`). That is the spelling the
REST send door already reads for its existing 400
(`message.startsWith('VALIDATION_FAILED')` in `email-routes.ts`, the
same branch that answers `subject: ""` today), so the door needed no
source change.
- A non-string display name on a caller address (a JSON body can carry
any value there) failed inside `formatAddress` as a `TypeError`
("obj.name?.trim is not a function"), which the door answers 500. It is
now the same `VALIDATION_FAILED` refusal. This is an in-place fix of the
same defect class in the same file, named here per the bounded-fix rule;
evidence is the ablation below.
- The SENDER keeps `formatAddress`'s plain `Invalid email address`
throw. `from` is the deployment's configured sender (`OS_EMAIL_FROM`,
Settings → Mail): the REST door already refuses a body `from` that is
not the configured address with 403 and otherwise forwards the
configured value, so an unsendable `from` is never the caller's input
and stays a 500.
- Changeset: patch for `@objectstack/plugin-email` only
(`@objectstack/rest` source is unchanged).
## Tests
New, no existing test edited:
- `packages/plugins/plugin-email/src/email-service.test.ts`: eight
refusal cases (malformed `to`, empty `to` string, one bad member of a
`to` list, object `to`, `cc`, `bcc`, `replyTo`, non-string display name)
each asserting the exact `VALIDATION_FAILED: …` text; a configured
sender at `noreply@localhost` asserting the plain `Invalid email
address` text and NOT the prefix; well-formed addresses in every field
still normalize; `EmailService.send` rejects with the prefix, never
calls the transport, and still writes one `failed` row.
- `packages/rest/src/email-send-door-bounds.test.ts`: bad `to`, empty
`to`, a `to` list with one bad member, bad `cc` → 400 with `code:
'VALIDATION_FAILED'` and the `error` text asserted, the caller's
addresses forwarded untouched; a well-formed send through the same
service → 200; a configured-sender fault → 500 `EMAIL_SEND_FAILED`, not
a 400. The service here is a double that throws the producer's text; the
producer's own suite pins that text per field (see Acceptance notes).
## Acceptance notes
- `sys_email` row: kept as today. A 400-refused send still writes its
`failed` rejection row: `sendInternal` catches the `normalizeMessage`
throw, calls `recordRejectedMessage`, and rethrows; that method's
docblock states the rule (the row is the only durable evidence when a
caller swallows the error). Pinned in the new `EmailService.send` case.
- Other callers of `normalizeMessage`: it has one call site,
`EmailService.sendInternal`, reached by `send()` / `sendInline()` /
`sendTemplate()`. Every internal sender still sees a rejection: template
sends and auth mail (plugin-auth `sendTemplate` callers) receive the
throw as before; the mail settings "Send test email" action returns `{
ok: false, severity: 'error', message }` from its catch; the messaging
email channel returns `{ ok: false, error }` and its `classifyError`
matches neither the old nor the new text, so it grades `retryable`
exactly as before. The only reader of the `VALIDATION_FAILED` prefix on
this path is the REST send door. No caller turns the failure into a
success.
- The rest pins drive the real `HonoHttpServer` door with a service
double, because `@objectstack/rest` does not depend on
`@objectstack/plugin-email`; the two suites together pin both halves
(producer text, door mapping), and each half was ablated on its own.
- Observation, not filed: the messaging email channel grades a malformed
recipient `retryable`, so a bad address burns the retry ladder before
going dead. Unchanged by this PR.
## Verification
Head `a53fb69fa` (after `git merge origin/main` at `5a194b41`).
<details><summary>Tests and typecheck (both packages, under
os-verify-lock)</summary>
- `@objectstack/plugin-email` test: Test Files 47 passed (47), Tests 775
passed (775); typecheck `tsc --noEmit` + check:test-typecheck OK.
VERDICT command-exit 0.
- `@objectstack/rest` test: Test Files 367 passed (367), Tests 6969
passed, 332 skipped (7301); typecheck + check:test-typecheck OK. VERDICT
command-exit 0 (run on `72cc0d7f`; rest source and tests are
byte-identical at the final head).
- After the merge: the four touched/neighbouring files re-run,
plugin-email 57/57, rest 258/258.
- `eslint --no-inline-config` on `packages/plugins/plugin-email/src` and
`packages/rest/src`: exit 0, no output.
</details>
<details><summary>Ablations (each landed on disk via
scripts/ablation-replace.mjs, restored to the HEAD blob)</summary>
Both suites import the subject from `src/` by relative path, so no build
sits between mutation and run.
- A1, recipients back on the plain throw (`if (false &&
!isSendableAddress(addr))`): plugin-email 8 failed / 33 passed. Expected
"VALIDATION_FAILED: invalid recipient address in to: not-an-email",
received "Invalid email address: not-an-email".
- A2, configured sender judged as a caller address: 1 failed. expected
"Invalid email address: noreply@localhost", received "VALIDATION_FAILED:
invalid recipient address in to: noreply@localhost".
- A3, door prefix branch removed (`if (false &&
message.startsWith('VALIDATION_FAILED'))`): rest 4 failed / 38 passed,
`expected 500 to be 400`.
- A4, door answers every send throw 400 (`if (true || …)`): rest 1
failed, `expected 400 to be 500` on the configured-sender case.
- A5, display-name guard disabled: 1 failed. expected
"VALIDATION_FAILED: invalid recipient address in cc: the display name of
c@d.com must be a string", received "obj.name?.trim is not a function".
</details>
<details><summary>Gates (dispatch-gates --commands, derived at the final
head)</summary>
- Derived at a53fb69: 61 families. All 61 run on that head, every one
exit 0. Reconciliation: "dispatch-gates --ran: 61 derived famil(ies)
accounted for — 61 run, 0 NOT-MEASURED (a DERIVED zero — all 61 recorded
an exit code and none of them is 3)."
- Two families first answered exit 3 (prerequisite, not a verdict) on
the earlier head: check-plugin-teardown-shape --self-test needed a
pinned fixture commit the shallow clone lacked (fetched it), and
check:dual-build-cjs-loads needs every package's dist (ran a full pnpm
build under the lock, exit 0). Both exit 0 in the final run.
- Lint family is not derived: eslint on both packages, exit 0 (above).
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmRW6HXmiYEciBx61dj)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent c347d22 commit 5cdaf9a
4 files changed
Lines changed: 189 additions & 7 deletions
File tree
- .changeset
- packages
- plugins/plugin-email/src
- rest/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
53 | 53 | | |
54 | 54 | | |
55 | 55 | | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
56 | 124 | | |
57 | 125 | | |
58 | 126 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
296 | 296 | | |
297 | 297 | | |
298 | 298 | | |
299 | | - | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
| 303 | + | |
| 304 | + | |
| 305 | + | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
300 | 341 | | |
301 | 342 | | |
302 | | - | |
| 343 | + | |
303 | 344 | | |
304 | 345 | | |
305 | 346 | | |
306 | 347 | | |
307 | | - | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
308 | 352 | | |
309 | 353 | | |
310 | 354 | | |
| |||
318 | 362 | | |
319 | 363 | | |
320 | 364 | | |
321 | | - | |
| 365 | + | |
322 | 366 | | |
323 | 367 | | |
324 | 368 | | |
| |||
335 | 379 | | |
336 | 380 | | |
337 | 381 | | |
338 | | - | |
| 382 | + | |
339 | 383 | | |
340 | | - | |
| 384 | + | |
341 | 385 | | |
342 | | - | |
| 386 | + | |
343 | 387 | | |
344 | 388 | | |
345 | 389 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
143 | 143 | | |
144 | 144 | | |
145 | 145 | | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
146 | 202 | | |
147 | 203 | | |
148 | 204 | | |
| |||
0 commit comments