SSE Setup - 🌲 Sonamu

Sonamu supports Server-Sent Events (SSE) based on the fastify-sse-v2 plugin. With SSE, you can push real-time data from the server to the client.

What is SSE?

Server-Sent Events is a technology that provides unidirectional real-time communication from server to client.

HTTP vs SSE vs WebSocket

Comparison Table

Feature	HTTP	SSE	WebSocket
Direction	Request→Response	Server→Client	Bidirectional
Protocol	HTTP	HTTP	WebSocket
Reconnection	X	Automatic	Manual
Complexity	Low	Medium	High
Use case	General API	Real-time push	Real-time chat

SSE Use Cases

Real-time Notifications

New messages, likes, comments, etc.

Progress Updates

File uploads, task processing progress

Live Feeds

News feeds, social media updates

Monitoring

Server status, log streaming

Basic Setup

sonamu.config.ts

import { type SonamuConfig } from "sonamu";

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,  // Enable SSE plugin
    }
  }
};

Default behavior:

Automatic SSE endpoint registration
Automatic reconnection support
Automatic keep-alive sending

SSE Plugin Options

boolean
SsePluginOptions

Simple enable/disable

plugins: {
  sse: true,   // Enable
  sse: false,  // Disable
}

Detailed configuration

import type { SsePluginOptions } from "fastify-sse-v2/lib/types";

plugins: {
  sse: {
    // Configure options (if needed)
  } as SsePluginOptions
}

Note: Default settings are sufficient in most cases.

How SSE Works

Connection Flow

HTTP Headers

SSE uses special HTTP headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Characteristics:

text/event-stream: SSE-specific Content-Type
no-cache: Prevents caching
keep-alive: Maintains connection

Practical Configuration Examples

1. Basic Setup (Recommended)

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,  // Simply enable
    }
  }
};

2. Development/Production Separation

const isDevelopment = process.env.NODE_ENV === 'development';

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: !isDevelopment,  // Enable only in production
    }
  }
};

Reason: In development, connections frequently disconnect due to HMR

3. Conditional Activation

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: process.env.ENABLE_SSE === 'true',
    }
  }
};

ENABLE_SSE=true

Disabling Compression

SSE is a streaming response, so compression must be disabled.

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,
      compress: {
        global: true,  // Enable global compression
        threshold: 1024,
        encodings: ["gzip"],
      }
    }
  }
};

Handled automatically in @stream decorator:

@stream({
  type: 'sse',
  events: z.object({
    message: z.string(),
  })
})
async streamUpdates(ctx: Context): Promise<void> {
  // The @stream decorator automatically disables compression.
  // ...
}

CORS Configuration

CORS configuration is required to use SSE from different domains.

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,
      cors: {
        origin: ['https://example.com', 'https://app.example.com'],
        credentials: true,
      }
    }
  }
};

Note: SSE can send authentication cookies, so credentials: true is required

Environment-specific Strategies

Development Environment

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,
      cors: {
        origin: 'http://localhost:5173',  // Vite dev server
        credentials: true,
      }
    }
  }
};

Production Environment

export const config: SonamuConfig = {
  server: {
    plugins: {
      sse: true,
      cors: {
        origin: process.env.FRONTEND_URL,
        credentials: true,
      }
    }
  }
};

FRONTEND_URL=https://app.example.com

Timeout Configuration

SSE connections are maintained for long periods, so timeout configuration is important.

export const config: SonamuConfig = {
  server: {
    fastify: {
      connectionTimeout: 0,  // Disable timeout
      keepAliveTimeout: 5000,  // Keep-alive: 5 seconds
    },
    plugins: {
      sse: true,
    }
  }
};

Configuration values:

connectionTimeout: 0: Disable connection timeout (SSE maintains long connections)
keepAliveTimeout: Keep-alive interval (default: 5 seconds)

Proxy Configuration (Nginx)

When using Nginx, SSE-specific configuration is required.

server {
    listen 80;
    server_name api.example.com;

    location /stream/ {
        proxy_pass http://localhost:3000;

        # SSE required settings
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;

        # Disable buffering
        proxy_buffering off;
        proxy_cache off;

        # Timeout
        proxy_read_timeout 24h;
        proxy_send_timeout 24h;
    }
}

Key settings:

proxy_buffering off: Disable buffering (immediate transmission)
proxy_cache off: Disable caching
proxy_read_timeout 24h: Read timeout (long duration)

Debugging

Browser Developer Tools

Network tab → Select stream request → Headers tab

Request Headers:
  Accept: text/event-stream

Response Headers:
  Content-Type: text/event-stream
  Cache-Control: no-cache
  Connection: keep-alive

EventStream tab:
  event: message
  data: {"text": "Hello"}

  event: update
  data: {"count": 5}

curl Test

# Test SSE connection
curl -N http://localhost:3000/stream/updates

# Result:
# event: message
# data: {"text": "Hello"}
#
# event: update
# data: {"count": 5}
#
# event: end
# data: END

Options:

-N: Disable buffering (immediate output)

Important Notes

Important considerations when configuring SSE:

Disable compression: SSE is streaming, so compression is prohibited (handled automatically by @stream decorator)

@stream({ type: 'sse', events: z.object({ message: z.string() }) })
async streamData(ctx: Context): Promise<void> { ... }

Timeout settings: Maintain long connections
fastify: { connectionTimeout: 0, }

CORS configuration: Required when using from different domains

cors: {
  origin: 'https://example.com',
  credentials: true,
}

Reconnection handling: Clients need to implement auto-reconnection

// EventSource handles this automatically
const source = new EventSource('/stream/updates');

Browser limitations: Concurrent SSE connection limit (6 per domain)
- Solution: Use HTTP/2 or reuse connections
Proxy buffering: Must disable buffering in Nginx, etc.
proxy_buffering off;

Browser Support

SSE is supported in all modern browsers:

Browser	Support
Chrome	✅
Firefox	✅
Safari	✅
Edge	✅
IE 11	❌ (polyfill required)

IE 11 support: event-source-polyfill

Next Steps

Creating SSE Endpoints

Build SSE APIs with the @stream decorator

Client Integration

Using SSE in the frontend

​What is SSE?

​HTTP vs SSE vs WebSocket

​Comparison Table

​SSE Use Cases

Real-time Notifications

Progress Updates

Live Feeds

Monitoring

​Basic Setup

​sonamu.config.ts

​SSE Plugin Options

​How SSE Works

​Connection Flow

​HTTP Headers

​Practical Configuration Examples

​1. Basic Setup (Recommended)

​2. Development/Production Separation

​3. Conditional Activation

​Disabling Compression

​CORS Configuration

​Environment-specific Strategies

​Development Environment

​Production Environment

​Timeout Configuration

​Proxy Configuration (Nginx)

​Debugging

​Browser Developer Tools

​curl Test

​Important Notes

​Browser Support

​Next Steps