SSE(Server-Sent Events) Spec 은 정해져 있다

서버 관련 예시 코드는 Java/Spring 으로 진행되며, SSE Spec(응답 형식)에 대해 알아보는 것으로 서버에서 SSE 구현 방법에는 다음 글을 참고해주세요.

 

클라이언트 예시 코드에 대해 더 알고싶다면 '참고' 의 상단 2개 링크를 참고해주세요.

 

0. SSE 의 Spec은 정해져 있다.

SSE는 HTML 스펙(WHATWG) 에 정의되어 있고, HTTP 스펙(IETF)과는 별개입니다.

WHATWG → SSE (EventSource, Event Stream 포맷) 정의
IETF   → HTTP/1.1, HTTP/2, HTTP/3 정의

 

HTTP 버전에 따라 달라지는 건 SSE 의 Spec이 아니라 그걸 전달하는 방식입니다.

 

예를 들어 HTTP/2.0 과 HTTP/1.1 은 데이터 전달 방식이 다릅니다.

SSE 를 HTTP/2.0 으로 서빙할 때는 HTTP/2.0 이 하나의 TCP 연결로 지속하기 때문에 keep-alive 헤더, Transfer-Encoding 헤더 등을 허용하지 않습니다. 하지만, SSE 를 HTTP/1.1 로 서빙할 때는 keep-alive 헤더, Transfer-Encoding 헤더가 추가됩니다.

 

즉 id:, data:, event:, retry: 필드로 구성된 SSE 의 Spec 은 HTTP/1.1이든 HTTP/2든 HTTP/3이든 동일하게 적용됩니다. 포맷은 그대로고, 어떻게 스트림 데이터를 전달할지를 HTTP 버전에 따라 달라집니다.

 

* 아래 글은 HTTP/1.1 을 기준으로 설명합니다.

1. Response Header

서버가 클라이언트에게 내려주는 Response 헤더는 아래와 같습니다.

header("X-Accel-Buffering: no");
header("Content-Type: text/event-stream");
header("Cache-Control: no-cache");

 

Content-Type 과 Cache-Control 은 워낙 유명하지만, X-Accel-Buffering 은 생소합니다.

 

X-Accel-Buffering 헤더는 Nginx만이 인식할 수 있는 헤더로, Nginx로 하여금 응답을 버퍼에 모았다가 한 번에 보내지 않도록 하는 설정에 사용합니다.

기본적으로 Nginx는 upstream(데이터 근원지, 예를 들면 Spring Boot 서버)의 응답을 버퍼에 모았다가 한 번에 클라이언트로 전달하는데, 이는 네트워크를 효율적으로 사용하기 위함이며 일반적인 HTTP 응답(JSON, HTML 등)에서는 이 방식이 유리하기 때문입니다.

 

하지만 SSE 같이 스트리밍 응답은 실시간으로 데이터를 흘려야 하므로 버퍼링을 사용되면 안 됩니다. 이 때 서버에서 X-Accel-Buffering: no 헤더를 응답에 포함하면, Nginx가 해당 응답에만 버퍼링을 끄고 실시간으로 흘립니다.

 

그리고, Nginx 는 기본적으로 http 1.0 을 사용하기 때문에 http1.1 의 keep-alive 를 사용할 수 있도록 http version 도 설정해줘야 하며, Connection 도 close 되지 않도록 추가 설정해야 합니다.

 

그래서 Nginx 전용(리버스 프록시 전용 헤더)인 X-Accel-Buffering 헤더도 서버가 내려주는 것이 아닌 Nginx 에 함께 설정하는 것이 유지보수 측면에서 좋다고 생각하며 X-Accel-Buffering 헤더를 Nginx 의 config 파일에 설정해줍시다.  

X-Accel-Buffering 은 Nginx 전용 헤더입니다.
Nginx 대신 HAProxy나 Apache HTTP Server를 리버스 프록시로 사용할 경우 별도의 설정이 필요합니다.
예를 들어 HAProxy server sent event timeout 으로 검색하면 쉽게 찾을 수 있습니다.

 

2. Response Body

SSE의 Response Body 필드는 id, event, data, retry로 구성되며 그 외 모든 필드는 무시됩니다.

 

id 필드

