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/mercurewith form-encodedtopic,data, and friends. - Authorization: JWT with a
mercureclaim that lists allowed matchers per role (publish, subscribe). - Reconnection:
Last-Event-IDheader andlastEventIDquery 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. - Encryption: JWE for end-to-end privacy.
#Matcher types (1.0)
| Matcher | Query parameter | Required of hubs | Reference |
|---|---|---|---|
Exact | match, matchExact | MUST | spec section 3.1 |
URLPattern | matchURLPattern | SHOULD | WHATWG URL Pattern |
Regexp | matchRegexp | SHOULD | RFC 9485 (I-Regexp) |
CEL | matchCEL | MAY | Common Expression Language |
URITemplate | matchURITemplate | MAY | RFC 6570 |
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 (currently draft-dunglas-mercure-07). The reference hub follows semver and ships breaking changes only at major versions. The current major is 1.0, aligned with the typed-matcher 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.