피드로 돌아가기
Dev.toInfrastructure
원문 읽기
4계층 네트워크 경로 최적화를 통한 WebSocket Upgrade 핸드셰이크 복구
How I bridged codex-tui's WebSocket /v1/responses through Cloudflare, nginx, and FastAPI
AI 요약
Context
codex-tui 0.128 버전의 응답 방식이 HTTP+SSE에서 WebSocket 기반 /v1/responses로 변경됨에 따른 통신 단절 발생. 기존 AI Gateway 아키텍처가 POST 핸들러만 지원하며, 중간 프록시 계층에서 WebSocket Upgrade 헤더를 제거함에 따라 405 Method Not Allowed 에러가 반복되는 구조적 한계 노출.
Technical Solution
- Cloudflare Worker의 Header Sanitizer 로직 수정으로 Upgrade 헤더 보존 및 WebSocket 전용 패스스루 경로 설계
- Cloudflare Tunnel의 기본 HTTP 서비스 설정을 통한 WebSocket 트래픽 투명 전달 유지
- nginx의 map 디렉티브를 활용하여 Upgrade 헤더 존재 여부에 따라 Connection 헤더를 동적으로 할당하는 구조 도입
- FastAPI 백엔드에 WebSocket 경로를 추가 등록하여 HTTP POST와 WebSocket 요청을 동일 경로에서 동시 처리하도록 구현
- RFC 7230의 Hop-by-hop 헤더 규정을 준수하면서도, 특정 조건에서만 헤더를 보존하는 조건부 포워딩 전략 채택
실천 포인트
- L7 프록시(Worker, nginx 등) 도입 시 Upgrade 및 Connection 헤더 제거 여부 확인 - 동일 엔드포인트(/v1/responses)에서 HTTP와 WebSocket을 동시 지원하는 다중 프로토콜 핸들러 설계 검토 - CDN 및 Edge 서비스의 WebSocket 지원 여부 및 전용 설정(Fastly 등) 필요성 사전 점검 - 클라이언트 라이브러리 업데이트에 따른 프로토콜 변경 가능성을 고려한 게이트웨이 유연성 확보