`id`는 커넥션이 끊겼다가 재연결 시 클라이언트가 `Last-Event-ID` 헤더로 마지막으로 받은 id를 서버에 보내줌으로써, 어디서부터 데이터를 다시 보낼지 확인하는 용도입니다.

 

브라우저(클라이언트)는 네트워크가 끊기거나 서버가 다운되면, SSE 응답을 받기 위해 `retry` 필드의 값(단위 ms)마다 반복해서 재연결을 시도하게 되는데, 아래처럼 Last-Event-ID를 포함해서 재연결을 시도하게 됩니다.(default 동작 방식)

 

Spring(서버) 은 아래와 같이 받을 수 있습니다.

@GetMapping(value = "/mvc/last-event-id", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public ResponseEntity<SseEmitter> lastEventIdDemo(
        @RequestHeader(value = "Last-Event-ID", required = false) Integer lastEventId
) {

 

 

문제는 서버가 계속 Event Stream 응답을 보내고 있는데, 네트워크가 일시적으로 끊겼을 때 데이터가 유실될 수 있다는 점입니다.

 

예를 들어 서버는 id 1부터 10까지의 데이터 중 6부터 보냈는데, 클라이언트는 네트워크 장애로 인해 커넥션이 잠깐 끊켜 4까지 받았습니다. 그러면, 클라이언트(브라우저)는 자동으로 커넥션 재연결을 시도하게 되며(기본 동작입니다), Last-Event-ID에 4를 넣어 서버에게 응답을 다시 요청하게 될 것입니다.

 

이 상태에서 서버가 4부터 다시 전달하려면 Event Stream 응답 데이터가 어딘가에 저장되어 있어야 합니다. 이미 서버는 6까지 보냈기 때문입니다. 이를 위해 서버가 내려줄 응답body를 저장하기 위해 메모리, Redis, Kafka, DB 등 다양한 선택지를 고려할 수 있습니다.

 

이처럼 Last-Event-ID(id 필드)를 이용해 특정 시점부터 다시 Event Stream 응답을 받으려면 Event Stream 데이터를 재생 가능하게로 구현해야 할 것입니다.

 

event 필드

이벤트 유형을 식별하는 문자열입니다. 이 값이 지정되어 있다면 브라우저는 지정된 이벤트 이름에 대한 리스너에게 이벤트를 발생시킵니다. 웹 사이트 소스 코드가 이름을 갖는 이벤트를 수신하기 위해서는 addEventListener()를 사용해야 합니다. 메시지에 이벤트 이름이 지정되지 않은 경우 onmessage 핸들러가 호출됩니다.

 

서버 예시는 Spring MVC가 Event Stream Spec을 잘 보여주는 SseEmitter 클래스를 이용했습니다.

예를 들어 서버가 아래와 같이 Event Stream 응답을 만들어 주고 있다면,

SseEmitter emitter = new SseEmitter(60_000L);
emitter.send(SseEmitter.event()
    .id(String.valueOf(i))
    .name("sse-event")
    .data("이벤트 #" + i + " [" + connectionLabel + "]")
    .reconnectTime(2000)); // 끊기면 2초 후 재연결

 

브라우저는 서버가 보내준 "sse-event"라는 문자열을 event 필드로 수신하게 됩니다.

 

 

JS에서는 "sse-event" 이벤트를 받았을 때 실행할 이벤트 리스너를 등록할 수 있습니다.

EventSource evtSource = new EventSource("서버 URL");
evtSource.addEventListener("sse-event", function (event) {
  ...
});

 

만약, 서버가 event 필드를 주지 않는다면

SseEmitter emitter = new SseEmitter(60_000L);
emitter.send(SseEmitter.event()
    .id(String.valueOf(i))
    .data("이벤트 #" + i + " [" + connectionLabel + "]")
    .reconnectTime(2000)); // 끊기면 2초 후 재연결

 

브라우저는 event 필드를 받지 못하고, message 이벤트로 수신이 되며,

 

JS에서는 onmessage 로 message 이벤트를 위한 핸들러를 추가할 수 있습니다.

evtSource.onmessage = function (e) {
  ...
};

 

data 필드

Event Stream 응답의 실제 데이터가 들어갑니다. SseEmitter를 사용할 경우 .data() 메서드에 데이터를 넣어줍니다.

 

retry 필드

재연결 대기 시간입니다. 서버와의 연결이 끊어지면 브라우저는 재연결을 시도하기 전에 지정된 시간을 기다립니다. 이 값은 밀리초 단위의 정수여야 하며, 정수가 아닌 값이 지정된 경우 이 필드는 무시됩니다.

 

3. 번외

SseEmitter의 comment

SseEmitter에는 Event Stream Spec에는 없는 .comment() 메서드가 있습니다.

@GetMapping(value = "/mvc/sse-emitter")
public SseEmitter sseEmitter() throws IOException {
    SseEmitter emitter = new SseEmitter();
    emitter.send(SseEmitter.event()
        .id("id-1")
        .data("Hello World")
        .name("event 필드")
        .comment("event 코멘트")
        .reconnectTime(10000));
    return emitter;
}

 

Window Powershell 에서 curl 요청을 보내면 아래와 같은 응답을 받습니다.

PS C:...\tech-playground> curl.exe -N http://localhost:8080/mvc/sse-emitter
id:id-1
data:Hello World
event:event 필드
:event 코멘트
retry:10000

 

즉, .comment()는 :event 코멘트 형태로 치환되며, 브라우저 개발자도구의 EventStream 탭에서는 확인할 수 없습니다.

 

 

그 이유는 :으로 시작하는 줄은 Event Stream Spec상 주석으로 취급되어 무시되기 때문입니다.

 

.comment()는 주로 heartbeat(연결 유지 신호) 용도로 사용됩니다. Nginx 같은 프록시는 일정 시간 동안 아무 데이터도 오지 않으면 idle 커넥션으로 판단해 끊어버리는데, heartbeat comment를 주기적으로 보내면 데이터가 흐르고 있다고 인식해 끊지 않습니다. 브라우저는 Event Stream Spec에 따라 이 데이터를 주석으로 처리하므로 실제 이벤트 처리 로직에 영향을 주지 않습니다.

 

SSE 종료 알림

클라이언트는 SSE 응답이 언제 끝날지 모릅니다. 이를 위해 event 필드를 통해 특정 이벤트가 발생하면 SSE 응답이 종료되었다고 서버가 알려주는 방식을 사용합니다.

 

Spring MVC의 Streaming 방식 비교

Spring MVC 의 Streaming 방식은 SseEmitter 와 StreamingResponseBody 가 있습니다.

엑셀 다운로드 기능같이 파일을 다운로드 할 때는 ResponseEntity<StreamingResponseBody> 를 컨트롤러에서 return 하면 됩니다.

	SseEmitter	StreamingResponseBody
포맷	SSE 스펙 자동 적용	raw 바이트 직접 작성
용도	SSE 이벤트 스트리밍	파일 다운로드, 대용량 데이터
클라이언트	EventSource	fetch, 일반 HTTP
포맷 처리	자동	직접

 

동시 SSE 연결 제한

HTTP/2에서 동시 SSE 연결 개수는 기본값 100개입니다. 그 아래 HTTP 버전은 도메인당 6개로 매우 낮게 설정되어 있습니다.

만약, 한 사용자당 동시 SSE 커넥션 연결을 제한해야 한다면, 서버 또는 JS에서 사용자 당 1개의 SSE 커넥션을 가지도록 추가 구현을 진행해야 합니다.

 

참고 영상 및 실습 코드

대규모 대기열에서의 WebSocket vs polling 도 같이 영상을 보면 좋을 것 같습니다.

엄청난 폴링 횟수. 과연 웹소켓에 비해 유리한가?

 

SSE 관련 실습 코드는 GitHub에서 확인할 수 있습니다.

 

다음 글로는 Spring 에서 SSE 구현하는 방법에 대해 알아보겠습니다.

 

참고

• HTML Standard - Last-Event-ID
• MDN 한글판: Server-Sent Events 사용하기
• 우아한 기술 블로그: Server-Sent Events로 실시간 알림 전달하기
• Sionic AI: SSE로 실시간 데이터 전송하기
• 테코블: Spring에서 Server-Sent-Events 구현하기
• Baeldung: Spring MVC Streaming and SSE Request Processing