0Pricing
NestJS Enterprise Backend APIs · 강의

단방향 푸시를 위한 서버 전송 이벤트

@Sse 데코레이터와 RxJS 옵저버블을 사용해 클라이언트에 실시간 업데이트를 스트리밍합니다

단방향 푸시를 위한 서버 전송 이벤트은(는) CoddyKit의 무료 NestJS Enterprise Backend APIs 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 NestJS Enterprise Backend APIs 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. NestJS Enterprise Backend APIs 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

Why Server-Sent Events?

Server-Sent Events (SSE) let a server push a continuous stream of updates to a client over a single, long-lived HTTP connection. It is the simplest way to deliver one-way, server-to-client live data such as notifications, progress bars, or dashboard metrics.

  • One-way only: the server talks, the client listens. There is no client-to-server channel on the same connection.
  • Plain HTTP: no special protocol upgrade like WebSockets need. It rides on a normal GET request.
  • Auto-reconnect: the browser's EventSource reconnects automatically if the connection drops.

In NestJS, SSE is a first-class feature exposed through the @Sse() decorator combined with RxJS observables.

SSE vs WebSockets

Both stream live data, but they solve different problems. Choosing the right one is an architectural decision.

  • SSE: server → client only, text-based, runs over HTTP/1.1 or HTTP/2, built-in reconnection and event IDs. Ideal for feeds, alerts, and progress.
  • WebSockets: full-duplex (both directions), binary or text, requires a protocol upgrade. Ideal for chat, multiplayer games, and collaborative editing.

If your clients only need to receive updates, SSE is lighter, easier to scale behind standard HTTP infrastructure, and requires no extra client library. Reach for WebSockets only when the client must also push messages in real time.

The wire format

SSE is just a streaming HTTP response with the content type text/event-stream. Each message is a block of text fields separated by newlines, and each block ends with a blank line.

  • data: the payload (often a JSON string).
  • event: a named event type the client can listen for.
  • id: a message identifier used for reconnection via Last-Event-ID.
  • retry: the reconnection delay in milliseconds.

You rarely format this by hand in NestJS — the framework serializes a typed object into these fields for you — but knowing the shape helps you debug with curl.

// Raw text/event-stream bytes the server emits
// (NestJS builds this for you from a MessageEvent)
const sample =
  'id: 42\n' +
  'event: heartbeat\n' +
  'data: {"status":"ok","ts":1718000000}\n' +
  '\n';

process.stdout.write(sample);

Your first @Sse endpoint

The @Sse() decorator marks a controller method as an SSE stream. Instead of returning a plain value, the method returns an RxJS Observable. Every value the observable emits becomes one SSE message sent to the client.

NestJS expects each emitted value to be a MessageEvent-shaped object with a data property. It automatically sets the text/event-stream headers and keeps the connection open.

import { Controller, Sse, MessageEvent } from '@nestjs/common';
import { interval, map, Observable } from 'rxjs';

@Controller('events')
export class EventsController {
  @Sse('clock')
  clock(): Observable<MessageEvent> {
    return interval(1000).pipe(
      map((n) => ({ data: { tick: n, time: new Date().toISOString() } })),
    );
  }
}

The MessageEvent shape

NestJS exports a MessageEvent interface that maps directly onto the SSE wire fields. Only data is required; the rest are optional.

  • data — string or object. Objects are JSON-stringified automatically.
  • type — becomes the event: field (a named event).
  • id — becomes the id: field, enabling resume-on-reconnect.
  • retry — becomes the retry: field in milliseconds.

Returning a well-typed object keeps your stream self-documenting and lets clients subscribe to specific named events.

import { MessageEvent } from '@nestjs/common';

function buildEvent(orderId: string, n: number): MessageEvent {
  return {
    id: String(n),
    type: 'order.updated',
    retry: 5000,
    data: { orderId, sequence: n },
  };
}

console.log(buildEvent('ord_123', 7));

Pushing domain events with a Subject

A fixed interval is fine for clocks, but real systems push when something happens. The idiomatic pattern is an RxJS Subject living in a service. Your business logic calls .next() on the subject whenever an event occurs, and the SSE endpoint simply exposes the subject as an observable.

This cleanly decouples the producer (any service) from the transport (the SSE controller).

import { Injectable, MessageEvent } from '@nestjs/common';
import { Subject, Observable } from 'rxjs';

@Injectable()
export class NotificationsService {
  private readonly stream$ = new Subject<MessageEvent>();

  emit(payload: unknown): void {
    this.stream$.next({ type: 'notification', data: payload });
  }

  asObservable(): Observable<MessageEvent> {
    return this.stream$.asObservable();
  }
}

Wiring the service to the controller

The controller injects the service and returns its observable from an @Sse() method. Any other part of the app — a queue consumer, a webhook handler, a cron job — can inject the same service and call emit() to broadcast to every connected client.

Because a plain Subject is multicast, all subscribers receive each emission. This is exactly what you want for a shared notification feed.

import { Controller, Post, Body, Sse, MessageEvent } from '@nestjs/common';
import { Observable } from 'rxjs';
import { NotificationsService } from './notifications.service';

@Controller('notifications')
export class NotificationsController {
  constructor(private readonly notifications: NotificationsService) {}

  @Sse('stream')
  stream(): Observable<MessageEvent> {
    return this.notifications.asObservable();
  }

