eventsource

js/globals/eventsource.ts

EventSource global for Server-Sent Events (SSE) clients.

Implements the browser-shaped EventSource client over Fino's server-side networking stack. The global handles connection management, automatic reconnection with Last-Event-ID resumption, and EventTarget-based event dispatch. It extends EventTarget so addEventListener() / removeEventListener() work as expected.

The client opens direct HTTP/1 socket or TLS connections and parses the SSE wire stream itself. It intentionally does not share the fetch() connection pool or provide HTTP/2 or HTTP/3 transport behavior in this release baseline. Transport-agnostic SSE parser and formatter primitives are documented in fino:net/http/eventstream.

EventSource / SSE specification: https://html.spec.whatwg.org/multipage/server-sent-events.html

Example

const es = new EventSource('http://localhost:3000/events');
es.onopen    = () => { ... };
es.onmessage = (e) => { console.log(e.data); };
es.onerror   = (e) => { ... };
es.addEventListener('update', (e) => { ... });
// later:
es.close();

SSE wire format

Each event is one or more field lines followed by a blank line: event: <type>n ← optional; defaults to "message" data: <line1>n data: <line2>n ← multi-line data: joined with "n" id: <id>n ← optional; updates lastEventId buffer retry: <ms>n ← optional; integer ms reconnection interval n ← blank line dispatches the event

Lines starting with : are comments (ignored). Unknown field names are ignored. Line terminators: LF, CRLF, or bare CR (per W3C spec).

Parser behavior

• id: field value must not contain null (U+0000); otherwise ignored.
• retry: value must be all ASCII digits; otherwise ignored.
• An empty id: field (i.e. id:\n) sets lastEventId to "".
• Events without any data: lines are not dispatched.
• A field name with no colon means the entire line is the field name and the value is empty string.
• A single leading space after the colon is stripped from field values.

EventSource reconnection (W3C spec + pragmatic additions)

• Reconnects on: EOF (stream ended normally), network errors, and HTTP status codes 429, 500, 502, 503, 504 (retriable errors).
• Follows local HTTP redirects for 301, 302, 303, 307, and 308 responses, resolving relative Location values against the current request URL. Redirects always remain GET requests and are capped to prevent loops.
• Does NOT reconnect on: wrong Content-Type, other HTTP error statuses.
• HTTP 204 closes the stream gracefully without reconnecting.
• Reconnection uses a configurable retry interval (default: 3000ms), updated dynamically by retry: fields in the event stream.
• The Last-Event-ID header is sent on every reconnect attempt once any id: field has been seen — including an empty id: field, which is sent as an empty header value per the WHATWG spec rather than omitted.

Credentials, CORS, and TLS

This is a server-side EventSource implementation. It supports explicit caller-provided headers for credentials such as bearer tokens, but it does not implement browser cookie credential modes, an implicit cookie jar, or browser CORS enforcement. Set-Cookie response headers are ignored; callers that need cookies must provide a Cookie header explicitly. TLS verification is enabled by default for https: URLs. Tests and private deployments may pass a pinned CA path through tls.ca; disabling certificate verification with tls.rejectUnauthorized: false should be limited to local development.

Interfaces

const es = new EventSource('https://example.com/events', {
  headers: { authorization: 'Bearer token' },
});

new EventSource(url, { withCredentials: true }).withCredentials; // true

new EventSource(url, { headers: new Headers({ authorization: 'Bearer t' }) });

new EventSource('https://localhost/events', { tls: { ca: '/tmp/test-ca.pem' } });

Classes

const es = new EventSource('http://localhost:3000/events');
es.onopen = () => console.log('connected');
es.onmessage = (e) => console.log('message:', e.data);
es.onerror = () => console.log('disconnected; will retry');
es.addEventListener('update', (e) => console.log('update:', e.data));
// later:
es.close();

if (es.readyState === EventSource.CONNECTING) console.log('connecting');

if (es.readyState === EventSource.OPEN) console.log('open');

if (es.readyState === EventSource.CLOSED) console.log('closed');

const es = new EventSource('https://example.com/events', {
  headers: { authorization: 'Bearer token' },
});
es.onmessage = (event) => console.log(event.data);

console.log(es.readyState);

console.log(es.url);

console.log(es.lastEventId);

const es = new EventSource('/events', { withCredentials: true });
console.log(es.withCredentials);

es.onopen = () => console.log('open');

es.onmessage = (event) => console.log(event.data);

es.onerror = () => console.log('stream error');

es.onopen = null;

es.onmessage = null;

es.onerror = null;

es.close();