Mercure

https://mercure.rocks/docs
Admin
Mercure is an open protocol and server for real-time updates over HTTP and Server-Sent Events (SSE),...
Tokens:97,149
Snippets:798
Trust Score:9.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies for Apollo Server example

Source: https://mercure.rocks/docs/use-cases/graphql

Install the required npm packages for the Apollo Server example. Requires Node.js 22 or later.

```bash
npm install @apollo/server @as-integrations/express5 express graphql @graphql-tools/schema graphql-subscriptions

```

--------------------------------

### Install Mercure Helm chart with development keys

Source: https://mercure.rocks/docs/deployment/kubernetes

Adds the Mercure Helm repository and installs the chart, setting publisher and subscriber JWT keys. Generate each key once with `openssl rand -base64 32` and export as MERCURE_PUBLISHER_JWT_KEY / MERCURE_SUBSCRIBER_JWT_KEY. Anyone can forge tokens signed with the development key.

```bash
helm repo add mercure https://charts.mercure.rocks
helm install mercure mercure/mercure \
  --set publisherJwtKey="$MERCURE_PUBLISHER_JWT_KEY" \
  --set subscriberJwtKey="$MERCURE_SUBSCRIBER_JWT_KEY"

```

--------------------------------

### Install Mercure on Arch Linux using yay

Source: https://mercure.rocks/docs/getting-started/installation

Install the Mercure hub on Arch Linux from the AUR using the yay helper. Alternatively, build directly from the PKGBUILD with makepkg -sri.

```bash
yay -S mercure

```

--------------------------------

### fetchEventSource with QUERY method

Source: https://mercure.rocks/docs/concepts/subscribing

JavaScript example using @microsoft/fetch-event-source to send a QUERY request. Since EventSource only issues GET requests, use fetchEventSource with method: 'QUERY' and a URLSearchParams body. The onmessage callback logs event data.

```javascript
import { fetchEventSource } from "@microsoft/fetch-event-source";

const body = new URLSearchParams();
body.append("match", "https://example.com/books/1");
body.append("match_urlpattern", "https://example.com/users/:id");

await fetchEventSource("https://hub.example.com/.well-known/mercure", {
  method: "QUERY",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
  onmessage: (event) => {
    console.log(event.data);
  },
});

```

--------------------------------

### Subscriber authorization_details example

Source: https://mercure.rocks/docs/concepts/authorization

Example of an authorization_details token for a subscriber, with subscribe action and topics using URLPattern and exact match types.

```json
{
  "authorization_details": [
    {
      "type": "https://mercure.rocks/authorization-detail",
      "actions": ["subscribe"],
      "topics": [
        {
          "match": "https://example.com/users/42/*",
          "match_type": "urlpattern"
        },
        { "match": "https://example.com/announcements" }
      ]
    }
  ]
}
```

--------------------------------

### caddy mercure-token --dev (quickstart token)

Source: https://mercure.rocks/docs/concepts/authorization

Mints a Mercure access token matching the quickstart's local hub with zero configuration. Use this for local development only.

```bash
caddy mercure-token --dev  # matches the quickstart's local hub, zero config
```

--------------------------------

### Publisher authorization_details example

Source: https://mercure.rocks/docs/concepts/authorization

Example of an authorization_details token for a publisher, with publish action and topics using URLPattern and exact match types.

```json
{
  "authorization_details": [
    {
      "type": "https://mercure.rocks/authorization-detail",
      "actions": ["publish"],
      "topics": [
        {
          "match": "https://example.com/books/:id",
          "match_type": "urlpattern"
        },
        { "match": "https://example.com/announcements" }
      ]
    }
  ]
}
```

--------------------------------

### Install Mercure broadcasting driver

Source: https://mercure.rocks/docs/use-cases/laravel-broadcasting

Run this artisan command to install the Mercure broadcasting driver in a Laravel release that supports the Mercure installer.

```bash
php artisan install:broadcasting --mercure

```

