DOCSEARCHbyAlgolia
Submit Docs

Mercure

website·Indexed 35 days ago

https://mercure.rocks/docs

A hub for streaming real-time updates from servers to clients over Server-Sent Events (SSE), supporting use cases such as LLM token streaming, AI agent status updates, live audio/video, and multiplayer game state.

Tokens
540
Snippets
2
Records
4
Agent score
23%

What's inside Mercure

  1. Overview of Mercure real-time streaming

    Mercure is an open-source hub (MIT license) that streams real-time updates from servers to clients using Server-Sent Events (SSE). It is designed for use cases such as LLM token streaming, AI agent state synchronization, live dashboards, notifications, and GraphQL/REST streaming. Unlike WebSockets, it uses standard HTTP, providing native browser support via EventSource, automatic reconnection with Last-Event-ID replay, and better compatibility with corporate proxies and CDNs. It is built on Caddy and is the official real-time component for the Symfony framework.

  2. Implement the Mercure publish-subscribe protocol

    The Mercure protocol splits real-time communication into two distinct HTTP operations:

    1. Subscribe: Clients open a connection to the hub to receive events. This is done via a GET request to the /.well-known/mercure endpoint. You can filter updates using the match parameter for exact URL matches or matchURLPattern for RFC-style templated patterns.
    2. Publish: Servers send updates to the hub via an authenticated POST request to the /.well-known/mercure endpoint. The hub then broadcasts the payload to all matching subscribers.
    # Subscribe
GET /.well-known/mercure?match=https://example.com/topic1

# Publish
POST /.well-known/mercure
Authorization: Bearer <token>
Content-Type: application/json

{"topic": "https://example.com/topic1", "data": "Hello World"}

  3. Choose between Mercure (SSE) and WebSockets

    Mercure/SSE is the preferred choice for server-to-client streaming of JSON or text payloads due to lower operational costs, native browser support (no SDK required), and superior firewall/proxy traversal. WebSockets should be reserved for high-frequency raw-binary workloads, such as live audio/video streaming or multiplayer game state synchronization.

  4. Deploy and host Mercure

    Mercure can be deployed in several ways:

    • Self-Hosted (OSS): Available as a single binary, an official Docker image (dunglas/mercure), or an official Helm chart for Kubernetes.
    • Mercure Cloud: A managed service hosted in the EU (Amsterdam) by Les-Tilleuls.coop.
    • Mercure Enterprise: A commercial self-hosted edition with additional support and features.
    # Official Docker image
docker pull dunglas/mercure