Protocol

Mercure is a public protocol, not just an implementation. The canonical source of truth is the IETF Internet-Draft, on track for publication as an RFC. The full text is also kept in this repository:

This page is a quick orientation, not a substitute. Read the spec for normative language and edge cases.

What's in the protocol

Subscription: GET /.well-known/mercure?match=... with one or more matcher query parameters.
Publication: POST /.well-known/mercure with form-encoded topic, data, and friends.
Authorization: OAuth 2.0 JWT access tokens (RFC 9068) with an authorization_details claim (RFC 9396) granting publish/subscribe per topic matcher; RFC 6750 errors.
Reconnection: Last-Event-ID header and last_event_id query parameter for replay.
Active subscriptions: subscription events on a well-known topic family + a JSON-LD API.
Discovery: Link: rel="mercure" headers on the publisher's resources, plus OAuth 2.0 protected resource metadata (RFC 9728).
Encryption: JWE for end-to-end privacy.

Matcher types

Matcher	Query parameter	Required of hubs	Reference
`exact`	`match`, `match_exact`	MUST	exact string comparison
`urlpattern`	`match_urlpattern`	MUST	WHATWG URL Pattern

See Topics and matchers for the developer-facing tour.

Mercure protocol implementations

Mercure.rocks Hub: the reference implementation. Caddy module, Go library, single static binary. Open-source (AGPL-3.0).
Freddie: PHP hub. Stable; covers everything except subscription events.
Ilshidur/node-mercure: Node.js hub and publisher. Beta.
Symfony Mercure component: PHP publisher and Symfony integration.
API Platform: full publisher + subscriber + GraphQL subscription support.
Laravel Mercure Broadcaster: publisher for Laravel.
dart_mercure: Dart / Flutter publisher and subscriber.

A non-exhaustive list, see Awesome Mercure for client libraries in other languages and the full ecosystem.

Mercure protocol conformance

The reference test suite is published in the conformance-tests/ directory of the repository. Any hub claiming to implement the spec should pass it. See Conformance tests for how to run the suite against your hub.

Mercure protocol versioning

The protocol is versioned via the IETF draft number. The reference hub follows SemVer and ships breaking changes only at major versions. The current major is 1.0, aligned with the two-matcher, OAuth 2.0 authorization model described in the spec.

If you're upgrading from a previous version, see the upgrade guide.

Mercure protocol patent and copyright

The specification is published under the IETF copyright policy. It can be implemented by any software, proprietary or otherwise. The reference hub itself is AGPL-3.0; see License for what that means in practice.