실시간 알림 구현 하기 : 1. SSE(Server Sent Events)는 무엇인가?

SSE(Server Sent Events)

• SSE의 경우 웹페이지(클라이언트)의 요청 없이도 언제든지 서버가 새로운 데이터를 보내는 것이 가능
  • 전통적으로 웹페이지(클라이언트)는 새로운 데이터를 받기 위해 서버로 요청을 보내야 함
• SSE(Server-Sent Events)는 실시간 웹 애플리케이션을 구현하는데 사용될 수 있는 Web API
• 실시간으로 소식 불러오기, 알림 받기 등 실시간으로 모니터링 해야하는 상황해서 사용할때 유용하게 사용

동작 흐름

왼 : 기존 HTTP, 오 : SSE

1. 클라이언트가 서버에게 SSE로 통신하자는 요청을 보냄. (Connection Request)
2. 서버는 이 요청을 수신하고 수락했음을 알리는 메시지를 보냄. (Connection Response)
3. 클라이언트는 이를 받고, 지금부터 서버가 보내주는 데이터들에 반응할 준비
4. 이제 서버는 정해진 이벤트가 있을 때마다 클라이언트에게 메시지를 보냄. (Event Response)
   이때, 클라이언트는 단방향 통신이므로 이에 응답할 수는 없음!
5. 클라이언트는 서버로부터 메시지가 도착할 때마다 이에 반응하여 화면을 업데이트하는 등 필요한 작업.
6. 이 과정들을 하나의 연결 안에서 계속 이뤄지고, 만약 연결이 끊기면 클라이언트는 자동으로 재연결을 요청하여 통신을 재개.
7. 필요한 작업을 마치면 클라이언트 또는 서버에서 상대방에게 종료를 통보하는 메시지를 보냄으로써 연결이 끝.(Connection Closed)

메시지 구조

content-type : text/event-stream

id: 123
event: message
data: Hello World
data: This is another message line

각 메시지는 여러 필드로 구성되며, 각 필드는 줄바꿈(\\n)으로 구분되고, 메시지의 끝은 두 줄바꿈(\\n\\n)으로 표시.

 

1. Data

• 역할: 실제 전송할 데이터를 담는 필드
• 특징:
  • 한 메시지에 여러 data: 필드를 포함
  • 각 data: 라인은 줄바꿈(\\n)으로 구분
  • 브라우저에서 수신 시, 여러 data: 줄은 하나의 문자열로 합쳐져 전달
• 예시:

data: Hello data: World

→ 클라이언트에서는 "Hello\\nWorld"로 수신

 

2. Event

• 역할: 기본 message 외에 커스텀 이벤트 타입을 정의
• 특징:
  • event: 필드를 사용해 이벤트 이름을 지정하면,
  • 클라이언트에서 addEventListener('customEventName', ...) 형식으로 수신가능
• 예시:

event: update data: New data available

→ 클라이언트에서는 eventSource.addEventListener('update', handler)로 처리

 

3. ID

• 역할: 메시지의 고유 ID를 지정
• 용도:
  • 재연결 시점 관리에 사용
  • 브라우저가 끊긴 후 다시 연결할 때, 마지막으로 받은 id 값을 Last-Event-ID 헤더에 포함하여 전송하므로, 서버는 중단된 시점 이후의 데이터만 다시 보낼 수 있음.
• 예시:
• id: 123 data: New message

4. 메시지 종료

• 각 이벤트 메시지는 반드시 두 줄바꿈(\\n\\n)으로 끝나야 함.
• 이 구분자가 없으면 브라우저는 메시지를 “아직 끝나지 않은 상태”로 간주

---

✅ 종합 예시

id: 42
event: update
data: {"status": "ok", "message": "Data refreshed"}
\\n

→ 클라이언트 측 동작 예시

const eventSource = new EventSource('/events');

eventSource.addEventListener('update', (e) => {
  console.log('Received event:', e.data);
  // {"status": "ok", "message": "Data refreshed"}
});

---

즉, SSE 메시지는 id, event, data 필드를 조합한 단순한 텍스트 기반 프로토콜이며, 줄바꿈과 메시지 구분 규칙을 통해 브라우저가 실시간 이벤트를 안정적으로 처리할 수 있도록 설계됨.

 

 

 

알아야 할 개념

