fix(transport): enforce fresh connections on selected fetches

[Ingwannu]

Summary

• close the post-fix(transport): decide fresh-connection opt-out at the dispatch boundary #4977 gap where oauthDispatch() selected route.provider.fetch outside the fresh-connection executor
• preserve the provider-scoped physical transport while reapplying manual-redirect and OCX_FRESH_CONNECTION_HOSTS policy at the actual send
• add a focused regression proving the captured fetch is not used, the newly selected fetch is used once, and the final init contains Connection: close, keepalive: false, and redirect: manual
• add public operator documentation and synchronize every structure owner mapped to src/server/

Closes #4992.

@lidge-jun This fixes a confirmed gap in the already-merged #4977 path. I am not self-approving or merging it; please review the exact head after hosted CI settles.

Why

providerFetch() correctly wrapped its captured base fetch, but credential revalidation can replace the route and its provider-scoped fetch. The production override then chose that newer fetch directly rather than the supplied executor. For xAI and any future provider-scoped transport, a matching host could therefore keep reusing Bun's pool despite the operator opt-out.

ProviderDispatchExecutor.withFetch() keeps the replacement transport but runs it through the same final-send policy. This avoids falling back to the stale captured transport and avoids duplicating policy inside OAuth routing.

Verification

• bun test tests/responses/fresh-connection-optout.test.ts --timeout 30000: 11 pass, 0 fail
• bun run typecheck: pass
• bun run structure:check: pass
• docs-site frozen install and bun run build: pass, 457 pages
• git diff --check: pass
• full bun run test: 26,382 pass, 21 skip, 15 fail; all 15 failures reproduce in the seven unrelated failing files when run separately and are outside this diff (existing local admission-key expectation, launchd fixture, remote-workspace sandbox, Cursor status, and Windows spill timing failures)
• protected OpenCodex/Codex/Paseo runtime configuration hashes remained unchanged before and after testing

Transition note

This is a TypeScript Responses transport correction with no Go counterpart in the current tree. The documented dev2-go remote branch does not currently exist, so there is no forward-port target available at submission time.

Summary by CodeRabbit

• New Features

  • Added OCX_FRESH_CONNECTION_HOSTS to bypass broken keep-alive connections for selected hosts and subdomains.
  • Matching requests now use fresh connections with Connection: close and keep-alive disabled.
  • The policy remains applied when provider-specific transports or credential revalidation are used.

• Documentation

  • Expanded configuration, operations, transport, provider, and integration documentation with setup details, matching rules, and service restart requirements.
  • Clarified that alternate provider transports cannot bypass the connection policy.

• Tests

  • Added coverage confirming provider-specific fetches honor fresh-connection settings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 91c004f1-370a-4af6-9e92-5b2ce79ac7e2

📥 Commits

Reviewing files that changed from the base of the PR and between facd2b6 and 1586845.

📒 Files selected for processing (18)

• docs-site/src/content/docs/reference/configuration/server.md
• src/server/responses/fetch-helpers.ts
• src/server/responses/request-transport.ts
• structure/adapters/registry.md
• structure/catalog.md
• structure/clients/claude-desktop.md
• structure/data-planes/images.md
• structure/data-planes/inbound-compat.md
• structure/gui-and-management-api.md
• structure/ops/service-and-sidecars.md
• structure/providers/xai-grok.md
• structure/runtime.md
• structure/subagents.md
• structure/transports/byte-accounting.md
• structure/transports/inventory.md
• structure/transports/responses.md
• structure/transports/streaming-health.md
• tests/responses/fresh-connection-optout.test.ts

 ____________________
< Expecto bugtronum! >
 --------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[Ingwannu]

Superseded by #5022, which landed first on dev as 56a99d3848988e8c29c9ee02fb6e8ac44aefa102 and covers both production override boundaries, including the native Chat path and an xAI end-to-end regression. Closing this duplicate rather than competing with the broader fix.

[lidge-jun]

리뷰 · 우선순위 42 / 80

이 PR은 OCX_FRESH_CONNECTION_HOSTS가 붙어 있어도, OAuth 재검증 뒤에 새로 고른 route.provider.fetch가 providerFetch가 만들어 둔 실행기를 건너뛰고 바로 호출되면 Bun 연결 풀을 다시 쓸 수 있다는 구멍을 막으려는 작업입니다. 작성자가 말한 흐름은 맞습니다. #4977이 디스패치 경계에서 정책 결정을 넣었고, 그다음 생산 경로의 oauthDispatch()가 재선택된 프로바이더 fetch를 그대로 쓰면 정책이 빠질 수 있습니다. 그래서 ProviderDispatchExecutor.withFetch로 “새 물리 전송은 유지하되 redirect·fresh-connection 정책은 다시 감싼다”는 API를 제안하고, 단위 테스트로 “예전 capture fetch는 0번, 새 fetch는 1번, Connection: close / keepalive: false / redirect: manual”을 고정하려 합니다. 문서와 structure 여러 owner에도 같은 계약을 적어 두었습니다.

