Directus SSE Bridge Extension

A minimal Server-Sent Events (SSE) bridge for Directus that provides a persistent connection as an availability signal.

Architecture

GET /sse-bridge/connect
       │
       ▼
persistent SSE connection
       │
       ├── initial `ready` event
       │
       ├── minimal keep-alive heartbeats
       │
       └── connection remains open

Core Principles

1. Connection = Availability: The existence and continuity of the SSE connection is itself useful as an availability signal. Contents of messages are not the availability signal.

2. Heartbeats ≠ Health Checks: Heartbeats exist only to prevent idle connections from being terminated by infrastructure (load balancers, reverse proxies). They contain no health information.

3. Generic Implementation: Completely unaware of its eventual consumer — no server or browser-specific logic, or application-specific semantics.

Endpoints

/connect (GET)

• Establishes a persistent SSE connection
• Sends initial ready event upon successful connection
• Sends periodic heartbeats to prevent idle timeouts
• Cleans up gracefully on disconnect

Full path: /sse-bridge/connect.

Heartbeat Configuration

Default interval: 30 seconds

Configure via environment variable:

SSE_BRIDGE_HEARTBEAT_INTERVAL_MS=30000

Heartbeats use minimal payload: : .\n\n (SSE comment with blank line)

Why 30 seconds?

Common reverse proxies and load balancers impose idle-connection timeouts that are opaque to the application. For example:

• Google Cloud HTTP(S) Load Balancer default idle timeout: 30s
• AWS Application Load Balancer default idle timeout: 60s
• nginx proxy_read_timeout default in many distributions: 60s

A 30s heartbeat is a deliberate conservative default. It is short enough to keep connections alive through the most common infrastructure defaults, while still avoiding excessive traffic. It is not derived from any single source and may not match every deployment's actual timeout configuration.

Deployment Note

Deployments behind infrastructure with known idle timeouts should configure the heartbeat interval to comfortably precede that timeout.

SSE Framing

The implementation follows standard SSE format:

event: ready
data: .

: .

: .

• Headers: Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no
• Response remains open indefinitely

Connection Lifecycle

Connect

1. Client makes GET request to /sse-bridge/connect
2. SSE headers set
3. Initial ready event sent
4. Heartbeat timer initialized

Disconnect

• Client disconnects gracefully or abruptly
• Cleanup clears heartbeat timer
• Response listeners removed
• Garbage collection allowed
• No error logs for normal disconnects
• Cleanup is idempotent: multiple close/error events cannot cause duplicate cleanup

Directus Version Compatibility

Built against @directus/[email protected] (@directus/[email protected]).

The endpoint implementation uses standard Express response/stream APIs and does not rely on Directus internals beyond the standard endpoint-extension API.