Building a WebSocket Debugging CLI with Node.js

Context

Chrome DevTools의 Network 탭은 WebSocket 메시지를 표시하지만 필터링, 리플레이, 기록, 스크립팅, 다중 연결 뷰, 레이턴시 측정 기능이 없다. 특히 초당 수십 개의 메시지를 보내는 바쁜 연결에서 특정 메시지를 찾기 어렵고, 백엔드 서비스나 IoT 기기 디버깅 시에는 wscat 같은 최소 기능 도구에만 의존해야 한다.

Technical Solution

• EventEmitter 기반 Connection Manager 설계: WebSocket 프로토콜 처리를 ws 라이브러리에 위임하고, 연결 상태·메시지 송수신·에러를 EventEmitter를 통해 이벤트로 변환해 로깅·기록·대화형 REPL과의 느슨한 결합 구현
• 연결별 상태 추적: 각 연결을 Map에 저장하고 ID로 관리하며, 메시지 개수·전송 바이트·생성 시간 등 통계를 연결 객체에 저장해 진단 정보 제공
• 메시지 로거 모듈화: 필터링과 포매팅을 연결 관리와 분리해 CLI 플래그 또는 대화형 세션 중 동적으로 필터 추가 가능하게 구현
• 세션 기록·리플레이 기능: JSON 파일 형식으로 상대 타임스탬프를 기록해 임의의 속도로 재생 가능하고, 팀원 공유·버그 리포트 첨부·버전 관리 용이하게 설계
• 다중 연결 지원: 연결 Map 패턴으로 1개에서 수십 개 연결로 확장 시 아키텍처 변경 없이 대응 가능하도록 구현

Key Takeaway

목적에 맞춘 CLI 도구를 모듈식으로 설계하면 EventEmitter 패턴을 통해 WebSocket 처리 계층과 UI·테스트 계층을 완전히 분리할 수 있으며, 이를 통해 약 500줄의 JavaScript로도 브라우저 DevTools보다 강력한 디버깅 환경을 제공할 수 있다.