  @Post()
  publish(@Body() body: { message: string }) {
    this.notifications.emit(body);
    return { accepted: true };
  }
}

Per-user filtered streams

A global subject broadcasts to everyone. In an enterprise API you usually want each client to receive only their events. Use RxJS operators like filter and map to tailor the stream per request, reading the user from a route param or the authenticated request.

The @Sse() method can accept normal route decorators such as @Param() and @Req(), so you can scope the observable to the current user.

import { Controller, Param, Sse, MessageEvent } from '@nestjs/common';
import { Observable, filter, map } from 'rxjs';
import { EventsBus } from './events.bus';

@Controller('users')
export class UserFeedController {
  constructor(private readonly bus: EventsBus) {}

  @Sse(':userId/feed')
  feed(@Param('userId') userId: string): Observable<MessageEvent> {
    return this.bus.events$.pipe(
      filter((e) => e.userId === userId),
      map((e) => ({ type: e.kind, data: e.payload })),
    );
  }
}

Heartbeats keep the connection alive

Proxies, load balancers, and browsers may close an idle connection. A heartbeat — a periodic comment or no-op event — keeps the pipe warm. With RxJS you merge your real event stream with a slow timer.

Send heartbeats as a distinct event type (or as SSE comment lines) so clients can ignore them. A common interval is every 15–30 seconds, comfortably under typical proxy idle timeouts.

import { merge, interval, map, Observable } from 'rxjs';
import { MessageEvent } from '@nestjs/common';

export function withHeartbeat(
  source$: Observable<MessageEvent>,
): Observable<MessageEvent> {
  const heartbeat$ = interval(15000).pipe(
    map((): MessageEvent => ({ type: 'heartbeat', data: 'ping' })),
  );
  return merge(source$, heartbeat$);
}

Cleanup, errors, and backpressure

When a client disconnects, NestJS unsubscribes from your observable. Make sure your stream releases resources on unsubscribe — use finalize() for cleanup and never leak timers or listeners.

  • Use catchError to convert errors into a final event instead of crashing the stream.
  • Use finalize to log or decrement a connection counter when the client leaves.
  • Beware backpressure: a fast producer with a slow client buffers in memory. Throttle or sample high-frequency sources.
import { Observable, catchError, finalize, of } from 'rxjs';
import { MessageEvent } from '@nestjs/common';

export function safeStream(
  source$: Observable<MessageEvent>,
  onClose: () => void,
): Observable<MessageEvent> {
  return source$.pipe(
    catchError((err) =>
      of<MessageEvent>({ type: 'error', data: { message: err.message } }),
    ),
    finalize(onClose),
  );
}

Consuming the stream from a client

Browsers consume SSE with the native EventSource API. It connects, dispatches messages, and reconnects automatically. Listen to the default message event for unnamed data, or add listeners for your named event types.

Note that EventSource only supports GET and cannot set custom headers, so auth is usually done via cookies or a token in the query string. Tools like curl -N are great for quick debugging from the terminal.

// Browser-side consumer
const es = new EventSource('/notifications/stream');

es.addEventListener('notification', (e) => {
  const payload = JSON.parse(e.data);
  console.log('new notification', payload);
});

es.addEventListener('heartbeat', () => {
  // keep-alive, ignore
});

es.onerror = () => console.warn('reconnecting...');

Quick Check

Test your understanding of when and how to use SSE in NestJS.

Recap

You learned how to stream one-way live updates from NestJS using Server-Sent Events:

  • SSE is server-to-client only over plain HTTP, with built-in browser auto-reconnect — choose it over WebSockets when clients only need to receive.
  • The @Sse() decorator turns a controller method into a stream that returns an Observable<MessageEvent>; each emission becomes one message.
  • A MessageEvent maps to the wire fields data, type, id, and retry; objects are JSON-serialized for you.
  • Push real domain events with a shared Subject in a service, and scope per-user streams with filter and map.
  • Keep connections healthy with heartbeats via merge, and clean up safely using catchError and finalize.
  • Consume on the client with the native EventSource API.

자주 묻는 질문

“단방향 푸시를 위한 서버 전송 이벤트” 강의는 무료인가요?

네 — “단방향 푸시를 위한 서버 전송 이벤트” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 NestJS Enterprise Backend APIs 강의 전체를 잠금 해제할 수 있습니다. NestJS Enterprise Backend APIs 강의에는 총 4개의 강의가 포함되어 있습니다.

“단방향 푸시를 위한 서버 전송 이벤트”에서 뭘 배우나요?

@Sse 데코레이터와 RxJS 옵저버블을 사용해 클라이언트에 실시간 업데이트를 스트리밍합니다 브라우저에서 직접 실행하는 실습 코드로 NestJS Enterprise Backend APIs을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

NestJS Enterprise Backend APIs을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 NestJS Enterprise Backend APIs은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.

“단방향 푸시를 위한 서버 전송 이벤트” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 NestJS Enterprise Backend APIs 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 NestJS Enterprise Backend APIs 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. Socket.IO 어댑터를 사용한 WebSocket 게이트웨이
  2. 소켓 연결 인증 및 보호
  3. 단방향 푸시를 위한 서버 전송 이벤트
  4. Redis Pub/Sub 어댑터로 실시간 기능 확장하기
← NestJS Enterprise Backend APIs(으)로 돌아가기