SSE 양방향 하트비트와 연결 번호로 죽은 연결을 서버가 먼저 닫는다

[m-a-king]

Situation

• SSE 양방향 하트비트와 연결 번호로 죽은 연결을 1분 안에 정리한다 #1057
• 착수 전 prod 실측(2026-09-07): SSE 에러 콜백에서 complete 로 요청을 끝맺는다 #1031(onError 에 complete) 이 든 이미지에서도 서버 에러 알림 두 줄이 그대로 났다. 스택은 Tomcat 의 /error ERROR 디스패치였고, Spring 은 async 결과를 한 번만 받으므로 하트비트 write 실패 쪽이 먼저 결과를 설정하면 onError 의 complete() 는 무력화된다. 즉 "누가 complete 를 부르나" 로는 경합을 못 이긴다.
• 서버 ping 은 앱과 같은 박스의 nginx 까지만 write 성공이 확인된다. 클라이언트가 비정상 종료돼도 nginx 커널 재전송(약 996초)이 끝나야 앱 소켓에 단절이 온다. 그 사이 서버는 죽은 연결을 살아 있는 것으로 취급한다.

Task

• SSE 양방향 하트비트와 연결 번호로 죽은 연결을 1분 안에 정리한다 #1057
• ERROR 디스패치 permitAll 안전망은 의도적으로 넣지 않는다. 이 작업만으로 알림이 멈추는지 관측한다.
• 60초 결측 정리는 클라이언트가 하트비트를 보내기 시작한 뒤 켠다. 플래그로 분리했고 이 PR 은 기본 off 다.

Action

계약 (client 팀과 합의)

방향	무엇	주기	판정 주체	결측 시
서버 → 클라	event: heartbeat / data: <connectionId>	30초	클라이언트	60초 안 오면 재연결
클라 → 서버	POST /api/v1/notifications/heartbeat {connectionId}	30초(연결 중·포그라운드)	서버	60초 안 오면 서버가 정상 종료

• 연결 번호: 서버가 연결마다 UUID 를 부여해 connect 와 heartbeat 이벤트 data 로 내린다. 클라이언트가 POST 에 되돌려 보내므로 유저가 아니라 연결 단위로 생존을 판정한다(탭·기기 여럿이어도 어느 연결인지 안다).
• 주석 ping 폐기: 표준 EventSource 는 주석 라인을 노출하지 않아 클라이언트가 스트림 생존을 관측할 수 없었다. data 없는 event 는 표준상 디스패치되지 않으므로 data 를 반드시 싣는다.

하트비트 응답

케이스	status	code	클라 동작
반영	200	없음	없음
connectionId 없음·UUID 아님	400	COMMON-INVALID-INPUT	클라 버그
미인증	401	COMMON-UNAUTHORIZED	토큰 갱신
서버에 없는 번호(배포로 서버 교체·이미 정리) 또는 남의 번호	409	NOTIFICATION-002	즉시 재연결

• 남의 번호는 모르는 번호와 같게 409 로 수렴시켜 번호 존재 여부가 새지 않게 했다.
• 규약대로 204 가 아니라 200 + ApiResponseBody.ok() 다. client 팀에 204 로 먼저 말했던 것은 정정이 필요하다.

결측 정리 설계

선택지	비용	채택
새 스케줄러로 lastSeen 순회	스케줄러 하나 추가	아니오
하트비트마다 유저별 타이머 취소·재등록	30초마다 유저 수만큼 취소·재등록	아니오
기존 30초 ping 순회에 얹기	추가 인프라 없음, 최악 감지 지연 = 임계값 + 30초	예

• 임계값 60초: 클라 주기의 1.5배(45초)가 아니라 2배. 클라이언트의 오탐 재연결은 FIN 을 서버에 먼저 보내는 경로라 SSE 하트비트 write 실패가 Tomcat ERROR 디스패치를 일으켜 서버 에러 알림이 재발한다 #1029 경합의 재료가 된다. 서버가 먼저 닫는 경로는 조용하므로 클라 판정은 넉넉히, 서버 판정도 같은 숫자로 맞췄다.
• 서버 선제 종료는 조용한 경로: 앱과 nginx 사이 소켓은 건강하므로 정상 ASYNC 종료로 끝난다. INFO 로 남기며 이 건수가 관측 지표다.
• 판정 대상은 하트비트를 한 번이라도 보낸 연결뿐: 앱스토어 롤아웃 기간엔 구 버전 클라이언트가 섞여 있는데, 그 연결까지 끊으면 60초마다 재연결하는 루프가 된다. 하트비트를 안 보내는 연결은 이전처럼 write 실패·타임아웃으로만 정리된다.
• 플래그 sse.client-heartbeat.eviction-enabled(기본 false): 위 조건 덕에 구 버전이 섞여 있어도 켜서 안전하다. 기본 off 는 클라이언트가 붙은 걸 확인한 뒤 켜는 관측 순서 때문이다.
• 임계값 가드: 단위 없는 숫자는 초로 읽고, ping 주기(30초) 이하면 부팅에 실패한다. 주기 이하로 잡히면 매 순회마다 전 연결이 끊기는 루프라 설정 단계에서 막는다.

구현