--------------------------------

### Start mercure hub

Source: https://mercure.rocks/docs/production/troubleshooting

Starts the mercure hub normally after removing the quarantine attribute. This is the standard way to run the hub.

```bash
./mercure run

```

--------------------------------

### Start Mercure hub with JWT keys and algorithms

Source: https://mercure.rocks/docs/deployment/configuration

Sets environment variables for publisher and subscriber JWT public keys and algorithms, then runs the hub with the Caddyfile. Uses RS256 algorithm.

```bash
MERCURE_PUBLISHER_JWT_KEY="$(cat publisher.key.pub)" \
MERCURE_PUBLISHER_JWT_ALG=RS256 \
MERCURE_SUBSCRIBER_JWT_KEY="$(cat subscriber.key.pub)" \
MERCURE_SUBSCRIBER_JWT_ALG=RS256 \
./mercure run --config Caddyfile

```

--------------------------------

### Apply Secret and install Mercure Helm chart

Source: https://mercure.rocks/docs/deployment/kubernetes

Commands to apply the Secret manifest and install or upgrade the Mercure chart with the production values file. Run the apply before installing the chart.

```bash
kubectl apply -f mercure-secret.yaml
helm upgrade --install mercure mercure/mercure -f values.yaml

```

--------------------------------

### Run the Mercure conformance test suite

Source: https://mercure.rocks/docs/ecosystem/conformance-tests

Clones the Mercure repository, installs dependencies, and runs the Playwright conformance tests. Requires an isolated playground hub with the bundled development key running before execution.

```bash
git clone https://github.com/dunglas/mercure
cd mercure/conformance-tests
npm ci
npx playwright install --with-deps
npx playwright test

```

--------------------------------

### Example subscription event JSON

Source: https://mercure.rocks/docs/concepts/active-subscriptions

Each event's data is a JSON document with fields for the matcher, subscriber, active status, and payload.

```json
{
  "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6",
  "type": "subscription",
  "match_type": "urlpattern",
  "match": "https://example.com/:selector",
  "subscriber": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6",
  "active": true,
  "payload": { "username": "alice" }
}
```

--------------------------------

### Example authorization_details attribute value

Source: https://mercure.rocks/docs/concepts/authorization-servers

Example JSON array stored in the `authorization_details` user attribute, granting subscribe actions on specific topics with a payload.

```json
[
  {
    "type": "https://mercure.rocks/authorization-detail",
    "actions": ["subscribe"],
    "topics": [
      { "match": "https://example.com/users/42/notifications" },
      { "match": "https://example.com/announcements" }
    ],
    "payload": { "user": "https://example.com/users/42" }
  }
]

```

--------------------------------

### Run Mercure hub with Docker

Source: https://mercure.rocks/docs/getting-started/quickstart

Starts the Mercure hub container with HTTP/3 support and the playground directive. The hub is served on https://localhost. The playground enables anonymous subscriptions and a debugger at https://localhost/.well-known/mercure/debug/ with a default secret. Drop the playground for production.

```bash
docker run -p 80:80 -p 443:443 -p 443:443/udp \
  -e MERCURE_EXTRA_DIRECTIVES=playground \
  dunglas/mercure
```

--------------------------------

### Run Mercure in Docker development mode with playground directive

Source: https://mercure.rocks/docs/deployment/docker

Starts the dunglas/mercure image with the playground directive enabled, which turns on the debug UI, anonymous subscribers, echo endpoints, and permissive CORS. Do not expose this to the internet.

```bash
docker run \
    -e MERCURE_EXTRA_DIRECTIVES=playground \
    -p 80:80 -p 443:443 \
    dunglas/mercure

```

--------------------------------

### Subscribe to Mercure from Python with sseclient

Source: https://mercure.rocks/docs/concepts/subscribing

This Python example uses the sseclient package to subscribe to Mercure and print event data. It requires anonymous subscriptions. Note that the similarly named sseclient-py package has a different constructor.

