# soaprs
`soaprs` is an idiomatic Rust interpretation of the architectural ideas behind
[`@soapjs/soap`](https://github.com/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`](https://crates.io/crates/soaprs-sqlx), with PostgreSQL support.
## Quick start
Add the facade crate:
```toml
[dependencies]
soaprs = "0.2"
```
Define application operations without depending on an asynchronous runtime or
transport framework in the core contract:
```rust
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`](https://github.com/soaprs/soap/tree/main/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`](https://github.com/soaprs/soap/tree/main/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`](https://github.com/soaprs/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
```bash
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
```
See the [documentation index](https://github.com/soaprs/soap/blob/main/docs/README.md),
the [architecture overview](https://github.com/soaprs/soap/blob/main/docs/architecture/OVERVIEW.md),
the [roadmap](https://github.com/soaprs/soap/blob/main/docs/architecture/ROADMAP.md),
and the [changelog](https://github.com/soaprs/soap/blob/main/CHANGELOG.md).