# 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,
- protocol-neutral credentials, principals, authentication strategies,
authorization decisions, sessions, token lifecycle ports, and shared auth
adapter contracts,
- a transport-neutral HTTP service-provider interface with validated endpoint
catalogs, request/response contracts, authorization and security policies,
safe response effects, telemetry declarations, and error mapping,
- a protocol-neutral realtime service-provider interface with typed message
handlers, deterministic catalogs, connection context, authorization,
correlated replies, and backpressure-aware delivery intent,
- 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.4"
```
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).
The authentication example demonstrates public, optional, required,
strategy-specific, role, permission, named-policy, Bearer, session-cookie,
login, and logout behavior:
[`examples/auth-http`](https://github.com/soaprs/soap/tree/main/examples/auth-http).
The accompanying [auth and HTTP usage guide](docs/guides/AUTH-AND-HTTP.md)
explains when to select each contract.
The realtime lobby example demonstrates an authenticated connection, typed
message dispatch into a use case, an external-service port, presence, channel
membership, correlated metadata, and explicit queue backpressure:
[`examples/realtime-lobby`](https://github.com/soaprs/soap/tree/main/examples/realtime-lobby).
The [realtime usage guide](docs/guides/REALTIME.md) explains which responsibilities
belong to the application, protocol adapter, and capability packages.
## 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-auth` — protocol-neutral credentials, principals, authentication,
authorization, session, token rotation, and revocation contracts.
- `soaprs-auth-http` — framework-neutral Bearer, API-key, and session-cookie
extraction plus auth cookies and challenge response effects.
- `soaprs-http` — transport-neutral HTTP endpoint catalogs, contracts,
policies, request/response effects, telemetry metadata, and error mapping.
- `soaprs-realtime` — protocol-neutral connection context, typed message
handlers, inbound catalogs, policies, and fallible outbound delivery.
- `soaprs` — convenience facade and prelude.
- `soaprs-contract-tests` — reusable behavioral checks for auth, repository,
and CQRS persistence adapters.
- `soaprs-memory` — reference session, 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.
- `auth-http` — runnable Bearer/session authentication and HTTP authorization
policy example.
- `realtime-lobby` — runnable authenticated lobby, channel membership, and
backpressure-aware delivery example.
## Ecosystem
Available separately:
- [`soaprs-sqlx`](https://github.com/soaprs/soap-sqlx) — SQLx repository and
PostgreSQL adapter.
M3.7 completed `soaprs-realtime`: protocol-neutral connection,
message-handler, channel, presence, authorization, delivery, acknowledgement,
safe-error, and backpressure contracts for realtime applications.
The following separate crates are planned:
- `soaprs-auth-jwt`, `soaprs-auth-password`, and `soaprs-auth-session` — concrete
cryptography, password verification, and session authentication packages,
- `soaprs-rate-limit` — limiter ports and algorithms independent from HTTP
frameworks and storage,
- `soaprs-http-security` — framework-neutral CORS, CSRF, and security-header
enforcement helpers,
- `soaprs-validation` — request contract resolution and typed validator bridges,
- `soaprs-openapi` — schema resolution and OpenAPI generation from endpoint
catalogs,
- `soaprs-http-otel` — tracing and metrics integration,
- `soaprs-axum`, `soaprs-actix-web`, and `soaprs-poem` — framework adapters,
- `soaprs-websocket`, `soaprs-socketio`, and `soaprs-axum-ws` — realtime
protocol and framework adapters,
- `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
cargo run -p soaprs-auth-http-example
cargo run -p soaprs-realtime-lobby-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).