```python
from sseclient import SSEClient

for event in SSEClient("https://hub.example.com/.well-known/mercure?match=topic"):
    print(event.data)
```

--------------------------------

### HTTP exchange for hub discovery

Source: https://mercure.rocks/docs/concepts/subscribing

Example of a GET request and response showing the Link header that advertises the Mercure hub.

```http
GET /books/1
Host: example.com

200 OK
Content-Type: application/ld+json
Link: <https://hub.example.com/.well-known/mercure>; rel="mercure"


```

--------------------------------

### Caddyfile: Configure write_timeout and drain_timeout in mercure directive

Source: https://mercure.rocks/docs/production/rolling-updates

Sets write_timeout to 1200s and drain_timeout to 300s. The drain starts on Caddy's stopping event, before shutdown_delay. Connections opened during the delay get a full drain_timeout. A Caddy grace_period shorter than drain_timeout cuts the drain short.

```caddyfile
localhost {
  mercure {
    write_timeout 1200s
    drain_timeout 300s
  }
}

```

--------------------------------

### Build custom Caddy binary with Mercure module using xcaddy

Source: https://mercure.rocks/docs/getting-started/installation

Build a custom Caddy binary that includes the Mercure Caddy module along with any other modules you need. Use the Caddy download page as an alternative to assemble a build in the browser.

```bash
xcaddy build \
  --with github.com/dunglas/mercure/caddy

```

--------------------------------

### Set MERCURE_LICENSE and run Mercure

Source: https://mercure.rocks/docs/production/high-availability

Sets the MERCURE_LICENSE environment variable to the license key supplied with the Self-Hosted plan, then runs the Mercure hub with the Caddyfile configuration. The license is validated locally at startup; a missing, invalid, or expired license prevents startup.

```bash
export MERCURE_LICENSE='<your license key>'
./mercure run --config Caddyfile

```

--------------------------------

### Run Mercure hub binary with playground directive

Source: https://mercure.rocks/docs/getting-started/installation

Run the Mercure hub binary with the playground directive enabled Gridview listens at https://localhost. For production, remove playground, configure keys, and set SERVER_NAME and MERCURE_TRUSTED_ISSUERS. On macOS, xattr -d com.apple.quarantine ./mercure may be needed. Set SERVER_NAME=:3000 if ports 80 or 443 are unavailable.

```bash
MERCURE_EXTRA_DIRECTIVES='playground' \
./mercure run --config Caddyfile
```

--------------------------------

### HTTP GET request to subscribe to Mercure updates

Source: https://mercure.rocks/docs/concepts/subscribing

A raw HTTP GET request to the hub's well-known URL with match parameters. The hub keeps the connection open and writes Server-Sent Events into it.

```http
GET /.well-known/mercure?match=https://example.com/books/1 HTTP/2
Host: hub.example.com
Accept: text/event-stream

```

--------------------------------

### GET /mercure/health/{name}/live

Source: https://mercure.rocks/docs/production/health-monitoring

Per-hub liveness.

```APIDOC
## [GET] /mercure/health/{name}/live

### Description
Per-hub liveness.

### Method
GET

### Endpoint
/mercure/health/{name}/live

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the hub.

### Response
#### Success Response (200)
- **status** (integer) - 200 if the hub is live.

#### Error Response (503)
- **status** (integer) - 503 if the hub is not live.

```

--------------------------------

### Helm chart installation commands for Mercure

Source: https://mercure.rocks/docs/getting-started/installation

Install Mercure hub on Kubernetes using Helm. The chart includes settings for draining SSE connections during rolling updates. Persistent BoltDB deployments need the Recreate strategy; use a shared transport for rolling upgrades.

```bash
helm repo add mercure https://charts.mercure.rocks
helm install my-release mercure/mercure
```

--------------------------------

### Configure the Mercure load test with environment variables

Source: https://mercure.rocks/docs/production/load-testing

