파이썬 SSE(Server-Sent Events)로 구현하는 실시간 스트리밍 네트워킹 핵심 가이드

파이썬 SSE(Server-Sent Events)로 구현하는 실시간 스트리밍 네트워킹 핵심 가이드

⚡ 서버가 일방적으로 푸시하는 SSE 스트림, 파이썬 httpx · aiohttp로 안전하게 받는 방법과 재연결까지 정리합니다

실시간 알림, 채팅의 타이핑 표시, 진행률 업데이트처럼 서버 쪽에서 계속 바뀌는 정보를 브라우저나 백엔드 워커가 꾸준히 받아야 하는 상황이 많습니다.
보통은 “실시간 = 웹소켓?”이라고 많이 생각하지만, 항상 양방향 통신이 필요한 건 아니죠.
한쪽(서버)에서만 계속 흘려보내 주면 되는 경우에는 더 단순한 방식이 오히려 안정적일 때가 많습니다.
그 대표 주자가 SSE(Server-Sent Events)입니다.
SSE는 HTTP 위에서 동작하는 텍스트 기반 스트리밍 프로토콜이고, 자동 재연결까지 기본으로 지원하기 때문에 브라우저의 EventSource 같은 API로도 쉽게 쓸 수 있다는 장점이 있습니다.
파이썬 쪽에서도 httpx나 aiohttp 같은 라이브러리로 iter_lines 형태로 한 줄씩 이벤트를 소비하는 패턴이 많이 사용되고 있습니다.
다만 스트리밍을 오래 유지하려면 프록시나 로드밸런서의 유휴 연결 타임아웃, 재연결 로직, 타임아웃 설정 같은 운영 포인트를 제대로 챙겨야 예기치 않은 끊김 없이 안정적으로 돌릴 수 있습니다.

이 글에서는 파이썬 네트워킹 관점에서 SSE를 이해하고 적용할 때 꼭 알아야 할 핵심만 콕 집어서 정리합니다.
SSE가 왜 “단방향 스트리밍”이라고 불리는지, 메시지가 왜 전부 텍스트 형식으로 내려오는지, 연결이 끊겨도 자동으로 다시 붙는 구조가 어떻게 보장되는지, 그리고 마지막으로 가장 많이 놓치는 인프라 레벨의 타임아웃 문제까지 다룹니다.
또한 httpx와 aiohttp에서 스트리밍 응답을 소비할 때 흔히 쓰는 iter_lines 패턴도 함께 짚어봅니다.

SSE(Server-Sent Events)는 기본적으로 서버에서 클라이언트로만 데이터가 흘러가는 단방향 스트리밍입니다.
즉 클라이언트가 따로 메시지를 역으로 보내지는 못합니다.
이 구조 덕분에 구현이 단순하면서도 푸시 알림처럼 “읽기 전용 실시간” 업데이트에는 굉장히 잘 맞습니다.
SSE 이벤트 포맷은 사람이 읽을 수 있는 텍스트 라인들로 구성되며, 보통 data:로 시작하는 줄들이 있고, 이벤트 블록은 빈 줄(\n\n)로 구분됩니다.
브라우저나 클라이언트는 이 스트림을 계속 읽으면서 화면을 갱신하게 됩니다.
만약 네트워크가 순간적으로 끊기거나 서버가 재시작되더라도, SSE 클라이언트는 자동으로 다시 연결을 시도하도록 설계되어 있습니다.
파이썬 쪽에서도 비슷한 아이디어로 재연결 루프를 짜거나, 아예 자동 재연결 기능을 가진 SSE 전용 클라이언트 구현체(예: aiohttp_sse_client)도 존재합니다.

한편 실서비스 단계에서는 “서버는 멀쩡한데 왜 스트림이 갑자기 멈췄지?”라는 상황이 꽤 자주 생깁니다.
원인은 애플리케이션 코드보다 그 앞단, 예를 들어 프록시나 로드밸런서가 유휴 연결을 일정 시간 후 강제로 끊어버리는 경우가 많습니다.
장시간 지속 연결(long-lived connection)을 기본 가정으로 하는 SSE 특성상 이 부분을 무시하면 장애처럼 보이는 끊김이 반복됩니다.
그래서 주기적으로 heartbeat 이벤트를 보내거나, 타임아웃이 난 경우 자동 재연결 로직으로 다시 붙는 흐름을 준비해 두는 게 사실상 필수입니다.

