use std::sync::Arc;
use axum::{Json, Router, response::Html, routing::get};
use che_orm::{Migration, MigrationError, ProjectState, SchemaObjectState, SchemaSet, StateChange};
use serde_json::{Map, Value, json};
use crate::{
AppError, AppResult, AppState, CrudViewSet, FilterSetSpec, Model, ModelSerializer, Permission,
SignalAccess, ViewAction, ViewSet, ViewSetConfig, openapi_column_schema,
};
pub trait AppModule: Send + Sync + 'static {
fn name(&self) -> &'static str;
fn schema(&self) -> SchemaSet;
fn migrations(&self) -> Vec<Migration> {
Vec::new()
}
fn migration_path(&self) -> Option<&'static str> {
None
}
fn sync_registry(&self) -> Option<che_sync::Registry> {
None
}
fn schema_objects(&self) -> Vec<SchemaObjectState> {
Vec::new()
}
fn init(&self, context: &mut ModuleContext);
fn subscribe(&self, _state: &AppState) {}
fn start(&self, _state: &AppState) {}
fn middleware(&self, router: Router, _state: &AppState) -> Router {
router
}
fn openapi(&self, _state: &AppState) -> Value {
json!({})
}
}
#[derive(Debug, Clone)]
pub struct ApiEndpoint {
pub crud: bool,
pub app_name: &'static str,
pub model_name: String,
pub resource: String,
pub fields: Vec<che_orm::SerializerField>,
pub list_fields: Vec<che_orm::SerializerField>,
pub columns: Vec<ApiColumn>,
pub filters: Vec<ApiFilter>,
pub extensions: Vec<crate::ApiExtension>,
}
#[derive(Debug, Clone)]
pub struct ApiSignal {
pub name: String,
pub access: SignalAccess,
}
#[derive(Debug, Clone)]
pub struct ApiColumn {
pub name: &'static str,
pub field_name: &'static str,
pub column_type: che_orm::ColumnType,
pub nullable: bool,
pub has_default: bool,
pub choices: Option<Vec<&'static str>>,
}
#[derive(Debug, Clone, Copy)]
pub struct ApiFilter {
pub name: &'static str,
pub source: &'static str,
pub lookup: crate::Lookup,
}
#[derive(Default)]
pub struct InstalledApps {
modules: Vec<Arc<dyn AppModule>>,
}
impl InstalledApps {
pub fn new() -> Self {
Self::default()
}
#[allow(clippy::should_implement_trait)]
pub fn add<M: AppModule>(mut self, module: M) -> Self {
self.modules.push(Arc::new(module));
self
}
pub fn iter(&self) -> impl Iterator<Item = &dyn AppModule> {
self.modules.iter().map(Arc::as_ref)
}
pub fn find(&self, name: &str) -> Option<&dyn AppModule> {
self.iter().find(|module| module.name() == name)
}
pub fn names(&self) -> impl Iterator<Item = &'static str> + '_ {
self.iter().map(AppModule::name)
}
pub fn migration_state(&self) -> Result<ProjectState, MigrationError> {
let schemas: Vec<_> = self
.iter()
.map(|module| (module.name(), module.schema()))
.collect();
let mut state =
ProjectState::from_app_schemas(schemas.iter().map(|(name, schema)| (*name, schema)))?;
for module in self.iter() {
if let Some(registry) = module.sync_registry() {
registry.extend_migration_state(&mut state, che_sync::SchemaRole::Server)?;
}
for mut object in module.schema_objects() {
object.app = module.name().into();
state.add_schema_object(object)?;
}
}
Ok(state)
}
pub fn migration_diff(
&self,
history: &ProjectState,
) -> Result<Vec<StateChange>, MigrationError> {
history.diff(&self.migration_state()?)
}
pub fn library_migrations(&self) -> Vec<Migration> {
self.iter().flat_map(AppModule::migrations).collect()
}
pub fn api_endpoints(&self, state: AppState) -> Vec<ApiEndpoint> {
let mut context = ModuleContext::new(state);
for module in self.iter() {
context.current_app = module.name();
module.init(&mut context);
}
context.api_endpoints
}
pub fn api_signals(&self, state: AppState) -> Vec<ApiSignal> {
let mut context = ModuleContext::new(state.clone());
for module in self.iter() {
context.current_app = module.name();
module.init(&mut context);
}
state
.signals()
.public_signals()
.into_iter()
.map(|(name, access)| ApiSignal { name, access })
.collect()
}
}
#[derive(Default)]
pub struct ModuleContext {
state: Option<AppState>,
routers: Vec<Router>,
root_routers: Vec<Router>,
schemas: Vec<SchemaSet>,
openapi_paths: Map<String, Value>,
openapi_components: Map<String, Value>,
api_endpoints: Vec<ApiEndpoint>,
registration_errors: Vec<String>,
access_models: std::collections::HashMap<&'static str, &'static str>,
media_access: crate::media::MediaAccess,
current_app: &'static str,
}
impl ModuleContext {
fn new(state: AppState) -> Self {
Self {
state: Some(state),
..Self::default()
}
}
pub fn route(&mut self, router: Router) {
self.routers.push(router);
}
pub fn actions<V: ViewSet>(&mut self, resource: &str, name: &str, config: ViewSetConfig<V>) {
let (router, extensions, schemas, _) = config.into_parts();
let document = crate::rest::extensions::extension_openapi(&extensions);
if let Some(paths) = document["paths"].as_object() {
self.openapi_paths.extend(paths.clone());
}
for schema in schemas {
self.openapi_components
.insert(schema.name.into(), schema.openapi);
}
self.api_endpoints.push(ApiEndpoint {
crud: false,
app_name: self.current_app,
model_name: name.into(),
resource: resource.into(),
fields: vec![],
list_fields: vec![],
columns: vec![],
filters: vec![],
extensions,
});
self.routers.push(router);
}
pub fn route_at_root(&mut self, router: Router) {
self.root_routers.push(router);
}
pub fn signal(&mut self, signal: impl Into<String>, access: SignalAccess) {
let state = self
.state
.as_ref()
.expect("module context is not initialized");
state.signals().declare(signal, access);
}
pub fn model<M: Model>(&mut self) {
self.schemas.push(SchemaSet::new().model::<M>());
}
pub fn viewset<M, S>(&mut self, viewset: CrudViewSet<M, S>)
where
M: Model<PrimaryKey: crate::rest::router::RestKey> + Send + Sync + 'static,
S: ModelSerializer<Model = M, Input = M>
+ che_orm::ModelWriteSerializer<Model = M>
+ serde::Serialize
+ Send
+ Sync
+ 'static,
{
self.viewset_with(viewset);
}
pub fn viewset_with<V>(&mut self, viewset: V)
where
V: ViewSet,
V::Serializer: serde::Serialize,
{
let path = viewset.path();
let permission = V::Permission::default();
if let Some(key) = permission.model_access_key()
&& let Some(previous) = self.access_models.insert(key, V::Model::table_name())
&& previous != V::Model::table_name()
{
self.registration_errors.push(format!(
"ACL model key {key} is already assigned to {previous}"
));
return;
}
if let Err(error) = permission
.validate(V::Serializer::fields())
.and_then(|_| permission.validate(V::ListSerializer::fields()))
{
self.registration_errors.push(error.to_string());
return;
}
if permission.object_scoped()
&& [
ViewAction::Create,
ViewAction::Update,
ViewAction::Patch,
ViewAction::Delete,
]
.iter()
.any(|action| viewset.signal_access(*action).is_some())
{
self.registration_errors.push("object permissions require recipient-aware signals; broad CRUD signals are not supported".into());
return;
}
let mut config = ViewSetConfig::<V>::new(path);
if let Err(error) = viewset.configure(&mut config) {
self.registration_errors.push(error.to_string());
}
let (extension_router, extensions, extension_schemas, hooks) = config.into_parts();
if permission.object_scoped()
&& hooks
.iter()
.filter_map(|hook| hook.backend())
.any(|backend| !backend.object_permissions())
{
self.registration_errors.push("object permissions require a transaction-aware mutation backend; the configured backend does not support this contract".into());
return;
}
self.api_endpoints.push(ApiEndpoint {
crud: true,
app_name: self.current_app,
model_name: std::any::type_name::<V::Model>()
.rsplit("::")
.next()
.unwrap_or("Model")
.to_owned(),
resource: path.trim_matches('/').to_owned(),
fields: V::Serializer::fields().to_vec(),
list_fields: V::ListSerializer::fields().to_vec(),
columns: V::Model::schema()
.columns
.iter()
.map(|column| ApiColumn {
name: column.name,
field_name: column.field_name,
column_type: column.column_type,
nullable: column.nullable,
has_default: column.default.is_some() || column.auto_now || column.auto_now_add,
choices: column.choices.clone(),
})
.collect(),
filters: V::FilterSet::default()
.filters()
.iter()
.map(|filter| ApiFilter {
name: filter.name,
source: filter.source(),
lookup: filter.lookup(),
})
.collect(),
extensions: extensions.clone(),
});
if let (Some(signal), Some(access)) = (
viewset.signal_name(ViewAction::Create),
viewset.signal_access(ViewAction::Create),
) {
self.signal(signal, access);
}
if let (Some(signal), Some(access)) = (
viewset.signal_name(ViewAction::Update),
viewset.signal_access(ViewAction::Update),
) {
self.signal(signal, access);
}
if let (Some(signal), Some(access)) = (
viewset.signal_name(ViewAction::Delete),
viewset.signal_access(ViewAction::Delete),
) {
self.signal(signal, access);
}
let state = self
.state
.as_ref()
.expect("module context is not initialized");
let document = crate::rest::router::openapi_json_for_with_list::<V::Model, V::Serializer>(
path,
V::ListSerializer::fields(),
);
let mut document = document;
if extensions.iter().any(|extension| extension.id == "sync") {
crate::sync::add_rest_openapi(&mut document);
}
if extensions
.iter()
.any(|extension| extension.id == "model-sync")
{
crate::sync::add_model_rest_openapi(&mut document);
}
if extensions
.iter()
.any(|extension| extension.id == "object-sync")
{
crate::sync::add_object_rest_openapi(&mut document);
}
add_filter_parameters::<V>(&mut document, &viewset);
let model_schema = V::Model::schema();
let primary_key = model_schema
.columns
.iter()
.find(|column| column.primary_key)
.expect("model primary key");
let extension_openapi = crate::rest::extensions::extension_openapi_with_id_schema(
&extensions,
crate::rest::router::openapi_column_schema(primary_key),
);
if let Some(action_paths) = extension_openapi.get("paths").and_then(Value::as_object)
&& let Some(paths) = document["paths"].as_object_mut()
{
for (path, item) in action_paths {
let target = paths.entry(path.clone()).or_insert_with(|| json!({}));
target
.as_object_mut()
.expect("OpenAPI path items are objects")
.extend(
item.as_object()
.expect("OpenAPI path item is an object")
.clone(),
);
}
}
if let Some(schemas) = document["components"]["schemas"].as_object_mut() {
for schema in extension_schemas {
if let Some(existing) = schemas.get(schema.name) {
if existing != &schema.openapi {
self.registration_errors
.push(format!("conflicting OpenAPI schema `{}`", schema.name));
}
} else {
schemas.insert(schema.name.to_owned(), schema.openapi);
}
}
}
if let Some(paths) = document["paths"].as_object() {
self.openapi_paths.extend(paths.clone());
}
if let Some(schemas) = document["components"]["schemas"].as_object() {
self.openapi_components.extend(schemas.clone());
}
self.routers.push(crate::rest::router::router_with_media(
state.clone(),
viewset,
extension_router,
hooks,
self.media_access.clone(),
));
}
fn schema(&self) -> SchemaSet {
self.schemas
.iter()
.cloned()
.fold(SchemaSet::new(), SchemaSet::merge)
}
pub fn api_endpoints(&self) -> &[ApiEndpoint] {
&self.api_endpoints
}
}
pub struct Server {
state: AppState,
apps: InstalledApps,
api_prefix: String,
startup_banner: bool,
}
#[cfg(test)]
mod tests {
use super::*;
struct First;
struct Second;
#[derive(Debug, che_orm::Model)]
#[orm(table = "migration_items")]
struct MigrationItem {
#[orm(primary_key)]
id: i64,
}
struct MigrationApp;
struct SchemaObjectApp;
impl AppModule for First {
fn name(&self) -> &'static str {
"first"
}
fn schema(&self) -> SchemaSet {
SchemaSet::new()
}
fn init(&self, _context: &mut ModuleContext) {}
}
impl AppModule for Second {
fn name(&self) -> &'static str {
"second"
}
fn schema(&self) -> SchemaSet {
SchemaSet::new()
}
fn init(&self, _context: &mut ModuleContext) {}
}
impl AppModule for MigrationApp {
fn name(&self) -> &'static str {
"migration_app"
}
fn schema(&self) -> SchemaSet {
SchemaSet::new().model::<MigrationItem>()
}
fn init(&self, _context: &mut ModuleContext) {}
}
impl AppModule for SchemaObjectApp {
fn name(&self) -> &'static str {
"schema_object_app"
}
fn schema(&self) -> SchemaSet {
SchemaSet::new()
}
fn schema_objects(&self) -> Vec<SchemaObjectState> {
vec![SchemaObjectState {
app: String::new(),
kind: che_orm::SchemaObjectKind::View,
name: "migration_items_view".into(),
sql: "CREATE VIEW migration_items_view AS SELECT 1 AS id".into(),
}]
}
fn init(&self, _context: &mut ModuleContext) {}
}
#[test]
fn installed_apps_preserve_registration_order() {
let apps = InstalledApps::new().add(First).add(Second);
assert_eq!(apps.names().collect::<Vec<_>>(), ["first", "second"]);
assert!(apps.find("first").is_some());
}
#[test]
fn banner_uses_effective_routes_and_session_settings_without_database_secrets() {
let mut config = crate::AppConfig::default();
config.server.host = "::1".into();
config.server.port = 8080;
config.database.url = "sqlite://private-database.sqlite?secret=hidden".into();
let apps = InstalledApps::new().add(crate::auth::module()).add(First);
let banner = startup_banner(&config, "/v1/", &apps);
assert!(banner.contains("http://[::1]:8080/v1/openapi.json"));
assert!(banner.contains("Apps: auth, first"));
assert!(banner.contains("Secure=false, SameSite=Lax, idle=7d"));
assert!(!banner.contains("private-database"));
assert!(!banner.contains("secret"));
assert!(!banner.contains("/api/"));
}
#[test]
fn banner_omits_uninstalled_auth_and_shows_actual_memory_pool_size() {
let mut config = crate::AppConfig::default();
config.database.url = ":memory:".into();
let banner = startup_banner(&config, "/api", &InstalledApps::new());
assert!(banner.contains("Apps: none"));
assert!(banner.contains("Database: SQLite, max connections: 1"));
assert!(!banner.contains("Session:"));
assert_eq!(format_duration(90), "90s");
assert_eq!(format_duration(0), "0s");
}
#[test]
fn installed_apps_expose_app_owned_migration_state() {
let apps = InstalledApps::new().add(MigrationApp);
let state = apps.migration_state().unwrap();
let models = state.models();
assert_eq!(models.len(), 1);
assert_eq!(models[0].key.app, "migration_app");
assert_eq!(models[0].key.name, "MigrationItem");
assert_eq!(models[0].table.name, "migration_items");
assert!(apps.migration_diff(&state).unwrap().is_empty());
}
#[test]
fn installed_apps_assign_schema_objects_to_their_module() {
let state = InstalledApps::new()
.add(SchemaObjectApp)
.migration_state()
.unwrap();
assert_eq!(state.objects().len(), 1);
assert_eq!(state.objects()[0].app, "schema_object_app");
}
#[tokio::test]
async fn lifecycle_signals_are_opt_in() {
let state = AppState::from_database(che_orm::Database::connect_in_memory().await.unwrap());
let mut context = ModuleContext::new(state.clone());
context.viewset_with(crate::auth::AdminUserViewSet);
assert!(state.signals().public_signals().is_empty());
}
#[tokio::test]
async fn viewset_path_drives_metadata_and_openapi() {
let state = AppState::from_database(che_orm::Database::connect_in_memory().await.unwrap());
let mut context = ModuleContext::new(state);
context.viewset_with(crate::auth::AdminUserViewSet);
assert_eq!(context.api_endpoints()[0].resource, "auth/users");
assert!(context.openapi_paths.contains_key("/auth/users/"));
}
}
impl Server {
pub fn new(state: AppState) -> Self {
Self {
state,
apps: InstalledApps::new(),
api_prefix: "/api".to_owned(),
startup_banner: true,
}
}
pub fn install(mut self, apps: InstalledApps) -> Self {
self.apps = apps;
self
}
pub fn api_prefix(mut self, prefix: impl Into<String>) -> Self {
self.api_prefix = prefix.into();
self
}
pub fn startup_banner(mut self, enabled: bool) -> Self {
self.startup_banner = enabled;
self
}
pub async fn build(self) -> AppResult<Router> {
let mut context = ModuleContext::new(self.state.clone());
for module in self.apps.iter() {
context.schemas.push(module.schema());
context.current_app = module.name();
module.init(&mut context);
}
if !context.registration_errors.is_empty() {
return Err(AppError::BadRequest(context.registration_errors.join("; ")));
}
let schema = context.schema();
schema
.validate()
.map_err(|error| AppError::BadRequest(format!("invalid app schema: {error:?}")))?;
let mut api = Router::new();
for route in context.routers {
api = api.merge(route);
}
let mut root = Router::new();
for route in context.root_routers {
root = root.merge(route);
}
let mut openapi_paths = context.openapi_paths;
let mut openapi_components = Map::new();
openapi_components.insert(
"schemas".to_owned(),
Value::Object(context.openapi_components),
);
for module in self.apps.iter() {
let metadata = module.openapi(&self.state);
if let Some(paths) = metadata.get("paths").and_then(Value::as_object) {
openapi_paths.extend(paths.clone());
}
if let Some(components) = metadata.get("components").and_then(Value::as_object) {
for (name, values) in components {
if name == "schemas" {
if let Some(target) = openapi_components
.get_mut("schemas")
.and_then(Value::as_object_mut)
&& let Some(values) = values.as_object()
{
target.extend(values.clone());
}
} else {
openapi_components.insert(name.clone(), values.clone());
}
}
}
}
let openapi = json!({
"openapi": "3.0.3",
"info": { "title": "che-rest API", "version": "0.1.0" },
"servers": [{"url": self.api_prefix.clone()}],
"paths": openapi_paths,
"components": openapi_components,
"x-che-rest-signals": self.state.signals().public_signals().into_iter().map(|(name, access)| json!({"name": name, "access": format!("{:?}", access)})).collect::<Vec<_>>(),
});
api = api.route(
"/openapi.json",
get(move || async move { Json(openapi.clone()) }),
);
for module in self.apps.iter() {
module.subscribe(&self.state);
}
for module in self.apps.iter() {
module.start(&self.state);
}
root = root.nest(&self.api_prefix, api);
let swagger_html = swagger_html(&self.state.config.auth.session.csrf_cookie_name);
root = root.route(
&format!("{}/", self.api_prefix.trim_end_matches('/')),
get(move || {
let html = swagger_html.clone();
async move { Html(html) }
}),
);
for module in self.apps.iter() {
root = module.middleware(root, &self.state);
}
if self.startup_banner {
println!(
"{}",
startup_banner(&self.state.config, &self.api_prefix, &self.apps)
);
}
Ok(root
.layer(axum::Extension(context.media_access))
.layer(axum::Extension(self.state)))
}
}
fn startup_banner(config: &crate::AppConfig, api_prefix: &str, apps: &InstalledApps) -> String {
let host = &config.server.host;
let host = if host.contains(':') && !host.starts_with('[') {
format!("[{host}]")
} else {
host.clone()
};
let address = format!("http://{host}:{}", config.server.port);
let prefix = api_prefix.trim_end_matches('/');
let names = apps.names().collect::<Vec<_>>();
let modules = if names.is_empty() {
"none".into()
} else {
names.join(", ")
};
let mut banner = format!(
"\nche-rest v{}\nServer: {address} (configured)\nAPI: {address}{prefix}/\nOpenAPI: {address}{prefix}/openapi.json\nApps: {modules}\nDatabase: SQLite, max connections: {}\nMedia: {}\n",
env!("CARGO_PKG_VERSION"),
if crate::config::sqlite_path(&config.database.url) == ":memory:" {
1
} else {
config.database.max_connections
},
config.media.root,
);
if apps.find("auth").is_some() {
let session = &config.auth.session;
banner.push_str(&format!(
"Session: Secure={}, SameSite={}, idle={}, renew-window={}, absolute={}\n",
session.secure,
session.same_site,
format_duration(session.ttl_seconds),
format_duration(session.renewal_window_seconds),
format_duration(session.absolute_ttl_seconds),
));
}
banner
}
fn format_duration(seconds: i64) -> String {
for (unit, suffix) in [(86_400, "d"), (3_600, "h"), (60, "m")] {
if seconds != 0 && seconds % unit == 0 {
return format!("{}{suffix}", seconds / unit);
}
}
format!("{seconds}s")
}
fn swagger_html(csrf_cookie_name: &str) -> String {
format!(
r##"<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>che-rest API</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
<script>
window.ui = SwaggerUIBundle({{
url: "./openapi.json",
dom_id: "#swagger-ui",
withCredentials: true,
requestInterceptor: (request) => {{
if (["POST", "PUT", "PATCH", "DELETE"].includes(request.method)) {{
const token = document.cookie.split("; ").find((cookie) => cookie.startsWith("{csrf_cookie_name}="));
if (token) request.headers["X-CSRF-Token"] = token.split("=").slice(1).join("=");
}}
return request;
}}
}});
</script>
</body>
</html>"##
)
}
fn add_filter_parameters<V: ViewSet>(document: &mut Value, viewset: &V) {
let Some(parameters) = document
.get_mut("paths")
.and_then(Value::as_object_mut)
.and_then(|paths| paths.values_mut().next())
.and_then(Value::as_object_mut)
.and_then(|path| path.get_mut("get"))
.and_then(Value::as_object_mut)
.map(|get| get.entry("parameters").or_insert_with(|| json!([])))
else {
return;
};
let Some(parameters) = parameters.as_array_mut() else {
return;
};
for filter in viewset.filterset().filters().iter() {
let name = match filter.lookup() {
crate::Lookup::Exact => filter.name.to_owned(),
crate::Lookup::Contains => return_filter_name(filter.name, "__contains"),
crate::Lookup::Gt => return_filter_name(filter.name, "__gt"),
crate::Lookup::Gte => return_filter_name(filter.name, "__gte"),
crate::Lookup::Lt => return_filter_name(filter.name, "__lt"),
crate::Lookup::Lte => return_filter_name(filter.name, "__lte"),
};
let model_schema = V::Model::schema();
let column = model_schema
.columns
.iter()
.find(|column| column.name == filter.source());
let mut schema = column
.map(openapi_column_schema)
.unwrap_or_else(|| json!({"type": "string"}));
schema["nullable"] = json!(false);
parameters.push(json!({"name": name, "in": "query", "required": false, "schema": schema}));
}
parameters.push(
json!({"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}}),
);
parameters.push(
json!({"name": "offset", "in": "query", "required": false, "schema": {"type": "integer"}}),
);
parameters.push(
json!({"name": "ordering", "in": "query", "required": false, "schema": {"type": "string"}}),
);
}
fn return_filter_name(name: &'static str, suffix: &str) -> String {
format!("{name}{suffix}")
}