TL;DR

• SSE는 HTTP 위에서 서버→클라이언트 단방향 이벤트 푸시를 구현하는 프로토콜이다.
• text/event-stream 미디어 타입, 필드 기반 메시지 포맷(data:, event:, id:, retry:), 빈 줄(\n\n)로 메시지 경계를 구분한다.

SSE (Server-Sent Events)

배경

전통적인 HTTP는 클라이언트가 요청해야 서버가 응답하는 구조다. SSE는 서버가 클라이언트에게 지속적으로 데이터를 푸시할 수 있게 해주는 표준으로, 폴링 없이 실시간 업데이트를 구현한다. WHATWG HTML 스펙의 일부로 정의되어 있다.

메시지 포맷

SSE 스트림은 필드 기반 텍스트 포맷이다. 각 줄은 field: value 형태이며, 빈 줄(\n\n)이 메시지 경계를 나타낸다.

필드 종류

필드	역할
data:	메시지 페이로드. 여러 줄이면 \n으로 연결
event:	이벤트 타입 (생략 시 "message")
id:	이벤트 ID. 재연결 시 Last-Event-ID 헤더로 전송
retry:	재연결 대기 시간 (밀리초, ASCII 숫자만)

: 로 시작하는 줄은 코멘트로 무시된다 (keep-alive 용도로 활용).

예시

event: update
data: {"score": 42}
id: 7

event: update
data: {"score": 43}
id: 8

핵심 특성

• 프로토콜: HTTP 전용 (단방향, 서버→클라이언트)
• 미디어 타입: text/event-stream
• 인코딩: UTF-8 필수
• 줄 끝: \n, \r\n, \r 모두 허용
• 메시지 구분: 빈 줄 (\n\n)
• 재연결: 연결 끊기면 자동 재연결. id: 필드가 있으면 Last-Event-ID 헤더로 이어받기 가능

서버 구현 (FastAPI)

sse-starlette의 EventSourceResponse를 사용하면 SSE 포맷팅을 직접 하지 않아도 된다:

from fastapi import FastAPI
from sse_starlette.sse import EventSourceResponse
import asyncio, json
 
app = FastAPI()
 
async def event_generator():
    for i in range(10):
        yield {"event": "update", "id": str(i), "data": json.dumps({"score": i})}
        await asyncio.sleep(1)
 
@app.get("/stream")
async def stream():
    return EventSourceResponse(event_generator())

EventSourceResponse가 text/event-stream 헤더, data:/event:/id: 필드 포맷팅, \n\n 구분을 모두 처리한다.

직접 구현

sse-starlette 없이도 StreamingResponse(generator, media_type="text/event-stream")으로 직접 f"data: {json}\n\n" 문자열을 yield하는 방식도 가능하다.

클라이언트 (EventSource API)

브라우저에서 SSE를 소비하는 표준 JavaScript API:

const source = new EventSource('/stream');
source.addEventListener('update', (e) => console.log(JSON.parse(e.data)));
source.addEventListener('error', (e) => console.error(e));

이벤트: open (연결 수립), message (기본 이벤트), error (연결 실패). 커스텀 event: 필드를 쓰면 해당 이벤트명으로 리스닝해야 한다.

활용 맥락

• LLM 스트리밍 응답: OpenAI, Anthropic 등 LLM API가 토큰 단위 스트리밍에 SSE 사용
• 실시간 대시보드: 주가, 스코어보드, 알림 등 서버 푸시
• CI/CD 로그 스트리밍: 빌드 로그를 실시간으로 브라우저에 전달

---

Connections

• NDJSON (Newline Delimited JSON) — 둘 다 줄 단위 스트리밍이지만, NDJSON은 프로토콜 무관 순수 JSON 직렬화 포맷이고 SSE는 HTTP 이벤트 시맨틱(id, retry, event type) 내장
• WebSocket — SSE는 단방향(서버→클라이언트), WebSocket은 양방향

Source Trail

• 원본 스펙: WHATWG HTML — Server-Sent Events

Related MOCs

• Computer Science