# Mercure — Real-Time Server Push with Server-Sent Events

> An open protocol and self-hosted hub for pushing updates to web and mobile clients using Server-Sent Events, built in Go for high concurrency.

## Install

Save in your project root:

# Mercure — Real-Time Server Push with Server-Sent Events

## Quick Use
```bash
# Run with Docker
docker run -e MERCURE_PUBLISHER_JWT_KEY=secret 
  -e MERCURE_SUBSCRIBER_JWT_KEY=secret 
  -p 3000:3000 dunglas/mercure

# Publish an update via curl
curl -X POST http://localhost:3000/.well-known/mercure 
  -H "Authorization: Bearer <jwt>" 
  -d "topic=https://example.com/books/1&data={"status":"sold"}"
```

## Introduction
Mercure is an open protocol and reference hub implementation for pushing real-time data to browsers, mobile apps, and IoT devices using native Server-Sent Events (SSE). It is a simpler alternative to WebSockets for unidirectional server-to-client updates.

## What Mercure Does
- Pushes updates from server to clients using native SSE with no custom JavaScript needed
- Implements topic-based publish/subscribe with JWT-based authorization
- Supports history and reconnection so clients catch up on missed events
- Handles private updates visible only to authorized subscribers
- Provides a built-in discovery mechanism via the Link HTTP header

## Architecture Overview
Mercure is a Go binary that acts as a hub between publishers (your backend) and subscribers (browsers/apps). Publishers POST updates to the hub's API with a JWT. The hub broadcasts those events to subscribers listening on matching topic URLs via SSE. The hub stores recent events for history replay and uses Bolt, Redis, or PostgreSQL as the transport and storage backend.

## Self-Hosting & Configuration
- Deploy via Docker, pre-built binaries, or from source with `go build`
- Set `MERCURE_PUBLISHER_JWT_KEY` and `MERCURE_SUBSCRIBER_JWT_KEY` for auth
- Configure transport backend: Bolt (default), Redis, or PostgreSQL
- Enable CORS with `MERCURE_CORS_ALLOWED_ORIGINS` for cross-domain subscriptions
- Use Caddy integration for automatic HTTPS and built-in Mercure module

## Key Features
- Native SSE means no client library required for browsers
- JWT-based fine-grained topic authorization
- Event history with automatic reconnection and catch-up
- Private updates scoped to specific subscribers
- Built-in Caddy module for seamless HTTPS integration

## Comparison with Similar Tools
- **Soketi/Pusher** — WebSocket-based; Mercure uses SSE which is simpler for server-to-client push
- **Centrifugo** — custom protocol; Mercure uses an open IETF-inspired protocol with native browser support
- **Firebase Realtime Database** — managed; Mercure is self-hosted and protocol-agnostic
- **NATS** — messaging system; Mercure is purpose-built for HTTP-based client push with SSE

## FAQ
**Q: Do I need a JavaScript library to use Mercure?**
A: No. Browsers natively support SSE via the `EventSource` API with no extra dependencies.

**Q: How does authorization work?**
A: Publishers and subscribers present JWTs with topic claims. The hub validates tokens before accepting publishes or serving events.

**Q: Can Mercure handle high concurrency?**
A: Yes. The Go implementation handles thousands of concurrent SSE connections efficiently.

**Q: Does Mercure support bidirectional communication?**
A: SSE is server-to-client only. For client-to-server messages, use standard HTTP requests to your backend.

## Sources
- https://github.com/dunglas/mercure
- https://mercure.rocks/

---
Source: https://tokrepo.com/en/workflows/asset-eb79b6dd
Author: AI Open Source