파이썬에서 SSE 스트림을 소비할 때는 보통 HTTP 응답 바디를 한 줄씩(async 이터레이터 또는 제너레이터처럼) 읽는 패턴을 사용합니다.
httpx나 aiohttp는 스트리밍 응답 바디를 순차적으로 처리할 수 있게 도와주는데, 예를 들어 iter_lines 스타일로 줄 단위 반복을 돌리면서 실시간 이벤트를 처리할 수 있습니다.
이 방식은 전체 응답을 메모리에 쌓지 않고 흘러오는 즉시 처리할 수 있다는 장점이 있어 로그 스트리밍, 모델 출력 토큰 스트리밍 같은 곳에서 널리 쓰입니다.
또한 httpx는 기본적으로 네트워크 관련 타임아웃을 가지고 있고(예: 응답 바이트 사이 간격이 너무 길어지면 예외 발생), aiohttp에서도 서버가 연결을 끊을 수 있기 때문에 이런 예외를 캐치해서 재시도 루틴으로 묶어주는 식의 안정화가 자주 쓰입니다.

아래 목차에서는 SSE의 기본 개념부터, 파이썬 비동기 환경에서 어떤 식으로 스트림을 소화하고 재연결을 설계하는지, 그리고 인프라 레벨에서 절대 놓치면 안 되는 타임아웃 포인트까지 차례대로 다룹니다.
특히 “장시간 열린 HTTP 연결이 프록시에서 끊기는 문제”는 실제 서비스 단계에서 가장 자주 맞닥뜨리는 장애라서 별도로 강조합니다.
마지막으로 자주 나오는 질문들을 FAQ로 묶어 파이썬 코드 관점에서 정리했습니다.

📡 SSE의 기본 개념과 특징

SSE(Server-Sent Events)는 이름 그대로 서버가 이벤트를 푸시(push)해서 보내고, 클라이언트는 그 흐름을 그대로 받아보는 구조의 스트리밍 기술입니다.
HTTP 연결 하나를 길게 열어 둔 상태에서 서버가 새로운 데이터가 생길 때마다 계속 밀어 넣는 방식이라서, 주식 시세, 알림 배지 카운트, 빌드 진행률, 실시간 로그처럼 “서버에서 계속 바뀌는 상황”을 전송하기에 딱 맞습니다.
핵심은 방향성에 있습니다.
SSE는 서버에서 클라이언트 방향으로만 데이터가 흐릅니다.
즉 단방향(one-way)입니다.
웹소켓처럼 양쪽이 서로 말을 주고받는(full-duplex) 구조가 아니라서, 구현 난이도가 낮고 인프라도 비교적 단순합니다.

SSE는 별도의 새로운 프로토콜을 쓰지 않고 기존의 HTTP 위에서 동작한다는 점이 실전에서 굉장히 편합니다.
브라우저에서는 EventSource라는 내장 객체로 바로 쓸 수 있고, 백엔드나 워커 같은 파이썬 측 소비자도 일반 HTTP 클라이언트로 스트리밍 응답을 읽을 수 있습니다.
이건 운영 쪽에서도 장점인데, 보안 정책, 로깅, 모니터링, 프록시 라우팅 등이 이미 HTTP 기반으로 깔려 있는 경우가 많기 때문입니다.
다만 이 말은 곧 HTTP 인프라의 제약(프록시나 로드밸런서의 유휴 타임아웃 등)도 그대로 따라온다는 뜻이라서, 장시간 연결을 유지할 때는 별도의 보호 장치가 필요합니다.
이는 뒤에서 인프라 파트에서 다시 짚습니다.

🧠 SSE는 왜 ‘텍스트 기반’이라고 할까?