Sets environment variables to target a real hub and configure subscriber and publisher rates, injection duration, and connection duration. Start below expected traffic and increase load while measuring latency and errors.

```bash
HUB_URL=https://hub.example.com/.well-known/mercure \
JWT='<publisher JWT>' \
INITIAL_SUBSCRIBERS=1000 \
SUBSCRIBERS_RATE_FROM=50 \
SUBSCRIBERS_RATE_TO=200 \
PUBLISHERS_RATE_FROM=10 \
PUBLISHERS_RATE_TO=100 \
INJECTION_DURATION=300 \
CONNECTION_DURATION=600 \
./mvnw gatling:test

```

--------------------------------

### GET /mercure/health/{name}/ready

Source: https://mercure.rocks/docs/production/health-monitoring

Per-hub readiness when running multiple hubs.

```APIDOC
## [GET] /mercure/health/{name}/ready

### Description
Per-hub readiness when running multiple hubs.

### Method
GET

### Endpoint
/mercure/health/{name}/ready

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the hub.

### Response
#### Success Response (200)
- **status** (integer) - 200 if the hub is ready.

#### Error Response (503)
- **status** (integer) - 503 if the hub is not ready.

```

--------------------------------

### Subscribe with match and match_urlpattern query parameters

Source: https://mercure.rocks/docs/concepts/topics-and-matchers

Opens an SSE connection to the Mercure hub with two match parameters: an exact topic and a URL pattern. The bare match parameter selects the exact matcher type; match_urlpattern selects the urlpattern type. Parameter names are case-sensitive and any other name under the reserved match prefix is rejected with 400 Bad Request.

```http
GET /.well-known/mercure?match=https://example.com/books/1&match_urlpattern=https://example.com/users/:id HTTP/2

```

--------------------------------

### GET /mercure/health/ready

Source: https://mercure.rocks/docs/production/health-monitoring

Returns 200 if all transports can serve traffic, 503 otherwise. Use for readiness.

```APIDOC
## [GET] /mercure/health/ready

### Description
Returns 200 if all transports can serve traffic, 503 otherwise. Use for readiness.

### Method
GET

### Endpoint
/mercure/health/ready

### Response
#### Success Response (200)
- **status** (integer) - 200 if all transports can serve traffic.

#### Error Response (503)
- **status** (integer) - 503 if any transport cannot serve traffic.

```

--------------------------------

### GET /.well-known/mercure/subscriptions

Source: https://mercure.rocks/docs/concepts/active-subscriptions

Fetches all active subscriptions on the hub. Requires a subscribe grant covering the request path.

```APIDOC
## GET /.well-known/mercure/subscriptions

### Description
Fetches all active subscriptions on the hub.

### Method
GET

### Endpoint
/.well-known/mercure/subscriptions

### Parameters
None

### Response
#### Success Response (200)
- **id** (string) - The identifier of the collection.
- **type** (string) - Always "subscriptions".
- **subscriptions** (array) - List of subscription objects.
  - **id** (string) - The subscription identifier.
  - **type** (string) - Always "subscription".
  - **match** (string) - The topic matcher.
  - **match_type** (string) - The matcher type (e.g., "urlpattern").
  - **subscriber** (string) - The subscriber identifier.
  - **active** (boolean) - Whether the subscription is active.
  - **payload** (object) - Additional payload.

#### Response Example
{
  "id": "/.well-known/mercure/subscriptions",
  "type": "subscriptions",
  "subscriptions": [
    {
      "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268",
      "type": "subscription",
      "match": "https://example.com/:selector",
      "match_type": "urlpattern",
      "subscriber": "urn:uuid:bb3de268",
      "active": true,
      "payload": { "username": "alice" }
    }
  ]
}
```

--------------------------------

### Check subscribers_connected metric with kubectl exec

Source: https://mercure.rocks/docs/production/rolling-updates

