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.

  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
Scroll to explore

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

See the implementation

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.

See the implementation

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.

See the implementation

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.

See the implementation

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.

See the implementation

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.

See the implementation

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.

See the implementation

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.

See the implementation
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.

Capabilities

Pick the modules your service needs.

rsfly / Conceptual architectureThe container supplies handlers and repositories with their dependencies.

Amber: Firefly modulesIvory lines: APIsAmber 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

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

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

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

SQLx repositories

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

See the source

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
  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
wallet_controller.rs
    /// `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))
    }

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
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
}

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.

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

October 2026 edition

Next step

Open Lumen Ledger and follow one deposit through it.