feat: HTTP Events Query as an opt-in alternative to SSE

[dunglas]

Implements the HTTP Events Query Internet-Draft as an opt-in alternative delivery mechanism to Server-Sent Events, plus binary event payloads.

What

With the new events_query directive (WithEventsQuery() in Go), a QUERY subscriber whose Accept header prefers multipart/mixed receives each update as a body part: the raw data as the part body, the event ID in Content-Event-Id (a MIME extension field carrying the ID verbatim), and the publisher-declared media type in Content-Type. Everything else stays byte-identical SSE, so enabling the option cannot regress existing clients.

• The existing form-encoded QUERY body (topics + last_event_id) serves as the draft's subscription data model realization; no new request format.
• Events: duration=N (request) caps the connection; the response advertises the effective bound, never longer than write_timeout or the token expiration. Gated on events_query since the field is not standard yet.
• Resumption is identical on both encodings: Last-Event-ID / last_event_id in, Mercure-Last-Event-Id out (now CORS-exposed, fixing a pre-existing gap for fetch-based clients).
• Incremental: ?1 and Accept-Query: application/x-www-form-urlencoded are sent on every subscription response: the former is the standardized no-buffering signal SSE benefits from too, the latter advertises the unconditional QUERY support (RFC 10008).
• No heartbeat inside multipart streams; the bounded duration plays that role and the hub ends the document with a proper close delimiter.
• Feature advertised via mercure_events_query in the RFC 9728 protected resource metadata.

Binary payloads

The publish endpoint also accepts multipart/form-data bodies (gated on events_query, 415 otherwise). The data part carries raw bytes and its Content-Type header declares the event media type, which travels to multipart subscribers as the part's Content-Type.

• Delivery: multipart subscribers get the bytes verbatim; SSE subscribers get data base64-encoded, always (even for text payloads), so decoding is deterministic without a per-event metadata slot. This also gives byte-exact round-tripping, which SSE line splitting cannot (CR/CRLF normalize to LF).
• Persistence: Update.MarshalJSON base64-encodes binary data (encoding/json would silently corrupt invalid UTF-8 to U+FFFD), so the bolt JSON history is lossless.

Spec

spec/mercure.md is untouched. Everything Events Query-specific lives in a new standalone RFC-style extension, spec/mercure-events-query.md (draft-dunglas-mercure-events-query), which updates the core requirements only for hubs implementing it: multipart/mixed negotiation on QUERY subscriptions, the notification encoding (Content-Event-Id rationale included), bounded responses and the Events header, resumption via the Mercure reconciliation model, multipart/form-data publications with the SSE base64 rule, discovery, and the generalized field-injection security considerations. Unlike the core spec, the extension cites the Events Query draft directly.

Design choices

• No Mercure-invented notification envelope: application/json-seq support was considered and dropped; the multipart realization only uses native slots (a Content-Event-Id MIME extension field, Content-Type, raw body). SSE-specific properties (type, retry) are not represented.
• The event media type comes from the data part's own Content-Type header — the native MIME slot — rather than a content_type form field (an earlier revision of this branch had one; it was removed to keep a single, native way to declare it).
• The encoding seam is a small internal streamEncoder interface (sseEncoder, multipartEncoder), one instance per connection; the SSE path is byte-for-byte the previous behavior.
• WithEventsQuery is marked experimental: individual I-D, subject to change.

[huanglinfei091-cmd]

Hi @dunglas — I noticed the lint job failed at Lint Code Base in this GitHub Actions run for this PR.

I’m testing RunBack, an early alpha CLI that reconstructs a failed public Actions run locally with act. For this run, the useful question is whether the same code-base lint diagnostic is reproduced, or whether reconstruction stops with an honest blocked result.

runback doctor
runback https://github.com/dunglas/mercure/actions/runs/32027374001

The Linux amd64 binary and checksum are in the v0.1.0-alpha release. If you try it, the verdict (SAME_FAILURE, DIFFERENT_FAILURE, or REPLAY_BLOCKED), Stage/Cause, and any install friction would be useful. Please do not post tokens or secrets. I’m asking for candid alpha evidence rather than a star or promotion; a failed reproduction is useful too.