use axum::extract::Request;
use axum::http::{HeaderValue, Method, StatusCode};
use axum::response::{IntoResponse, Json};
use axum::Router;
use dashmap::DashMap;
use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::{Arc, OnceLock};
use std::time::Instant;
use tower_http::compression::CompressionLayer;
use tower_http::cors::{AllowOrigin, CorsLayer};
use tower_http::services::ServeDir;
use tracing::info;
use tracing::warn;
use crate::chain::{apply_chain, priorities, MiddlewareEntry};
use crate::middleware as mw;
#[cfg(feature = "cache")]
use crate::middleware::nonce::{nonce, NonceState};
use crate::resources::*;
use crate::router::{RouteEntry, RouteGuard, WordvalRouter};
use wordval_config::{AppConfig, ConfigManager};
use wordval_core::api::{codes, Res};
use wordval_core::{PluginManager, Result};
use wordval_utils::web::TrustedProxies;
#[derive(Clone)]
pub struct AppSettings {
pub config_path: Option<String>,
pub gen_config_only: bool,
pub print_config: bool,
}
type CustomMiddlewareEntry = (String, i32, Arc<dyn Fn(Router) -> Router + Send + Sync>);
type StartupHook =
Box<dyn FnOnce() -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>> + Send>;
pub struct App {
router: Option<WordvalRouter>,
plugins: PluginManager,
settings: AppSettings,
config_mgr: Option<Arc<ConfigManager>>,
prefix: String,
rate_limit_store: Arc<DashMap<String, mw::IpWindow>>,
custom_middleware_hook: Option<Box<dyn FnOnce(Router) -> Router + Send>>,
custom_middlewares: Vec<CustomMiddlewareEntry>,
startup_hook: Option<StartupHook>,
audit: Option<Arc<crate::audit::AuditWriter>>,
on_listening_hook: Option<Arc<dyn Fn(SocketAddr) + Send + Sync>>,
}
impl App {
pub fn new() -> Result<Self> {
Self::from_config_dir("config")
}
pub fn from_config() -> Result<Self> {
Self::new()
}
pub fn from_config_dir(dir: &str) -> Result<Self> {
let cm = Arc::new(ConfigManager::load(Some(dir)));
Self::with_config_manager(cm)
}
pub fn with_config(cfg: AppConfig) -> Result<Self> {
let cm = ConfigManager {
static_config: cfg,
dynamic: parking_lot::RwLock::new(HashMap::new()),
};
Self::with_config_manager(Arc::new(cm))
}
pub fn with_config_manager(cm: Arc<ConfigManager>) -> Result<Self> {
let cm = Arc::new(
Arc::try_unwrap(cm)
.unwrap_or_else(|cm| (*cm).clone())
.normalized_databases(),
);
let cfg = cm.get();
wordval_config::log::init(&cfg.log);
let prefix = cfg.router.prefix.clone();
Ok(Self {
router: Some(WordvalRouter::new()),
plugins: PluginManager::new(),
settings: AppSettings {
config_path: Some("config".into()),
gen_config_only: false,
print_config: false,
},
config_mgr: Some(cm),
prefix,
rate_limit_store: Arc::new(DashMap::new()),
custom_middleware_hook: None,
custom_middlewares: Vec::new(),
startup_hook: None,
audit: None,
on_listening_hook: None,
})
}
pub fn on_listening<F>(mut self, f: F) -> Self
where
F: Fn(SocketAddr) + Send + Sync + 'static,
{
self.on_listening_hook = Some(Arc::new(f));
self
}
pub fn parse_cli(mut self) -> Self {
let (gen_config, print_config) = wordval_config::env::parse_args();
self.settings.gen_config_only = gen_config;
self.settings.print_config = print_config;
self
}
pub fn parse_cli_with<F>(mut self, f: F) -> Self
where
F: FnOnce(&[String]) -> (bool, bool),
{
let args = wordval_config::env::raw_args();
let (gen_config, print_config) = f(&args);
self.settings.gen_config_only = gen_config;
self.settings.print_config = print_config;
self
}
pub fn override_config<F>(mut self, f: F) -> Self
where
F: FnOnce(&mut AppConfig),
{
let mut cm = match self.config_mgr.take() {
Some(cm) => (*cm).clone(),
None => ConfigManager {
static_config: AppConfig::default(),
dynamic: parking_lot::RwLock::new(HashMap::new()),
},
};
f(&mut cm.static_config);
cm.static_config.normalize_databases();
self.prefix = cm.static_config.router.prefix.clone();
self.config_mgr = Some(Arc::new(cm));
self
}
pub fn get<H, T>(mut self, path: &str, handler: H) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_get(path, handler);
}
self
}
pub fn post<H, T>(mut self, path: &str, handler: H) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_post(path, handler);
}
self
}
pub fn put<H, T>(mut self, path: &str, handler: H) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_put(path, handler);
}
self
}
pub fn delete<H, T>(mut self, path: &str, handler: H) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_delete(path, handler);
}
self
}
pub fn route<H, T>(mut self, method: &str, path: &str, handler: H) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_route(method, path, handler);
}
self
}
pub fn guarded<H, T>(
mut self,
method: &str,
path: &str,
handler: H,
guard: RouteGuard,
) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_route_guarded(method, path, handler, guard);
}
self
}
pub fn group(mut self, prefix: &str, f: impl FnOnce(Self) -> Self) -> Self {
let sub = f(Self {
router: Some(WordvalRouter::new()),
plugins: PluginManager::new(),
settings: self.settings.clone(),
config_mgr: self.config_mgr.clone(),
prefix: String::new(),
rate_limit_store: self.rate_limit_store.clone(),
custom_middleware_hook: None,
custom_middlewares: Vec::new(),
startup_hook: None,
audit: None,
on_listening_hook: None,
});
if let (Some(ref mut r), Some(sub_r)) = (self.router.as_mut(), sub.router) {
r.merge(prefix, sub_r);
}
self
}
pub fn scan(mut self) -> Self {
for register in crate::ROUTES {
if let Some(ref mut r) = self.router {
register(r);
}
}
self
}
pub fn print_routes(self) -> Self {
if let Some(ref router) = self.router {
let routes = router.list_routes();
info!("========== 已注册路由列表 ({} 条) ==========", routes.len());
for r in routes {
info!(" [路由] {:<7} {}{}", r.method, r.path, guard_display(&r.guard));
}
info!("============================================");
}
self
}
pub fn list_routes(&self) -> &[RouteEntry] {
self.router.as_ref().map(|r| r.list_routes()).unwrap_or(&[])
}
pub fn merge(mut self, prefix: &str, sub: WordvalRouter) -> Self {
if let Some(ref mut r) = self.router {
r.merge(prefix, sub);
}
self
}
pub fn with_permission<H, T>(
mut self,
method: &str,
path: &str,
handler: H,
permission: &str,
) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
if let Some(ref mut r) = self.router {
r.add_route_guarded(method, path, handler, RouteGuard::permission(permission));
}
self
}
pub fn with_role<H, T>(mut self, method: &str, path: &str, handler: H, role: &str) -> Self
where
H: axum::handler::Handler<T, ()>,
T: 'static,
{
let rl = role.to_string();
if let Some(ref mut r) = self.router {
let wrap = move |mr: axum::routing::MethodRouter<()>| {
mr.route_layer(mw::RequireRoleLayer::any(vec![rl]))
};
r.add_route_with_layer(method, path, handler, wrap);
}
self
}
pub fn plugin<P: wordval_core::Plugin + 'static>(mut self, plugin: P) -> Self {
self.plugins = self.plugins.add(plugin);
self
}
pub fn on_startup<F, Fut>(mut self, hook: F) -> Self
where
F: FnOnce() -> Fut + Send + 'static,
Fut: std::future::Future<Output = ()> + Send + 'static,
{
self.startup_hook = Some(Box::new(|| Box::pin(hook())));
self
}
pub fn audit_writer(mut self, writer: Arc<crate::audit::AuditWriter>) -> Self {
self.audit = Some(writer);
self
}
pub fn with_middleware_hook<F>(mut self, hook: F) -> Self
where
F: FnOnce(Router) -> Router + Send + 'static,
{
self.custom_middleware_hook = Some(Box::new(hook));
self
}
pub fn middleware<F>(mut self, name: impl Into<String>, priority: i32, apply: F) -> Self
where
F: Fn(Router) -> Router + Send + Sync + 'static,
{
self.custom_middlewares
.push((name.into(), priority, Arc::new(apply)));
self
}
pub async fn start(mut self) -> Result<()> {
let startup_start = Instant::now();
if self.settings.gen_config_only {
let dir = self.settings.config_path.as_deref().unwrap_or("config");
ConfigManager::generate_default(dir)?;
return Ok(());
}
if self.config_mgr.is_none() {
let _ = tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| "wordval=info".into()),
)
.try_init();
}
if self.settings.print_config {
if let Some(ref cm) = self.config_mgr {
if let Ok(toml_str) = toml::to_string_pretty(cm.get()) {
println!("{}", toml_str);
}
}
}
if let Some(ref cm) = self.config_mgr {
Self::init_global_resources(cm).await?;
}
if let Some(writer) = self.audit.take() {
set_audit_writer(writer).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
} else if let Some(cm) = &self.config_mgr {
let acfg = &cm.get().middleware.audit;
if acfg.enabled {
let writer = crate::audit::writer_from_config(acfg).await?;
set_audit_writer(writer).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
}
}
if try_audit_writer().is_none() {
let guard_rules = self
.router
.as_ref()
.map(|r| {
r.list_routes()
.iter()
.filter(|e| e.guard.audit.is_some())
.count()
})
.unwrap_or(0);
let config_rules = self
.config_mgr
.as_ref()
.map(|cm| {
let audit = &cm.get().middleware.audit;
if audit.enabled {
audit.routes.len()
} else {
0
}
})
.unwrap_or(0);
if guard_rules + config_rules > 0 {
warn!(
"存在 {} 条审计规则(路由守卫 {} / 配置 {})但未装配审计写入器:\
启用 middleware.audit.enabled 或调用 App::audit_writer() 才会记录",
guard_rules + config_rules,
guard_rules,
config_rules
);
}
}
if let Some(hook) = self.startup_hook.take() {
(hook)().await;
}
self.plugins
.check_duplicate_names()
.map_err(wordval_core::Error::Config)?;
self.plugins.start_all().await?;
let router = self.router.take().unwrap_or_default();
let routes = router.list_routes().to_vec();
let mut axum_router: Router = router.into_axum();
if !self.prefix.is_empty() {
let prefix = self.prefix.trim_matches('/').to_string();
let mut prefixed = Router::new();
prefixed = prefixed.nest(&format!("/{}", prefix), axum_router);
axum_router = prefixed;
info!("全局路由前缀已启用: /{}", prefix);
}
if let Some(ref cm) = self.config_mgr {
let cfg = cm.get();
if cfg.static_files.enabled {
let static_path = cfg.static_files.path.clone();
std::fs::create_dir_all(&static_path).ok();
info!("静态文件服务就绪 path={}", static_path);
axum_router = axum_router.fallback_service(ServeDir::new(&static_path));
} else if cfg.router.not_found.enabled {
axum_router = axum_router.fallback(Self::handle_not_found);
}
}
self.validate_middleware_config()?;
if let Some(ref cm) = self.config_mgr {
let cfg = cm.get();
let policy_table = crate::policy::RoutePolicyTable::build(
&self.prefix,
&routes,
cfg.middleware.auth.enabled,
&cfg.middleware.auth.ignore_paths,
cfg.middleware.permission.enabled,
&cfg.middleware.permission.rules,
);
policy_table
.validate()
.map_err(wordval_core::Error::Config)?;
policy_table.log(
&self.prefix,
&routes,
&cfg.middleware.auth.ignore_paths,
&cfg.middleware.auth.api_prefixes,
cfg.middleware.auth.enabled,
);
}
axum_router = self.build_middleware_chain(axum_router, &routes);
if let Some(hook) = self.custom_middleware_hook.take() {
axum_router = hook(axum_router);
}
let bind_addr = self
.config_mgr
.as_ref()
.map(|cm| cm.get().server.listen.clone())
.unwrap_or_else(|| "0.0.0.0:0".to_string());
let socket_addr = parse_addr(&bind_addr)?;
let listener = tokio::net::TcpListener::bind(socket_addr).await?;
let local_addr = listener.local_addr().unwrap_or(socket_addr);
let display_addr = resolve_display_addr(local_addr);
let app_name = self
.config_mgr
.as_ref()
.map(|cm| cm.get().app_name.as_str())
.unwrap_or("Wordval");
info!("{} 启动 -> http://{}", app_name, display_addr);
if let Some(cm) = &self.config_mgr {
info!(
" profile={}, request_id={} log={} cors={} compression={} rate_limit={} auth={} security_headers={} permission={} nonce={} audit={} static_files={} not_found={}",
cm.get().profile,
cm.get().middleware.request_id,
cm.get().middleware.request_log,
cm.get().middleware.cors.enabled,
cm.get().middleware.compression.enabled,
cm.get().middleware.rate_limit.enabled,
cm.get().middleware.auth.enabled,
cm.get().middleware.security_headers.enabled,
cm.get().middleware.permission.enabled,
cm.get().middleware.nonce.enabled,
cm.get().middleware.audit.enabled,
cm.get().static_files.enabled,
cm.get().router.not_found.enabled,
);
}
let startup_ms = startup_start.elapsed().as_millis();
info!("{} 启动完成, 耗时 {}ms", app_name, startup_ms);
if let Some(cb) = self.on_listening_hook.take() {
cb(local_addr);
}
axum::serve(
listener,
axum_router.into_make_service_with_connect_info::<SocketAddr>(),
)
.with_graceful_shutdown(shutdown_signal())
.await?;
self.plugins.stop_all().await;
let audit_timeout = self
.config_mgr
.as_ref()
.map(|cm| cm.get().middleware.audit.shutdown_timeout_secs)
.unwrap_or(crate::audit::DEFAULT_SHUTDOWN_TIMEOUT.as_secs());
if let Err(e) =
shutdown_audit_writer(std::time::Duration::from_secs(audit_timeout)).await
{
warn!("审计写入器关停失败: {}", e);
}
Ok(())
}
pub async fn serve(self, addr: impl Into<String>) -> Result<()> {
let mut s = self;
let addr_str = addr.into();
if s.config_mgr.is_none() {
let default_cfg = AppConfig {
server: wordval_config::ServerConfig {
listen: addr_str.clone(),
},
..Default::default()
};
s.config_mgr = Some(Arc::new(ConfigManager {
static_config: default_cfg,
dynamic: parking_lot::RwLock::new(HashMap::new()),
}));
} else if let Some(ref cm) = s.config_mgr {
let mut cfg = cm.get().clone();
cfg.server.listen = addr_str.clone();
s.config_mgr = Some(Arc::new(ConfigManager {
static_config: cfg,
dynamic: parking_lot::RwLock::new(HashMap::new()),
}));
}
s.start().await
}
async fn init_global_resources(cm: &Arc<ConfigManager>) -> Result<()> {
set_config(cm.clone()).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
let cfg = cfg();
if let Err(e) = crate::tenant::set_tenant_header(&cfg.middleware.tenant_header) {
tracing::warn!("租户头名初始化跳过: {}", e);
}
#[cfg(feature = "db")]
{
let created = match wordval_db::factory::create_named_dbs(&cfg.databases).await {
Ok(list) => list,
Err(e) => {
tracing::error!("数据库连接失败: {}", e);
return Err(wordval_core::Error::Config(format!(
"数据库连接失败: {}",
e
)));
}
};
let mut dbs: std::collections::HashMap<String, wordval_db::Db> = HashMap::new();
for (name, db) in created {
let mcfg = cfg.databases[&name].migration.clone();
if mcfg.enabled && mcfg.auto_migrate {
let migrator = wordval_db::migrate::Migrator::new(db.clone(), mcfg);
match migrator.run().await {
Ok(records) => info!(
"数据库 '{}' 迁移完成: {:?}",
name,
records.iter().map(|r| &r.version).collect::<Vec<_>>()
),
Err(e) => {
tracing::error!("数据库 '{}' 迁移失败: {}", name, e);
return Err(wordval_core::Error::Config(format!(
"数据库 '{}' 迁移失败: {}",
name, e
)));
}
}
}
dbs.insert(name, db);
}
if !dbs.is_empty() {
set_dbs(dbs).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
info!("数据库服务就绪 aliases={:?}", db_names());
}
}
#[cfg(feature = "cache")]
if cfg.cache.r#type != "local" || cfg.cache.max_capacity > 0 {
match wordval_cache::create_cache(&cfg.cache, &cfg.redis).await {
Ok(c) => {
set_cache(c).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
info!("缓存服务就绪 type={}", cfg.cache.r#type);
}
Err(e) => {
tracing::warn!("缓存初始化失败: {},将不使用缓存", e);
}
}
}
#[cfg(feature = "template")]
{
match crate::template_engine::TemplateEngine::from_dir(&cfg.template.path) {
Ok(engine) => {
info!("模板引擎就绪 path={}", cfg.template.path);
set_template(engine).map_err(|e| wordval_core::Error::Config(e.to_string()))?;
}
Err(e) => {
tracing::warn!("模板引擎初始化失败: {},将使用空引擎", e);
let _ = set_template(crate::template_engine::TemplateEngine::new());
}
}
}
{
let upload_path = &cfg.upload.path;
std::fs::create_dir_all(upload_path).map_err(|e| {
wordval_core::Error::Config(format!("创建上传目录失败 '{}': {}", upload_path, e))
})?;
set_upload_path(upload_path.clone())
.map_err(|e| wordval_core::Error::Config(e.to_string()))?;
info!(
"上传目录就绪 path={} max_size_mb={}",
upload_path, cfg.upload.max_size_mb
);
}
{
let download_path = &cfg.download.path;
std::fs::create_dir_all(download_path).map_err(|e| {
wordval_core::Error::Config(format!("创建下载目录失败 '{}': {}", download_path, e))
})?;
set_download_path(download_path.clone())
.map_err(|e| wordval_core::Error::Config(e.to_string()))?;
info!("下载目录就绪 path={}", download_path);
}
Ok(())
}
async fn handle_not_found(req: Request) -> impl IntoResponse {
warn!(
method = %req.method(),
path = %req.uri().path(),
status = 404,
"请求404"
);
let msg = cfg().router.not_found.message.clone();
(
StatusCode::NOT_FOUND,
Json(Res::<()>::fail(codes::NOT_FOUND, msg)),
)
}
fn build_middleware_chain(&self, router: Router, routes: &[RouteEntry]) -> Router {
let Some(cm) = &self.config_mgr else {
return router;
};
let cfg = cm.get();
let mut entries: Vec<MiddlewareEntry> = Vec::new();
#[cfg(feature = "cache")]
if cfg.middleware.nonce.enabled {
let state = std::sync::Arc::new(NonceState::new(
mw::nonce::NonceAvailability::from_config(&cfg.middleware.nonce.availability),
cfg.middleware.nonce.require_for_write,
cfg.middleware.nonce.ttl_secs as u32,
));
entries.push(MiddlewareEntry::new("nonce", priorities::NONCE, move |r| {
r.layer(axum::middleware::from_fn_with_state(state, nonce))
}));
}
let mut perm_layer =
mw::PermissionCheckLayer::empty().with_route_guards(routes, &self.prefix);
if cfg.middleware.permission.enabled {
perm_layer =
perm_layer.with_config_rules(&cfg.middleware.permission.rules, &self.prefix);
}
if perm_layer.has_rules() {
entries.push(MiddlewareEntry::new(
"permission_check",
priorities::PERMISSION_CHECK,
move |r| r.layer(perm_layer),
));
}
if cfg.middleware.auth.enabled {
let ignore: Vec<String> = cfg
.middleware
.auth
.ignore_paths
.iter()
.map(|p| mw::auth::join_route_path(&self.prefix, p))
.collect();
let method_ignore: Vec<(String, String)> = routes
.iter()
.filter(|r| r.guard.public)
.map(|r| {
(
r.method.clone(),
mw::auth::join_route_path(&self.prefix, &r.path),
)
})
.collect();
let auth_layer = mw::AuthLayer {
ignore_paths: Arc::new(ignore),
method_ignore_rules: Arc::new(method_ignore),
api_prefixes: Arc::new(cfg.middleware.auth.api_prefixes.clone()),
compiled: Arc::new(OnceLock::new()),
};
entries.push(MiddlewareEntry::new(
"require_auth",
priorities::REQUIRE_AUTH,
move |r| r.layer(auth_layer),
));
}
if try_audit_writer().is_some() {
let mut audit_layer = mw::AuditLayer::empty().with_route_guards(routes, &self.prefix);
if cfg.middleware.audit.enabled {
audit_layer =
audit_layer.with_config_routes(&cfg.middleware.audit.routes, &self.prefix);
}
if audit_layer.has_rules() {
entries.push(MiddlewareEntry::new(
"audit",
priorities::AUDIT,
move |r| r.layer(audit_layer),
));
}
}
entries.push(MiddlewareEntry::new(
"tenant_context",
priorities::TENANT_CONTEXT,
|r| {
r.layer(axum::middleware::from_fn(
crate::tenant::tenant_context_layer,
))
},
));
#[cfg(feature = "cache")]
if let Some(cache) = try_cache().cloned() {
let state = std::sync::Arc::new(mw::SessionResolverState { cache });
entries.push(MiddlewareEntry::new(
"session_resolver",
priorities::SESSION_RESOLVER,
move |r| {
r.layer(axum::middleware::from_fn_with_state(
state,
mw::session_resolver,
))
},
));
}
let trusted = if cfg.middleware.rate_limit.trust_xff {
Arc::new(TrustedProxies::new(
&cfg.middleware.rate_limit.trusted_proxies,
))
} else {
Arc::new(TrustedProxies::new(&[]))
};
if cfg.middleware.rate_limit.enabled {
let rl_layer = mw::RateLimitLayer {
requests_per_window: cfg.middleware.rate_limit.requests_per_window,
window_secs: cfg.middleware.rate_limit.window_secs,
store: self.rate_limit_store.clone(),
trusted: trusted.clone(),
};
rl_layer.start_cleanup_task();
entries.push(MiddlewareEntry::new(
"rate_limit",
priorities::RATE_LIMIT,
move |r| r.layer(rl_layer),
));
}
if cfg.middleware.compression.enabled {
entries.push(MiddlewareEntry::new(
"compression",
priorities::COMPRESSION,
|r| r.layer(CompressionLayer::new().gzip(true)),
));
}
let body_limit_bytes = (cfg.upload.max_size_mb as usize).saturating_mul(1024 * 1024);
entries.push(MiddlewareEntry::new(
"body_limit",
priorities::BODY_LIMIT,
move |r| r.layer(axum::extract::DefaultBodyLimit::max(body_limit_bytes)),
));
if cfg.middleware.cors.enabled {
let cors = Self::build_cors_layer(&cfg.middleware.cors);
entries.push(MiddlewareEntry::new("cors", priorities::CORS, move |r| {
r.layer(cors)
}));
}
if cfg.middleware.security_headers.enabled {
let sh = mw::SecurityHeadersLayer::new(cfg.middleware.security_headers.clone());
entries.push(MiddlewareEntry::new(
"security_headers",
priorities::SECURITY_HEADERS,
move |r| r.layer(sh),
));
}
if cfg.middleware.request_log {
let log_cfg = &cfg.middleware.request_log_config;
let prefix_excluded: Vec<String> = log_cfg
.exclude_paths
.iter()
.map(|p| mw::auth::join_route_path(&self.prefix, p))
.collect();
let log_layer = mw::RequestLogLayer {
exclude_paths: Arc::new(prefix_excluded),
log_duration: log_cfg.log_duration,
print_body: log_cfg.print_body,
report_multiline: log_cfg.report_multiline,
};
entries.push(MiddlewareEntry::new(
"request_log",
priorities::REQUEST_LOG,
move |r| r.layer(log_layer),
));
}
entries.push(MiddlewareEntry::new(
"client_identity",
priorities::CLIENT_IDENTITY,
move |r| r.layer(mw::ClientIdentityLayer { trusted }),
));
if cfg.middleware.request_id {
entries.push(MiddlewareEntry::new(
"request_id",
priorities::REQUEST_ID,
|r| r.layer(mw::RequestIdLayer),
));
}
for (name, priority, apply) in &self.custom_middlewares {
let apply = apply.clone();
entries.push(MiddlewareEntry::new(name.clone(), *priority, move |r| {
apply(r)
}));
}
let (router, order) = apply_chain(router, entries);
info!("中间件链(外 -> 内): {}", order.join(" -> "));
router
}
fn validate_middleware_config(&self) -> Result<()> {
let Some(cm) = &self.config_mgr else {
return Ok(());
};
let cfg = cm.get();
if cfg.middleware.cors.enabled {
for o in &cfg.middleware.cors.allow_origins {
o.parse::<HeaderValue>().map_err(|e| {
wordval_core::Error::Config(format!(
"CORS allow_origins 含非法值 '{}': {}",
o, e
))
})?;
}
for m in &cfg.middleware.cors.allow_methods {
m.parse::<Method>().map_err(|e| {
wordval_core::Error::Config(format!(
"CORS allow_methods 含非法值 '{}': {}",
m, e
))
})?;
}
for h in &cfg.middleware.cors.allow_headers {
h.parse::<axum::http::HeaderName>().map_err(|e| {
wordval_core::Error::Config(format!(
"CORS allow_headers 含非法值 '{}': {}",
h, e
))
})?;
}
if cfg.middleware.cors.allow_credentials && cfg.middleware.cors.allow_origins.is_empty()
{
return Err(wordval_core::Error::Config(
"CORS 配置错误:allow_credentials=true 时 allow_origins 不能为空\
(禁止反射源带凭据,防止任意网站携带用户凭据发起跨域请求)。\
请显式配置 allow_origins。"
.to_string(),
));
}
}
if cfg.middleware.auth.enabled {
#[cfg(not(feature = "cache"))]
{
return Err(wordval_core::Error::Config(
"启用了 auth 中间件(middleware.auth.enabled=true)但未编译 cache feature,\
无法解析会话(所有受保护 API 都会返回 401)。请在 Cargo.toml 中为 \
wordval-web 启用 cache feature,或关闭 auth 中间件。"
.to_string(),
));
}
#[cfg(feature = "cache")]
if try_cache().is_none() {
return Err(wordval_core::Error::Config(
"启用了 auth 中间件(middleware.auth.enabled=true)但缓存未初始化。\
请在 App 构建阶段先初始化缓存(init_cache/with_cache),\
或关闭 auth 中间件后再启动。"
.to_string(),
));
}
}
#[cfg(feature = "cache")]
if cfg.middleware.nonce.enabled
&& mw::nonce::NonceAvailability::from_config(&cfg.middleware.nonce.availability)
== mw::nonce::NonceAvailability::Required
&& try_cache().is_none()
{
return Err(wordval_core::Error::Config(
"nonce 配置为 Required 策略(fail-closed)但缓存未初始化,\
所有携带 X-Nonce 的请求都会被拒绝。请先初始化缓存,\
或改用 best_effort / disabled 策略。"
.to_string(),
));
}
Ok(())
}
fn build_cors_layer(cfg: &wordval_config::CorsConfig) -> CorsLayer {
let mut cors = CorsLayer::new();
if !cfg.allow_origins.is_empty() {
let origins: Vec<HeaderValue> = cfg
.allow_origins
.iter()
.map(|o| o.parse().expect("CORS origin 已通过启动校验"))
.collect();
cors = cors.allow_origin(AllowOrigin::list(origins));
} else {
cors = cors.allow_origin(AllowOrigin::mirror_request());
}
if !cfg.allow_methods.is_empty() {
let methods: Vec<Method> = cfg
.allow_methods
.iter()
.map(|m| m.parse().expect("CORS method 已通过启动校验"))
.collect();
cors = cors.allow_methods(methods);
}
if !cfg.allow_headers.is_empty() {
let headers: Vec<axum::http::HeaderName> = cfg
.allow_headers
.iter()
.map(|h| h.parse().expect("CORS header 已通过启动校验"))
.collect();
cors = cors.allow_headers(headers);
} else {
cors = cors.allow_headers(tower_http::cors::AllowHeaders::any());
}
if cfg.allow_credentials {
cors = cors.allow_credentials(true);
}
cors = cors.max_age(std::time::Duration::from_secs(cfg.max_age_secs));
cors
}
}
impl Default for App {
fn default() -> Self {
Self {
router: Some(WordvalRouter::new()),
plugins: PluginManager::new(),
settings: AppSettings {
config_path: Some("config".into()),
gen_config_only: false,
print_config: false,
},
config_mgr: None,
prefix: String::new(),
rate_limit_store: Arc::new(DashMap::new()),
custom_middleware_hook: None,
custom_middlewares: Vec::new(),
startup_hook: None,
audit: None,
on_listening_hook: None,
}
}
}
fn parse_addr(addr: &str) -> wordval_core::Result<SocketAddr> {
let addr = match addr {
a if a.starts_with(':') => format!("0.0.0.0{}", a),
a if !a.contains(':') => format!("0.0.0.0:{}", a),
a => a.to_string(),
};
addr.parse()
.map_err(|e| wordval_core::Error::Config(format!("无效地址 '{}': {}", addr, e)))
}
fn guard_display(guard: &RouteGuard) -> String {
let mut parts = Vec::new();
if guard.public {
parts.push("public".to_string());
}
if let Some(p) = &guard.permission {
parts.push(format!("perm={}", p));
}
if let Some(a) = &guard.audit {
parts.push(format!("audit={}", a));
}
if parts.is_empty() {
String::new()
} else {
format!(" [{}]", parts.join(","))
}
}
fn resolve_display_addr(addr: SocketAddr) -> String {
if addr.ip().is_unspecified() {
format!("127.0.0.1:{}", addr.port())
} else {
addr.to_string()
}
}
async fn shutdown_signal() {
let ctrl_c = async {
tokio::signal::ctrl_c().await.expect("Ctrl-C 注册失败");
};
#[cfg(unix)]
let terminate = async {
tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
.expect("SIGTERM 注册失败")
.recv()
.await;
};
#[cfg(not(unix))]
let terminate = std::future::pending::<()>();
tokio::select! {
_ = ctrl_c => {},
_ = terminate => {},
}
info!("收到关闭信号,优雅退出中...");
}
#[cfg(test)]
mod tests {
use super::*;
use axum::body::Body;
use axum::extract::ConnectInfo;
use axum::http::Request;
use axum::routing::get;
use std::net::SocketAddr;
use std::sync::{Arc, Mutex};
use tower::ServiceExt;
use wordval_config::{AppConfig, PermissionRule};
fn base_config() -> AppConfig {
let mut cfg = AppConfig::default();
cfg.middleware.request_id = true;
cfg.middleware.request_log = true;
cfg.middleware.security_headers.enabled = true;
cfg.middleware.auth.enabled = true;
cfg.middleware.auth.api_prefixes = vec!["/api".to_string()];
cfg.middleware.permission.enabled = true;
cfg.middleware.cors.enabled = true;
cfg.middleware.cors.allow_credentials = false;
cfg.middleware.cors.allow_origins = vec!["http://example.com".to_string()];
cfg.middleware.cors.allow_methods = vec!["GET".to_string(), "POST".to_string()];
cfg
}
fn build(cfg: AppConfig) -> axum::Router {
let app = App::with_config(cfg).expect("测试配置应合法");
app.build_middleware_chain(axum::Router::new(), &[])
}
fn request(method: &str, uri: &str) -> Request<Body> {
Request::builder()
.method(method)
.uri(uri)
.body(Body::empty())
.expect("request 构建失败")
}
async fn send(router: &axum::Router, req: Request<Body>) -> axum::response::Response {
router.clone().oneshot(req).await.expect("infallible")
}
fn assert_has_envelope(resp: &axum::response::Response) {
assert!(
resp.headers().contains_key("x-request-id"),
"短路响应缺少 x-request-id: {:?}",
resp.headers()
);
assert!(
resp.headers().contains_key("x-content-type-options"),
"短路响应缺少安全头 x-content-type-options"
);
assert!(
resp.headers().contains_key("x-frame-options"),
"短路响应缺少安全头 x-frame-options"
);
}
#[tokio::test]
async fn short_circuit_401_has_request_id_and_security_headers() {
let mut cfg = base_config();
cfg.middleware.permission.enabled = false;
let app = App::with_config(cfg).expect("配置合法");
let router = app.build_middleware_chain(
axum::Router::new().route("/api/protected", get(|| async { "ok" })),
&[],
);
let resp = send(&router, request("GET", "/api/protected")).await;
assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
assert_has_envelope(&resp);
}
#[tokio::test]
async fn short_circuit_403_has_request_id_and_security_headers() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.rules = vec![PermissionRule {
path: "/api/admin".to_string(),
methods: vec![],
permission: "admin:access".to_string(),
}];
let router = build(cfg);
let resp = send(&router, request("GET", "/api/admin")).await;
assert_eq!(resp.status(), StatusCode::FORBIDDEN);
assert_has_envelope(&resp);
}
#[tokio::test]
async fn guard_permission_is_derived_from_route_metadata() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
let app = App::with_config(cfg)
.expect("配置合法")
.with_permission("GET", "/api/admin", || async { "ok" }, "admin:access");
let routes = app.list_routes().to_vec();
let router = app.build_middleware_chain(
axum::Router::new().route("/api/admin", get(|| async { "ok" })),
&routes,
);
let resp = send(&router, request("GET", "/api/admin")).await;
assert_eq!(resp.status(), StatusCode::FORBIDDEN);
assert_has_envelope(&resp);
let resp = send(&router, request("HEAD", "/api/admin")).await;
assert_eq!(
resp.status(),
StatusCode::FORBIDDEN,
"GET 权限守卫应覆盖 Axum 自动接受的 HEAD 请求"
);
assert_has_envelope(&resp);
}
#[tokio::test]
async fn guard_public_only_applies_to_declared_route() {
let cfg = base_config();
let app = App::with_config(cfg).expect("配置合法").guarded(
"GET",
"/api/orders",
|| async { "ok" },
RouteGuard::public(),
);
let routes = app.list_routes().to_vec();
let router = app.build_middleware_chain(
axum::Router::new()
.route("/api/orders", get(|| async { "ok" }).post(|| async { "ok" })),
&routes,
);
assert_eq!(
send(&router, request("GET", "/api/orders")).await.status(),
StatusCode::OK,
"守卫声明 public 的路由应免认证"
);
assert_eq!(
send(&router, request("HEAD", "/api/orders")).await.status(),
StatusCode::OK,
"GET public 守卫应覆盖 Axum 自动接受的 HEAD 请求"
);
assert_eq!(
send(&router, request("POST", "/api/orders")).await.status(),
StatusCode::UNAUTHORIZED,
"public 只作用于声明它的那条路由(方法精确绑定)"
);
}
#[tokio::test]
async fn short_circuit_429_has_request_id_and_security_headers() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.rate_limit.enabled = true;
cfg.middleware.rate_limit.requests_per_window = 1;
cfg.middleware.rate_limit.window_secs = 60;
let router = build(cfg);
let first = send(&router, request("GET", "/api/probe")).await;
assert_ne!(first.status(), StatusCode::TOO_MANY_REQUESTS);
let second = send(&router, request("GET", "/api/probe")).await;
assert_eq!(second.status(), StatusCode::TOO_MANY_REQUESTS);
assert_has_envelope(&second);
}
#[tokio::test]
async fn not_found_404_has_request_id_and_security_headers() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.cors.enabled = false;
let router = build(cfg);
let resp = send(&router, request("GET", "/no/such/route")).await;
assert_eq!(resp.status(), StatusCode::NOT_FOUND);
assert_has_envelope(&resp);
}
#[tokio::test]
async fn upload_max_size_mb_governs_request_body_limit() {
use axum::body::Bytes;
use axum::routing::post;
fn router_with(cfg: AppConfig) -> axum::Router {
App::with_config(cfg)
.expect("配置合法")
.build_middleware_chain(
axum::Router::new().route(
"/api/echo",
post(|body: Bytes| async move { body.len().to_string() }),
),
&[RouteEntry {
method: "POST".to_string(),
path: "/api/echo".to_string(),
guard: RouteGuard::default(),
}],
)
}
fn plain_cfg() -> AppConfig {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.cors.enabled = false;
cfg
}
let mk = |n: usize| {
Request::builder()
.method("POST")
.uri("/api/echo")
.header("content-type", "application/octet-stream")
.body(Body::from(vec![b'x'; n]))
.unwrap()
};
let mut cfg = plain_cfg();
cfg.upload.max_size_mb = 1;
let router = router_with(cfg);
let over = send(&router, mk(2 * 1024 * 1024)).await;
assert_eq!(over.status(), StatusCode::PAYLOAD_TOO_LARGE);
let ok = send(&router, mk(512 * 1024)).await;
assert_eq!(ok.status(), StatusCode::OK);
let router2 = router_with(plain_cfg());
let big = send(&router2, mk(3 * 1024 * 1024)).await;
assert_eq!(big.status(), StatusCode::OK);
}
#[tokio::test]
async fn cors_preflight_has_request_id_and_security_headers() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
let router = build(cfg);
let resp = send(
&router,
Request::builder()
.method("OPTIONS")
.uri("/api/probe")
.header("Origin", "http://example.com")
.header("Access-Control-Request-Method", "GET")
.body(Body::empty())
.expect("preflight 构建失败"),
)
.await;
assert!(
resp.headers().get("access-control-allow-origin").is_some(),
"预检应返回 CORS 头"
);
assert_has_envelope(&resp);
}
#[tokio::test]
async fn rate_limit_uses_resolved_client_ip_from_trusted_proxy() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.rate_limit.enabled = true;
cfg.middleware.rate_limit.requests_per_window = 1;
cfg.middleware.rate_limit.window_secs = 60;
cfg.middleware.rate_limit.trust_xff = true;
cfg.middleware.rate_limit.trusted_proxies = vec!["127.0.0.1".to_string()];
let router = build(cfg);
let peer = SocketAddr::from(([127, 0, 0, 1], 12345));
let req_with_xff = |xff: &str| {
Request::builder()
.method("GET")
.uri("/api/probe")
.header("X-Forwarded-For", xff)
.extension(ConnectInfo(peer))
.body(Body::empty())
.expect("请求构建失败")
};
let a = send(&router, req_with_xff("1.1.1.1")).await;
assert_ne!(
a.status(),
StatusCode::TOO_MANY_REQUESTS,
"1.1.1.1 第一次应放行"
);
let b = send(&router, req_with_xff("2.2.2.2")).await;
assert_ne!(
b.status(),
StatusCode::TOO_MANY_REQUESTS,
"2.2.2.2 第一次应放行"
);
let a2 = send(&router, req_with_xff("1.1.1.1")).await;
assert_eq!(
a2.status(),
StatusCode::TOO_MANY_REQUESTS,
"1.1.1.1 第二次应 429"
);
}
struct CaptureSubscriber {
events: Arc<Mutex<Vec<String>>>,
}
impl tracing::Subscriber for CaptureSubscriber {
fn register_callsite(
&self,
_: &'static tracing::Metadata<'static>,
) -> tracing::subscriber::Interest {
tracing::subscriber::Interest::always()
}
fn enabled(&self, _: &tracing::Metadata<'_>) -> bool {
true
}
fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
tracing::span::Id::from_u64(1)
}
fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
fn event(&self, event: &tracing::Event<'_>) {
let mut visitor = FieldCollector::default();
event.record(&mut visitor);
let mut line = format!("{} {}", event.metadata().level(), visitor.message);
for (k, v) in visitor.fields {
line.push_str(&format!(" {}={}", k, v));
}
self.events.lock().expect("events lock").push(line);
}
fn enter(&self, _: &tracing::span::Id) {}
fn exit(&self, _: &tracing::span::Id) {}
}
#[derive(Default)]
struct FieldCollector {
message: String,
fields: Vec<(String, String)>,
}
impl tracing::field::Visit for FieldCollector {
fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
let name = field.name();
if name == "message" {
self.message = format!("{:?}", value);
} else {
self.fields.push((name.to_string(), format!("{:?}", value)));
}
}
fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
self.fields
.push((field.name().to_string(), value.to_string()));
}
}
fn with_captured_logs<T>(f: impl FnOnce(Arc<Mutex<Vec<String>>>) -> T) -> T {
let events = Arc::new(Mutex::new(Vec::new()));
let events_clone = events.clone();
let subscriber = CaptureSubscriber {
events: events_clone,
};
tracing::subscriber::with_default(subscriber, move || f(events))
}
#[test]
fn short_circuit_401_is_recorded_in_access_log() {
let mut cfg = base_config();
cfg.middleware.permission.enabled = false;
let app = App::with_config(cfg).expect("配置合法");
let router = app.build_middleware_chain(
axum::Router::new().route("/api/protected", get(|| async { "ok" })),
&[],
);
with_captured_logs(|events| {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("runtime 构建失败");
rt.block_on(async {
let resp = send(&router, request("GET", "/api/protected")).await;
assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
});
let events = events.lock().expect("events lock");
assert!(
events
.iter()
.any(|e| e.contains("/api/protected") && e.contains("401")),
"访问日志未记录 401 短路响应: {:#?}",
*events
);
});
}
#[test]
fn access_log_uses_resolved_client_ip() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.rate_limit.trust_xff = true;
cfg.middleware.rate_limit.trusted_proxies = vec!["127.0.0.1".to_string()];
let app = App::with_config(cfg).expect("配置合法");
let router = app.build_middleware_chain(axum::Router::new(), &[]);
let peer = SocketAddr::from(([127, 0, 0, 1], 23456));
let req = Request::builder()
.method("GET")
.uri("/api/probe")
.header("X-Forwarded-For", "9.9.9.9")
.extension(ConnectInfo(peer))
.body(Body::empty())
.expect("请求构建失败");
with_captured_logs(|events| {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("runtime 构建失败");
rt.block_on(async {
let _ = send(&router, req).await;
});
let events = events.lock().expect("events lock");
assert!(
events.iter().any(|e| e.contains("9.9.9.9")),
"访问日志未记录已解析 client IP: {:#?}",
*events
);
});
}
#[tokio::test]
async fn custom_middleware_inserted_by_priority() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.request_log = false;
let order: Arc<Mutex<Vec<&'static str>>> = Arc::new(Mutex::new(Vec::new()));
let seen_ip: Arc<Mutex<Option<bool>>> = Arc::new(Mutex::new(None));
let o1 = order.clone();
let s1 = seen_ip.clone();
let o2 = order.clone();
let app = App::with_config(cfg)
.expect("配置合法")
.middleware("custom_outer", 15, move |router| {
let o1 = o1.clone();
let s1 = s1.clone();
router.layer(axum::middleware::from_fn(
move |req: axum::extract::Request, next: axum::middleware::Next| {
let o1 = o1.clone();
let s1 = s1.clone();
async move {
o1.lock().unwrap().push("custom_outer");
*s1.lock().unwrap() =
Some(req.extensions().get::<mw::ClientIp>().is_some());
next.run(req).await
}
},
))
})
.middleware("custom_inner", 25, move |router| {
let o2 = o2.clone();
router.layer(axum::middleware::from_fn(
move |req: axum::extract::Request, next: axum::middleware::Next| {
let o2 = o2.clone();
async move {
o2.lock().unwrap().push("custom_inner");
next.run(req).await
}
},
))
});
let router = app.build_middleware_chain(
axum::Router::new().route("/probe", get(|| async { "ok" })),
&[],
);
let resp = send(&router, request("GET", "/probe")).await;
assert_eq!(resp.status(), StatusCode::OK);
assert_eq!(
*seen_ip.lock().unwrap(),
Some(true),
"优先级 15 的自定义层应位于 ClientIdentity 内侧(能读到 ClientIp)"
);
assert_eq!(
*order.lock().unwrap(),
vec!["custom_outer", "custom_inner"],
"执行顺序应按优先级升序(小者在外先执行)"
);
}
#[test]
fn parse_addr_variants() {
assert_eq!(parse_addr(":8080").unwrap(), "0.0.0.0:8080".parse().unwrap());
assert_eq!(parse_addr("8080").unwrap(), "0.0.0.0:8080".parse().unwrap());
assert_eq!(
parse_addr("127.0.0.1:9090").unwrap(),
"127.0.0.1:9090".parse().unwrap()
);
let e = parse_addr("1.2.3.4:notaport").unwrap_err();
assert!(matches!(e, wordval_core::Error::Config(_)));
assert!(e.to_string().contains("无效地址"), "{}", e);
assert!(parse_addr("127.0.0.1").unwrap_err().to_string().contains("无效地址"));
}
#[test]
fn resolve_display_addr_variants() {
assert_eq!(
resolve_display_addr("0.0.0.0:80".parse().unwrap()),
"127.0.0.1:80"
);
assert_eq!(
resolve_display_addr("[::]:8080".parse().unwrap()),
"127.0.0.1:8080"
);
assert_eq!(
resolve_display_addr("127.0.0.1:9".parse().unwrap()),
"127.0.0.1:9"
);
}
fn validate_of(cfg: AppConfig) -> Result<()> {
App::with_config(cfg).unwrap().validate_middleware_config()
}
fn cors_cfg(bad: fn(&mut wordval_config::CorsConfig)) -> AppConfig {
let mut cfg = AppConfig::default();
cfg.middleware.cors.enabled = true;
bad(&mut cfg.middleware.cors);
cfg
}
#[test]
fn validate_middleware_config_cors_rejects_and_accepts() {
assert!(App::default().validate_middleware_config().is_ok());
assert!(validate_of(AppConfig::default()).is_ok());
assert!(validate_of(cors_cfg(|c| {
c.allow_origins = vec!["http://a.com".into()];
c.allow_methods = vec!["GET".into(), "DELETE".into()];
c.allow_headers = vec!["x-token".into()];
}))
.is_ok());
let e = validate_of(cors_cfg(|c| c.allow_origins = vec!["bad\norigin".into()]))
.unwrap_err();
assert!(e.to_string().contains("allow_origins"), "{}", e);
let e = validate_of(cors_cfg(|c| c.allow_methods = vec!["GE T".into()])).unwrap_err();
assert!(e.to_string().contains("allow_methods"), "{}", e);
let e = validate_of(cors_cfg(|c| c.allow_headers = vec!["X Bad".into()])).unwrap_err();
assert!(e.to_string().contains("allow_headers"), "{}", e);
let e = validate_of(cors_cfg(|c| {
c.allow_credentials = true;
c.allow_origins = vec![];
}))
.unwrap_err();
assert!(e.to_string().contains("allow_credentials"), "{}", e);
}
#[test]
fn validate_middleware_config_auth_branch() {
let mut cfg = AppConfig::default();
cfg.middleware.auth.enabled = true;
cfg.middleware.nonce.enabled = true;
cfg.middleware.nonce.availability = "required".into();
let r = validate_of(cfg);
if cfg!(feature = "cache") {
} else {
let e = r.unwrap_err();
assert!(e.to_string().contains("cache"), "{}", e);
}
}
async fn preflight(cors: wordval_config::CorsConfig, origin: &str, acr_headers: Option<&str>) -> axum::response::Response {
let layer = App::build_cors_layer(&cors);
let router = axum::Router::new()
.route("/x", get(|| async { "ok" }))
.layer(layer);
let mut b = Request::builder()
.method("OPTIONS")
.uri("/x")
.header("Origin", origin)
.header("Access-Control-Request-Method", "GET");
if let Some(h) = acr_headers {
b = b.header("Access-Control-Request-Headers", h);
}
router.oneshot(b.body(Body::empty()).unwrap()).await.unwrap()
}
#[tokio::test]
async fn build_cors_layer_mirror_and_any_headers() {
let resp = preflight(
wordval_config::CorsConfig::default(),
"http://anywhere.example",
Some("x-foo,bar"),
)
.await;
assert_eq!(
resp.headers()
.get("access-control-allow-origin")
.and_then(|v| v.to_str().ok()),
Some("http://anywhere.example")
);
let ah = resp
.headers()
.get("access-control-allow-headers")
.and_then(|v| v.to_str().ok())
.unwrap_or_default()
.to_lowercase();
assert!(
ah.contains("x-foo") || ah.contains('*'),
"any headers 应回显请求头或返回 *: {}",
ah
);
assert!(
resp.headers()
.get("access-control-allow-credentials")
.is_none()
);
}
#[tokio::test]
async fn build_cors_layer_list_credentials_max_age() {
let cors = wordval_config::CorsConfig {
enabled: true,
allow_origins: vec!["http://a.com".into()],
allow_methods: vec!["PATCH".into()],
allow_headers: vec!["x-custom".into()],
allow_credentials: true,
..Default::default()
};
let resp = preflight(cors, "http://a.com", Some("x-custom")).await;
assert_eq!(
resp.headers()
.get("access-control-allow-origin")
.and_then(|v| v.to_str().ok()),
Some("http://a.com")
);
assert_eq!(
resp.headers()
.get("access-control-allow-credentials")
.and_then(|v| v.to_str().ok()),
Some("true")
);
let am = resp
.headers()
.get("access-control-allow-methods")
.and_then(|v| v.to_str().ok())
.unwrap_or_default();
assert!(am.contains("PATCH"), "{}", am);
assert!(resp
.headers()
.get("access-control-max-age")
.is_some());
let miss = preflight(
wordval_config::CorsConfig {
enabled: true,
allow_origins: vec!["http://a.com".into()],
..Default::default()
},
"http://evil.com",
None,
)
.await;
assert!(miss
.headers()
.get("access-control-allow-origin")
.is_none());
}
#[tokio::test]
async fn builder_route_group_merge_and_unknown_method() {
let mut sub = WordvalRouter::new();
sub.add_get("/sub", || async { "s" });
let mut sub2 = WordvalRouter::new();
sub2.add_get("/deep", || async { "d" });
let app = App::with_config(AppConfig::default())
.unwrap()
.parse_cli()
.get("/g", || async { "g" })
.post("/p", || async { "p" })
.put("/u", || async { "u" })
.delete("/d", || async { "d" })
.route("PATCH", "/pa", || async { "pa" })
.route("FOO", "/bad", || async { "bad" })
.group("/api/v2", |app| app.get("/users", || async { "users" }))
.merge("/m", sub)
.merge("noslash", sub2) .with_permission("GET", "/admin", || async { "a" }, "admin:access")
.with_role("GET", "/roles", || async { "r" }, "admin")
.scan()
.print_routes();
let routes = app.router.as_ref().unwrap().list_routes().to_vec();
let has = |m: &str, p: &str| {
routes
.iter()
.any(|r| r.method == m && r.path == p)
};
assert!(has("GET", "/g") && has("POST", "/p") && has("PUT", "/u"));
assert!(has("DELETE", "/d") && has("PATCH", "/pa"));
assert!(has("GET", "/api/v2/users"), "group 应拼接前缀");
assert!(has("GET", "/m/sub"), "merge 应拼接前缀");
assert!(has("GET", "/noslash/deep"), "无斜杠前缀应规范化为 /noslash/deep");
assert!(has("GET", "/admin") && has("GET", "/roles"));
assert!(!has("FOO", "/bad"), "未知方法不应注册");
let router: axum::Router = app.router.unwrap().into_axum();
let resp = send(&router, request("GET", "/g")).await;
assert_eq!(resp.status(), StatusCode::OK);
let resp = send(&router, request("GET", "/bad")).await;
assert_eq!(resp.status(), StatusCode::NOT_FOUND);
let resp = send(&router, request("GET", "/noslash/deep")).await;
assert_eq!(resp.status(), StatusCode::OK, "规范化前缀的 nest 应可分发");
}
#[test]
fn override_config_updates_config_and_prefix() {
let mut cfg = AppConfig::default();
cfg.router.prefix = "old".into();
let app = App::with_config(cfg).unwrap().override_config(|c| {
c.server.listen = "127.0.0.1:9000".into();
c.router.prefix = "v2".into();
c.upload.max_size_mb = 64;
c.middleware.cors.enabled = true;
});
let cm = app.config_mgr.as_ref().unwrap();
assert_eq!(cm.get().server.listen, "127.0.0.1:9000");
assert_eq!(app.prefix, "v2", "内部路由前缀应与覆盖后的配置同步");
assert_eq!(cm.get().upload.max_size_mb, 64);
assert!(cm.get().middleware.cors.enabled);
let app2 = App::default().override_config(|c| c.log.level = "debug".into());
assert_eq!(app2.config_mgr.as_ref().unwrap().get().log.level, "debug");
}
#[test]
fn parse_cli_with_receives_args_and_sets_flags() {
let mut seen = 0usize;
let app = App::default().parse_cli_with(|args| {
seen = args.len();
(false, false)
});
assert!(seen >= 1, "应传入含程序名的完整 argv");
assert!(!app.settings.gen_config_only);
assert!(!app.settings.print_config);
}
#[tokio::test]
async fn start_gen_config_only_writes_default_file() {
let dir = std::env::temp_dir().join(format!("wv_gen_cfg_app_{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
let mut app = App::with_config(AppConfig::default()).unwrap();
app.settings.gen_config_only = true;
app.settings.config_path = Some(dir.to_string_lossy().into_owned());
app.start().await.unwrap();
assert!(dir.join("config.toml").exists());
let _ = std::fs::remove_dir_all(&dir);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn start_reports_real_listening_addr() {
let captured: Arc<Mutex<Option<SocketAddr>>> = Arc::new(Mutex::new(None));
let c2 = captured.clone();
let app = App::default()
.get("/ping", || async { "pong" })
.on_listening(move |addr| *c2.lock().unwrap() = Some(addr));
let handle = tokio::spawn(app.start());
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
let addr = loop {
if let Some(a) = *captured.lock().unwrap() {
break a;
}
assert!(
std::time::Instant::now() < deadline,
"on_listening 回调未在 5s 内触发"
);
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
};
assert_ne!(addr.port(), 0, "回调应拿到内核分配的真实端口");
let resp = http_roundtrip(
addr.port(),
"GET /ping HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n",
)
.expect("服务应已就绪");
assert!(resp.contains("200 OK") && resp.contains("pong"), "{}", resp);
handle.abort();
}
struct DummyPlugin;
#[async_trait::async_trait]
impl wordval_core::Plugin for DummyPlugin {
fn name(&self) -> &str {
"dummy"
}
async fn start(&self) -> Result<()> {
Ok(())
}
async fn stop(&self) -> Result<()> {
Ok(())
}
}
fn http_roundtrip(port: u16, req: &str) -> std::io::Result<String> {
use std::io::{Read, Write};
let mut s = std::net::TcpStream::connect(("127.0.0.1", port))?;
s.set_read_timeout(Some(std::time::Duration::from_secs(5)))?;
s.write_all(req.as_bytes())?;
s.flush()?;
let mut buf = Vec::new();
s.read_to_end(&mut buf)?;
Ok(String::from_utf8_lossy(&buf).into_owned())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn serve_full_pipeline_with_prefix_and_not_found() {
let probe = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = probe.local_addr().unwrap().port();
drop(probe);
let mut cfg = AppConfig::default();
cfg.middleware.request_id = true;
cfg.middleware.security_headers.enabled = true;
cfg.middleware.compression.enabled = true;
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.router.prefix = "v9".into();
cfg.router.not_found.enabled = true;
cfg.static_files.enabled = false;
cfg.database.enabled = false;
cfg.cache.r#type = "local".into();
cfg.cache.max_capacity = 0;
let base = std::env::temp_dir().join(format!("wv_app_serve_{}", std::process::id()));
cfg.upload.path = base.join("up").to_string_lossy().into_owned();
cfg.download.path = base.join("dn").to_string_lossy().into_owned();
let flag = Arc::new(std::sync::atomic::AtomicBool::new(false));
let f2 = flag.clone();
let mut app = App::with_config(cfg)
.unwrap()
.on_startup(move || async move { f2.store(true, std::sync::atomic::Ordering::SeqCst); })
.plugin(DummyPlugin)
.get("/ping", || async { "pong" });
app.settings.print_config = true;
let handle = tokio::spawn(app.serve(format!("127.0.0.1:{}", port)));
let resp;
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
loop {
match http_roundtrip(
port,
"GET /v9/ping HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n",
) {
Ok(r) => {
resp = r;
break;
}
Err(_) if std::time::Instant::now() < deadline => {
tokio::time::sleep(std::time::Duration::from_millis(100)).await;
}
Err(e) => panic!("服务器未就绪: {}", e),
}
}
assert!(resp.contains("200 OK"), "{}", resp);
assert!(resp.contains("pong"));
let low = resp.to_lowercase();
assert!(low.contains("x-request-id"), "外壳层应覆盖真实响应");
assert!(low.contains("x-frame-options"));
assert!(flag.load(std::sync::atomic::Ordering::SeqCst));
let _ = http_roundtrip(
port,
"GET /v9/ping HTTP/1.1\r\nHost: x\r\nAccept-Encoding: gzip\r\nConnection: close\r\n\r\n",
);
let nf = http_roundtrip(
port,
"GET /v9/nope HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n",
)
.expect("404 请求");
assert!(nf.contains("404 Not Found"), "{}", nf);
assert!(nf.contains("\"code\""), "404 应返回 JSON 外壳: {}", nf);
handle.abort();
let _ = std::fs::remove_dir_all(&base);
}
#[test]
fn compression_enabled_and_request_log_excludes_path() {
let mut cfg = base_config();
cfg.middleware.auth.enabled = false;
cfg.middleware.permission.enabled = false;
cfg.middleware.compression.enabled = true;
cfg.middleware.request_log_config.exclude_paths = vec!["/health".to_string()];
let router = build(cfg);
with_captured_logs(|events| {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap();
rt.block_on(async {
let req = Request::builder()
.method("GET")
.uri("/probe2")
.header("accept-encoding", "gzip")
.body(Body::empty())
.unwrap();
let resp = send(&router, req).await;
assert_eq!(resp.status(), StatusCode::NOT_FOUND);
let _ = send(&router, request("GET", "/health")).await;
let _ = send(&router, request("GET", "/other")).await;
});
let events = events.lock().unwrap();
assert!(
!events.iter().any(|e| e.contains("/health")),
"排除路径不应记录访问日志: {:#?}",
*events
);
assert!(
events.iter().any(|e| e.contains("/other")),
"普通路径应记录访问日志: {:#?}",
*events
);
});
}
}