Run this command to check the active subscribers metric during a deploy. A healthy drain shows a smooth ramp down on the old replica and a matching ramp up on the new one. A sudden drop may indicate forced termination.

```bash
kubectl exec -it $POD -- wget -qO- localhost:2019/metrics | grep subscribers_connected

```

--------------------------------

### GET /mercure/health/live

Source: https://mercure.rocks/docs/production/health-monitoring

Returns 200 if all transports are fundamentally operational, 503 if a transport reports a liveness failure. Use for liveness.

```APIDOC
## [GET] /mercure/health/live

### Description
Returns 200 if all transports are fundamentally operational, 503 if a transport reports a liveness failure. Use for liveness.

### Method
GET

### Endpoint
/mercure/health/live

### Response
#### Success Response (200)
- **status** (integer) - 200 if all transports are fundamentally operational.

#### Error Response (503)
- **status** (integer) - 503 if a transport reports a liveness failure.

```

--------------------------------

### Check and set file descriptor limits on Linux

Source: https://mercure.rocks/docs/production/load-testing

Use prlimit to inspect the current limit for the Mercure process, ulimit to set it for the current shell, and a systemd override to persist the limit.

```bash
prlimit --pid $(pgrep mercure)

# Set the limit for this shell and its child processes
ulimit -n 100000

# Persist via systemd
# /etc/systemd/system/mercure.service.d/override.conf
[Service]
LimitNOFILE=100000

```

--------------------------------

### Subscribe to product availability with match_urlpattern

Source: https://mercure.rocks/docs/use-cases/live-data

Creates an EventSource that subscribes to a family of product availability topics using the match_urlpattern parameter. One connection receives updates for all products matching the pattern.

```javascript
const url = new URL("https://hub.example.com/.well-known/mercure");
url.searchParams.append(
  "match_urlpattern",
  "https://shop.example.com/products/:id/availability",
);
new EventSource(url);

```

--------------------------------

### GET /.well-known/mercure/subscriptions/{match_type}/{match}/{subscriber}

Source: https://mercure.rocks/docs/concepts/active-subscriptions

Fetches a single subscription. Requires a subscribe grant covering the request path.

```APIDOC
## GET /.well-known/mercure/subscriptions/{match_type}/{match}/{subscriber}

### Description
Fetches a single subscription.

### Method
GET

### Endpoint
/.well-known/mercure/subscriptions/{match_type}/{match}/{subscriber}

### Parameters
#### Path Parameters
- **match_type** (string) - Required - The type of matcher (e.g., "urlpattern").
- **match** (string) - Required - The matcher pattern (URL-encoded).
- **subscriber** (string) - Required - The subscriber identifier.

### Response
#### Success Response (200)
- **id** (string) - The subscription identifier.
- **type** (string) - Always "subscription".
- **match** (string) - The topic matcher.
- **match_type** (string) - The matcher type.
- **subscriber** (string) - The subscriber identifier.
- **active** (boolean) - Whether the subscription is active.
- **payload** (object) - Additional payload.

#### Response Example
{
  "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268",
  "type": "subscription",
  "match": "https://example.com/:selector",
  "match_type": "urlpattern",
  "subscriber": "urn:uuid:bb3de268",
  "active": true,
  "payload": { "username": "alice" }
}
```

--------------------------------

### GET /.well-known/mercure/subscriptions/{match_type}/{match}

Source: https://mercure.rocks/docs/concepts/active-subscriptions

Fetches subscriptions for a specific matcher. Requires a subscribe grant covering the request path.

