Source: https://fireflyframework.org/frameworks/rust/
Language: en

rsfly, the Rust framework by Firefly

# Tokio and Axum, plus a typed service architecture in crates.

rsfly’s crates cover SQLx and MongoDB repositories, a CQRS bus, optional event sourcing, Kafka and PostgreSQL brokers, sagas, and security filters.

[Read the documentation](https://github.com/fireflyframework/fireflyframework-rust/blob/11fb6a2f4ac51d413390ddb1846584f20d4fb00d/docs/book/README.md) [View the source](https://github.com/fireflyframework/fireflyframework-rust)

1. 01 Service composition
2. 02 Domain and data
3. 03 Commands and queries
4. 04 Event history
5. 05 Integration contracts
6. 06 Business coordination
7. 07 Access and resilience
8. 08 Service operations

Rust 1.88+ · Tokio · Axum · SQLx

Native stack and framework

## What rsfly adds to Axum, Tokio, and SQLx.

Axum serves requests, Tokio runs tasks, and SQLx queries the database. rsfly links your crates’ components into one application when the binary starts.

### Service composition

Components from every linked crate are discovered, built, and mounted when the application starts.

With Axum, Tokio, and SQLx alone, your team builds

Tokio startup code that gathers Axum routers, component registrations, and configuration across crates.

rsfly provides

Component discovery, async bean factories, mounted controllers and handlers, and reloadable typed configuration.

How it works

Component scanning registers and autowires your beans at startup. `ReloadableConfig` merges configuration sources, resolves placeholders, and publishes a new typed snapshot on each reload.

A crate’s registrations reach the application only if the binary links it, as the sample does with `firefly::link!`.

[Controller mounting and handler discovery](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L288-L308) [Reloadable typed configuration](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/config/src/reload.rs#L84-L123) [Lumen Ledger entry point](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger/web/src/main.rs#L32-L46)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L220-L244)

### Domain and data

Domain rules live in typed models. The SQLx and MongoDB repositories page results, and the SQLx one rejects stale versioned writes.

With Axum, Tokio, and SQLx alone, your team builds

Repository, specification, concurrency, and soft-delete conventions built around SQLx or MongoDB.

rsfly provides

DDD contracts and specifications, SQLx and MongoDB repositories with paging, and optimistic locking on SQLx.

How it works

`SqlxRepository` pages filtered queries and rejects a stale versioned write with `OptimisticLock`. Repository writes join the surrounding transaction, and a rollback undoes them.

Test queries, locking, and transactions against the SQL dialect or MongoDB deployment you choose.

[SQLx repository operations](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/data-sqlx/src/repository.rs#L1520-L1580) [Optimistic locking test](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/data-sqlx/tests/version.rs#L64-L105) [Transaction rollback test](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/data-sqlx/tests/transactional.rs#L61-L94) [MongoDB repository guards](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/data-mongodb/src/repository.rs#L150-L216)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/kernel/src/ddd.rs#L93-L138)

### Commands and queries

Handlers receive typed commands and queries through middleware your services share.

With Axum, Tokio, and SQLx alone, your team builds

A dispatch boundary for handlers, with validation, cached queries, and invalidation wired to events.

rsfly provides

A typed CQRS bus with validation middleware, a query cache, and an EDA bridge that invalidates it.

How it works

The core starter installs validation middleware on the bus. The cache bridge maps an event’s type or payload to the cached queries it evicts.

Handle dispatch errors such as a missing handler. The default cache and broker are in-process.

[Validation middleware by default](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/starter-core/src/lib.rs#L398-L412) [Query cache tests](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/cqrs/tests/cqrs_test.rs#L120-L167) [Event-driven cache invalidation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/cqrs/src/eda_bridge.rs#L148-L211)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/cqrs/src/bus.rs#L517-L550)

### Event history

Services that need history store changes as events and rebuild read models from them.

With Axum, Tokio, and SQLx alone, your team builds

Aggregate replay, event versions, snapshot stores, and projections.

rsfly provides

Event-sourced aggregates, versioned appends, snapshots, and projections that can replay a stream.

How it works

The SQL event store checks the expected version and appends in one transaction. The repository restores the latest snapshot and replays the events after it.

The domain starter keeps events and snapshots in memory until you select persistent stores.

[Snapshot restore and replay](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eventsourcing/src/repository.rs#L174-L252) [SQL event store append](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eventsourcing/src/sql_store.rs#L139-L216) [Projection runner](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eventsourcing/src/projection.rs#L117-L190) [Domain starter defaults](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/starter-domain/src/lib.rs#L82-L121)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eventsourcing/src/aggregate.rs#L96-L146)

### Integration contracts

Adapters behind provider ports carry events and calls, and domain code never names the transport.

With Axum, Tokio, and SQLx alone, your team builds

Shared event and service interfaces around broker clients and provider SDKs.

rsfly provides

Event envelopes, Kafka and PostgreSQL brokers, and notification services behind provider ports.

How it works

Broker adapters implement the publish and subscribe contracts. The PostgreSQL broker writes its own outbox table and wakes its drain loop with `NOTIFY`.

The core broker is in memory. The PostgreSQL outbox commits apart from your domain tables unless you join the writes.

[PostgreSQL outbox broker](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eda-postgres/src/broker.rs#L235-L267) [Event-sourcing sink to EDA](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eventsourcing/src/outbox.rs#L114-L163) [Email notification service](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/notifications/src/services.rs#L80-L165) [SendGrid provider](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/notifications-sendgrid/src/lib.rs#L312-L356)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/eda-kafka/src/broker.rs#L87-L125)

### Business coordination

Multi-step operations declare their steps, dependencies, and compensation in code.

With Axum, Tokio, and SQLx alone, your team builds

Step dependencies, compensation, execution state, and event triggers, modeled directly on Tokio.

rsfly provides

A saga engine and macros, event-triggered sagas, persistence ports, and orchestration metrics.

How it works

Saga macros declare steps, their dependencies, and their compensations, and the saga’s policy sets how compensation runs. `EventGateway` can start a saga from a broker event.

Your integration maps the event’s payload to step inputs, because the saga trigger doesn’t.

[Saga macro tests](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/tests/saga_macro.rs#L36-L94) [Saga triggers from events](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/gateway.rs#L121-L153) [Gateway binding to a broker](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/gateway.rs#L215-L241) [Persistence adapters](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/persistence.rs#L15-L21) [Orchestration metrics](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/observability.rs#L631-L641)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/saga.rs#L730-L769)

### Access and resilience

Access rules and failure policies are named once and reused across routes and outbound calls.

With Axum, Tokio, and SQLx alone, your team builds

Named policies composed from Tower middleware, identity clients, and resilience libraries.

rsfly provides

A filter chain and bearer layer, a Keycloak adapter, and named resilience policies.

How it works

`FilterChain` matches method and path rules with role requirements, and `BearerLayer` verifies tokens. A resilience `Chain` nests its decorators, the first added outermost.

An empty filter chain checks nothing. Once it has a rule, unmatched requests get 403.

[Deny-by-default filter chain](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/security/src/filter_chain.rs#L145-L224) [Bearer token layer](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/security/src/bearer.rs#L107-L125) [Resilience decorators](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/resilience/src/chain.rs#L49-L84) [Resilience chain order](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/resilience/src/chain.rs#L121-L168) [Named policy registry](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/resilience/src/registry.rs#L200-L215) [Keycloak adapter](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/idp-keycloak/src/lib.rs#L454-L520)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L258-L277)

### Service operations

Service owners get health, request metrics, and API documentation from the running application.

With Axum, Tokio, and SQLx alone, your team builds

Request instrumentation, dependency health, management endpoints, and API descriptions.

rsfly provides

Default request metrics and cache health, plus OpenAPI from discovered controllers on the management port.

How it works

The core starter records HTTP request metrics by default and adds a cache health check. `FireflyApplication` serves OpenAPI on the management port.

Secure the management port, and add health checks for the dependencies your operators watch.

[OpenAPI on the management port](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L327-L349) [Orchestration metrics listener](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/observability.rs#L631-L641)

[See the implementation](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/starter-core/src/lib.rs#L384-L442)

Already in the native stack

Axum provides routing, typed extraction, shared state, and Tower middleware. Tokio runs async tasks and I/O. SQLx provides connection pools, queries, and transactions.

Your team still owns

Domain behavior, handlers, resource factories, schemas and mappings, security policy, deployment configuration, and compensating actions. Your crates also declare their components with macros and `firefly::link!`.

Startup sequence

## What an rsfly binary does before it serves a request.

`FireflyApplication` runs a fixed startup sequence over the components your crates declare.

### Linking crates into a running service

1. The binary links the crates that contribute components.
2. The container discovers components and awaits their async factories.
3. Declared controllers mount, and handlers register on the bus.
4. Event listeners subscribe, and scheduled tasks are registered.
5. Configured health and metrics endpoints report on the application.

Business operations and provider configuration stay in your code.

[Component scan and async factories](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L220-L244) [Mounting and handler registration](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/firefly/src/application.rs#L288-L308)

Capabilities

## Pick the modules your service needs.

rsfly / Conceptual architecture

The container supplies handlers and repositories with their dependencies.

1. [01Reactive composition](https://fireflyframework.org/frameworks/rust/#rust-capability-0)
2. [02Dependency injection](https://fireflyframework.org/frameworks/rust/#rust-capability-1)
3. [03Typed CQRS dispatch](https://fireflyframework.org/frameworks/rust/#rust-capability-2)
4. [04Compensating sagas](https://fireflyframework.org/frameworks/rust/#rust-capability-3)
5. [05SQLx repositories](https://fireflyframework.org/frameworks/rust/#rust-capability-4)

Amber: Firefly modules · Ivory lines: APIs · Amber lines: events

### Reactive composition

`Mono` maps and chains asynchronous values, and an empty `Mono` stays empty through each step. Its operators follow Reactor’s names.

[See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/reactive/src/mono.rs#L164-L202)

### Dependency injection

The container registers components and resolves their dependencies. Singletons are built once and cached, and transient components are built on each resolve.

[See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/container/src/lib.rs#L1013-L1058)

### Typed CQRS dispatch

Commands and queries are typed messages that the bus routes to registered handlers. An execution context can travel with each one.

[See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/cqrs/src/bus.rs#L517-L560)

### Compensating sagas

Saga steps can declare a compensation. When a later step fails, the saga compensates the completed steps in reverse order.

[See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/saga.rs#L734-L769)

### SQLx repositories

`SqlxRepository` reads, writes, filters, and pages rows. A missing row returns `NotFound`, and a stale versioned write returns `OptimisticLock`.

[See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/data-sqlx/src/repository.rs#L1526-L1580)

Code

## How Lumen Ledger handles a deposit.

`deposit` handles `POST /api/v1/wallets/:id/deposit`. It calls the wallet service, maps service errors to HTTP problems, and returns the updated wallet.

### Follow a wallet through the layers

1. #### Validate the amount

   `Valid` rejects a non-positive amount with 422 before the wallet service runs.
2. #### Credit the wallet

   `WalletServiceImpl` loads the active wallet, adds the amount, and saves it through the repository.

   [See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger/core/src/services/wallet/v1/wallet_service_impl.rs#L276-L280)
3. #### Check it end to end

   The sample’s integration test opens a wallet over HTTP, deposits into it, and checks the stored version.

   [See the source](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger/web/src/main.rs#L119-L161)

wallet\_controller.rs

```rust
    /// `POST /api/v1/wallets/:id/deposit` — credit a wallet (`Valid<…>` rejects a
    /// non-positive amount as 422 before the service runs).
    #[post("/wallets/:id/deposit", summary = "Deposit funds", status = 200)]
    async fn deposit(
        State(api): State<WalletController>,
        Path(id): Path<Uuid>,
        Valid(body): Valid<AmountRequest>,
    ) -> WebResult<Json<WalletResponse>> {
        let view = api
            .service
            .deposit(id, body.amount)
            .await
            .map_err(service_to_web)?;
        Ok(Json(view))
    }
```

[View the full file](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger/web/src/controllers/wallet/v1/wallet_controller.rs#L211-L225)

### A bootstrap that links the layers

`firefly::link!` keeps the layer crates’ registrations in the binary. `FireflyApplication` then discovers the components, awaits async resources, and mounts the controllers.

main.rs

```rust
firefly::link!(
    lumen_ledger_core,
    lumen_ledger_models,
    lumen_ledger_interfaces
);

mod controllers;

#[tokio::main]
async fn main() -> Result<(), firefly::BoxError> {
    firefly::FireflyApplication::new("lumen-ledger")
        .version(firefly::VERSION)
        .run()
        .await
}
```

[View the full file](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger/web/src/main.rs#L32-L46)

Releases and setup

## rsfly ships from its GitHub workspace.

Depend on the framework’s crates and enable the features your service uses. Optional adapters still need their own infrastructure.

rsfly v26.6.36 is on GitHub Releases, and CI passed on its release commit.

Saga compensation alone doesn’t give restart recovery, and persisted records don’t resume suspended work by themselves. `Idempotency-Key` replay is on, with an in-memory store that each instance keeps to itself and loses on restart.

[Read the documentation](https://github.com/fireflyframework/fireflyframework-rust/blob/11fb6a2f4ac51d413390ddb1846584f20d4fb00d/docs/book/README.md) [View releases](https://github.com/fireflyframework/fireflyframework-rust/releases)

### The crates.io package named firefly is another project

Use the crates in this framework’s source workspace and the book’s setup chapters. A `firefly` dependency from crates.io names that other project.

[Open the book’s contents](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/docs/book/src/SUMMARY.md)

Front cover of rsfly by example

### rsfly by example

Composing typed services with Tokio, Axum and SQLx

The book grows Lumen, a wallet and ledger service, from an empty crate to an event-sourced service. Its Layered Microservices chapter splits it into Lumen Ledger.

[Read the manuscript](https://github.com/fireflyframework/fireflyframework-rust/tree/books-2026.10.08/docs/book/src)
- [English PDF](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example.pdf)
- [English EPUB](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example.epub)
- [Spanish PDF](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example-es.pdf)
- [Spanish EPUB](https://github.com/fireflyframework/fireflyframework-rust/releases/download/books-2026.10.08/firefly-rust-by-example-es.epub)

October 2026 edition

Related

## Two starting points from the book, and a saga test.

### Lumen Ledger sample

The book’s layered sample, with web, core, models, interfaces, and SDK crates.

[View the source](https://github.com/fireflyframework/fireflyframework-rust/tree/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger)

### Quickstart

The book’s first service, generated with the CLI or built by hand.

[Read the chapter](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/docs/book/src/02-quickstart.md)

### Saga compensation test

A checkout saga whose shipping step fails, compensated in reverse order.

[Read the test](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/orchestration/src/saga.rs#L979-L999)

Sources behind this page

- [Runtime configuration](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/Cargo.toml#L92-L98)
- [Reactive composition tests](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/reactive/src/mono.rs#L723-L749)
- [Dependency injection tests](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/container/tests/container_basics.rs#L38-L74)
- [Typed CQRS dispatch tests](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/cqrs/tests/cqrs_test.rs#L87-L139)
- [Release commit CI](https://github.com/fireflyframework/fireflyframework-rust/actions/runs/27853792515)
- [Axum native routing and state](https://docs.rs/axum/0.7.9/axum/)
- [SQLx native transactions](https://docs.rs/sqlx/0.8.6/sqlx/struct.Transaction.html)
- [Published v26.6.36 release](https://github.com/fireflyframework/fireflyframework-rust/releases/tag/v26.6.36)
- [Idempotency layer on every route](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/starter-core/src/lib.rs#L484-L506)
- [Idempotency defaults: memory store, 24-hour TTL](https://github.com/fireflyframework/fireflyframework-rust/blob/e18e12e207921bf06cb42cf81c883160b45b15a2/crates/starter-core/src/lib.rs#L199-L202)

Next step

## Open Lumen Ledger and follow one deposit through it.

[Read the documentation](https://github.com/fireflyframework/fireflyframework-rust/blob/11fb6a2f4ac51d413390ddb1846584f20d4fb00d/docs/book/README.md) [Open the sample](https://github.com/fireflyframework/fireflyframework-rust/tree/e18e12e207921bf06cb42cf81c883160b45b15a2/samples/lumen-ledger)