• SseConnection(id·userId·emitter·lastHeartbeatAt, null 이면 하트비트를 안 보낸 연결)이 레지스트리의 단일 키다. SseEmitterRegistry 는 register가 돌려준 연결로 unregister·touch·removeStale 을 하고, 번호 조회는 인증된 유저 파티션 안 선형 탐색이라 별도 색인이 없다. LocalSseDelivery.ping()·evictStale() 과 complete 헬퍼 하나, SsePingScheduler(옛 SseHeartbeatScheduler 개명, 임계값 > 주기 불변식 검사), SseClientHeartbeatProperties(notification.sse.client-heartbeat), ClientHeartbeatRequest, NotificationErrorCode.UNKNOWN_CONNECTION.
• 하트비트 POST 는 접근 로그와 관측(span·http.server.requests 시리즈)에서 actuator 와 같이 뺐다. 연결마다 30초에 한 번 오는 인메모리 갱신이 가장 잦은 요청이 되는데 무료 한도가 빠듯하다.
• 통합 테스트는 구독 응답의 connect 이벤트에서 번호를 정규식으로 뽑아 하트비트 POST 로 되돌리는 클라이언트 흐름을 그대로 밟는다. 400 detail 은 실측으로 example 과 잠갔다.

리뷰로 잡은 것

• 레지스트리 등록 경합: computeIfAbsent 뒤 밖에서 add 하던 것을 compute 하나로 묶었다. 그 사이 unregister 가 빈 리스트를 키째 지우면 새 연결이 맵에서 떨어진 리스트에 붙어 알림·ping 을 못 받는데, 번호 색인엔 남아 하트비트가 200 을 돌려주고 종료 시 색인에서 영영 안 빠졌다. 이 PR 전부터 있던 경합이 번호 색인 때문에 누수로 커진 것.
• connect 전송 실패 경로의 completeWithError: SSE 죽은 연결 정리가 ERROR 디스패치를 일으켜 서버 에러 알림을 내는 문제 #1024 가 고친 것과 같은 ERROR 디스패치 경로가 이 자리에만 남아 있었다. complete() 로 바꿨다.
• 하트비트 POST 접근 로그 제외: 연결마다 30초에 한 번 오는 무내용 요청이라 /subscribe 처럼 뺐다.
• 토큰 15분 대 SSE 30분: 연결 중 한 번은 하트비트가 401 을 만난다. 다른 API 와 같은 토큰 갱신으로 풀고 계약에 명시했다. 리뷰가 제안한 "write 성공 시 lastSeen 갱신" 은 write 성공을 생존 신호로 되돌리는 것이라 채택하지 않았다.
• 채택하지 않은 지적 둘: ERROR 디스패치 permitAll 은 결정대로 보류. 단일 스레드 스케줄러에서의 블로킹 write 는 이 PR 전부터 있던 구조이고 파싱 스케줄러가 단일 스레드 전제를 가져 풀 확장이 안 되므로 별건(SSE 전용 executor)으로 남긴다.
• 품질 리뷰(simplify)로 정리한 것: 연결 상태를 nullable 시각 하나로 접음, 번호 색인 제거, 종료 경로 세 벌을 헬퍼 하나로, tick 은 ping 을 먼저(keep-alive 예산 보호), 요청 DTO 는 non-null 로. 채택하지 않은 제안 하나는 409 를 200 무시로 바꾸는 것이다. 멀티 인스턴스가 되면 하트비트 POST 가 연결을 든 인스턴스와 무관하게 라우팅돼 정상 연결에도 409 가 난다는 지적은 맞다. 스케일아웃(배포 플랫폼 개선 검토 — 인스턴스 증설 / ECS Fargate / EKS (overlap-OOM 근본 해결) #439) 시점에 계약을 다시 본다.

Result

• 클라이언트가 하트비트를 붙이고 플래그를 켜면, 비정상 종료된 클라이언트의 연결 정리가 약 17분에서 60초에서 90초 사이로 준다(검사가 30초 ping 순회에 얹혀 있어 임계값 60초에 순회 지연이 더해진다).
• 배포 전 client 팀 확인 하나: 현재 클라이언트가 connect 의 data 가 "connected" 인지 검사하는지. 검사한다면 서버가 먼저 나가는 순간 연결 확인이 깨진다. 합의된 계약은 연결 번호이므로 확인만 받으면 된다.
• 판정 지표는 둘이다. 서버 에러 알림 두 줄의 빈도, 그리고 "SSE 클라이언트 하트비트 결측으로 연결 종료" INFO 건수. 알림이 멈추고 결측 종료가 하루 한 건 안팎이면 매일의 알림이 비정상 종료 케이스였다는 것이 확정된다. 알림이 계속 나면 정상 종료·nginx reload 쪽 경합이고 그때 안전망을 다시 논의한다.
• 후속: client 하트비트 배포 확인 후 SSE_CLIENT_HEARTBEAT_EVICTION_ENABLED=true. 읽음 주체를 클라이언트로 옮기는 SSE write 성공을 읽음으로 간주하는 서버 자동 읽음을 제거하고 읽음 주체를 클라이언트로 되돌린다 #1056 이 끝나면 이 작업은 정확성이 아니라 연결 위생만 다룬다.

---

연관 이슈

• close SSE 양방향 하트비트와 연결 번호로 죽은 연결을 1분 안에 정리한다 #1057

[github-actions]

Discord 스레드 연동용 메타데이터입니다. discord-pr-bot 워크플로가 자동 생성하며, 수정·삭제하면 PR 과 Discord 알림 연동이 끊깁니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: 5ca3ffe0-03ca-417c-b3f6-6d78a8364318

---

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