Mercure protocol
Mercure is an open protocol. The specification in this repository describes the behavior documented here. Track standardization through the IETF Internet-Draft; an Internet-Draft is a work in progress, not an RFC.
This overview introduces the main operations. Consult the specification for normative requirements.
#What's in the protocol
- Subscription:
GET /.well-known/mercure?match=...with one or more matcher query parameters. - Publication:
POST /.well-known/mercurewith form-encodedtopic,data, and optional delivery fields. - Authorization: OAuth 2.0 JWT access tokens (RFC 9068) with an
authorization_detailsclaim (RFC 9396) granting publish/subscribe per topic matcher; RFC 6750 errors. - Reconnection:
Last-Event-IDheader andlast_event_idquery parameter for replay. - Active subscriptions: subscription events on a well-known topic family and a JSON 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; check its supported protocol revision.
- Ilshidur/node-mercure: Node.js hub and publisher; check its supported protocol revision.
- 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
IETF draft numbers and hub release versions are separate. These pages describe the 1.0 hub and the specification in this checkout. Verify a third-party implementation's supported protocol revision before using 1.0 features.
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.