Parsec
Parsec is a scalable realtime messaging engine built on Centrifuge (OSS). It ships as a Go library (primary), a CLI binary, and a Twirp JSON RPC service — three surfaces over the same engine.
This book is the reference manual. Start with the quickstart, or skip to the section that matches your role:
- Building against parsec — library overview → options → custom sinks
- Operating parsec — deployment → config file → observability
- Integrating from another language — Twirp RPC
- Curious about the model — architecture
Capability map
| Need | Read |
|---|---|
| Try parsec in 30 seconds | Running with Docker |
| Wire a browser to parsec | Browser client |
| Test code that embeds parsec | parsectest helpers |
| Open a channel, publish, subscribe | Quickstart |
| Understand the namespace grammar | Channel naming |
| Token-gate a channel with patterns | ACL scopes |
| Rotate signing keys without downtime | Key rotation |
| Accept IdP-issued bearers | OIDC bridge |
| Survive sink outages | DLQ |
| Gate abusive callers | Rate limiting |
| Cluster across machines | Deployment |
| Span regions | Multi-region |
| Speak HTTP/3 | WebTransport |
| Compress chatty channels | Delta compression |
| Embed the operator UI | Admin UI |
| Scrape metrics | Observability |
What Parsec is
- A broker process that holds long-lived client connections (WebSocket + optional WebTransport).
- A channel manager with a strict
public:/private:namespace convention and TTL-driven lifecycle. - A library you embed in Go services to publish, subscribe, and authenticate.
- A CLI and a Twirp RPC surface — two ways to control the same engine from outside.
What Parsec is not
- Not an everything-store. It does not own your business data; it ships events.
- Not a durable work queue. Use one for jobs; use parsec for “you have a notification”.
- Not a Centrifugo Pro replacement. Parsec uses the OSS library; we ship our own delta-compression toggle, admin UI, and presence primitives — only the subset we need.