Agent-Skills.md

Agent Skills: Real-Time & WebSockets

Implement WebSocket gateways with Socket.io and Server-Sent Events endpoints in NestJS. Use when building chat features, live feeds, or choosing between WebSocket and SSE for real-time communication. (triggers: **/*.gateway.ts, **/*.controller.ts, WebSocketGateway, SubscribeMessage, Sse, Socket.io)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nestjs-real-time

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nestjs/nestjs-real-time

Skill Files

Browse the full folder contents for nestjs-real-time.

Download Skill

Loading file tree…

skills/nestjs/nestjs-real-time/SKILL.md

Skill Metadata

Name
nestjs-real-time
Description
"Implement WebSocket gateways with Socket.io and Server-Sent Events endpoints in NestJS. Use when building chat features, live feeds, or choosing between WebSocket and SSE for real-time communication. (triggers: **/*.gateway.ts, **/*.controller.ts, WebSocketGateway, SubscribeMessage, Sse, Socket.io)"

Real-Time & WebSockets

Priority: P1 (OPERATIONAL)

WebSocket and real-time communication patterns with NestJS.

Workflow: Add Real-Time Feature

  1. Choose protocol — WebSocket for bi-directional (chat, collab); SSE for uni-directional (feeds, notifications).
  2. Implement gateway or SSE — Create a @WebSocketGateway() or @Sse() controller.
  3. Add auth — Validate JWT in handleConnection() for WebSocket; use standard guards for SSE.
  4. Scale — Add @socket.io/redis-adapter for multi-pod WebSocket; use HTTP/2 for SSE.
  5. Test connections — Verify WebSocket handshake auth rejects invalid tokens; confirm SSE streams data.

SSE Endpoint Example

See implementation examples

WebSocket Gateway with Auth Example

See implementation examples

Protocol Selection

  • WebSockets (Bi-directional): Use for Chat, Multiplayer Games, Collaborative Editing.
    • High Complexity: Requires custom scaling (Redis Adapter) and sticky sessions (sometimes).
  • Server-Sent Events (SSE) (Uni-directional): Use for Notifications, Live Feeds, Tickers, CI Log streaming.
    • Low Complexity: Standard HTTP. Works with standard Load Balancers. Easy to secure.
    • NestJS: Use @Sse('route') returning Observable<MessageEvent>.
  • Long Polling: Use only as a fallback or for extremely low-frequency updates (e.g., job status check every 10m).
    • Impact: High header overhead. Blocks threads if not handled carefully.

WebSockets Implementation

  • Socket.io: Default choice. Features "Rooms", "Namespaces", and automatic reconnection. Heavy protocol.
  • Fastify/WS: Use ws adapter if performance is critical (e.g., high-frequency trading updates) and you don't need "Rooms" logic.

Scaling (Critical)

  • WebSockets: In K8s, a client connects to Pod A. If Pod B emits an event, the client won't receive it.
    • Solution: Redis Adapter (@socket.io/redis-adapter). Every pod publishes to Redis; Redis distributes to all other pods.
  • SSE: Stateless. No special adapter needed, but be aware of Connection Limits (6 concurrent connections per domain in HTTP/1.1; virtually unlimited in HTTP/2).
    • Rule: Must use HTTP/2 for SSE at scale.

Security

  • Handshake Auth: Standard HTTP Guards don't trigger on Ws connection efficiently.
    • Pattern: Validate JWT during the handleConnection() lifecycle method. Disconnect immediately if invalid.
  • Rate Limiting: Sockets are expensive. Apply strict throttling on "Message" events to prevent flooding.

Architecture

  • Gateway != Service: The WebSocketGateway should only handle client comms (Join Room, Ack message).
    • Rule: Delegate business logic to a Service or Command Bus.
  • Events: Use AsyncApi or SocketApi decorators (from community packages) to document WS events similarly to OpenAPI.

Anti-Patterns

  • No HTTP guards for WebSocket auth: Validate JWT in handleConnection(); HTTP guards don't trigger on WS.
  • No WebSocket at scale without Redis adapter: Without @socket.io/redis-adapter, cross-pod events are lost.
  • No SSE over HTTP/1.1 at scale: Use HTTP/2 to avoid the 6-connection-per-domain browser limit.