SSE에서 데이터는 text/event-stream이라는 MIME 타입으로 내려오며, 사람이 읽을 수 있는 순수 텍스트 라인들로 구성됩니다.
이벤트 하나는 여러 줄로 이뤄질 수 있고, 각 줄에는 필드명: 값 형태가 들어갑니다.
가장 많이 쓰는 필드는 data:로, 실제 비즈니스 데이터(예: JSON 문자열 등)를 담습니다.
이벤트 블록과 블록 사이는 빈 줄 한 줄(\n\n)로 구분합니다.
즉 스트림은 거대한 한 덩어리의 바이너리가 아니라 “줄 단위 이벤트” 모음인 셈입니다.

data: {"progress":42,"status":"running"}
id: 12345
event: job_update

data: {"progress":43,"status":"running"}
id: 12346
event: job_update

보면 알 수 있듯이, 각각의 블록이 “이벤트” 역할을 합니다.
클라이언트는 이걸 순서대로 읽으면서 UI 반영을 하거나 백엔드 로직을 업데이트하면 됩니다.
중요한 점은 이 전체 과정이 텍스트 라인 단위로 흘러온다는 점입니다.
이 특성 덕분에 파이썬에서도 한 줄씩 읽어 들이는 iter_lines() 같은 패턴이 잘 맞습니다.
httpx는 스트리밍 응답 컨텍스트 안에서 for line in response.iter_lines(): 식으로 소비할 수 있게 지원하고 있고, 이건 SSE처럼 줄 단위 이벤트 모델에 거의 그대로 들어맞습니다.

🔄 자동 재연결 메커니즘의 의미

SSE의 또 다른 특징은 “연결이 끊어지면 다시 붙는다”는 동작을 명세 차원에서 가지고 있다는 점입니다.
브라우저의 EventSource는 서버와의 연결이 끊어졌다고 판단되면 일정 시간 뒤 자동으로 재접속을 시도합니다.
서버 쪽에서 retry: 라는 필드를 내려보내 재연결 대기 시간을 밀리초 단위로 안내할 수도 있습니다.
이 덕분에 네트워크가 순간 끊기거나 서버가 재시작돼도, 사용자는 “화면이 잠깐 멈췄다가 다시 살아나는” 정도로 끝나고 별도의 수동 새로고침 없이 스트림이 복구되는 경험을 하게 됩니다.

🔁 자동 재연결과 이벤트 ID 관리

SSE의 자동 재연결은 단순히 연결을 다시 맺는 수준이 아니라, 데이터 연속성을 보장하기 위한 체계적인 설계가 포함되어 있습니다.
SSE 스트림에는 id라는 필드가 존재하며, 서버가 이벤트마다 고유 ID를 붙여 보낼 수 있습니다.
클라이언트는 이 ID를 내부적으로 기억해 두었다가, 재연결 시 Last-Event-ID 헤더에 포함해 서버로 전송합니다.
이 구조 덕분에 잠깐 끊겼다가 다시 연결돼도 중복 없이 이어받을 수 있는 것입니다.
즉, 신뢰성 있는 스트리밍 복구 메커니즘이 HTTP 수준에서 이미 마련되어 있는 셈이죠.

📄 이벤트 ID 필드와 Last-Event-ID의 관계

서버가 스트림에 id: 필드를 추가하면, 클라이언트는 그 값을 내부 상태에 저장합니다.
만약 네트워크 문제나 서버 재시작 등으로 스트림이 끊기면, 브라우저나 파이썬 클라이언트가 다시 연결하면서 Last-Event-ID 헤더를 자동으로 보냅니다.
서버는 이를 보고 “이전 ID 이후의 이벤트”만 다시 보내면 되므로, 중복 데이터나 유실을 막을 수 있습니다.
예를 들어 다음과 같이 스트림을 구성할 수 있습니다.

data: {"msg":"첫 번째 이벤트"}
id: 1

data: {"msg":"두 번째 이벤트"}
id: 2

data: {"msg":"세 번째 이벤트"}
id: 3

