evx
evx is a type-safe asynchronous event bus for Rust applications. It combines
domain-event fan-out, CQRS request-response messaging, in-process dispatch,
Redis Pub/Sub, and Redis Stream work queues behind one API. Messages crossing a
transport boundary use CloudEvents 1.0-style envelopes.
Features
| Cargo feature | Default | Provides |
|---|---|---|
in-process |
yes | InProcessBroker, backed by a disruptor ring buffer |
redis |
no | RedisBroker and RedisStreamQueue |
The core message, broker, queue, and EventBus abstractions are available with
default-features = false.
[]
= "0.1"
# Add Redis Pub/Sub and Redis Stream support.
# evx = { version = "0.1", features = ["redis"] }
Evx requires Rust 1.88 or newer. Redis-backed queues require Redis or Valkey
6.2 or newer because stale pending jobs are recovered with XAUTOCLAIM.
Message model
Every message implements Message, which defines its stable wire type, source,
and routing scope:
EventScope::Processuses the process broker.EventScope::Appuses the application broker, normally Redis Pub/Sub.
Domain events implement DomainEvent. Commands and queries implement
RequestMessage plus CommandMessage or QueryMessage; their response type is
selected at compile time.
use ;
use ;
Use stable reverse-domain message types. Renaming a type after deployment breaks compatibility between producers and consumers.
In-process commands and queries
An EventBus has a process broker and an application broker. A local-only application can use in-process brokers for both scopes:
use Arc;
use Duration;
use ;
let runtime = current;
let eventbus = new;
eventbus
.
.await?;
let response = eventbus
.call
.await?;
Process-scoped calls use direct typed dispatch when a handler is registered,
avoiding a CloudEvent serialization round trip. Calls return
EventError::Timeout when their deadline expires.
handle and subscribe return a SubscriptionId. Cancel the registration
with eventbus.unsubscribe(id).await.
Domain events
Domain events describe facts that already happened and use fire-and-forget fan-out:
use ;
use ;
eventbus
.
.await?;
eventbus.publish.await?;
A successful publish means the broker accepted the event. Subscriber failures are logged and are not returned to the publisher. Redis Pub/Sub is not durable; offline subscribers do not receive earlier events.
Redis Pub/Sub and cross-node calls
Enable the redis feature and provide separate, connected fred clients for
publishing and subscribing:
use Arc;
use ;
let process = new;
let application = new;
let eventbus = new;
RedisBroker::new uses the evx channel prefix. Use
RedisBroker::with_prefix to isolate applications or environments. App-scoped
commands use correlation IDs and temporary Redis reply channels, so the caller
and handler may run on different nodes.
Durable work queues
Configure a queue backend when constructing the EventBus:
use Arc;
use ;
let queue = new;
let eventbus = new;
Then implement QueuedCommand and start a worker:
use ;
let job_id = eventbus.enqueue.await?;
let worker = eventbus
.
.await?;
// During application shutdown:
worker.abort;
Each consumer instance needs a unique name. Successful jobs are acknowledged.
Failures are re-enqueued immediately until max_attempts, then written to a
dead-letter stream. Jobs left pending by a crashed worker become claimable after
claim_idle_ms.
The default Redis keys are:
- queue:
evx:queue:<queue> - dead letter:
evx:dlq:<queue>
Use RedisStreamQueue::with_prefix for a different namespace. Delivery can be
duplicated when a worker completes a side effect but stops before acknowledging
the job, so queued handlers must be idempotent. Evx does not currently apply a
retry backoff.
CloudEvent envelopes
Business code normally works only with typed messages. For custom transports or
external integrations, CloudEvent::from_message, into_message, to_json,
and from_json expose the wire envelope. Evx uses the reply_to and
correlationid extension attributes for request-response messaging.
Shutdown
Call eventbus.shutdown().await to stop both brokers. Queue workers are separate
Tokio tasks; retain their JoinHandles and stop them as part of application
shutdown.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE), or
- MIT License (LICENSE-MIT)
at your option.