Start here
The fastest path is: start one broker, authenticate a producer, negotiate a communication contract, publish a message, and inspect the broker decision. From there, the documentation separates concepts from protocol details so application code does not need to reimplement broker policy.
Quickstart
Install the package, start a broker, negotiate a communication contract and publish your first governed message.
Open →Core concepts
Learn principals, subjects, communication contracts, message envelopes, admission gates, decisions, quarantine and audit evidence.
Open →Protocol v1
Use the language-neutral HTTP + JSON protocol directly or through a client implementation.
Open →Use cases
Apply the same broker model to service messaging, asynchronous workers, agent-to-tool calls, regional flows and operational events.
Open →Live demo
Run an allowed or violating message and inspect the broker decision before receiver delivery.
Open →Architecture
Read ADRs, message flows and implementation notes in the repository.
Open →Broker model in one view
credential
↓
authenticated principal
↓
request subjects + operations
↓
communication contract
↓
publish / receive / replay / acknowledge
↓
identity → intent → schema → region → data → idempotency
↓
allow | deny | quarantine
↓
delivery + evidenceWhat the broker is responsible for
| Concern | PigeonMQ behaviour |
|---|---|
| Identity | Resolve the principal from credentials at the broker boundary. |
| Authority | Issue a short-lived contract containing the permitted communication scope. |
| Message admission | Evaluate runtime constraints before a governed operation proceeds. |
| Containment | Deny or quarantine communication that falls outside policy. |
| Evidence | Return typed decisions and retain audit information for governed operations. |
Protocol and clients
Pigeon Protocol v1 uses HTTP + JSON. The Node.js implementation is the canonical broker today. JavaScript, Python and Rust clients target the same protocol semantics, so language choice does not change how contracts and broker decisions work.
Suggested reading order
- Quickstart — run the system end to end.
- Core concepts — understand the runtime objects.
- Protocol v1 — integrate without relying on a specific SDK.
- Use cases — map the model to real messaging patterns.
- Live demo — inspect an allow/quarantine decision interactively.