Events Query in Mercure Re: Mercure Protocol: spec stabilized for 1.0, refreshed Internet-Draft

[Rahul Gupta <[e-mail]>]

Hi Kévin,

Thanks for implementing Events Query in Mercure. And doing it so soon.

I had also started working on an implementation during the weekend, but I had two disadvantages: I do not speak Golang which forced me to use AI and I find that at times the coding proclivities of Claude are borderline offensive. It took me two more rewrites on the weekend implementation to get it in the form that I can share and might be instructive. It was also helpful to look at your implementation in the interim and stolen bits and pieces from it. The Draft PR is at https://github.com/dunglas/mercure/pull/1364.

The first and most important part of Events Query is that it is a standardized model to query for events - it allows clients to ask for additional modalities (say over EventSource) that servers can now provide. This allows servers to tune updates to client requirements. It does not mandate a request or response format. You would see in the PR that after refactoring your code, I built Events Query using form-encoding (with Mercure data model save the additional "events" property) for requests and Event Stream for response that you already had implemented (SSE are a valid, although anaemic response). It is only after I had step-by-step implemented the data model parsing, headers and content negotiation, did I add JSON subscription requests and Multipart notifications responses. Adding a new parser for subscriptions or new format for responses is now as simple as writing a parser or encoder according to the template and two lines to wire it up in `parser.go` or `encoder.go` respectively. You can play with new formats to your heart's content.

Choosing multipart/digest instead of multipart/mixed is a better pattern for Mercure as it side-steps your concerns. The default message/rfc822 part allows for headers that provide room for response fields like Event-ID or Mercure prefixed headers. The body can be used to send messages in any format you want -- there is no need to convert data to text or base64 (or deal with line breaks). I also have a great parser for multipart https://github.com/CxRes/multipart-fetch that is being used in production code, which breaks the parts into their own fetch responses.

The fact that you can send a message in another format with multipart is much more powerful than the comment hack in Event Stream (it is not a feature in my reading of the spec). You could, for example, use application/problem+json to send control messages. I am sending an empty "part" (containing only line breaks) as heartbeat, but if that is too heavy, we can use one empty part for multiple heartbeats.

In working with the code, it seems to me that things in Mercure are built around the limitations of SSE, especially writing to the hub. A real opportunity would be to send arbitrary media type in POST to the hub with a Mercure structured field or similar carrying the properties the hub needs to be aware of. And then multipart/mixed would be an ideal response type to forward those arbitrary media-type notifications. A step down would be allow clients to POST message/rfc822 messages. Events Query shines when you give users the freedom to send data however they want.

As for the code, I have mostly left your QUERY implementation untouched (except to fix conneg: goautoneg library was not consistent with RFC9110; and missing content-type for QUERY, which was counter to guidance of RFC10008). The only thing that I am slightly nervous about (for the Events Query side) is how the duration header modifies the timers; it seems correct but I am not 100% certain. This will not affect existing implementation as the code does not kick-in when the duration is zero (which is always true in the non-Events Query path).

Looking forward to your feedback on the PR,

Best Regards,
Rahul


On Sunday, August 16th, 2026 at 7:09 PM, Kévin Dunglas <[e-mail]> wrote:

> 

> 

> Hi Rahul,
> 

> 

> 

> I opened a draft PR adding Events Query support to the Mercure Hub: https://github.com/dunglas/mercure/pull/1358
> 

> 

> 

> Could you check if it's going in the right direction and implements Events Query correctly?
> 

> 

> 

> I decided to only support "multipart/mixed" for now, as it fits well with the opaque nature of Mercure's payload-agnostic events compared to JSON sequences or an ad hoc format.
> 

> 

> 

> Overall, it was straightforward, but I think I'm filling the extension slot your I-D anticipates in §2.4.3, and here are some limitations of the current implementation compared to the Server-Sent Events transport:
> 

> 

> 