만약 두 번째 이벤트 중간에 네트워크가 끊기더라도, 클라이언트는 자동으로 재연결하면서 Last-Event-ID: 2 헤더를 포함하게 됩니다.
서버는 이 정보를 보고 이후 이벤트(3번부터)를 다시 전송하면 되죠.
이런 방식은 단방향 스트리밍임에도 불구하고 “세션 일관성”을 유지하는 데 큰 도움이 됩니다.
즉, SSE는 단순히 데이터를 흘려보내는 기술이 아니라, 장애 회복성과 상태 복원까지 고려된 프로토콜이라고 볼 수 있습니다.

🕒 retry 필드와 재연결 주기 조정

SSE 명세에는 retry: 필드가 포함되어 있습니다.
이 필드는 연결이 끊어졌을 때, 클라이언트가 다음 재연결을 시도하기까지 기다릴 시간을 밀리초 단위로 지정합니다.
예를 들어 서버가 아래와 같이 응답하면:

retry: 10000
data: {"notice":"서버가 일시적으로 점검 중입니다. 잠시 후 다시 연결됩니다."}

이 경우 클라이언트는 스트림이 끊기더라도 10초 후에 다시 접속을 시도합니다.
즉, 서버가 상황에 따라 재연결 대기 시간을 동적으로 제어할 수 있는 구조입니다.
이는 서비스 유지보수나 장애 상황에서 서버 부하를 줄이거나, 백엔드에서 처리 큐를 정리할 시간을 확보할 때 유용합니다.

🐍 파이썬 httpx·aiohttp로 스트림 읽기와 iter_lines

SSE(Server-Sent Events)는 텍스트 스트림으로 이루어져 있기 때문에, 파이썬에서는 ‘줄 단위(line-based)’로 데이터를 읽는 패턴이 가장 자연스럽습니다.
이를 위해 널리 사용되는 방법이 iter_lines()입니다.
이 메서드는 서버가 보내는 데이터를 한 줄씩 받아볼 수 있게 해주며, 전체 응답을 메모리에 저장하지 않고 스트리밍 방식으로 처리할 수 있다는 장점이 있습니다.
즉, 대용량 로그 스트림이나 모델의 토큰 스트리밍처럼 “끝없이 이어지는 데이터”를 다룰 때 매우 효율적입니다.

⚙️ httpx로 SSE 스트림 처리하기

파이썬의 httpx 라이브러리는 HTTP 비동기 통신과 스트리밍 처리를 모두 지원합니다.
SSE는 단방향 스트림이므로, 응답을 스트리밍 모드로 열고 iter_lines()로 순회하면 실시간 이벤트를 바로 받을 수 있습니다.
다음은 예시 코드입니다.

import httpx

with httpx.stream("GET", "https://example.com/sse") as response:
    for line in response.iter_lines():
        if line:
            print("이벤트 수신:", line)

이 코드는 서버가 데이터를 보낼 때마다 즉시 해당 라인을 출력합니다.
만약 서버에서 빈 줄을 보내면, SSE 이벤트 하나가 끝났다는 의미로 해석할 수 있습니다.
이런 식으로 간단히 로그를 처리하거나, JSON으로 파싱해 실시간 대시보드에 반영할 수도 있습니다.

⚡ aiohttp로 비동기 SSE 처리

비동기 환경에서는 aiohttp가 훌륭한 선택입니다.
async/await 구문을 이용해 I/O를 효율적으로 처리할 수 있으며, 서버가 푸시하는 이벤트를 비동기 반복문으로 소비할 수 있습니다.
aiohttp의 content.iter_any() 또는 content.iter_chunked() 메서드를 이용하면 비슷한 효과를 낼 수 있습니다.

import aiohttp
import asyncio

async def listen_sse():
    async with aiohttp.ClientSession() as session:
        async with session.get("https://example.com/sse") as resp:
            async for line in resp.content:
                if line.strip():
                    print("이벤트 수신:", line.decode())

asyncio.run(listen_sse())

