EventSource

An informal specification of EventSource as implemented in workerd, derived from, and kept in lockstep with, the test suite in this directory. The tests are the normative artifact. Both the C++ implementation (src/workerd/api/eventsource.{h,c++}) and the TypeScript implementation (src/per_isolate/eventsource/eventsource.ts, behind the TS_EVENT_SOURCE autogate) are covered. The TypeScript class subclasses EventTarget through the seam in src/per_isolate/events/event-target-internals.ts and does its I/O through RequestIo (src/workerd/api/request-io.{h,c++}), so dispatch, fetch and request binding are shared; the divergences are in class shape, in event stream parsing, in the Last-Event-ID header, and in how reads are driven.

Interface

[Exposed=Worker]
interface EventSource : EventTarget {
  constructor(USVString url, optional EventSourceInit eventSourceInitDict = {});
  static EventSource from(ReadableStream stream);  // Workers extension

  readonly attribute USVString url;
  readonly attribute boolean withCredentials;  // always false

  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSED = 2;
  readonly attribute unsigned short readyState;

  attribute EventHandler onopen;
  attribute EventHandler onmessage;
  attribute EventHandler onerror;
  undefined close();
};

dictionary EventSourceInit {
  boolean withCredentials = false;  // a truthy value throws NotSupportedError
  Fetcher fetcher;                  // Workers extension
};

• EventSource is always a global, with no compatibility flag.
• An EventSource can only be created within a request: NotSupportedError, from the constructor and from() alike.
• The URL must be absolute (SyntaxError); it is normalized as the URL parser does. Both arguments are converted, init's members in order, before anything is checked.
• EventSource.from() takes a ReadableStream that is neither locked nor disturbed, needs no receiver, and returns an EventSource that is already OPEN, with url ''.
• [Symbol.dispose] is a function of its own that calls close().
• Every member is brand-checked and throws JSG's illegal-invocation TypeError for any other receiver. Members are enumerable, like every JSG member; names, lengths and constants' configurability follow spec_compliant_property_attributes.

Core semantics

• Request: a GET through the init's fetcher, else the global fetch(), with Accept: text/event-stream, Cache-Control: no-cache, and Last-Event-ID on a reconnection that has one (whitespace trimmed in the TypeScript implementation, #16).
• Response: a status other than 200, or a content type other than text/event-stream (parameters allowed), fails the EventSource for good with an AbortError. A redirect moves url and the messages' origin. A response without a body is retried once, as an end of the stream; a second in a row fails the EventSource. A rejected fetch() closes it without reconnecting.
• Reconnection: the end of a connected EventSource's stream fires an 'error' (The server disconnected.) in CONNECTING and reconnects after the reconnection time, 2 seconds unless a retry field set it, clamped to 1 to 10 seconds. The end of an EventSource.from() stream closes it.
• Parsing follows the HTML standard in the TypeScript implementation; the C++ parser departs from it in the cases of ledger #4 to #9. The stream is decoded as UTF-8 with replacement. A string chunk from a from() stream is read as its UTF-8 bytes, any buffer or view as its bytes; anything else fails the EventSource with the TypeError the streams implementation's byte reads throw.
• Events: a trusted OpenEvent (whose class is not a global), trusted MessageEvents carrying lastEventId and the URL's origin (null for a from() source), and trusted ErrorEvents whose error says why. None bubbles or is cancelable.
• Event handlers: onopen, onmessage and onerror are HTML event handler attributes, positioned at first assignment and kept across reassignment; any other on<type> property is called as EventTarget calls it.
• close() is idempotent and fires nothing. Callbacks resumed by another request do nothing, and close() from another request throws.
• Listener exceptions under spec_compliant_dispatch_exceptions: a throwing 'open' or 'message' listener's exception is reported, the remaining listeners run, then the EventSource errors out with it and the rest of the messages are dropped. A throwing 'error' listener's exception is only reported. Without the flag the first throwing 'message' listener ends the dispatch, unreported, and errors the EventSource out.
• Lifetime: a pending read retains its EventSource; once the stream has ended, nothing does.
• Prototype pollution: the TypeScript implementation reaches built-ins only through primordials. The C++ implementation calls no built-in either, except that reading the TypeScript streams, the native pump resolves a promise with another, which looks up Promise.prototype.then; pollution.js leaves that unpatched for the cpp-ts-streams cell.

Compatibility flags

The main cells pin the two dated flags on; the legacy cells pin them off by their disable names, so every cell keeps its @all-compat-flags variant. The main cells also pin nodejs_compat (node:assert, node:util), enable_weak_ref and rpc (for gc.js), and streams_enable_constructors.

Divergence ledger (C++ vs TypeScript)

The C++ implementation also logs a from() stream's non-byte chunk error twice; the TypeScript one, once. Not in the ledger, as only the logs see it.

Assertion catalogue

Web Platform Tests

src/wpt runs the eventsource WPTs, but most need a base URL to resolve relative URLs, which workerd lacks, or browser features (workers, CORS, credentials). The format cases are adapted here instead, through EventSource.from() or server.js: format-bom-2, format-data-before-final-empty-line, format-field-data, format-field-event-empty, format-field-parsing, format-leading-space, format-newlines and format-null-character.

Tests that live elsewhere (by design)

• src/workerd/api/eventsource-test.c++: a unit test of the C++ implementation's native pump, removed with it.
• eventSourceLegacyError in src/workerd/api/tests/legacy-dispatch-exceptions-test.js, which pins the legacy dispatch policy across several APIs at once.