그런데 지금 dev HEAD(facd2b6ca)에는 이미 같은 버그를 닫은 #5022이 들어가 있습니다. #5022는 sendWithConnectionPolicy()를 공개하고, request-transport.ts의 oauth 디스패치뿐 아니라 chat-native.ts의 재선택 경로까지 같은 정책으로 감쌌습니다. 이슈 #4992는 #5022 머지 직후 이미 CLOSED 상태입니다. 이 PR의 merge-base는 #5022 이전 SHA(6467235a8)이고, GitHub는 지금 mergeable_state=dirty로 보고합니다. 즉 같은 날 같은 구멍을 다른 API 모양으로 고친 병렬·중복 PR입니다.

현재 dev에서 이미 있는 계약은 대략 이렇습니다. src/server/responses/fetch-helpers.ts의 sendWithConnectionPolicy가 선택된 physical fetch 바깥에서 Connection/keepalive/redirect를 적용하고, providerFetch의 dispatch도 그 함수를 씁니다. oauthDispatch는 fetchImpl = route.provider.fetch ?? execute를 고른 뒤 sendWithConnectionPolicy(fetchImpl, ...)로 보냅니다. 회귀 테스트도 handleResponses + xAI OAuth 경로로 “프로바이더 스코프 전송이 정책을 받는다”를 한 번 더 고정해 두었습니다. 운영자 문서의 “Connection reuse for specific upstream hosts” 절도 이미 docs-site에 있습니다.

이 PR이 제안한 withFetch는 설계상 나쁘지 않습니다. 실행기 타입에 “대체 fetch를 정책 안으로 넣는” 메서드를 붙이면 호출부가 조금 더 명시적일 수 있습니다. 다만 dev는 이미 더 단순한 자유 함수 + 호출부 두 곳(Responses + chat-native)으로 같은 결과를 냈고, 이 PR은 chat-native를 건드리지 않습니다. structure 쪽에는 여러 owner 문서에 “fresh-connection final-send contract를 우회하지 않는다”는 한 줄씩을 대량으로 추가했는데, #5022는 structure/transports/responses.md에 핵심만 보강한 쪽에 가깝습니다. 지금 리베이스하면 거의 전부가 충돌·삭제·재작성이 되고, 남는 이득은 거의 없습니다.

라인 수준으로 보면 아래가 핵심입니다.

Closes #4992 - 이슈는 이미 #5022로 닫혔다. 다시 Closes를 달아도 추적 가치가 없고, 기여자·메인테이너 모두 “아직 열린 버그”로 오해하기 쉽다.

src/server/responses/fetch-helpers.ts (ProviderDispatchExecutor / dispatchWithConnectionPolicy) - dev의 sendWithConnectionPolicy와 역할이 겹친다. 둘을 같이 두면 정책 적용 경로가 두 갈래가 된다.

src/server/responses/request-transport.ts (execute.withFetch(...)) - 의도한 수정은 맞지만, dev는 이미 sendWithConnectionPolicy(fetchImpl, ...)로 같은 줄을 고쳤다. 리베이스 시 이 덩어리는 사실상 no-op이거나 충돌이다.

chat-native 경로 부재 - #5022가 막은 두 번째 생산 경로(src/server/chat-native.ts)가 이 PR에는 없다. “Responses만 고친 대안”이라 현재 HEAD 기준으로 불완전하다.

structure/*.md 다수 owner 한 줄 추가 - 계약 동기화 의도는 이해되지만, 이미 랜딩된 수정 위에 문서 노이즈만 키운다. #5022의 responses.md 보강으로 충분한 상태다.

docs-site/.../server.md - dev에 이미 같은 종류의 절이 있다. 문구만 다른 중복 문서다.

tests/responses/fresh-connection-optout.test.ts (withFetch 단위 테스트) - 협력형 override 테스트라 도움이 되지만, #5022의 handleResponses 회귀가 생산 경로를 더 직접 고정한다. 이 테스트만 살리려고 PR을 열어 둘 필요는 없다.

mergeable_state=dirty / base 6467235 - #5022·이후 catalog/spend/gui 머지들과 충돌한다. 리베이스 비용이 크고 남는 코드 가치가 거의 없다.

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

• 감사 코멘트만 남기고 바로 close할지, 아니면 “#5022가 이미 같은 구멍을 닫았다”를 본문에 인용한 뒤 close할지
• 기여자가 withFetch API를 선호한다면 별도 설계 PR로 나중에 논의할지(지금 이 브랜치로 합치지는 말 것)
• structure owner 전수 동기화 문구를 앞으로 필수로 둘지, responses.md 한곳이면 충분할지

너의 추천
close(중복·이미 랜딩). #4992는 #5022(56a99d384)로 이미 해결됐고 chat-native까지 포함된다. 이 PR은 같은 진단의 병렬 구현이며 dirty conflict 상태다. 리베이스하지 말고, 작성자에게 #5022 링크와 함께 감사 멘션 후 completed/superseded로 닫는 편이 큐를 덜 부풀린다. 남길 가치가 있다면 withFetch 설계 메모만 이슈 코멘트로 옮기고 코드 PR은 닫자.

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