manta_server/lib.rs
1//! Library root for the `manta-server` crate.
2//!
3//! `manta-server` is the Axum HTTPS service that brokers between
4//! `manta-cli` clients and the per-site backend implementations (CSM
5//! via `csm-rs`, OpenCHAMI via `ochami-rs`). Requests arrive at the
6//! [`server`] module's handlers, which delegate to the [`service`]
7//! layer, which in turn dispatches to the chosen backend through
8//! [`dispatcher::StaticBackendDispatcher`] and the trait impls under
9//! [`backend_dispatcher`].
10//!
11//! # Layering
12//!
13//! The crate enforces a strict three-tier shape (see `CLAUDE.md` for
14//! the canonical statement of the rule):
15//!
16//! 1. **HTTP layer** — [`server`]: Axum handlers, routing, middleware,
17//! request/response wire types. Handlers MUST only call functions
18//! in [`service`] (or shared helpers in `manta-shared`), never the
19//! backend directly.
20//! 2. **Service layer** — [`service`]: pure business logic + access
21//! control, parameterised on a borrowed `InfraContext<'_>`. All
22//! fallible paths return [`manta_backend_dispatcher::error::Error`].
23//! 3. **Backend layer** — [`dispatcher`] + [`backend_dispatcher`]:
24//! the `StaticBackendDispatcher` enum routes each trait method to
25//! the active CSM or OCHAMI backend.
26//!
27//! [`wire_conv`] sits at the service boundary and maps the
28//! `MantaError` produced by `manta-shared` helpers onto the structured
29//! `BackendError` the service layer uses.
30//!
31//! # Configuration
32//!
33//! Server-side configuration lives in [`config::ServerConfiguration`]
34//! and is loaded once at startup from `~/.config/manta/server.toml`.
35//! Each request carries an `X-Manta-Site` header that picks which
36//! configured site's backend to dispatch through.
37//!
38//! # Entry points
39//!
40//! The `main.rs` binary is a thin bootstrap shim that loads config,
41//! constructs the per-site backends, and hands off to the router built
42//! in [`server`]. Integration tests under `crates/manta-server/tests/`
43//! import the library directly via `use manta_server::...`.
44
45// Warn (not deny) on undocumented pub items. The server isn't
46// docs.rs-bound (publish = false), so the goal here is contributor
47// onboarding rather than a public API contract. CI still surfaces
48// these warnings via the rustdoc build step.
49#![warn(missing_docs)]
50
51pub mod backend_dispatcher;
52pub mod config;
53pub mod dispatcher;
54pub mod server;
55pub mod service;
56pub mod wire_conv;