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,
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, with PostgreSQL support.

Quick start

Add the facade crate:

[dependencies]
soaprs = "0.4"

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.

The authentication example demonstrates public, optional, required, strategy-specific, role, permission, named-policy, Bearer, session-cookie, login, and logout behavior: examples/auth-http. The accompanying auth and HTTP usage guide 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. The realtime usage guide 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 — 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

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