This document describes the Server-Sent Events (SSE) implementation for the Red5 server, which provides W3C-compliant SSE functionality integrated with the existing Red5 Tomcat servlet infrastructure.
The SSE implementation consists of several components that work together to provide real-time server-to-client communication:
- SSEConnection: Manages individual SSE connections
- SSEManager: Handles connection lifecycle and broadcasting
- SSEServlet: HTTP servlet that establishes SSE connections
- SSEService: High-level API for application developers
- SSEEvent: Data structure for SSE events
- SSEApplicationAdapter: Example Red5 application adapter with built-in SSE support
- W3C SSE Specification Compliance: Full support for id, event, data, and retry fields
- Connection Management: Automatic cleanup of stale connections
- Keep-alive Support: Optional keep-alive messages to maintain connections
- Scope Integration: Events can be broadcast to specific Red5 scopes
- CORS Support: Built-in Cross-Origin Resource Sharing support
- Async Servlet Processing: Non-blocking connection handling
- Thread-safe: Concurrent connection management
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ SSEServlet │────│ SSEManager │────│ SSEConnection │
│ │ │ │ │ │
│ - HTTP endpoint │ │ - Lifecycle mgmt │ │ - Client conn │
│ - Async support │ │ - Broadcasting │ │ - Event sending │
│ - CORS handling │ │ - Cleanup tasks │ │ - Keep-alive │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ SSEService │ │ SSEApplication │
│ │ │ Adapter │
│ - High-level │ │ │
│ API │ │ - Red5 events │
│ - Application │ │ - SSE integration│
│ interface │ │ - Broadcasting │
└─────────────────┘ └──────────────────┘
Add the SSE beans to your Spring configuration, in red5-common.xml (they should already be present if you are using a recent version of Red5):
<!-- Server-Sent Events Configuration -->
<!-- SSE Manager - handles connection lifecycle and cleanup -->
<bean id="sseManager" class="org.red5.server.net.sse.SSEManager" init-method="afterPropertiesSet" destroy-method="destroy">
<!-- Connection timeout in milliseconds (default: 5 minutes) -->
<property name="connectionTimeoutMs" value="${sse.connection.timeout.ms:300000}"/>
<!-- Keep-alive interval in milliseconds (default: 30 seconds) -->
<property name="keepAliveIntervalMs" value="${sse.keepalive.interval.ms:30000}"/>
<!-- Enable/disable keep-alive messages (default: true) -->
<property name="keepAliveEnabled" value="${sse.keepalive.enabled:true}"/>
</bean>
<!-- SSE Service - high-level API for applications -->
<bean id="sseService" class="org.red5.server.net.sse.SSEService">
<property name="sseManager" ref="sseManager"/>
</bean>Enable the SSE service in your Red5 Tomcat / JEE setup by setting sse.enabled to true in red5.properties:
sse.enabled=trueThis will carryover to the Tomcat loader configuration:
<bean id="tomcat.server" class="org.red5.server.tomcat.TomcatLoader" depends-on="context.loader" lazy-init="true">
<property name="secureEnabled" value="${secure.enabled}" />
<property name="sseEnabled" value="${sse.enabled}" />
<property name="websocketEnabled" value="${websocket.enabled}" />Update your web.xml to include the SSE servlet:
<servlet>
<servlet-name>sse</servlet-name>
<servlet-class>org.red5.server.net.sse.SSEServlet</servlet-class>
<load-on-startup>-1</load-on-startup>
<async-supported>true</async-supported>
<init-param>
<param-name>cors.enabled</param-name>
<param-value>true</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>sse</servlet-name>
<url-pattern>/events</url-pattern>
<url-pattern>/events/*</url-pattern>
</servlet-mapping>The servlet accepts these optional init parameters:
| Parameter | Default | Purpose |
|---|---|---|
allowedOrigins |
none | Comma separated origins, such as https://app.example.com, granted cross-origin access with credentials. * grants any origin without credentials. When unset no CORS headers are sent, so only same-origin pages can connect. |
allowPost |
false |
Accept POST requests that publish events. Posted events only reach connections of the servlet's own application; a scope target must be inside that application. There is no built-in authentication, so only enable this behind your own access control. |
maxPostBytes |
65536 |
Largest accepted POST body. |
maxConnections |
1000 |
SSE connections allowed across the server before new ones get 503. |
cors.enabled |
true |
Set to false to leave CORS to an external filter. |
Before 2.0.46 the servlet echoed back any Origin with credentials allowed and accepted unauthenticated posts that could broadcast to every SSE connection on the server.
If an external CORS filter is used, you can disable CORS directly in the servlet by adding the following init parameters:
<init-param>
<param-name>cors.enabled</param-name>
<param-value>false</param-value>
</init-param>Ensure that the CORS filter allows these headers:
AcceptCache-ControlLast-Event-ID
Configure SSE behavior using properties in red5.properties:
# Enable/disable SSE support (default: true)
sse.enabled=true
# Connection timeout in milliseconds (default: 5 minutes)
sse.connection.timeout.ms=300000
# Keep-alive interval in milliseconds (default: 30 seconds)
sse.keepalive.interval.ms=30000
# Enable/disable keep-alive messages (default: true)
sse.keepalive.enabled=true@Autowired
private ISSEService sseService;
// Broadcast to all connections
sseService.broadcastMessage("Hello, everyone!");
// Broadcast with event type
sseService.broadcastEvent("notification", "New message received");
// Broadcast to specific scope
sseService.broadcastToScope(scope, "Welcome to the application");
// Send to specific connection
sseService.sendToConnection(connectionId, "Personal message");public class MyApplication extends SSEApplicationAdapter {
@Override
public boolean appConnect(IConnection conn, Object[] params) {
// Parent method automatically broadcasts user.connect event
boolean result = super.appConnect(conn, params);
// Send custom welcome message via SSE
broadcastSSEEvent("welcome", "New user joined: " + conn.getClient().getId());
return result;
}
public void sendNotification(String message) {
// Custom method to send notifications
broadcastSSEEvent("notification", message);
}
}// Simple message
SSEEvent event1 = SSEEvent.message("Hello World");
// Event with type and data
SSEEvent event2 = SSEEvent.of("chat", "User says hello");
// Full event with all fields
SSEEvent event3 = SSEEvent.builder()
.setId("msg-123")
.setEvent("notification")
.setData("System maintenance in 5 minutes")
.setRetry(5000);
sseService.broadcastEvent(event3);// Connect to SSE endpoint
const eventSource = new EventSource('/events');
// Handle connection events
eventSource.onopen = function(event) {
console.log('Connected to SSE');
};
// Handle messages (default event type)
eventSource.onmessage = function(event) {
console.log('Message:', event.data);
};
// Handle custom event types
eventSource.addEventListener('notification', function(event) {
console.log('Notification:', event.data);
});
eventSource.addEventListener('user.connect', function(event) {
console.log('User connected:', event.data);
});
// Handle errors
eventSource.onerror = function(event) {
console.error('SSE error:', event);
};
// Close connection when done
eventSource.close();A test HTML page is provided at /sse-test.html which demonstrates:
- Connecting to the SSE endpoint
- Receiving various event types
- Connection status monitoring
- Event logging and statistics
The implementation follows the W3C Server-Sent Events specification:
id: unique-event-id
event: event-type
data: event data line 1
data: event data line 2
retry: 5000
- id: Unique identifier for the event (optional)
- event: Event type name (optional, defaults to "message")
- data: Event payload (can be multi-line)
- retry: Reconnection timeout in milliseconds (optional)
Events can be broadcast to specific Red5 scopes, allowing for:
- Room-based messaging
- Application-specific notifications
- User group communications
SSE connections are managed alongside Red5's existing connection handling:
- Automatic cleanup when connections are lost
- Integration with Red5's scope lifecycle
- Thread-safe concurrent access
The SSEApplicationAdapter automatically broadcasts SSE events for:
- Application start/stop
- User connect/disconnect
- Custom application events
- Each SSE connection consumes one thread in async mode
- Configure thread pools appropriately for expected load
- Monitor connection count and cleanup effectiveness
- Each connection maintains minimal state
- Connection timeout prevents memory leaks
- Regular cleanup cycles remove stale connections
- Keep-alive messages maintain connection state
- Event compression is handled by HTTP layer
- Batch broadcasts are more efficient than individual sends
-
Connection Timeouts
- Increase
sse.connection.timeout.ms - Check network stability
- Verify keep-alive configuration
- Increase
-
CORS Errors
- Ensure proper CORS headers are set
- Check origin restrictions
- Verify browser CORS policy compliance
-
Memory Leaks
- Monitor connection cleanup logs
- Verify timeout configuration
- Check for proper connection closing
Enable debug logging for SSE components:
<logger name="org.red5.server.net.sse" level="DEBUG"/>- Authentication: Implement authentication in the servlet if needed
- Authorization: Control access to different event types/scopes
- Rate Limiting: Consider implementing rate limiting for broadcast operations
- Input Validation: Validate all event data before broadcasting
- CORS: Configure CORS policies appropriately for your deployment
This implementation follows:
- W3C Server-Sent Events specification
- HTTP/1.1 and HTTP/2 compatibility
- Jakarta EE servlet specification
- Red5 coding standards and patterns
org.red5.server.net.sse.SSEConnectionorg.red5.server.net.sse.SSEManagerorg.red5.server.net.sse.SSEServletorg.red5.server.net.sse.SSEEventorg.red5.server.net.sse.ISSEServiceorg.red5.server.net.sse.SSEServiceorg.red5.server.adapter.SSEApplicationAdapter
server/src/main/server/webapps/root/sse-test.html
This SSE implementation provides a robust, standards-compliant solution for real-time server-to-client communication in Red5 applications.