Implement complete SSE plugin with streaming, lifecycle, and session management

[mcollina]

Summary

This PR implements a comprehensive Server-Sent Events (SSE) plugin for Fastify, directly implementing the API design agreed upon in fastify/fastify#6276. The implementation provides first-class SSE support with clean reply.sse.send() and reply.sse.stream() methods as specified in the community discussion.

Key Features Implemented

• Unified API Interface: Clean reply.sse.* methods that integrate seamlessly with Fastify's request/reply cycle
• Multiple Data Sources: Support for single messages, async generators, Node.js streams, and plain strings
• Session Management: Built-in connection state tracking with isConnected and keepAlive() functionality
• Message Replay: Automatic handling of client reconnections with Last-Event-ID header support
• Heartbeat System: Configurable keep-alive mechanism to maintain connections
• Route-level Configuration: Routes can be marked with { sse: true } for automatic SSE handling
• Graceful Fallback: Non-SSE requests to SSE routes receive regular JSON responses

API Examples

Basic Message Sending with reply.sse.send()

// Send simple message
await reply.sse.send('Hello World');

// Send structured data with event type
await reply.sse.send({ user: 'john', message: 'Hello' }, { 
  event: 'chat-message',
  id: '123'
});

// Send with retry configuration
await reply.sse.send(data, { 
  event: 'notification',
  retry: 5000 
});

Streaming with reply.sse.stream()

// Stream from async generator
async function* dataGenerator() {
  for (let i = 0; i < 10; i++) {
    yield { count: i, timestamp: Date.now() };
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

await reply.sse.stream(dataGenerator());

// Stream from Node.js readable stream
const fs = require('fs');
const stream = fs.createReadStream('data.json');
await reply.sse.stream(stream);

Route Configuration

fastify.register(ssePlugin);

fastify.get('/events', { sse: true }, async (request, reply) => {
  // SSE context automatically available
  await reply.sse.send({ message: 'Connected!' });
  
  // Stream live data
  await reply.sse.stream(getLiveDataStream());
});

Testing Coverage

Comprehensive test suite covering:

• Core SSE functionality: Message formatting, headers, connection setup
• API methods: Both reply.sse.send() and reply.sse.stream() with various data types
• Connection lifecycle: Connect, disconnect, reconnection with Last-Event-ID
• Session management: Heartbeat, keep-alive, connection state tracking
• Error handling: Invalid data, connection errors, stream failures
• Edge cases: Non-SSE requests, malformed headers, concurrent connections

TypeScript Support

Complete TypeScript definitions provided:

• Plugin registration: Proper typing for plugin options and configuration
• Reply decoration: Full IntelliSense support for reply.sse.* methods
• Route configuration: Type-safe SSE route options with { sse: true }
• Method signatures: Detailed parameter and return types for all SSE methods
• Generic support: Parameterized types for data payloads

interface SSEOptions {
  event?: string;
  id?: string;
  retry?: number;
}

interface FastifyReply {
  sse: {
    send<T = any>(data: T, options?: SSEOptions): Promise<void>;
    stream(source: AsyncIterable<any> | NodeJS.ReadableStream): Promise<void>;
    isConnected: boolean;
    keepAlive(): void;
  };
}

Implementation Architecture

The plugin follows the API design from fastify/fastify#6276 by:

1. Route-level Detection: Automatically detects SSE requests via Accept: text/event-stream header
2. SSE Context Creation: Sets up connection management with proper headers and state tracking
3. Reply Decoration: Adds reply.sse.send() and reply.sse.stream() methods to the reply object
4. Lifecycle Management: Handles connection cleanup, heartbeat timers, and graceful shutdowns
5. Fallback Handling: Provides regular JSON responses for non-SSE clients

This implementation is production-ready and follows Fastify plugin conventions while delivering the exact API interface agreed upon in the GitHub issue discussion.

[mcollina]

cc @climba03003 @Uzlopak

[climba03003]

LGTM.

We should change to neostandard + eslint before release.

[Uzlopak]

I need a day to review

[Uzlopak]

I will try to use this plugin for smee.io to check if I see issues in real use

[mcollina]

@Uzlopak if you lgtm it I'll ship a 0.0.1.

[Uzlopak]

LGTM

[Uzlopak]

Lets go :)