rust_bus 3.0.5

bus — Lightweight CQRS Library for Rust
Documentation

🚌 rust_bus — Lightweight, flexible, and production-ready Event Bus for Rust.

🧐 What is rust_bus?

In modern software architecture, you often need to decouple your business logic from side effects (like sending emails, processing images, or updating external APIs).

rust_bus acts as a mediator. Instead of calling a function directly, you dispatch an Event. The Bus then ensures that all registered Handlers for that event are executed.

🚀 How it Works

The Bus operates on three main pillars:

  1. Events: Simple Rust structs that implement IBusEvent (carrying your data).
  2. Handlers: Logic units that implement IEventHandler or IEventHandlerDatabase.
  3. The Dispatcher: The engine that matches events to their corresponding handlers.

🛠 Why use rust_bus?

  • Decoupling: Your main business flow doesn't need to know who is listening to its events.
  • Reliability: With the database-backed worker system, if a handler fails or the server crashes, the job is not lost. It remains in the DB for a retry.
  • Scalability: You can run multiple instances of your application (Nodes), and they will coordinate to process jobs from the shared database.
  • Flexibility: Use it purely in-memory for speed, or plug in a database for persistence.

📦 Out-Of-The-Box Features

Unlike simple event emitters, rust_bus provides a full-featured background job system:

  • Retries with Backoff: Automatically retry failed jobs with configurable delays ($2^{attempt}$ minutes).
  • Timeouts: Ensure no job hangs forever and blocks your workers.
  • Priority Queues: Execute critical tasks (like "Process Payment") before lower priority ones (like "Send Newsletter").
  • Graceful Shutdown: Integrated with Tokio, allowing workers to finish current tasks before stopping.
  • Event Uniqueness: Prevent duplicate jobs using sophisticated Unique constraints. Define uniqueness based on specific fields (Event payload, Queue, Meta, etc.) and time periods (Infinite or Duration-based).
  • Smart Replacement: Define Replace strategies to update existing jobs instead of creating new ones. For example, if a job is in Available or Retryable state, you can automatically update its Payload, Priority, or Metadata with the latest data.

💾 Storage Backends

rust_bus is highly modular. You can choose your level of persistence via Cargo features:

1. In-Memory (Default)

Fastest performance. Best for UI updates or transient state changes where losing data on crash is acceptable.

2. Database-Backed (Persistent)

If you need 100% delivery guarantees, choose one of the supported backends:

Feature Description
sea-orm-postgres Advanced ORM support for PostgreSQL
sea-orm-mysql Advanced ORM support for MySQL
sqlx-postgres Lightweight async SQL support for PostgreSQL
sqlx-mysql Lightweight async SQL support for MySQL

🛡 Fault Tolerance

rust_bus is designed for production. It handles:

  • Panics: If a handler panics, the worker catches it, logs it, and marks the job for retry.
  • Timeouts: If a job exceeds its execution_timeout_sec, the worker kills the task and recovers.
  • Recovery Supervisor: A dedicated background process that finds "zombie" jobs (e.g., from a node that crashed) and puts them back into the queue.

📦 Migrations for Database Events

If you're using database-backed events with SeaORM or SQLX, 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
├── mysql.sql
├── postgres.sql
└── ...

migration

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

🧠 Design Philosophy

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

📚 Documentation Index

Topic File
📣 Events (in-memory) event.md
🐘️ Events SeaOrm Postgres event_sea_orm_postgres.md
🐬️ Events SeaOrm Mysql event_sea_orm_mysql.md
🐘️ Events sqlx Postgres event_sqlx_postgres.md
🐬️ Events sqlx Mysql event_sqlx_mysql.md
🧬️ Context context.md
🏗️ Migrations bus app folder migration

#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.