> 1. Mercure needs event IDs for its state reconciliation feature (reconnecting without losing events after a connection loss). It's provided by SSE's "id" field, but there is no comparable solution in Events Query. I "invented" a "Content-Event-Id" header for the multipart/mixed body parts, but I'm not very happy with it. Per RFC 2046, a 'Mercure-' prefixed part header cannot be relied on (non-Content- fields may be ignored or discarded by gateways), and Events Query §9.2.2 excludes them from body parts entirely. Another alternative would be to define a custom format for the Mercure payload, but this would give less flexibility to the end user and feels less native than "multipart/mixed". Another alternative would be to use headers defined in Michael Toomim's HTTP Resource Versioning (https://datatracker.ietf.org/doc/draft-toomim-httpbis-versions/) but it's not standardized yet and currently only accepts ASCII values, meaning IRI IDs (recommended by Mercure) would require a percent-encoding convention that both sides must reverse, and IDs aren't guaranteed to be IRIs at all. RFC 2045 Content-ID also doesn't work because it requires angle brackets syntax, which cannot carry IRIs.
> 

> 

> 

> 2. SSE has a "comment" feature (lines starting with a colon are ignored by clients), which is very practical for preventing disconnections/timeouts from HTTP/1 intermediaries such as reverse proxies. It seems there is no easy way to do that with Events Query, as MIME multipart/mixed lacks an inline comment syntax. We could use synthetic messages, but they will be received by clients, which mixes protocol layers. The only workaround I've found is to bound response durations below intermediary timeouts (the PR implements the Events Query duration mechanism), but this introduces reconnection churn SSE doesn't have.
> 

> 

> 

> The main advantage over SSE is that multipart parts could carry binary events, which SSE can't do without base64-encoding (binary has been a non-goal for Mercure so far). Not implemented in the PR yet, but I may work on it at some point.
> 

> 

> 

> Best,
> 

> 

> 

> Kévin
> 

> 

> On Thu, Aug 13, 2026 at 6:10 PM Rahul Gupta <[e-mail]> wrote:
> 

> > Hi Kevin,
> > 

> > The spec has two independent implementations, so I would say it is settled enough that you should be able to test it with a Mercure hub (and it would be good feedback for the spec). You can look at the libraries linked in Implementation Status for inspiration, it is quite simple to implement. Or ask me if you have questions!
> > 

> > The caveat is that it is still a proposal at HTTPAPI, so not so mature in terms of IETF process.
> > 

> > BR/Rahul
> > 

> > On Thursday, August 13th, 2026 at 8:13 PM, Kévin Dunglas <[e-mail]> wrote:
> > 

> > > Hi Rahul,
> > > 

> > > Noted, thanks for the clarification. As Mark suggested, I'm working on a
> > > problem statement, and this will be in it.
> > > 

> > > Also: whenever you feel Events Query is mature enough, I'd be glad to add
> > > support for it to the reference Mercure hub. It could be the most direct way to
> > > find out whether the composition actually holds.
> > > 

> > > Best,
> > > 

> > > Kévin Dunglas
> > > Les-Tilleuls.coop
> > > 

> > > On Thu, Aug 13, 2026 at 3:57 PM Rahul Gupta <[e-mail]> wrote:
> > > 

> > > > Hi Kevin,
> > > > 

> > > > Events Query does not need to be subject resource-centric. As you suggest at the end of the mail, it can work with a hub resource as well (baring section 10) in a similar way as SSE, with a minor extension to the QUERY data-model. I mentioned it precisely because I also see it as composable, something that could benefit Mercure users in the future.
> > > > 

> > > > Best Regards,
> > > > Rahul
> > > > 

> > > > 

> > > > On Wednesday, August 12th, 2026 at 10:42 PM, Kévin Dunglas <[e-mail]> wrote:
> > > > 

> > > > > Hi Rahul,
> > > > > 

> > > > > Fair point on venue. Mercure does not extend HTTP; it is an application
> > > > > protocol on top of it, so HTTPAPI may well be the better home. I would
> > > > > rather have that routed than assume it, so I am putting the question to
> > > > > the HTTP WG chairs and the AD, and will follow whichever answer comes
> > > > > back.
> > > > > 

> > > > > Thanks for your work on Events Query. I follow the proposal, and it looks indeedmore complementary to Mercure, than an alternative to it.
> > > > > 

> > > > > Events Query is resource-centric: notifications for events on a given resource, temporal
> > > > > coordination across responses out of scope, authorization left to the
> > > > > server.
> > > > > 

> > > > > On the other hand, Mercure is deliberately hub-based (It was heavily inspired by
> > > > > WebSub in the beginning).
> > > > > 

> > > > > Topics are decoupled from origin resources, one connection multiplexes many topics,
> > > > > authorization is specified (RFC 9396 authorization_details in an RFC 9068 access token,
> > > > > discoverable per RFC 9728 etc), and reconnection is defined with
> > > > > Last-Event-ID replay from the hub.
> > > > > 

> > > > > Also, the refreshed draft already allows QUERY (RFC 10008) for subscription.
> > > > > Hubs must support GET, since that is what EventSource uses,
> > > > > and can also accept any other safe method (QUERY is explicitly listed) that
> > > > > can carry the topic matcher parameters in the request body,
> > > > > so subscribers can send matcher lists too large for
> > > > > intermediary URI length limits.
> > > > > 

> > > > > So the two look composable rather than exclusive. A hub is itself a
> > > > > resource, and I see nothing that would stop a hub from serving its
> > > > > stream via Events Query alongside Event Stream.
> > > > > 

> > > > > Best regards and thanks for your reply,
> > > > > 

> > > > > Kévin Dunglas
> > > > > Les-Tilleuls.coop
> > > > > 

> > > > > On Wed, Aug 12, 2026 at 2:38 AM Rahul Gupta <[e-mail]> wrote:
> > > > > 

> > > > > > Hi Kevin,
> > > > > > 

> > > > > > For Mercure, HTTPAPI might be a more appropriate venue for discussion. Nothing in it modifies HTTP or requires HTTP extension itself.
> > > > > > 

> > > > > > As a shameless plug: you might want to check out my Events Query proposal https://cxres.github.io/events-query/draft-gupta-httpapi-events-query.html as a powerful SSE alternative, which should be useful even for Mercure.
> > > > > > 

> > > > > > BR/Rahul
> > > > > > 

> > > > > > On Tuesday, August 11th, 2026 at 6:10 PM, Kévin Dunglas <[e-mail]> wrote:
> > > > > > 

> > > > > > > 

> > > > > > > Hi there,
> > > > > > > 

> > > > > > > I am re-announcing the Mercure Protocol on this list. The spec was first
> > > > > > > published in 2018 (draft-dunglas-mercure-00, October 2018) and has been
> > > > > > > in continuous use and revision since. It has now stabilized for a 1.0
> > > > > > > release. The reference implementation is currently tagged v1.0.0-alpha.3
> > > > > > > while the code catches up to the spec, and I have refreshed the
> > > > > > > Internet-Draft accordingly.
> > > > > > > 

> > > > > > > - Datatracker: https://datatracker.ietf.org/doc/draft-dunglas-mercure/- Spec source (pinned): https://github.com/dunglas/mercure/blob/v1.0.0-alpha.3/spec/mercure.md
> > > > > > > - Reference implementation: https://github.com/dunglas/mercure
> > > > > > > 

> > > > > > > Mercure is a hub-based publish/subscribe protocol over HTTP and SSE,
> > > > > > > designed to push updates to web browsers and HTTP clients. It targets
> > > > > > > the "server-to-client real-time updates" use case that today is usually
> > > > > > > served by ad-hoc WebSocket protocols.
> > > > > > > 

> > > > > > > For context, the I-D was first submitted in October 2018, brought to
> > > > > > > this list in 2020
> > > > > > > (https://lists.w3.org/Archives/Public/ietf-http-wg/2020JulSep/0020.html)
> > > > > > > and surfaced again in 2022 in Michael Toomim's "Mnot's Pub/Sub for the
> > > > > > > Web" thread
> > > > > > > (https://lists.w3.org/Archives/Public/ietf-http-wg/2022JanMar/0164.html)
> > > > > > > The protocol has been in production use across multiple ecosystems for
> > > > > > > roughly seven years.
> > > > > > > 

> > > > > > > A note on timing and relevance: SSE has become the de-facto transport for
> > > > > > > streaming output from AI systems. The OpenAI and Anthropic APIs, and the
> > > > > > > Model Context Protocol, all stream tokens over SSE. Mercure is SSE-native and
> > > > > > > adds the pieces those ad-hoc uses lack: authorization, multiplexing, discovery,
> > > > > > > and reconnection with state reconciliation, all over plain HTTP. A standardized,
> > > > > > > authenticated way to stream incremental results to browsers and HTTP clients is
> > > > > > > more useful now than when this work started.
> > > > > > > 

> > > > > > > What is new since draft-dunglas-mercure-07 (2020) is largely a matter of
> > > > > > > removing Mercure-specific machinery in favor of standards that did not exist,
> > > > > > > or were not mature, when the protocol was first drafted in 2018:
> > > > > > > 

> > > > > > > - URL matching now uses the WHATWG URL Pattern standard instead of URI
> > > > > > > Templates. URI Templates (RFC 6570) define expansion, not matching, and
> > > > > > > Mercure had to specify matching itself; URL Pattern is purpose-built for
> > > > > > > matching and did not exist in 2018. The matcher set is reduced to two types,
> > > > > > > Exact and URL Pattern.
> > > > > > > - Authorization now uses OAuth 2.0 Rich Authorization Requests
> > > > > > > (authorization_details, RFC 9396) instead of a bespoke "mercure" JWT claim.
> > > > > > > The hub is an OAuth 2.0 protected resource; access tokens follow the JWT
> > > > > > > access token profile (RFC 9068), are presented and error-reported per the
> > > > > > > Bearer usage spec (RFC 6750), and auth requirements are discoverable via
> > > > > > > OAuth 2.0 Protected Resource Metadata (RFC 9728, published 2025). None of
> > > > > > > these existed or were usable in 2018.
> > > > > > > - Security hardening
> > > > > > > - Editorial pass for IETF style and consistency.
> > > > > > > 

> > > > > > > The result is a smaller spec that reuses existing IETF and web standards rather
> > > > > > > than reinventing them, and that a generic OAuth resource-server library can
> > > > > > > enforce.
> > > > > > > 

> > > > > > > Deployment status:
> > > > > > > 

> > > > > > > - Reference hub (Go, ~5k GitHub stars) used in production:
> > > > > > > https://github.com/dunglas/mercure
> > > > > > > - FrankenPHP, the modern PHP application server (~11.1k GitHub stars,
> > > > > > > now supported by the PHP Foundation), ships a native Mercure hub,
> > > > > > > exposes it through native PHP functions, and uses it internally for
> > > > > > > its hot-reload feature: https://frankenphp.dev
> > > > > > > - First-class integration in Symfony (official real-time solution),
> > > > > > > API Platform, Laravel, Spiral, and others; community clients across
> > > > > > > JavaScript, Python, PHP, Java, .NET, Rust, Swift, and more.
> > > > > > > - Production deployments include UEFA Euro 2020, COP26, France Titres
> > > > > > > (ANTS, French government agency for secure documents), France Médias
> > > > > > > Monde, M6, Treezor (Société Générale group), Multitude Bank,
> > > > > > > BRAC Bank, Yousign, Rectangle Health,
> > > > > > > Lush, Adore Me, Printify, Sellsy, and others. A fuller list:
> > > > > > > https://mercure.rocks/references
> > > > > > > 

> > > > > > > I would like to gauge whether there is interest in pursuing this work
> > > > > > > within HTTP, or whether the WG would prefer that I take it to the
> > > > > > > independent stream. I will follow up with the co-chairs separately with
> > > > > > > a concrete request.
> > > > > > > 

> > > > > > > Reviews and feedback on the refreshed draft are very welcome.
> > > > > > > 

> > > > > > > Thanks,
> > > > > > > 

> > > > > > > Kévin Dunglas
> > > > > > > Les-Tilleuls.coop
> > > > > > >