stateset_http/lib.rs
1#![deny(unsafe_code)]
2#![cfg_attr(not(test), deny(clippy::unwrap_used))]
3#![cfg_attr(not(test), warn(unused_crate_dependencies))]
4#![cfg_attr(docsrs, feature(doc_cfg))]
5#![doc(
6 html_logo_url = "https://raw.githubusercontent.com/stateset/stateset-icommerce/main/assets/stateset.png",
7 html_favicon_url = "https://raw.githubusercontent.com/stateset/stateset-icommerce/main/assets/favicon.ico",
8 issue_tracker_base_url = "https://github.com/stateset/stateset-icommerce/issues/"
9)]
10
11//! # StateSet HTTP
12//!
13//! HTTP service layer (REST + SSE) for the StateSet embedded commerce engine.
14//!
15//! Turns [`stateset_embedded::Commerce`] into a real HTTP API powered by
16//! [`axum`], complete with JSON endpoints, pagination, Server-Sent Events,
17//! CORS, request-ID tracing, and structured error responses.
18//!
19//! ## Quick Start
20//!
21//! ```rust,ignore
22//! use stateset_embedded::Commerce;
23//! use stateset_http::ServerBuilder;
24//! use std::net::SocketAddr;
25//!
26//! let commerce = Commerce::new(":memory:")?;
27//! let addr: SocketAddr = "0.0.0.0:3000".parse()?;
28//!
29//! ServerBuilder::new_from_env(commerce)?
30//! .bind(addr)
31//! .with_cors()
32//! .with_request_id()
33//! .with_bearer_auth("replace-me-with-a-secret")
34//! .serve()
35//! .await?;
36//! ```
37//!
38//! ## Architecture
39//!
40//! ```text
41//! ┌────────────────────────────────────────────────┐
42//! │ HTTP Client │
43//! │ ┌──────────────────────────────────────────┐ │
44//! │ │ axum Router (this crate) │ │
45//! │ │ ┌────────────────────────────────────┐ │ │
46//! │ │ │ stateset-embedded (Commerce) │ │ │
47//! │ │ │ ┌──────────────────────────────┐ │ │ │
48//! │ │ │ │ SQLite / PostgreSQL │ │ │ │
49//! │ │ │ └──────────────────────────────┘ │ │ │
50//! │ │ └────────────────────────────────────┘ │ │
51//! │ └──────────────────────────────────────────┘ │
52//! └────────────────────────────────────────────────┘
53//! ```
54
55mod dto;
56mod error;
57pub mod etag;
58mod events_replay;
59mod idempotency;
60mod middleware;
61pub mod openapi;
62pub mod routes;
63mod server;
64mod state;
65
66pub use dto::*;
67pub use error::HttpError;
68pub use server::ServerBuilder;
69pub use state::{AppState, IpCidr, MetricsHeaderLimits};
70
71// Re-export the router assembly function for users who want to embed the
72// routes in a larger application.
73pub use routes::api_router;
74
75use http as _;
76use tower as _;
77
78/// Compiles the code examples in `README.md` as doctests, so the crates.io
79/// landing page can never drift from the real API.
80#[cfg(doctest)]
81#[doc = include_str!("../README.md")]
82struct ReadmeDoctests;