Qubit Event Bus (rs-event-bus)

Documentation: API Reference

qubit-event-bus is a lightweight, thread-safe, in-process event bus for Rust applications.

It provides type-safe topics, event envelopes, subscriber options, publish options, qubit-retry retry policies, acknowledgement handles, factory-configured typed and global interceptors, best-effort batch results, transactional staged-event contracts, and dead-letter records with qubit-metadata diagnostics.

Why Use It

Use qubit-event-bus when you need:

• type-safe publish/subscribe routing inside one process
• consistent event metadata through EventEnvelope
• automatic or manual acknowledgement for subscriber handlers
• subscriber retry and dead-letter behavior
• publisher interceptors that can modify or drop outgoing events
• global metadata interceptors for tracing, logging, and metrics across all payload types
• subscriber interceptors that can wrap, observe, or short-circuit handler execution
• typed and global default dead-letter strategies
• heterogeneous staged-event contracts for transactional backends
• deterministic test synchronization through wait_for_idle

Installation

[dependencies]
qubit-event-bus = "0.6.2"

Quick Start

use std::sync::{Arc, Mutex};

use qubit_event_bus::{LocalEventBus, Topic};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bus = LocalEventBus::started()?;
    let topic = Topic::<String>::try_new("orders.created")?;
    let received = Arc::new(Mutex::new(Vec::new()));

    let captured = Arc::clone(&received);
    bus.subscribe("audit-log", &topic, move |event| {
        captured.lock().expect("received events should lock").push(event.payload().clone());
        Ok(())
    })?;

    bus.publish(&topic, "order-1001".to_string())?;
    bus.wait_for_idle(&topic)?;

    assert_eq!(
        received.lock().expect("received events should lock").as_slice(),
        &["order-1001".to_string()],
    );
    Ok(())
}

Common Next Steps

Core API At A Glance

Project Scope

• qubit-event-bus is an in-process event bus. It does not persist events or provide cross-process delivery.
• Subscriber handlers run on a configurable rs-thread-pool fixed worker pool. Publishing schedules handler work and returns after dispatch.
• Payloads must be Clone + Send + Sync + 'static when published through LocalEventBus.
• Dead-letter strategies return EventEnvelope<DeadLetterPayload> so one dead-letter topic can receive archived records from multiple source event types.
• standard_dead_letters_to, prefixed_dead_letters, and discard_dead_letters cover common dead-letter routing policies without requiring custom closures.
• A subscription-level dead-letter strategy that returns Ok(None) disables fallback to a factory default strategy for that failed delivery. If no subscription or typed default strategy is configured, the local factory can use a global default dead-letter strategy.
• Interceptors are configured on LocalEventBusFactory before creating a bus. Runtime interceptor mutation is intentionally not part of LocalEventBus; use add_error_observer for runtime error observation.
• Explicit publish and subscribe options are merged with type-level factory defaults. Scalar subscribe settings such as acknowledgement mode and priority override defaults only when explicitly set through the builder.
• Manual NACK is treated as subscriber failure and participates in subscriber retry before error handlers or dead-letter routing run.
• Subscribe error handlers run in registration order until one records a new acknowledgement decision, or changes the decision to ACK.
• publish_all is best-effort after lifecycle and option validation. It submits every envelope in input order and returns BatchPublishResult with accepted, dropped, and failed counts. Envelopes with the same ordering_key are delivered serially per topic and subscriber; envelopes without an ordering key may run concurrently.
• delay defers local subscriber handling for at least the requested duration. Delayed work is scheduled by rs-executor's SingleThreadScheduledExecutorService and does not occupy handler workers while waiting.
• Transactional traits use StagedEvent as the core batch abstraction. Typed convenience methods lower into staged events so backends can commit heterogeneous event batches atomically.
• Retry attempt_timeout options are rejected by LocalEventBus because local handlers do not receive a cooperative cancellation signal.
• Blocking shutdown must not be called from one of the same bus's subscriber worker threads. Use shutdown_nonblocking or shutdown_with_timeout from subscriber code.
• After shutdown_with_timeout reports a timeout, start is rejected until the old subscriber work has become idle.
• wait_for_idle and wait_for_idle_timeout are intended for tests and controlled shutdown flows that need to wait for scheduled handler work.

Contributing

Issues and pull requests are welcome.

Please keep contributions focused and easy to review:

• open an issue for bug reports, design questions, or larger feature proposals
• keep pull requests scoped to one behavior change, fix, or documentation update
• follow the Rust coding style used by the existing rs-* projects
• include tests when changing runtime behavior
• update the README when public API behavior changes

By contributing to this project, you agree that your contribution will be licensed under the same license as the project.

License

Licensed under the Apache License, Version 2.0.