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

배경

lib/internel/_http_server 에 있는 TODO 주석을 보고 기여를 시작.

현재 Node.js의 http.Server는 server.keepAliveTimeout 값을 기준으로 소켓의 타임아웃을 설정하지만, 이 값에 추가적인 버퍼를 더하는 동작을 내부적으로 하고 있다:

socket.setTimeout(server.keepAliveTimeout + HTTP_SERVER_KEEP_ALIVE_TIMEOUT_BUFFER);

여기서 HTTP_SERVER_KEEP_ALIVE_TIMEOUT_BUFFER는 하드코딩된 상수(1000ms)로 정의되어 있으며, 사용자가 이 값을 조정할 수 있는 방법이 없다. 그러나:

• 이 버퍼 값은 클라이언트 측에서 발생할 수 있는 ECONNRESET 오류를 줄이기 위한 중요한 역할을 하며,
• 사용 환경에 따라 더 짧거나 더 긴 값을 요구할 수 있음에도 불구하고,
• 현재는 고정값으로만 동작하고 있어 유연성이 부족하다.

따라서 이 기여는 해당 버퍼를 사용자가 설정 가능하도록 옵션화함으로써, 더 유연하고 커스터마이징 가능한 서버 설정을 지원하려는 목적이다.

---

---

수정사항

1. http.Server 생성자 수정

   • keepAliveTimeoutBuffer 값을 options 객체에서 받아 저장하도록 함.
   • 사용자가 지정하지 않으면 기본값(1000)을 사용하도록 디폴트 처리.

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

2. 내부 socket timeout 설정 코드 수정 (resOnFinish)

   • 기존의 HTTP_SERVER_KEEP_ALIVE_TIMEOUT_BUFFER 상수 대신, 인스턴스에 저장된 server.keepAliveTimeoutBuffer를 사용.

   // This allows fine-tuning beyond the advertised keepAliveTimeout.
         socket.setTimeout(server.keepAliveTimeout + server.keepAliveTimeoutBuffer);

3. 상수 제거

   • 더 이상 사용되지 않는 HTTP_SERVER_KEEP_ALIVE_TIMEOUT_BUFFER 상수 제거.

4. 관련 주석 수정

   • 하드코딩된 값이 아닌 옵션으로 설정된다는 점을 반영하여 주석 수정:

     // Add a buffer to the keep-alive timeout to reduce the likelihood of ECONNRESET errors.

5. 문서화
   • http.Server의 옵션 설명 문서에 keepAliveTimeoutBuffer를 추가
   • 예: doc/api/http.md 파일 내 Server options 표에 옵션 항목 추가.

→

💡

Node.js 옵션 추가 시 문서화 패턴: added 블록 (메타데이터)

Node.js에 새로운 옵션을 추가하면서 알게 된 게 있다.

문서화는 단순한 주석이 아니라 릴리스와 연결되는 체계적인 메타데이터라는 점이다.

이번에 server.keepAliveTimeoutBuffer 옵션을 추가하면서

mcollina의 피드백을 받았는데, 핵심은 이거였다:

please add an added block like the previous option

즉, 새로 추가된 옵션은 다음과 같은 added: 메타블록이 꼭 필요하다:

<!-- YAML
added: REPLACEME
-->

여기서 REPLACEME는 해당 PR이 어떤 Node.js 버전에 포함될지 아직 확정되지 않았을 때 사용하는 placeholder 다.

릴리스 타이밍이 결정되면 이를 예: v24.6.0 등의 형식으로 채운다.

이 <!-- YAML --> 블록은 단순한 주석이 아니고

빌드 타임에 자동 문서 생성 도구가 파싱해서 changelog와 버전별 API 차이를 추적하는 데 쓰이는 규칙이다.

6. 테스트 코드
   • 새 옵션이 동작하는지 검증할 수 있는 테스트 케이스 작성

---

---

정리

이제 벌써 3번째 반영이다 ! 슬슬 이제 PR 올리는 법, 컨벤션들이 익숙해지는 것 같다.

이번 기여가 http 서버의 타임아웃 버퍼 옵션 추가여서 찾아보니 http Agent 즉 클라이언트 쪽 타임아웃 버퍼 옵션도 하드코딩 되어있길래 다음 기여는 이 주제가 될 것 같다.

마지막으로 이 블로그를 쓰는 시점 기준 내 전역 날이다 🎉 후임 중에 내 블로그 잘 보고 있다고 전역 복에 적어준 친구도 있었는데 더 열심히 공부해야겠다. 18개월 기간이 아깝지 않을 정도로 가득 채워 보낸 것 같아서 뿌듯하고 감사하다.