비동기 방식은 여러 SSE 연결을 동시에 관리하거나, 이벤트를 받아 바로 다른 API로 전송해야 할 때 특히 강력합니다.
또한 asyncio 기반 구조 덕분에 백엔드 서비스, 데이터 파이프라인, 실시간 AI 응답 스트리밍에도 활용하기 좋습니다.

결국 iter_lines() 패턴은 SSE의 본질과 매우 잘 맞습니다.
SSE가 텍스트 기반으로 한 줄씩 이벤트를 구분하기 때문에, 파이썬 쪽에서도 같은 방식으로 다루면 코드가 깔끔하고 직관적이죠.
또한 이 구조는 OpenAI API처럼 스트리밍으로 데이터를 보내는 AI 모델 응답 처리에도 자주 응용되고 있습니다.

⏳ 프록시·로드밸런서 타임아웃과 운영상 주의점

SSE는 장시간 열린 연결을 유지한다는 점에서, 인프라 레벨의 설정에 크게 영향을 받습니다.
특히 프록시(proxy)나 로드밸런서(load balancer)를 사용하는 환경에서는 일정 시간 동안 트래픽이 없다고 판단되면 연결을 강제로 끊어버리는 일이 자주 발생합니다.
서버와 클라이언트 입장에서는 문제가 없어도, 그 사이 계층에서 타임아웃을 적용해버리기 때문에 실서비스에서는 “간헐적 끊김” 형태로 자주 나타납니다.

🧱 인프라 타임아웃의 실제 사례

예를 들어 Nginx는 기본적으로 proxy_read_timeout이 60초로 설정되어 있습니다.
즉, 1분 동안 데이터가 오지 않으면 해당 연결을 끊습니다.
AWS ALB(Application Load Balancer)는 60초~120초의 idle timeout이 기본값이고, Cloudflare나 Fastly 같은 CDN 역시 비슷한 정책을 가집니다.
이런 환경에서 SSE를 그대로 사용하면, 서버가 아무 메시지도 보내지 않는 구간이 1분만 되어도 연결이 닫혀버리는 것입니다.
클라이언트는 곧바로 재연결을 시도하지만, 이 과정이 반복되면 불필요한 부하가 발생합니다.

💓 heartbeat 이벤트로 유휴 연결 유지하기

이 문제를 해결하는 가장 일반적인 방법은 일정 간격으로 heartbeat 이벤트를 보내는 것입니다.
서버가 주기적으로 “빈 데이터”를 보내면, 프록시 입장에서는 연결이 여전히 유효하다고 판단합니다.
이렇게 하면 유휴 타임아웃을 넘어서는 장기 연결도 안정적으로 유지할 수 있습니다.

data: [heartbeat]
id: 0

이런 단순한 heartbeat 패킷만으로도 연결이 끊기는 빈도를 눈에 띄게 줄일 수 있습니다.
특히 클라이언트 쪽에서는 이 메시지를 무시하도록 처리하면 되고, 서버는 타임아웃이 발생하기 전마다 주기적으로 전송하면 됩니다.
보통 15~30초 간격이 안정적입니다.

🧩 재연결 전략과 예외 처리

프록시 타임아웃을 피하는 것도 중요하지만, 완벽히 막을 수는 없습니다.
따라서 클라이언트 코드에는 항상 예외 처리 및 재시도 로직을 포함해야 합니다.
예를 들어 httpx의 경우 ReadTimeout이나 RemoteProtocolError 예외를 잡아 다시 연결을 시도하는 구조로 짜면 좋습니다.
aiohttp도 ClientPayloadError 등을 잡아 비슷한 재시도 루프를 돌릴 수 있습니다.

import httpx, time

while True:
    try:
        with httpx.stream("GET", "https://example.com/sse", timeout=None) as resp:
            for line in resp.iter_lines():
                if line:
                    print("이벤트:", line)
    except Exception as e:
        print("연결 끊김, 재시도 중:", e)
        time.sleep(3)

이런 방식으로 재시도 루프를 구성하면, 프록시나 네트워크 장애로 인한 일시적인 끊김에도 스트림을 복구할 수 있습니다.
핵심은 “끊길 수 있다”는 전제를 인정하고, 그때 자동으로 다시 붙는 구조를 만드는 것입니다.

