arcature 2026.0.0

//! Arcature — one full-stack web framework over the certified Rust ecosystem.
//!
//! Arcature is a high-level application framework that composes the certified
//! Arcature subsystem crates (Inertia, database, auth, cache, storage, mail,
//! jobs, pages, observability, API) behind a single facade, while preserving a
//! guaranteed escape hatch down to the raw Axum/Tower/Tokio ecosystem
//! underneath.
//!
//! # Getting started
//!
//! A normal application depends on the `arcature` crate with the capabilities
//! it needs, and drives the framework through [`Application`]. The simplest
//! stateless app — compiles with no features beyond the kernel:
//!
//! ```no_run
//! use arcature::prelude::*;
//!
//! async fn hello() -> &'static str {
//!     "hello"
//! }
//!
//! # // `serve` is generic over `axum::serve::Listener`; an expert user brings
//! # // their own runtime. The `macros` feature's `run()` helper binds a
//! # // TcpListener for the common case (shown in the ignore block below).
//! ```
//!
//! With the `macros` feature, `#[arcature::main]` and `Application::run()`
//! remove the need for a direct `tokio` dependency:
//!
//! ```ignore
//! use arcature::prelude::*;
//!
//! async fn hello() -> &'static str {
//!     "hello"
//! }
//!
//! #[arcature::main]
//! async fn main() -> Result<()> {
//!     Application::new()
//!         .routes(Routes::new().route("/", get(hello)))
//!         .run()
//!         .await
//! }
//! ```
//!
//! `Application` is the high-level composition root: it owns framework
//! lifecycle, request-pipeline assembly, and subsystem coordination. It sits
//! *above* the low-level [`App`] kernel, which remains the raw Axum-compatible
//! seam for expert use.
//!
//! # The two layers
//!
//! ```text
//! Application   — high-level framework facade (lifecycle, composition)
//!     |
//! App<S>        — low-level HTTP kernel (raw Axum/Tower interop)
//!     |
//! Axum / Tower  — the upstream ecosystem
//! ```
//!
//! - **[`Application`]** — the normal user entry point. Owns routing
//!   assembly, the request pipeline (pre-routing proxy, post-routing
//!   middleware, fallback pages), and — when subsystem features are enabled —
//!   deterministic startup and graceful shutdown of database, cache, storage,
//!   mail, jobs, and observability.
//! - **[`App`]** — the low-level HTTP kernel. A thin wrapper over
//!   [`axum::Router`] that forwards to `axum::serve`. Use it directly when you
//!   want raw Axum/Tower with no framework opinions.
//!
//! # Features
//!
//! The facade re-exports each certified subsystem behind a Cargo feature, so a
//! minimal application pulls no heavyweight runtime:
//!
//! ```toml
//! [dependencies]
//! arcature = { version = "2026.0.0", features = ["inertia", "db", "pages", "observe"] }
//! ```
//!
//! `default = []` keeps the bare HTTP kernel. `fullstack` enables every runtime
//! subsystem (but never auto-connects to a service — features are compile-time
//! capabilities, not runtime permission). See the crate `Cargo.toml` for the
//! full feature graph.
//!
//! # Advanced: the raw escape hatch
//!
//! Arcature hides complexity without hiding capability. Expert code can still
//! reach Axum, Tower, and every subsystem crate directly:
//!
//! ```no_run
//! use arcature::App;
//! use arcature::axum::routing::get;
//! use arcature::axum::Router;
//!
//! async fn hello() -> &'static str { "hello" }
//!
//! // Build a raw Axum router, wrap it in the kernel, serve it.
//! # #[tokio::main] async fn main() -> std::io::Result<()> {
//! let router: Router = Router::new().route("/", get(hello));
//! # let _ = router;
//! # Ok(()) }
//! ```
//!
//! [`axum::Router`] is re-exported as [`axum`] so downstream code targets the
//! certified version through Arcature. Use [`App::into_router`] /
//! [`App::from_router`] to move between the kernel and a raw router.
//!
//! [Axum]: https://docs.rs/axum

#![forbid(unsafe_code)]
#![doc(html_root_url = "https://docs.rs/arcature")]

// Re-export the certified `axum` crate so downstream code uses the escape
// hatch through Arcature's pinned dependency (e.g. `arcature::axum::routing`).
pub use axum;

// Low-level HTTP kernel (Phase 1) — the raw Axum/Tower seam.
mod app;
mod server;

// High-level Application engine (engine phase) — the composition root.
mod application;
mod facade;
mod pipeline;
pub mod proxy;
mod routing;

// The curated prelude is a public module so applications write
// `use arcature::prelude::*;` (engine spec §19).
pub mod prelude;

pub use app::App;
pub use application::Application;
pub use application::ApplicationBuilder;
pub use application::EngineError;
pub use application::ProxyFn;
pub use application::Result;
// `Resources` is the typed handle bundle passed to the `state_fn` closure of
// `run_with_lifecycle` / `serve_with_lifecycle`. It is re-exported at the
// crate root so application code can name the type (e.g. in helper function
// signatures). Only available when the `macros` feature + at least one
// lifecycle subsystem is enabled.
#[cfg(all(
    feature = "macros",
    any(
        feature = "db",
        feature = "cache",
        feature = "storage",
        feature = "mail",
        feature = "jobs"
    )
))]
#[allow(unused_imports)]
pub use application::Resources;
pub use routing::Routes;

// Facade modules — namespaced re-exports of the certified subsystem crates.
// `facade` is private; its `pub mod` children are re-exported at the crate
// root so a normal application reaches them as `arcature::inertia`,
// `arcature::db`, etc. Each re-export is feature-gated so only enabled
// subsystems appear on the public surface, and no `pub use` fires under
// `--no-default-features` (engine spec §18/§34/§55). Explicit per-feature
// re-exports (rather than a glob) keep the public surface auditable.
#[cfg(feature = "api")]
pub use facade::api;
#[cfg(feature = "auth")]
pub use facade::auth;
#[cfg(feature = "cache")]
pub use facade::cache;
#[cfg(feature = "db")]
pub use facade::db;
#[cfg(feature = "inertia")]
pub use facade::inertia;
#[cfg(feature = "jobs")]
pub use facade::jobs;
#[cfg(feature = "mail")]
pub use facade::mail;
#[cfg(feature = "observe")]
pub use facade::observe;
#[cfg(feature = "pages")]
pub use facade::pages;
#[cfg(feature = "storage")]
pub use facade::storage;

// `#[arcature::main]` re-exports the certified Tokio multi-thread runtime macro
// so a normal application needs no direct `tokio` dependency merely for
// `#[tokio::main]` (engine spec §23). Expert users may still bring their own
// runtime and call the async `Application::serve` / `App::serve` APIs without
// this feature.
#[cfg(feature = "macros")]
pub use tokio::main;