use std::sync::Arc;
use axum::Router;
use axum::extract::{Request, State};
use axum::http::{HeaderMap, HeaderValue, Method, StatusCode, Uri, header};
use axum::middleware::{self, Next};
#[cfg(feature = "demo")]
use axum::response::Html;
use axum::response::{IntoResponse, Json, Response};
use axum::routing::{MethodRouter, any};
use serde::Serialize;
use serde_json::{Map, Value};
use crate::auth::Authenticate;
#[cfg(feature = "demo")]
use crate::auth::{Basic, Bearer};
#[cfg(feature = "demo")]
use crate::catalogue::Catalogue;
#[cfg(feature = "demo")]
use crate::config::ServeConfig;
#[cfg(feature = "demo")]
use crate::operation::Principal;
use crate::operation::{Args, InvalidDeclaration, OpError, Operation, Param};
#[cfg(feature = "demo")]
use crate::site::Site;
pub const MAX_TARGET_BYTES: usize = 2048;
pub const DEFAULT_HTML_CSP: &str = "default-src 'none'; style-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'";
#[cfg(feature = "demo")]
const SITE_CSP: &str = "default-src 'none'; style-src 'self'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'";
const STYLESHEET_PATH: &str = "/_senu/ui.css";
const STYLESHEET: &str = include_str!("../assets/ui.generated.css");
pub struct AppState<S> {
state: S,
html: Option<Arc<dyn Authenticate>>,
api: Option<Arc<dyn Authenticate>>,
html_csp: HeaderValue,
}
impl<S> std::fmt::Debug for AppState<S> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("AppState")
.field("html_auth", &self.html.is_some())
.field("api_auth", &self.api.is_some())
.finish_non_exhaustive()
}
}
pub struct AppStateBuilder<S> {
app: AppState<S>,
}
impl<S> AppStateBuilder<S> {
pub fn html_auth(mut self, authenticator: impl Authenticate) -> Self {
self.app.html = Some(Arc::new(authenticator));
self
}
pub fn api_auth(mut self, authenticator: impl Authenticate) -> Self {
self.app.api = Some(Arc::new(authenticator));
self
}
pub fn build(self) -> AppState<S> {
self.app
}
}
#[cfg(feature = "demo")]
impl AppState<Catalogue> {
pub fn new(catalogue: Catalogue, config: &ServeConfig) -> Self {
Self::with_principals(
catalogue,
config,
Principal::demo_web(),
Principal::demo_api(),
)
}
}
impl<S> AppState<S> {
pub fn builder(state: S) -> AppStateBuilder<S> {
AppStateBuilder {
app: Self {
state,
html: None,
api: None,
html_csp: HeaderValue::from_static(DEFAULT_HTML_CSP),
},
}
}
#[cfg(feature = "demo")]
#[cfg_attr(docsrs, doc(cfg(feature = "demo")))]
pub fn with_principals(
state: S,
config: &ServeConfig,
web_principal: Principal,
api_principal: Principal,
) -> Self {
Self::builder(state)
.html_auth(Basic::new(
config.web_user.clone(),
config.web_password.clone(),
web_principal,
))
.api_auth(Bearer::new(config.api_token.clone(), api_principal))
.build()
}
pub fn state(&self) -> &S {
&self.state
}
fn authenticator(&self, surface: Surface) -> Option<&Arc<dyn Authenticate>> {
match surface {
Surface::Html => self.html.as_ref(),
Surface::Api => self.api.as_ref(),
}
}
}
pub type Shared<S> = Arc<AppState<S>>;
#[cfg(feature = "demo")]
#[cfg_attr(docsrs, doc(cfg(feature = "demo")))]
pub fn router(state: AppState<Catalogue>) -> Router {
crate::demo::endpoints()
.into_router(state)
.expect("the demo's route table is valid")
}
pub type View<T> = fn(&Args, &T) -> Result<String, askama::Error>;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Kind {
Html,
Api,
Custom,
Asset,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Declared {
pub path: &'static str,
pub kind: Kind,
pub operation: Option<&'static str>,
pub params: &'static [Param],
}
pub struct Endpoints<S> {
routes: Vec<Route<S>>,
html_csp: &'static str,
}
struct Route<S> {
declared: Declared,
invalid: Option<InvalidDeclaration>,
content_type: Option<&'static str>,
handler: MethodRouter<Shared<S>>,
}
impl<S: Send + Sync + 'static> Default for Endpoints<S> {
fn default() -> Self {
Self::new()
}
}
impl<S: Send + Sync + 'static> Endpoints<S> {
pub fn new() -> Self {
Self {
routes: Vec::new(),
html_csp: DEFAULT_HTML_CSP,
}
}
pub fn html<T: Send + 'static>(
self,
path: &'static str,
operation: &'static Operation<S, T>,
view: View<T>,
) -> Self {
let handler = move |State(app): State<Shared<S>>,
method: Method,
uri: Uri,
headers: HeaderMap| async move {
html_route(&app, &method, &uri, &headers, operation, view).await
};
self.push(path, Kind::Html, operation, any(handler))
}
pub fn api<T: Serialize + Send + 'static>(
self,
path: &'static str,
operation: &'static Operation<S, T>,
) -> Self {
let handler = move |State(app): State<Shared<S>>,
method: Method,
uri: Uri,
headers: HeaderMap| async move {
api_route(&app, &method, &uri, &headers, operation).await
};
self.push(path, Kind::Api, operation, any(handler))
}
pub fn asset(
mut self,
path: &'static str,
content_type: &'static str,
body: &'static [u8],
) -> Self {
let handler = move |method: Method| async move {
if method != Method::GET {
return Surface::Html.error(HttpError::MethodNotAllowed);
}
match HeaderValue::from_str(content_type) {
Ok(content_type) => ([(header::CONTENT_TYPE, content_type)], body).into_response(),
Err(_) => Surface::Html.error(HttpError::Internal),
}
};
self.routes.push(Route {
declared: Declared {
path,
kind: Kind::Asset,
operation: None,
params: &[],
},
invalid: None,
content_type: Some(content_type),
handler: any(handler),
});
self
}
pub fn html_csp(mut self, policy: &'static str) -> Self {
self.html_csp = policy;
self
}
pub fn custom(mut self, path: &'static str, handler: MethodRouter<Shared<S>>) -> Self {
self.routes.push(Route {
declared: Declared {
path,
kind: Kind::Custom,
operation: None,
params: &[],
},
invalid: None,
content_type: None,
handler,
});
self
}
fn push<T>(
mut self,
path: &'static str,
kind: Kind,
operation: &'static Operation<S, T>,
handler: MethodRouter<Shared<S>>,
) -> Self {
self.routes.push(Route {
declared: Declared {
path,
kind,
operation: Some(operation.name),
params: operation.params,
},
invalid: operation.check().err(),
content_type: None,
handler,
});
self
}
pub fn csp(&self) -> &'static str {
self.html_csp
}
pub fn declared(&self) -> Vec<Declared> {
self.routes.iter().map(|route| route.declared).collect()
}
pub fn into_router(self, mut state: AppState<S>) -> Result<Router, RouteError> {
self.check(&state)?;
state.html_csp =
HeaderValue::from_str(self.html_csp).map_err(|_| RouteError::InvalidCsp)?;
let mut router = Router::new();
for route in self.routes {
router = router.route(route.declared.path, route.handler);
}
Ok(router
.route(STYLESHEET_PATH, any(stylesheet))
.fallback(not_found)
.with_state(Arc::new(state))
.layer(middleware::from_fn(limits))
.layer(middleware::from_fn(response_headers)))
}
fn check(&self, state: &AppState<S>) -> Result<(), RouteError> {
let visible = |text: &str| text.bytes().all(|b| b == b' ' || b.is_ascii_graphic());
if self.html_csp.trim().is_empty() || !visible(self.html_csp) {
return Err(RouteError::InvalidCsp);
}
for (i, route) in self.routes.iter().enumerate() {
let Declared { path, kind, .. } = route.declared;
if !is_exact_path(path) {
return Err(RouteError::InvalidPath(path));
}
if path == "/_senu" || path.starts_with("/_senu/") {
return Err(RouteError::Reserved(path));
}
let wrong_prefix = match kind {
Kind::Api => !path.starts_with("/api/"),
Kind::Html | Kind::Asset => Surface::for_path(path) == Surface::Api,
Kind::Custom => false,
};
if wrong_prefix {
return Err(RouteError::WrongPrefix(path));
}
if self.routes[..i].iter().any(|r| r.declared.path == path) {
return Err(RouteError::Duplicate(path));
}
if let Some(invalid) = route.invalid {
return Err(RouteError::Operation(invalid));
}
let unguarded = match kind {
Kind::Html => state.html.is_none(),
Kind::Api => state.api.is_none(),
Kind::Custom | Kind::Asset => false,
};
if unguarded {
return Err(RouteError::NoAuthenticator(path));
}
if let Some(content_type) = route.content_type
&& (content_type.trim().is_empty() || !visible(content_type))
{
return Err(RouteError::InvalidAsset(path));
}
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum RouteError {
InvalidPath(&'static str),
Reserved(&'static str),
WrongPrefix(&'static str),
Duplicate(&'static str),
Operation(InvalidDeclaration),
NoAuthenticator(&'static str),
InvalidAsset(&'static str),
InvalidCsp,
}
impl std::fmt::Display for RouteError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::InvalidPath(path) => write!(f, "senu: route {path:?} is not an exact path"),
Self::Reserved(path) => write!(f, "senu: route {path:?} is reserved for Senu"),
Self::WrongPrefix(path) => write!(
f,
"senu: route {path:?}: API routes must be under /api/ and HTML routes must not"
),
Self::Duplicate(path) => write!(f, "senu: route {path:?} is listed twice"),
Self::Operation(invalid) => write!(f, "senu: {invalid}"),
Self::NoAuthenticator(path) => write!(
f,
"senu: route {path:?} has no authenticator; set html_auth or api_auth on the AppState"
),
Self::InvalidAsset(path) => {
write!(f, "senu: asset {path:?} has an invalid content type")
}
Self::InvalidCsp => {
f.write_str("senu: the HTML Content-Security-Policy is empty or not visible ASCII")
}
}
}
}
impl std::error::Error for RouteError {}
fn is_exact_path(path: &str) -> bool {
path.starts_with('/')
&& path
.bytes()
.all(|b| b.is_ascii_graphic() && !b"{}*?#%\\".contains(&b))
&& path
.split('/')
.all(|segment| segment != "." && segment != ".." && !segment.starts_with(':'))
}
#[cfg(feature = "demo")]
#[cfg_attr(docsrs, doc(cfg(feature = "demo")))]
pub fn site_router(site: Site) -> Router {
Router::new()
.route(STYLESHEET_PATH, any(stylesheet))
.fallback(site_page)
.with_state(Arc::new(site))
.layer(middleware::from_fn(site_limits))
.layer(middleware::from_fn(response_headers))
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum HttpError {
Unauthorized,
Forbidden,
InvalidRequest,
NotFound,
MethodNotAllowed,
UriTooLong,
PayloadTooLarge,
Internal,
Invalid {
code: &'static str,
phrase: &'static str,
},
}
impl HttpError {
pub fn status(self) -> StatusCode {
match self {
Self::Unauthorized => StatusCode::UNAUTHORIZED,
Self::Forbidden => StatusCode::FORBIDDEN,
Self::InvalidRequest | Self::Invalid { .. } => StatusCode::BAD_REQUEST,
Self::NotFound => StatusCode::NOT_FOUND,
Self::MethodNotAllowed => StatusCode::METHOD_NOT_ALLOWED,
Self::UriTooLong => StatusCode::URI_TOO_LONG,
Self::PayloadTooLarge => StatusCode::PAYLOAD_TOO_LARGE,
Self::Internal => StatusCode::INTERNAL_SERVER_ERROR,
}
}
pub fn code(self) -> &'static str {
match self {
Self::Unauthorized => "unauthorized",
Self::Forbidden => "forbidden",
Self::InvalidRequest => "invalid_request",
Self::NotFound => "not_found",
Self::MethodNotAllowed => "method_not_allowed",
Self::UriTooLong => "uri_too_long",
Self::PayloadTooLarge => "payload_too_large",
Self::Internal => "internal",
Self::Invalid { code, .. } => code,
}
}
pub fn phrase(self) -> &'static str {
match self {
Self::Unauthorized => "Unauthorized",
Self::Forbidden => "Forbidden",
Self::InvalidRequest => "Invalid request",
Self::NotFound => "Not Found",
Self::MethodNotAllowed => "Method Not Allowed",
Self::UriTooLong => "URI Too Long",
Self::PayloadTooLarge => "Payload Too Large",
Self::Internal => "Internal Server Error",
Self::Invalid { phrase, .. } => phrase,
}
}
}
impl From<OpError> for HttpError {
fn from(err: OpError) -> Self {
match err {
OpError::Forbidden => Self::Forbidden,
OpError::InvalidRequest => Self::InvalidRequest,
OpError::NotFound => Self::NotFound,
OpError::Internal => Self::Internal,
OpError::Invalid { code, phrase } => Self::Invalid { code, phrase },
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Surface {
Api,
Html,
}
impl Surface {
fn for_path(path: &str) -> Self {
if path == "/api" || path.starts_with("/api/") {
Self::Api
} else {
Self::Html
}
}
fn error(self, err: HttpError) -> Response {
let mut response = match self {
Self::Api => (
err.status(),
Json(serde_json::json!({ "error": err.code() })),
)
.into_response(),
Self::Html => (
err.status(),
[(header::CONTENT_TYPE, "text/plain; charset=utf-8")],
err.phrase(),
)
.into_response(),
};
if err == HttpError::MethodNotAllowed {
response
.headers_mut()
.insert(header::ALLOW, HeaderValue::from_static("GET"));
}
response
}
fn unauthorized(self, challenge: HeaderValue) -> Response {
let mut response = self.error(HttpError::Unauthorized);
response
.headers_mut()
.insert(header::WWW_AUTHENTICATE, challenge);
response
}
}
async fn run_route<S, T>(
app: &AppState<S>,
surface: Surface,
method: &Method,
uri: &Uri,
headers: &HeaderMap,
operation: &Operation<S, T>,
) -> Result<(Args, T), Box<Response>> {
if method != Method::GET {
return Err(Box::new(surface.error(HttpError::MethodNotAllowed)));
}
let Some(authenticator) = app.authenticator(surface) else {
return Err(Box::new(surface.error(HttpError::Internal)));
};
let Some(principal) = authenticator.authenticate(headers).await else {
return Err(Box::new(surface.unauthorized(authenticator.challenge())));
};
let args = query_arguments(uri.query());
match operation.call(&app.state, &principal, &args).await {
Ok(result) => Ok((args, result)),
Err(err) => Err(Box::new(surface.error(err.into()))),
}
}
async fn api_route<S, T: Serialize>(
app: &AppState<S>,
method: &Method,
uri: &Uri,
headers: &HeaderMap,
operation: &Operation<S, T>,
) -> Response {
match run_route(app, Surface::Api, method, uri, headers, operation).await {
Ok((_args, result)) => Json(result).into_response(),
Err(response) => *response,
}
}
async fn html_route<S, T>(
app: &AppState<S>,
method: &Method,
uri: &Uri,
headers: &HeaderMap,
operation: &Operation<S, T>,
view: View<T>,
) -> Response {
let (args, result) = match run_route(app, Surface::Html, method, uri, headers, operation).await
{
Ok(done) => done,
Err(response) => return *response,
};
match view(&args, &result) {
Ok(page) => (
[
(header::CONTENT_SECURITY_POLICY, app.html_csp.clone()),
(
header::CONTENT_TYPE,
HeaderValue::from_static("text/html; charset=utf-8"),
),
],
page,
)
.into_response(),
Err(_) => Surface::Html.error(HttpError::Internal),
}
}
#[cfg(feature = "demo")]
async fn site_page(State(site): State<Arc<Site>>, request: Request) -> Response {
let Some(page) = site.page(request.uri().path()) else {
return Surface::Html.error(HttpError::NotFound);
};
if request.method() != Method::GET {
return Surface::Html.error(HttpError::MethodNotAllowed);
}
(
[(header::CONTENT_SECURITY_POLICY, SITE_CSP)],
Html(page.to_owned()),
)
.into_response()
}
async fn stylesheet(method: Method) -> Response {
if method != Method::GET {
return Surface::Html.error(HttpError::MethodNotAllowed);
}
(
[(header::CONTENT_TYPE, "text/css; charset=utf-8")],
STYLESHEET,
)
.into_response()
}
async fn not_found(uri: Uri) -> Response {
Surface::for_path(uri.path()).error(HttpError::NotFound)
}
async fn limits(request: Request, next: Next) -> Response {
match over_limits(&request) {
Some(err) => Surface::for_path(request.uri().path()).error(err),
None => next.run(request).await,
}
}
#[cfg(feature = "demo")]
async fn site_limits(request: Request, next: Next) -> Response {
match over_limits(&request) {
Some(err) => Surface::Html.error(err),
None => next.run(request).await,
}
}
fn over_limits(request: &Request) -> Option<HttpError> {
let target = request
.uri()
.path_and_query()
.map_or(0, |target| target.as_str().len());
if target > MAX_TARGET_BYTES {
Some(HttpError::UriTooLong)
} else if has_body(request.headers()) {
Some(HttpError::PayloadTooLarge)
} else {
None
}
}
async fn response_headers(request: Request, next: Next) -> Response {
let mut response = next.run(request).await;
let headers = response.headers_mut();
headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
headers.insert(
header::X_CONTENT_TYPE_OPTIONS,
HeaderValue::from_static("nosniff"),
);
response
}
fn has_body(headers: &HeaderMap) -> bool {
headers.contains_key(header::TRANSFER_ENCODING)
|| headers
.get_all(header::CONTENT_LENGTH)
.iter()
.any(|length| !is_decimal_zero(length.as_bytes()))
}
fn is_decimal_zero(value: &[u8]) -> bool {
!value.is_empty() && value.iter().all(|&byte| byte == b'0')
}
pub fn query_arguments(query: Option<&str>) -> Map<String, Value> {
let mut args = Map::new();
for (key, value) in form_urlencoded::parse(query.unwrap_or("").as_bytes()) {
let value = Value::String(value.into_owned());
match args.get_mut(key.as_ref()) {
None => {
args.insert(key.into_owned(), value);
}
Some(Value::Array(values)) => values.push(value),
Some(existing) => {
let first = existing.take();
*existing = Value::Array(vec![first, value]);
}
}
}
args
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn query_arguments_decode_plus_and_percent_escapes() {
assert_eq!(
Value::Object(query_arguments(Some("q=caf%C3%A9+roadmap"))),
json!({"q": "café roadmap"})
);
}
#[test]
fn query_arguments_turn_repeated_keys_into_arrays() {
assert_eq!(
Value::Object(query_arguments(Some("q=a&q=b&q=c"))),
json!({"q": ["a", "b", "c"]})
);
}
#[test]
fn query_arguments_keep_unknown_keys_for_the_operation_to_reject() {
assert_eq!(
Value::Object(query_arguments(Some("tenant=globex&q"))),
json!({"tenant": "globex", "q": ""})
);
assert!(query_arguments(None).is_empty());
assert!(query_arguments(Some("")).is_empty());
}
#[test]
fn query_arguments_replace_invalid_utf8() {
assert_eq!(
Value::Object(query_arguments(Some("q=%FF"))),
json!({"q": "\u{FFFD}"})
);
}
#[test]
fn errors_map_to_spec_status_codes() {
let table = [
(HttpError::Unauthorized, 401, "unauthorized"),
(HttpError::Forbidden, 403, "forbidden"),
(HttpError::InvalidRequest, 400, "invalid_request"),
(HttpError::NotFound, 404, "not_found"),
(HttpError::MethodNotAllowed, 405, "method_not_allowed"),
(HttpError::UriTooLong, 414, "uri_too_long"),
(HttpError::PayloadTooLarge, 413, "payload_too_large"),
(HttpError::Internal, 500, "internal"),
];
for (err, status, code) in table {
assert_eq!(err.status().as_u16(), status);
assert_eq!(err.code(), code);
assert!(!err.phrase().is_empty());
}
}
#[test]
fn operation_errors_keep_their_codes() {
for err in [
OpError::Forbidden,
OpError::InvalidRequest,
OpError::NotFound,
OpError::Internal,
OpError::Invalid {
code: "invalid_sku",
phrase: "Invalid SKU",
},
] {
assert_eq!(HttpError::from(err).code(), err.code());
}
assert_eq!(HttpError::from(OpError::Internal).status().as_u16(), 500);
}
#[cfg(feature = "demo")]
#[test]
fn the_demo_errors_keep_their_codes_as_constants() {
assert_eq!(HttpError::InvalidSearch.status().as_u16(), 400);
assert_eq!(HttpError::InvalidSearch.code(), "invalid_search");
assert_eq!(HttpError::InvalidSearch.phrase(), "Invalid search");
assert_eq!(
HttpError::from(OpError::InvalidSearch),
HttpError::InvalidSearch
);
}
#[cfg(feature = "demo")]
#[test]
fn get_project_errors_keep_their_codes_and_statuses() {
assert_eq!(HttpError::InvalidId.status().as_u16(), 400);
assert_eq!(HttpError::InvalidId.code(), "invalid_id");
assert_eq!(HttpError::InvalidId.phrase(), "Invalid id");
for (err, status) in [(OpError::InvalidId, 400), (OpError::NotFound, 404)] {
assert_eq!(HttpError::from(err).code(), err.code());
assert_eq!(HttpError::from(err).status().as_u16(), status);
}
}
#[test]
fn api_surface_covers_the_api_prefix_only() {
assert_eq!(Surface::for_path("/api/projects"), Surface::Api);
assert_eq!(Surface::for_path("/api"), Surface::Api);
assert_eq!(Surface::for_path("/api/"), Surface::Api);
assert_eq!(Surface::for_path("/apiary"), Surface::Html);
assert_eq!(Surface::for_path("/projects"), Surface::Html);
}
#[test]
fn body_detection_treats_zero_length_as_no_body() {
let mut headers = HeaderMap::new();
assert!(!has_body(&headers));
headers.insert(header::CONTENT_LENGTH, HeaderValue::from_static("0"));
assert!(!has_body(&headers));
headers.insert(header::CONTENT_LENGTH, HeaderValue::from_static("1"));
assert!(has_body(&headers));
let mut chunked = HeaderMap::new();
chunked.insert(
header::TRANSFER_ENCODING,
HeaderValue::from_static("chunked"),
);
assert!(has_body(&chunked));
}
#[test]
fn body_detection_accepts_any_decimal_spelling_of_zero() {
let lengths = |values: &[&'static str]| {
let mut headers = HeaderMap::new();
for value in values {
headers.append(header::CONTENT_LENGTH, HeaderValue::from_static(value));
}
headers
};
for zero in [&["00"][..], &["000"], &["0", "00"]] {
assert!(!has_body(&lengths(zero)), "{zero:?}");
}
for other in [
&["01"][..],
&["10"],
&["0", "1"],
&[""],
&[" 0"],
&["+0"],
&["-0"],
&["0x0"],
&["0, 0"],
] {
assert!(has_body(&lengths(other)), "{other:?}");
}
}
}