messaging

Opinionated multi-transport messaging with shared specification, conformance testing, and topology visualization.

---

This repo contains the shared specification and tooling for messaging — a multi-transport messaging library for event-driven microservices. It provides:

• Deterministic naming — exchange, queue, and stream names derive from service name + pattern
• Topology validation — catch wiring errors before deployment
• Topology visualization — auto-generated Mermaid diagrams of your message flows
• CloudEvents 1.0 — all messages carry standardized metadata
• Conformance testing — the TCK proves transport implementations are correct

This repo is for transport implementors. For end-user guides, see the transport repos below.

Ecosystem

Package	Language	Description
messaging	Go	Shared library, TCK runner, validation, visualization
@sparetimecoders/messaging	TypeScript	Shared library (mirrors Go)
go-messaging-amqp	Go	AMQP/RabbitMQ transport
go-messaging-nats	Go	NATS/JetStream transport
@sparetimecoders/messaging-amqp	TypeScript	AMQP/RabbitMQ transport
@sparetimecoders/messaging-nats	TypeScript	NATS/JetStream transport

Documentation

See the docs/ directory for detailed guides:

Guide	Description
Communication Patterns	The five messaging patterns and broker mappings
Naming Conventions	How exchanges, queues, and streams are named
CloudEvents	CloudEvents 1.0 metadata on every message
Topology Tools	Validation, visualization, and broker discovery
Specification Reference	Formal rules, types, and contracts
Implementing a Transport	Step-by-step guide to building a conformant transport
TCK Guide	Running and writing adapters for the conformance test suite
Test Fixtures	Shared JSON test fixtures that define expected behavior

Project Structure

.
├── *.go                  Go shared library (naming, topology, validation, CloudEvents, visualization)
├── spectest/             Conformance test helpers and assertion functions
├── tck/                  Technology Compatibility Kit (runner, protocol, broker access)
│   ├── adapterutil/      Reusable JSON-RPC handler for adapter implementations
│   └── cmd/tck-runner/   TCK CLI runner
├── specverify/           CLI for topology validation and visualization
├── testdata/             Shared JSON test fixtures (canonical specification)
├── typescript/           TypeScript shared messaging library (mirrors Go)
└── docs/                 Implementor documentation

Development

# Run Go tests
go test ./...

# Run TCK (requires running brokers)
cd tck && docker compose up -d
go run ./cmd/tck-runner/ --adapter path/to/adapter

# Regenerate fixtures
go test -run TestGenerateFixtures ./...

# TypeScript tests
cd typescript && npm install && npm test

License

MIT