soaprs

soaprs is an idiomatic Rust interpretation of the architectural ideas behind @soapjs/soap. It provides small contracts for Clean Architecture applications without a runtime dependency-injection container, reflection, or framework-specific types in the core.

The project is at an early design and contract-validation stage. Pre-1.0 releases may still refine their public API as production adapters validate the ports.

Development is pinned to Rust 1.97.1 and Edition 2024. The workspace supports Rust 1.85.0 or newer; CI verifies both the MSRV and the current stable toolchain.

Current scope

The current workspace provides:

object-safe asynchronous use-case, command, and named-query contracts with strongly typed dispatch and runtime-independent middleware pipelines,
DDD-friendly entities and constructor-injected ports,
read and read-write repository contracts,
a database-independent query AST with documented semantics,
structured errors with preserved technical sources and diagnostic IDs,
transport-neutral HTTP metadata and default error mapping,
a reference in-memory adapter and reusable adapter contract tests,
typed domain and integration events with caller-generated trace metadata,
CQRS and event-sourcing ports for streams, explicitly idempotent or atomic projections, replay, upcasting, snapshots, and sagas,
serialization-neutral stored events and a codec-backed typed event store for JSON, BSON, binary, or other adapter-selected payloads,
a reusable event-sourced aggregate repository for validated rehydration and optimistic commits,
reliable delivery ports for atomic outbox writes, idempotent inbox claims, and runtime-independent retry decisions,
reusable inbox and outbox processors covering claim ownership, delivery, retry scheduling, duplicate suppression, and terminal dead-letter handling,
atomic saga state/action commits with durable commands, compensations, scheduled timers, retries, and terminal dead-letter processing,
reference in-memory CQRS, event, outbox, inbox, checkpoint, snapshot, and saga action/timer adapters with reusable contract tests.

Production database and web-framework adapters are not included in this workspace. They live in separate crates and repositories so applications only select the infrastructure they use. The first such adapter is soaprs-sqlx, with PostgreSQL support.

Quick start

Add the facade crate:

[dependencies]
soaprs = "0.2"

Define application operations without depending on an asynchronous runtime or transport framework in the core contract:

use soaprs::prelude::{BoxFuture, SoapResult, UseCase};

struct WelcomeUser;

impl UseCase for WelcomeUser {
    type Input = String;
    type Output = String;

    fn execute(&self, name: Self::Input) -> BoxFuture<'_, SoapResult<Self::Output>> {
        Box::pin(async move { Ok(format!("Welcome, {name}!")) })
    }
}

The complete example shows validation, write repositories, portable named queries, constructor injection, and an in-memory adapter in one application: examples/users-memory.

The CQRS example shows a traced command committing a domain event and an integration event to one atomic in-memory outbox: examples/orders-cqrs.

Workspace

soaprs-core — structured errors, entities, boxed futures, use cases, commands, queries, externally supplied clocks, and message correlation metadata.
soaprs-events — typed domain/integration events and publisher/handler ports.
soaprs-cqrs — event stores, projections, replay, upcasting, snapshots, stored-event codecs, aggregate loading/commits, sagas, durable action timers, outbox/inbox, and retry contracts.
soaprs-repository — validated fields, query AST, repository ports, and a reusable handler for portable named queries.
soaprs-http — transport-neutral endpoint metadata and HTTP error mapping.
soaprs — convenience facade and prelude.
soaprs-contract-tests — reusable behavioral checks for repository and CQRS persistence adapters.
soaprs-memory — reference repository, event, CQRS, and delivery adapters.
users-memory — runnable example with use cases, portable named queries, constructor injection, and the in-memory adapter.
orders-cqrs — runnable command, event-store, and atomic outbox example.

Ecosystem

Available separately:

soaprs-sqlx — SQLx repository and PostgreSQL adapter.

The following separate crates are planned:

soaprs-axum — Axum HTTP adapter,
soaprs-mongodb — MongoDB adapter,
soaprs-redis — Redis repository and cache adapters,
soaprs-kafka and soaprs-rabbitmq — integration-event adapters,
soaprs-cli and cargo-soap — project and module generation.

The roadmap describes direction rather than release dates. Framework, database, cache, and broker adapters will live in separate repositories after their ports stabilize.

Development

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run -p soaprs-users-memory-example
cargo run -p soaprs-orders-cqrs-example