fix(responses): surface rewrite failures before tee cancellation

[devswha]

Summary

• Deliver an SSE rewrite failure immediately while upstream cancellation completes asynchronously. Waiting for cancellation of one tee branch could otherwise block the error that the outer relay needs to tear down the inspection branch, leaving the client waiting.
• Preserve cancellation rejection handling, rewrite disposal, and translator-budget cleanup. Add two real-tee regression cases proving that the failure terminal arrives while inspection remains open, including a later cancellation rejection.
• Document the failure behavior in the Responses protocol reference.

Verification

• Original production reproduction confirmed the wait with the standard 32 MiB translation budget; the two new regression cases also failed against a preserved copy of the original rewriter.
• bun run test tests/responses/sse-payload-rewrite.test.ts tests/responses/sse-failed-tail.test.ts — 23 passed, 0 failed on the final head with bundled Bun 1.4.0.
• bun run typecheck and bun run privacy:scan — passed on the final head.
• cd docs-site && bun run build — passed, 425 pages.
• bun run test:changed on final head 077dd61f6 — 5,221 passed, 4 skipped, 0 failed across 264 files.
• CodeRabbit manual review completed with no actionable comments.
• Draft remains pending the full local-CI readiness gate and maintainer approval to run fork CI.
• A separate full-suite review baseline completed with 19,250 passed, 16 skipped, 9 default-timeout failures, and 1 related asynchronous error. This branch does not claim a green full-suite run.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No credential, authentication, or destination behavior changes.

Review readiness

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 84ffc718-7ef7-455c-8974-314e8cd2dba5

📥 Commits

Reviewing files that changed from the base of the PR and between 6585e6a and 077dd61.

📒 Files selected for processing (3)

• docs-site/src/content/docs/reference/proxy-formats.md
• src/server/sse-payload-rewrite.ts
• tests/responses/sse-payload-rewrite.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The relay now reports native passthrough rewrite failures without waiting for upstream cancellation. Tests cover resolved and rejected cancellation. Documentation describes the failure events and translation_buffer_limit error code.

Changes

SSE rewrite failure handling

Layer / File(s)	Summary
Non-blocking failure path src/server/sse-payload-rewrite.ts, tests/responses/sse-payload-rewrite.test.ts, docs-site/src/content/docs/reference/proxy-formats.md	The relay starts reader cancellation without awaiting it, then immediately calls controller.error. Tests verify prompt failure delivery, upstream aborts, single disposal, budget cleanup, deferred inspection cancellation, and late cancellation rejection handling. The documentation describes response.failed, data: [DONE], and the translation_buffer_limit error code.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 077dd

Responses SSE rewrite failures now reach clients promptly rather than waiting for upstream cancellation, while cancellation continues in the background. No concrete current-head merge-blocking risk remains.

Suggested reviewers: lidge-j

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: Responses SSE rewrite failures are surfaced before tee cancellation completes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (2/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 2/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

2/4 boxes ticked.

This PR stays in draft until every box above is ticked.

Hygiene

✅ Deterministic PR hygiene checks passed.

[devswha]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[lidge-jun]

리뷰 · 우선순위 70 / 80

이 PR은 Responses SSE 페이로드 rewrite가 실패했을 때, tee의 한쪽 reader.cancel이 형제 inspection 브랜치 종료를 기다리다가 바깥 relay가 response.failed를 못 내고 클라이언트가 멈추는 문제를 고칩니다. 변경은 src/server/sse-payload-rewrite.ts에서 await reader.cancel(error)를 void reader.cancel(error).catch(() => {})로 바꿔, 실패를 즉시 controller.error로 올린 뒤 취소는 비동기로 돌리는 한 줄입니다. dispose·budget release 순서는 유지합니다. 테스트 두 케이스가 실제 tee로 “failure terminal이 inspection이 열린 채 도착”하고, 이후 cancel resolve/reject 모두 unhandled rejection 없이 끝나는지 보여 줍니다. proxy-formats.md에 budget overflow 시 translation_buffer_limit과 response.failed+[DONE] 동작을 문서화했습니다.

지금 dev HEAD의 해당 파일은 여전히 await cancel이라, 32MiB translation budget을 넘는 rewrite 실패에서 재현 가능하다는 본문 설명과 맞습니다. 수정이 극소이고 회귀가 실패 모드를 직접 고정하므로, Draft여도 내용 자체는 merge 후보입니다. 취소 rejection을 .catch로 삼키는 것은 tee sibling이 나중에 cancel될 때 쌍으로 처리된다는 테스트와 맞춰 두었습니다.

한 줄 패치라 부작용면은 “cancel이 완료되기 전에 downstream이 abort하는가”인데, 그게 오히려 원하는 동작(inspection 해제·클라이언트 해제)입니다. #3664 WebSocket pool 등과 충돌면은 작고, split-train과도 무관합니다.

src/server/sse-payload-rewrite.ts catch - await cancel 제거, void cancel + 즉시 controller.error
tests/responses/sse-payload-rewrite.test.ts - tee hang 1s deadline·inspectionSettled false·cancelCalls 0 후 sibling cancel
docs proxy-formats.md - rewrite 실패를 inspection 완료 전에 보고한다고 명시
Draft + full suite 미주장 - focused 23 + test:changed Greenery가 실질 게이트

메인테이너의 판단이 필요한 지점

• Draft라도 이 hang 수정을 빨리 dev에 넣을지(권장)
• cancel fire-and-forget이 다른 Windows rewrite 경로와 문서 문장과 일치하는지 최종 확인

너의 추천
CI/focused 그린 확인 후 우선 merge. 한 줄이라 리스크 대비 효과가 큼.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

Carried into #3683 and merged to dev as c6d8678f73ce6e1ae9df004ab032af09837b5b45. Original contributor commits and co-author attribution are preserved. Exact carried-head full cross-platform verification: https://github.com/lidge-jun/opencodex/actions/runs/33981578769. Dev ancestry was verified after merge.

[lidge-jun]

Landed via #3683 at c6d8678f73ce6e1ae9df004ab032af09837b5b45