```APIDOC
## GET /.well-known/mercure/subscriptions/{match_type}/{match}

### Description
Fetches subscriptions for a specific matcher.

### Method
GET

### Endpoint
/.well-known/mercure/subscriptions/{match_type}/{match}

### Parameters
#### Path Parameters
- **match_type** (string) - Required - The type of matcher (e.g., "urlpattern").
- **match** (string) - Required - The matcher pattern (URL-encoded).

### Response
#### Success Response (200)
- **id** (string) - The identifier of the collection.
- **type** (string) - Always "subscriptions".
- **subscriptions** (array) - List of subscription objects.
  - **id** (string) - The subscription identifier.
  - **type** (string) - Always "subscription".
  - **match** (string) - The topic matcher.
  - **match_type** (string) - The matcher type.
  - **subscriber** (string) - The subscriber identifier.
  - **active** (boolean) - Whether the subscription is active.
  - **payload** (object) - Additional payload.

#### Response Example
{
  "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector",
  "type": "subscriptions",
  "subscriptions": [
    {
      "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268",
      "type": "subscription",
      "match": "https://example.com/:selector",
      "match_type": "urlpattern",
      "subscriber": "urn:uuid:bb3de268",
      "active": true,
      "payload": { "username": "alice" }
    }
  ]
}
```

--------------------------------

### Agent event stream example

Source: https://mercure.rocks/docs/use-cases/ai-agent-progress

Shows the sequence of structured events an agent publishes to describe its progress, including step started/completed, tool called/completed, token chunks, and run completion. The browser updates its state from these events; concurrent steps need unique step IDs and separate state.

```json
{ "type": "step.started",      "step": "search_web",       "input": {"query": "mercure protocol"} }
{ "type": "tool.called",       "tool": "fetch",            "url":   "https://mercure.rocks" }
{ "type": "tool.completed",    "tool": "fetch",            "bytes": 14732 }
{ "type": "step.completed",    "step": "search_web",       "results": 5 }
{ "type": "step.started",      "step": "summarize" }
{ "type": "token",             "text": "Mercure is a..." }
{ "type": "token",             "text": " protocol for..." }
{ "type": "step.completed",    "step": "summarize" }
{ "type": "run.completed",     "output": "..." }

```

--------------------------------

### Subscribe to Mercure from Go with r3labs/sse

Source: https://mercure.rocks/docs/concepts/subscribing

This Go program uses the r3labs/sse/v2 package to subscribe to Mercure and print event data. It requires anonymous subscriptions.

```go
package main

import (
    "fmt"
    "log"

    "github.com/r3labs/sse/v2"
)

func main() {
    client := sse.NewClient("https://hub.example.com/.well-known/mercure?match=topic")
    if err := client.SubscribeRaw(func(msg *sse.Event) {
        fmt.Println(string(msg.Data))
    }); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Enable tracing in Caddy route with Mercure

Source: https://mercure.rocks/docs/production/tracing

Adds the `tracing` directive inside a `route` block to start collecting traces for Mercure spans. The `mercure` directive is configured within the same route.

```caddyfile
route {
	tracing
	mercure {
		# ...
	}
}

```

--------------------------------

### Combining matchers in a subscription

Source: https://mercure.rocks/docs/concepts/topics-and-matchers

Shows how to create a subscription with multiple matchers (match and match_urlpattern) to receive topics matching any of them.

```APIDOC
## Subscription with multiple matchers

### Description
A subscription can include several `match*` parameters, which are combined as a logical OR. The subscriber receives topics that match any of the provided matchers.

### Method
GET

### Endpoint
`https://hub.example.com/.well-known/mercure`

### Parameters
#### Query Parameters
- **match** (string) - Required - Exact topic matcher. Example: `https://example.com/site/announcement`
- **match_urlpattern** (string) - Required - URL Pattern matcher. Example: `https://example.com/users/:id/notifications`

### Request Example
```
const url = new URL("https://hub.example.com/.well-known/mercure");
url.searchParams.append("match", "https://example.com/site/announcement");
url.searchParams.append(
  "match_urlpattern",
  "https://example.com/users/:id/notifications",
);
new EventSource(url);
```

### Response
#### Success Response (200)
- **EventSource** - The subscriber receives events for topics matching any of the provided matchers.

#### Response Example
```
// The subscriber receives:
// - exactly the announcement topic, OR
// - any user-notifications URL.
```
```
Tokens:
Raw