# Hexeract

> The 6-dimension Rust messaging framework: Mediator, Bus, Outbox, Sagas, Scheduler, Request/Reply.

[![crates.io](https://img.shields.io/crates/v/hexeract-outbox.svg?label=crates.io)](https://crates.io/crates/hexeract-outbox)
[![docs.rs](https://img.shields.io/docsrs/hexeract-outbox?label=docs.rs)](https://docs.rs/hexeract-outbox)
[![CI](https://github.com/nubster-opensources/hexeract/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nubster-opensources/hexeract/actions/workflows/ci.yml)
[![MSRV](https://img.shields.io/badge/MSRV-1.88-blue.svg)](./docs/MSRV_POLICY.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Made with Rust](https://img.shields.io/badge/made%20with-Rust-orange?logo=rust)](https://www.rust-lang.org/)

Hexeract is a server-side messaging framework written in Rust. It unifies in-process mediator handlers, external message bus transports, transactional outbox and inbox, long-running sagas, scheduled messages and request/reply RPC in a single coherent SDK. The framework relies on Rust's type system and procedural macros to provide compile-time guarantees in place of runtime reflection.

Hexeract is sponsored by [Encelade Technologies](https://encelade.tech).

## Status

🚀 **v0.1.0 released on crates.io.** Outbox MVP shipped end to end against PostgreSQL via `deadpool_postgres`.

| Feature | v0.1.0 |
| --- | --- |
| Transactional outbox (PostgreSQL) | ✅ |
| Worker poll loop with `SKIP LOCKED` | ✅ |
| Fluent builder API | ✅ |
| `hexeract` CLI for schema management | ✅ |
| Mediator | ⏳ v0.3.0 |
| Bus (RabbitMQ, NATS, Kafka, SQS) | ⏳ v0.2.0 then v0.9.0 |
| Sagas, Scheduler, Request and Reply | ⏳ later milestones |

See the [CHANGELOG](./CHANGELOG.md) for the detailed history.

## Quick start

Add the PostgreSQL backend to your `Cargo.toml`:

```toml
[dependencies]
hexeract-outbox = "0.1"
hexeract-outbox-postgres = "0.1"
```

Declare a domain event, a handler and wire a worker:

```rust
use std::time::Duration;
use hexeract_core::HandlerContext;
use hexeract_outbox::{Event, Handler, OutboxError, OutboxPublisher};
use hexeract_outbox_postgres::{PgOutboxPublisher, PgOutboxWorkerBuilder};
use serde::{Deserialize, Serialize};
use tokio_util::sync::CancellationToken;
use uuid::Uuid;

#[derive(Debug, Serialize, Deserialize)]
struct UserRegistered { user_id: Uuid }

impl Event for UserRegistered {
    const EVENT_TYPE: &'static str = "users.registered";
}

struct AuditWriter;
impl Handler<UserRegistered> for AuditWriter {
    type Error = OutboxError;
    async fn handle(&self, event: UserRegistered, _ctx: &HandlerContext) -> Result<(), Self::Error> {
        // ... write to audit storage ...
        Ok(())
    }
}

# async fn run(pool: deadpool_postgres::Pool) -> Result<(), Box<dyn std::error::Error>> {
let publisher = PgOutboxPublisher::new(pool.clone(), "audit_outbox")?;

let worker = PgOutboxWorkerBuilder::new(pool.clone())
    .table_name("audit_outbox")
    .register_handler::<UserRegistered, _>(AuditWriter)
    .poll_interval(Duration::from_millis(50))
    .build()?;

let cancel = CancellationToken::new();
let join = tokio::spawn(worker.run(cancel.clone()));

// inside a business use case:
let mut client = pool.get().await?;
let mut tx = client.transaction().await?;
let event_id = publisher.publish_in_tx(&mut tx, &UserRegistered { user_id: Uuid::new_v4() }).await?;
tx.commit().await?;
println!("published event {event_id}");

cancel.cancel();
join.await??;
# Ok(()) }
```

See [`docs/getting-started.md`](./docs/getting-started.md) and the runnable [`examples/`](./crates/hexeract-outbox-postgres/examples/) for the full integration walkthrough.

## Why Hexeract

Building event-driven services in Rust today means manually wiring a broker client, an outbox table, a job queue, a workflow library and a saga state machine together. Hexeract closes that gap with a single SDK that covers the full surface area while keeping each feature independently usable:

- **Mediator**, dispatch commands to handlers in-process, type-safe and reflection-free.
- **Bus**, send messages to RabbitMQ, NATS, Kafka or AWS SQS through a unified transport abstraction.
- **Outbox**, save business state and outgoing messages atomically in a single database transaction.
- **Sagas**, orchestrate long-running workflows with persisted state, retries and compensations.
- **Scheduler**, schedule messages for later delivery, with cron, delays, exponential backoff retries and dead-letter handling.
- **Request/Reply**, perform RPC-style synchronous calls on top of an asynchronous bus via correlation identifiers.

The bet behind Hexeract is that Rust's compile-time guarantees turn the outbox pattern from a vigilance discipline into something the type system enforces.

## What Hexeract is **not**

To stay focused, the following are explicitly out of scope:

- **Not a service mesh.** No automatic mTLS or network policies between services. Use Linkerd or Istio.
- **Not a broker.** Hexeract is a client; you keep your existing RabbitMQ, NATS or Kafka.
- **Not a standalone workflow engine.** Sagas live inside your services, not in a dedicated cluster. Use Temporal or Airflow when you need that shape.
- **Not an event streaming engine.** No real-time stream processing. Use Kafka Streams or Apache Flink.

## Audience

- **Rust backend teams** building microservices who want a cohesive messaging toolkit instead of stacking incompatible crates.
- **Developers migrating to Rust** looking for a cohesive messaging SDK.
- **Polyglot teams** with part of their stack moving to Rust and the need to stay interoperable on a shared bus alongside their Node, Python or Go services.

## Contributing

Contributions are welcome. Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first for the workflow and conventions, and [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for the community guidelines. For vulnerability reports, see [`SECURITY.md`](./SECURITY.md). For open-ended questions and design conversations, use [GitHub Discussions](https://github.com/nubster-opensources/hexeract/discussions).

Stability and versioning are documented in [`docs/SEMVER_POLICY.md`](./docs/SEMVER_POLICY.md) and [`docs/MSRV_POLICY.md`](./docs/MSRV_POLICY.md).

## License

Hexeract is distributed under the terms of the [MIT license](./LICENSE).

Copyright © Encelade Technologies.