🧩 SSE vs 웹소켓 언제 무엇을 쓸까

SSE(Server-Sent Events)와 웹소켓(WebSocket)은 모두 “실시간 통신”을 위한 기술이지만, 구조와 사용 목적이 다릅니다.
두 기술 모두 서버가 클라이언트에 데이터를 푸시할 수 있지만, SSE는 단방향 스트리밍, 웹소켓은 양방향 통신이라는 점이 핵심 차이입니다.
이 차이를 이해하면 언제 어떤 기술을 선택해야 하는지 명확해집니다.

🔍 구조적 차이 한눈에 보기

SSE는 단방향 스트리밍에 특화되어 있기 때문에, “서버가 데이터를 흘려보내는 역할”이 중심인 시스템에서 적합합니다.
예를 들어 뉴스 피드, 실시간 알림, 모델 출력 토큰 스트리밍(OpenAI API 등), 빌드 로그 모니터링 등이 대표적입니다.
반면, 사용자의 입력을 서버로 즉시 보내야 하거나, 실시간 상호작용이 핵심인 서비스(예: 채팅, 온라인 게임 등)는 웹소켓이 적합합니다.

💡 파이썬에서의 선택 기준

파이썬에서는 httpx, aiohttp 같은 HTTP 클라이언트가 SSE를 다루기에 적합하고, websockets 라이브러리가 양방향 WebSocket에 사용됩니다.
두 방식을 모두 다뤄본다면 “통신 방향성과 트래픽 패턴”으로 결정하는 것이 가장 명확합니다.
한쪽만 데이터가 흐르고, 메시지량이 적으며, 연결 유지 시간이 긴 경우라면 SSE가 훨씬 간결하고 안정적입니다.
특히 HTTP 인프라 위에서 자연스럽게 동작한다는 점은 운영 측면에서도 큰 장점입니다.

❓ 자주 묻는 질문 (FAQ)

🧠 파이썬 SSE 네트워킹의 핵심 정리

SSE(Server-Sent Events)는 복잡한 설정 없이도 실시간 스트리밍을 구현할 수 있는 가장 단순하고 안정적인 기술입니다.
HTTP 기반이라 방화벽이나 프록시 환경에서도 잘 동작하며, 텍스트 기반으로 메시지를 주고받기 때문에 디버깅도 쉽습니다.
파이썬에서는 httpx와 aiohttp로 손쉽게 구현할 수 있고, iter_lines() 형태로 데이터를 스트림 단위로 처리할 수 있다는 점이 특히 유용합니다.

자동 재연결과 이벤트 ID 복구 구조 덕분에 네트워크 장애에도 비교적 강하며, heartbeat 이벤트를 추가하면 프록시 타임아웃 문제도 예방할 수 있습니다.
웹소켓처럼 복잡한 핸드셰이크나 이중 통신 채널이 필요 없기 때문에, 읽기 전용 실시간 데이터 전송에는 SSE가 훨씬 효율적입니다.
단, 채팅이나 양방향 메시징처럼 클라이언트에서 서버로도 이벤트를 전송해야 하는 경우에는 웹소켓이 적합합니다.

결론적으로, SSE는 단방향 스트리밍이 필요한 모든 영역—예를 들어 AI 응답 스트리밍, 로그 모니터링, 서버 상태 피드, 실시간 데이터 시각화 등—에서 안정적이고 가볍게 사용할 수 있는 기술입니다.
HTTP 인프라 위에서 그대로 작동하기 때문에 유지보수나 배포 과정에서도 추가 설정이 거의 필요 없습니다.
이 특성 덕분에 많은 파이썬 기반 백엔드 시스템들이 SSE를 표준 실시간 통신 방법으로 채택하고 있습니다.

🏷️ 관련 태그 : SSE, ServerSentEvents, 파이썬네트워킹, httpx, aiohttp, 실시간스트리밍, 자동재연결, 프록시타임아웃, iter_lines, 단방향통신