🚌 bus — Lightweight CQRS Library for Rust

bus is a modular, async-first CQRS library for Rust that helps you structure your application around clear boundaries: Commands, Queries, and Events. It supports both in-memory and database-backed event processing, middleware pipelines, and graceful shutdown — all with minimal boilerplate.

🧠 What Problems Does bus Solve?

• ❌ Tightly coupled business logic and infrastructure
• ❌ Scattered side effects and background jobs
• ❌ No clear separation between commands, queries, and events
• ❌ Manual registration of handlers and middleware

✅ bus introduces a clean, extensible architecture for:

• 🧱 Structuring your domain logic with CQRS
• 🔁 Handling commands and queries with type-safe handlers
• 📬 Publishing events (in-memory or persisted)
• 🧩 Composing middleware pipelines for logging, validation, metrics, etc.
• 🧵 Running background workers for database-backed events

🧭 What is CQRS?

CQRS stands for Command Query Responsibility Segregation — a pattern that separates:

• Commands — operations that change state (e.g. CreateUser)
• Queries — operations that return data (e.g. GetUserById)
• Events — notifications that something happened (e.g. UserCreated)

This separation improves clarity, testability, and scalability.

🧱 Core Concepts

🔨 Command

A command represents an intention to change state. It is handled by a single handler and returns a result.

📖 Read more → command.md

🔍 Query

A query retrieves data without modifying state. It is also handled by a single handler.

📖 Read more → query.md

📣 Event

An event represents something that has already happened. It can be:

In-memory — handled immediately during bus::publish(...)

Database-backed — persisted and processed asynchronously by background workers

• 📖 Read more → event.md
• 📖 Database-backed events → event_database_sea_orm.md

🧩 Middleware Pipelines

You can wrap handlers with composable pipelines for:

• Logging
• Validation
• Metrics
• Tracing
• Retry instrumentation

Supported for:

• In-memory events → event_pipeline.md
• Database-backed events → event_database_pipeline.md
• Requests (commands/queries) → request_pipeline.md

⚙️ Installation

Add bus to your Cargo.toml:

[dependencies]
bus = { package = "rust_bus", version = "" }
ctor = "0.4" # Required for automatic handler & pipeline registration

Why ctor?

bus uses the ctor crate to automatically register handlers and pipelines at startup. Without it, nothing will be wired up.

📦 Migrations for Database Events

If you're using database-backed events with SeaORM, you must apply the required database migrations before running workers.

All required migrations are located in the root of the repository under the migration/ directory:

/migration
├── 2023_..._create_bus_events_table.sql
├── 2023_..._create_bus_events_archive.sql
└── ...

migration

You can apply them using your preferred migration tool (e.g. SeaORM CLI, refinery, sqlx-cli, or manually via psql/MySQL client).

🚀 Getting Started

1. Define your command, query, or event
2. Implement the corresponding handler trait
3. Register it using a macro (e.g. #[bus::registry::BusCommandHandler])
4. Optionally define pipelines for cross-cutting concerns
5. Use bus::send(...) or bus::publish(...) to dispatch

🧠 Design Philosophy

• ✅ Explicit over implicit
• ✅ Async-first
• ✅ Minimal boilerplate
• ✅ Composable middleware
• ✅ Type-safe boundaries

📚 Documentation Index

StandForUkraine 🇺🇦

This project aims to show support for Ukraine and its people amidst a war that has been ongoing since 2014. This war has a genocidal nature and has led to the deaths of thousands, injuries to millions, and significant property damage. We believe that the international community should focus on supporting Ukraine and ensuring security and freedom for its people.

Join us and show your support using the hashtag #StandForUkraine. Together, we can help bring attention to the issues faced by Ukraine and provide aid.