[Node.js 기여] agentKeepAliveTimeoutBuffer 옵션 추가 PR

배경

이전 3번째 기여에서 http.Server에 keepAliveTimeoutBuffer 옵션을 추가하면서, 서버 측 타임아웃 버퍼를 유연하게 조정할 수 있게 되었다.

그러다 보니 자연스럽게 클라이언트 측 HTTP Agent도 동일한 논리를 적용할 수 있겠다는 생각이 들었다.

찾아보니, 정말 server 처럼 TODO 주석이 박혀있었다.

• 기존 http.Agent는 서버가 보낸 Keep-Alive: timeout=N 헤더를 기반으로 소켓 타임아웃을 계산하지만,
• 추가적인 버퍼를 넣어주지 않으면 서버보다 먼저 클라이언트에서 소켓이 닫히는 상황이 발생할 수 있음.
• 따라서 서버와 마찬가지로, 클라이언트도 버퍼를 옵션화하면 안전하게 Keep-Alive를 유지할 수 있다.

---

수정사항

1. http.Agent 생성자 수정

   • 새로운 옵션 agentKeepAliveTimeoutBuffer 추가
   • 사용자가 지정하지 않으면 기본값 1000ms 사용

   const agentKeepAliveTimeoutBuffer = options.agentKeepAliveTimeoutBuffer;
   if (agentKeepAliveTimeoutBuffer !== undefined) {
     validateInteger(agentKeepAliveTimeoutBuffer, 'agentKeepAliveTimeoutBuffer', 0);
     this.agentKeepAliveTimeoutBuffer = agentKeepAliveTimeoutBuffer;
   } else {
     this.agentKeepAliveTimeoutBuffer = 1000;
   }
   

2. 서버에서 받은 Keep-Alive: timeout=N 처리 수정

   • 기존 계산: timeout * 1000
   • 수정 계산: (timeout * 1000) - agent.agentKeepAliveTimeoutBuffer

   effectiveTimeout = (timeout * 1000) - agent.agentKeepAliveTimeoutBuffer;
   

   → 서버보다 조금 늦게 소켓을 닫도록 안전 여유를 줌으로써 ECONNRESET 발생 감소.

3. 문서화

   • doc/api/http.md에 agentKeepAliveTimeoutBuffer 옵션 추가
   • <!-- YAML added: REPLACEME --> 메타데이터 블록 삽입
   • PR URL, 기본값, 설명까지 포함

4. 테스트

   • test-http-agent-keep-alive-timeout-buffer.js 파일 작성
   • 다양한 버퍼 값에 따라 소켓 타임아웃이 정확히 적용되는지 검증

---

결과

• 이전에 서버 버퍼 옵션 추가와 동일한 로직이다 보니, 별일 없이 금방 머지되었다.
• 클라이언트 측 HTTP Agent도 서버처럼 keep-alive 버퍼 옵션을 유연하게 조정 가능
• 기존 연결에는 영향 없음

---

정리

이제 Node.js에서 HTTP 관련 타임아웃 버퍼를 서버와 클라이언트 모두 옵션화했다.

HTTP Agent 쪽 코드를 들여다보면서, 서버와 클라이언트의 동기화 문제와 실제 운영 환경에서 발생하는 ECONNRESET을 방지하는 작은 디테일의 중요성을 다시 한 번 느꼈다.

3번째 기여가 HTTP 서버 쪽이면 이번 4번째 기여는 자연스럽게 클라이언트 쪽을 보게 되었던 것 같다.