• Event ID 및 Last-Event-ID 헤더
  • 이벤트의 순서를 보장하기 위해 event ID를 사용가능
  • 클라이언트는 Last-Event-ID 헤더를 통해 마지막으로 수신한 이벤트 ID를 서버에 전달하여, 연결이 재설정된 경우에도 데이터 손실 없이 이어서 받을 수 있음
• Custom Event Types
  • 기본 이벤트 타입 외에도, 커스텀 이벤트 타입 정의 가능
  • 서버에서 특정 이벤트 타입을 설정하고, 클라이언트에서는 해당 타입에 대한 핸들러를 설정하여 다양한 이벤트를 처리
  • 메시지에 이벤트 이름이 지정되지 않은 경우 onmessage 핸들러가 호출
• Retry Mechanism
  • SSE는 자동으로 재연결을 시도하며, 기본 재연결 간격은 3초
  • 정수 값이 아닌 경우 retry 필더는 무시됨
  • 서버는 retry 필드를 통해 클라이언트의 재연결 간격을 조정
  • res.write(`retry: 5000\\n`); // 5초 후 재연결 시도
• 브라우저 지원 및 폴리필
  • 대부분의 현대적인 브라우저는 SSE를 지원하지만, Internet Explorer와 같은 구형 브라우저에서는 지원되지 않을 수 있음
  • 이런 경우 폴리필 라이브러리를 사용하여 호환성을 보장

한계점

1. Open connection 제한과 HTTP/2
   • 한 브라우저 domain 당 open connection 제한
     • mdnhttps://developer.mozilla.org/ko/docs/Web/API/Server-sent_events/Using_server-sent_events
   • 주의: HTTP/2 를 사용하지 않을 때 SSE는 활성화된 연결의 최대 개수 제한으로 인한 한계를 겪을 수 있으며, 이 제한은 브라우저당 적용될 뿐만 아니라 매우 낮은 수(6)로 설정되어 있어 특히 여러 탭을 열 때 문제를 겪을 수 있습니다. 이 문제는 Chrome과 Firefox에서 수정되지 않을 것으로 표시되었습니다. 이 제한은 브라우저와 도메인별로 적용되므로 www.example1.com 에 대해 모든 탭에서 6개의 SSE 연결을 열 수 있고, www.example2.com 에 대해서도 6개의 SSE 연결을 열 수 있습니다. (출처: Stackoverflow). HTTP/2를 사용할 때는 동시에 열 수 있는 HTTP 스트림의 최대 개수가 서버와 클라이언트 간에 협상되며, 기본값은 100입니다.
2. EventSource의 한계와 polyffils

• Web API로 주어지는 EventSource는 편리하지만, GET 요청 밖에 안되는 점, header 수정이 안되는 점 등의 한계
• polyfill 라이브러리를 통해 극복 가능
  • event-source-polyfill
  • @microsoft/fetch-event-source

 

기본 구성

클라이언트 - 프론트 구성

• 이벤트 리스너 등록 방식 - addEventListner 활용 시

// 이벤트를 전달 받기 위해서 서버로 접속을 시작하려면 우선, 
// 이벤트를 생성하는 서버측 스크립트를 URI로 지정하여 새로운 EventSource 객체를 생성한다
// EventSource 생성자에 전달 된 URL이 절대 URL 인 경우 
// 해당 출처 (scheme, domain, port)가 호출 페이지의 출처와 일치해야 한다.
const eventSource = new EventSource(`/subscribe`); // sse코드가 있는 서버단 파일

// 서버로부터 데이터가 오면
eventSource.addEventListener('message', function(e) {
  console.log(e.data);
});

// connection되면
eventSource.addEventListener('open', function(e) {
  // Connection was opened.
});

// error 나면
eventSource.addEventListener('error', function(e) {
  if (e.readyState == EventSource.CLOSED) {
    // Connection was closed.
  }
});

• 프로퍼티 핸들러 방식 - on

const eventSource = new EventSource('http://localhost:3000/events');

eventSource.onopen = () => {
  console.log('SSE 연결 성공');
  setError(null);
};

eventSource.onmessage = (event: MessageEvent) => {
  const eventData = JSON.parse(event.data);
  const newNotification: Notification = {
    id: Date.now(),
    message: eventData.message,
  };
  
  setMessages((prevMessages) => [...prevMessages, newNotification]);
};

eventSource.onerror = (err) => {
  console.error('SSE 에러:', err);
  setError('실시간 알림 연결에 문제가 발생했습니다.');
	
	
	// 이벤트 스트림 닫기
  eventSource.close();
};

 

 

 

❓eventSource의 addEventListner vs on (프로퍼티 핸들러) 방식은 어떤 차이를 가질까?

• 프로퍼티 핸들러를 사용하는 것과 addEventListner를 활용한 이벤트 리스너 등록 방식은 작동은 같다. 하지만, 실제로는 addEventListner가 훨씬 더 유연하고 확장성 있는 방법
• onmessage / onopen / onerror → 기본 이벤트 3종만 지원
• addEventListener() → 커스텀 이벤트까지 포함해 모든 이벤트 수신 가능
• 주요 차이점 요약 

  구분	onmessage / onopen / onerror	addEventListener()
  지원 이벤트	'open', 'message', 'error'	'open', 'message', 'error', 커스텀 이벤트
  중복 핸들러 등록	❌ 불가능 (마지막 할당만 유효)	✅ 가능 (여러 개 등록 가능)
  이벤트 제거	❌ 직접 제거 불가능	✅ removeEventListener()로 제거 가능
  코드 구조	간단	더 유연, 확장성 높음
  커스텀 이벤트 수신	❌ 불가능	✅ 가능 (event: customName)

• 상황 별 추천 방식 

  상황	추천 방식
  단순한 연결 / 기본 메시지 처리만 필요할 때	onmessage, onopen, onerror
  커스텀 이벤트(event: 필드) 사용 / 여러 리스너 필요 / 유지보수 중요	addEventListener() 방식 권장

 

서버 - 백엔드(node.js) 구성

import express from 'express';
import cors from 'cors';

const app = express();

const FRONTEND_URL = '<http://localhost:5173>';

const corsOptions = {
  origin: FRONTEND_URL,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
	// CORS 요청 시 인증정보(쿠키, 세션, Authorization 헤더 등) 포함 여부 설정
	// false(기본값): 교차 출처 요청 시 쿠키 등 인증정보를 전송하지 않음
	// true: 서버에서 Access-Control-Allow-Credentials: true 응답 시 인증정보 포함 가능
	// 주의: credentials: true 사용 시 origin을 반드시 명시해야 하며, '*'와 함께 사용할 수 없음
  **credentials: true,**
};

app.use(cors(corsOptions));

const port = 5000;
app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

app.get('/events', (req, res) => {
	**// Content-Type을 'text/event-stream'으로 전송해야 SSE 메시지 전송 가능"
  res.setHeader('Content-Type', 'text/event-stream');**
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  setInterval(()=>{
    const data = { message: `5초에 1번씩 보내는 메시지 : ${new Date().toISOString()}` };
    res.write(`data: ${JSON.stringify(data)}\\n\\n`);
  },5000)
});

• Content-Type text/event-stream
  • 서버에서 클라이언트로 실시간 데이터를 전송하기 위해 사용하는 MIME 타입
• Cache-Control no-cache
  • 클라이언트가 항상 최신 데이터를 받을 수 있게 하기 위해 응답을 캐싱하지 않도록 설정
• Connection keep-alive
  • HTTP연결 세션을 지속적으로 유지 시키기 위해 사용

커스텀 이벤트 타입 설정

// 서버에서 이벤트 타입 설정
res.write(`event: customEvent\\n`);
res.write(`data: ${JSON.stringify({ message: 'Custom Event Data' })}\\n\\n`);

• 클라이언트에서는 addEventListner를 통해서 이벤트 타입을 설정한다.

 

 

Reference

https://sanghee01.tistory.com/186

https://developer.mozilla.org/ko/docs/Web/API/Server-sent_events/Using_server-sent_events

https://techblog.woowahan.com/23199/

https://phsun102.tistory.com/202

https://velog.io/@blessoms2017/Event-Source-Polyfill로-모든-브라우저에서-SSE-구현하기

https://itsfuad.medium.com/understanding-server-sent-events-sse-with-node-js-3e881c533081

https://velog.io/@overslept/React에서-안전한-SSEServer-Sent-Events-연결-관리하기

https://cocococo331.tistory.com/76

https://boseong.dev/post/2025-09-05-sse-deep-dive

https://github.com/Azure/fetch-event-source?tab=readme-ov-file