use crate::error::BaseError;
use crate::table::RegexCache;
use std::any::{type_name, Any, TypeId};
use std::collections::HashMap;
use std::fmt;
use std::sync::atomic::{AtomicU8, Ordering};
use tokio::sync::Mutex;
#[cfg(any(feature = "mysql", feature = "postgres"))]
use crate::database::{
AnyDatabase, Datasource, DatasourceHealth, DatasourcePoolStatus, DatasourceRegistry,
};
#[cfg(any(feature = "mysql", feature = "postgres"))]
use crate::datasource::DatasourceId;
#[cfg(feature = "http")]
use crate::http::HttpClient;
#[cfg(feature = "token")]
use crate::token::TokenManager;
#[cfg(any(feature = "mysql", feature = "postgres"))]
use yang_db::BackendCapability;
#[cfg(feature = "redis")]
use yang_db::RedisClient;
const RUNNING: u8 = 0;
const CLOSING: u8 = 1;
const CLOSED: u8 = 2;
#[cfg(any(feature = "mysql", feature = "postgres"))]
const REQUIRED_DATABASE_CAPABILITIES: &[BackendCapability] = &[
BackendCapability::CheckedIdentifiers,
BackendCapability::Select,
BackendCapability::Aggregate,
BackendCapability::Join,
BackendCapability::Insert,
BackendCapability::BatchInsert,
BackendCapability::Update,
BackendCapability::BatchUpdate,
BackendCapability::Delete,
BackendCapability::Upsert,
BackendCapability::BatchUpsert,
BackendCapability::TransactionCrud,
];
type TypeMap = HashMap<TypeId, Box<dyn Any + Send + Sync>>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolsState {
Running,
Closing,
Closed,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResourceHealth {
pub resource: &'static str,
pub healthy: bool,
pub detail: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToolsHealth {
pub state: ToolsState,
pub resources: Vec<ResourceHealth>,
}
impl ToolsHealth {
pub fn is_healthy(&self) -> bool {
self.state == ToolsState::Running && self.resources.iter().all(|item| item.healthy)
}
}
pub struct Tools {
#[cfg(any(feature = "mysql", feature = "postgres"))]
databases: Option<DatasourceRegistry>,
#[cfg(feature = "redis")]
cache: Option<RedisClient>,
#[cfg(feature = "token")]
token: Option<TokenManager>,
#[cfg(feature = "http")]
http: Option<HttpClient>,
regex_cache: RegexCache,
extensions: TypeMap,
config: TypeMap,
state: AtomicU8,
close_lock: Mutex<()>,
}
impl fmt::Debug for Tools {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Tools")
.field("state", &self.state())
.field("extension_count", &self.extensions.len())
.field("config_count", &self.config.len())
.finish_non_exhaustive()
}
}
impl Tools {
pub fn state(&self) -> ToolsState {
match self.state.load(Ordering::Acquire) {
RUNNING => ToolsState::Running,
CLOSING => ToolsState::Closing,
_ => ToolsState::Closed,
}
}
fn ensure_running(&self) -> Result<(), BaseError> {
match self.state() {
ToolsState::Running => Ok(()),
ToolsState::Closing => Err(BaseError::ConfigError("Tools 正在关闭".to_string())),
ToolsState::Closed => Err(BaseError::ConfigError("Tools 已关闭".to_string())),
}
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn database(&self) -> Result<&AnyDatabase, BaseError> {
self.ensure_running()?;
self.databases
.as_ref()
.map(|databases| databases.default_datasource().database())
.ok_or(BaseError::DatabaseNotInitialized)
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn datasource(&self, id: &DatasourceId) -> Result<&crate::database::Datasource, BaseError> {
self.ensure_running()?;
let databases = self
.databases
.as_ref()
.ok_or(BaseError::DatabaseNotInitialized)?;
databases.resolve_id(id)
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn database_named(&self, id: &DatasourceId) -> Result<&AnyDatabase, BaseError> {
self.datasource(id).map(|datasource| datasource.database())
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn datasources(&self) -> Result<&DatasourceRegistry, BaseError> {
self.ensure_running()?;
self.databases
.as_ref()
.ok_or(BaseError::DatabaseNotInitialized)
}
#[cfg(feature = "mysql")]
pub fn mysql(&self) -> Result<&yang_db::mysql::Database, BaseError> {
self.database()
.and_then(|database| database.as_mysql().ok_or(BaseError::DatabaseNotInitialized))
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn pool_status(&self) -> Option<yang_db::PoolStatus> {
self.databases
.as_ref()
.map(|databases| databases.default_datasource().pool_status())
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn pool_statuses(&self) -> Vec<DatasourcePoolStatus> {
self.databases
.as_ref()
.map(DatasourceRegistry::pool_statuses)
.unwrap_or_default()
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub async fn datasource_health(&self) -> Vec<DatasourceHealth> {
match &self.databases {
Some(databases) if self.state() == ToolsState::Running => databases.health().await,
_ => Vec::new(),
}
}
#[cfg(feature = "redis")]
pub fn cache(&self) -> Result<&RedisClient, BaseError> {
self.ensure_running()?;
self.cache.as_ref().ok_or(BaseError::RedisNotInitialized)
}
#[cfg(feature = "token")]
pub fn token(&self) -> Result<&TokenManager, BaseError> {
self.ensure_running()?;
self.token
.as_ref()
.ok_or_else(|| BaseError::ConfigError("Tools 未配置 TokenManager".to_string()))
}
#[cfg(feature = "http")]
pub fn http(&self) -> Result<&HttpClient, BaseError> {
self.ensure_running()?;
self.http
.as_ref()
.ok_or(BaseError::HttpClientNotInitialized)
}
pub fn regex_cache(&self) -> &RegexCache {
&self.regex_cache
}
pub fn extension<T>(&self) -> Result<&T, BaseError>
where
T: Any + Send + Sync,
{
self.ensure_running()?;
self.extensions
.get(&TypeId::of::<T>())
.and_then(|value| value.downcast_ref::<T>())
.ok_or_else(|| {
BaseError::ConfigError(format!("Tools 未配置扩展: {}", type_name::<T>()))
})
}
pub fn config<T>(&self) -> Result<&T, BaseError>
where
T: Any + Send + Sync,
{
self.ensure_running()?;
self.config
.get(&TypeId::of::<T>())
.and_then(|value| value.downcast_ref::<T>())
.ok_or_else(|| {
BaseError::ConfigError(format!("Tools 未配置配置类型: {}", type_name::<T>()))
})
}
pub async fn health_check(&self) -> ToolsHealth {
let state = self.state();
if state != ToolsState::Running {
return ToolsHealth {
state,
resources: Vec::new(),
};
}
#[cfg(any(feature = "mysql", feature = "postgres", feature = "redis"))]
let mut resources = Vec::new();
#[cfg(not(any(feature = "mysql", feature = "postgres", feature = "redis")))]
let resources = Vec::new();
#[cfg(any(feature = "mysql", feature = "postgres"))]
if let Some(databases) = &self.databases {
resources.extend(databases.health_check().await);
}
#[cfg(feature = "redis")]
if let Some(cache) = &self.cache {
resources.push(match cache.health_check().await {
Ok(healthy) => ResourceHealth {
resource: "cache",
healthy,
detail: None,
},
Err(error) => ResourceHealth {
resource: "cache",
healthy: false,
detail: Some(error.to_string()),
},
});
}
ToolsHealth { state, resources }
}
pub async fn close(&self) {
let _guard = self.close_lock.lock().await;
if self.state() == ToolsState::Closed {
return;
}
self.state.store(CLOSING, Ordering::Release);
#[cfg(feature = "redis")]
if let Some(cache) = &self.cache {
cache.close().await;
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
if let Some(databases) = &self.databases {
databases.close().await;
}
self.state.store(CLOSED, Ordering::Release);
}
}
#[derive(Default)]
#[must_use = "ToolsBuilder 必须调用 build() 才会冻结并交给应用"]
pub struct ToolsBuilder {
#[cfg(any(feature = "mysql", feature = "postgres"))]
databases: Vec<Datasource>,
#[cfg(any(feature = "mysql", feature = "postgres"))]
default_datasource: Option<DatasourceId>,
#[cfg(feature = "redis")]
cache: Option<RedisClient>,
#[cfg(feature = "token")]
token: Option<TokenManager>,
#[cfg(feature = "http")]
http: Option<HttpClient>,
regex_cache: RegexCache,
extensions: TypeMap,
config: TypeMap,
duplicate: Option<String>,
}
impl fmt::Debug for ToolsBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ToolsBuilder")
.field("extension_count", &self.extensions.len())
.field("config_count", &self.config.len())
.field("duplicate", &self.duplicate)
.finish_non_exhaustive()
}
}
impl ToolsBuilder {
pub fn new() -> Self {
Self::default()
}
#[cfg(feature = "mysql")]
pub fn mysql(self, mysql: yang_db::mysql::Database) -> Self {
self.database_named(DatasourceId::default_source(), AnyDatabase::mysql(mysql))
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn database(self, database: AnyDatabase) -> Self {
self.database_named(DatasourceId::default_source(), database)
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn database_named(mut self, id: DatasourceId, database: AnyDatabase) -> Self {
if id.is_default() && self.default_datasource.is_none() {
self.default_datasource = Some(id.clone());
}
self.databases.push(Datasource::new(id, database, true));
self
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn database_named_with_policy(
mut self,
id: DatasourceId,
database: AnyDatabase,
required: bool,
) -> Self {
if id.is_default() && self.default_datasource.is_none() {
self.default_datasource = Some(id.clone());
}
self.databases.push(Datasource::new(id, database, required));
self
}
#[cfg(feature = "mysql")]
pub fn mysql_named(self, id: DatasourceId, database: yang_db::mysql::Database) -> Self {
self.database_named(id, AnyDatabase::mysql(database))
}
#[cfg(feature = "postgres")]
pub fn postgres_named(self, id: DatasourceId, database: yang_db::postgres::Database) -> Self {
self.database_named(id, AnyDatabase::postgres(database))
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
pub fn default_datasource(mut self, id: DatasourceId) -> Self {
self.default_datasource = Some(id);
self
}
#[cfg(feature = "redis")]
pub fn cache(mut self, cache: RedisClient) -> Self {
if self.cache.replace(cache).is_some() {
self.record_duplicate("RedisClient");
}
self
}
#[cfg(feature = "redis")]
pub async fn cache_from_url(
self,
url: impl Into<String>,
config: yang_db::RedisConfig,
) -> Result<Self, BaseError> {
let client = RedisClient::connect_with_config(url, config)
.await
.map_err(BaseError::RedisConnectionFailed)?;
Ok(self.cache(client))
}
#[cfg(feature = "token")]
pub fn token(mut self, token: TokenManager) -> Self {
if self.token.replace(token).is_some() {
self.record_duplicate("TokenManager");
}
self
}
#[cfg(feature = "http")]
pub fn http(mut self, client: HttpClient) -> Self {
if self.http.replace(client).is_some() {
self.record_duplicate("HttpClient");
}
self
}
pub fn regex_cache(mut self, cache: RegexCache) -> Self {
self.regex_cache = cache;
self
}
pub fn extension<T>(mut self, extension: T) -> Self
where
T: Any + Send + Sync,
{
if self
.extensions
.insert(TypeId::of::<T>(), Box::new(extension))
.is_some()
{
self.record_duplicate(type_name::<T>());
}
self
}
pub fn config<T>(mut self, config: T) -> Self
where
T: Any + Send + Sync,
{
if self
.config
.insert(TypeId::of::<T>(), Box::new(config))
.is_some()
{
self.record_duplicate(type_name::<T>());
}
self
}
fn record_duplicate(&mut self, resource: &str) {
if self.duplicate.is_none() {
self.duplicate = Some(resource.to_string());
}
}
pub fn build(self) -> Result<Tools, BaseError> {
if let Some(resource) = self.duplicate {
return Err(BaseError::ConfigError(format!(
"Tools 资源重复注册: {resource}"
)));
}
#[cfg(any(feature = "mysql", feature = "postgres"))]
let databases = if self.databases.is_empty() {
if let Some(default) = &self.default_datasource {
return Err(BaseError::ConfigError(format!(
"指定了默认数据源 {default},但没有注册任何数据源"
)));
}
None
} else {
let registry =
DatasourceRegistry::new(self.default_datasource.clone(), self.databases)?;
for datasource in registry.iter() {
datasource
.database()
.require_capabilities(REQUIRED_DATABASE_CAPABILITIES)?;
}
Some(registry)
};
#[cfg(feature = "token")]
let token = {
let mut token = self.token;
if let (Some(token), Some(cache)) = (&mut token, &self.cache) {
token.attach_revocation_cache(cache.clone());
}
token
};
Ok(Tools {
#[cfg(any(feature = "mysql", feature = "postgres"))]
databases,
#[cfg(feature = "redis")]
cache: self.cache,
#[cfg(feature = "token")]
token,
#[cfg(feature = "http")]
http: self.http,
regex_cache: self.regex_cache,
extensions: self.extensions,
config: self.config,
state: AtomicU8::new(RUNNING),
close_lock: Mutex::new(()),
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Debug, PartialEq, Eq)]
struct TestExtension(u32);
#[derive(Debug, PartialEq, Eq)]
struct TestConfig(&'static str);
#[test]
fn typed_entries_are_frozen_and_separate() {
let tools = ToolsBuilder::new()
.extension(TestExtension(7))
.config(TestConfig("local"))
.build()
.expect("类型化资源应构建成功");
assert_eq!(
tools.extension::<TestExtension>().expect("扩展应存在"),
&TestExtension(7)
);
assert_eq!(
tools.config::<TestConfig>().expect("配置应存在"),
&TestConfig("local")
);
assert!(tools.extension::<TestConfig>().is_err());
assert!(tools.config::<TestExtension>().is_err());
}
#[test]
fn duplicate_type_is_rejected_at_build_time() {
let result = ToolsBuilder::new()
.extension(TestExtension(1))
.extension(TestExtension(2))
.build();
assert!(
matches!(result, Err(BaseError::ConfigError(message)) if message.contains("重复注册"))
);
}
#[tokio::test]
async fn close_is_idempotent_and_changes_health_semantics() {
let tools = ToolsBuilder::new()
.build()
.expect("空资源集合可用于纯逻辑测试");
assert!(tools.health_check().await.is_healthy());
tools.close().await;
tools.close().await;
let health = tools.health_check().await;
assert_eq!(health.state, ToolsState::Closed);
assert!(!health.is_healthy());
assert!(matches!(
tools.extension::<TestExtension>(),
Err(BaseError::ConfigError(message)) if message == "Tools 已关闭"
));
}
#[cfg(feature = "http")]
fn test_http_client() -> crate::http::HttpClient {
crate::http::HttpClient::new(30).expect("测试 HTTP 客户端应创建成功")
}
#[cfg(feature = "http")]
#[test]
fn http_slot_returns_client_when_configured() {
let tools = ToolsBuilder::new()
.http(test_http_client())
.build()
.expect("配置 HTTP 客户端后应构建成功");
let client = tools.http().expect("已配置时应返回 HTTP 客户端");
let _builder = client.get("https://api.example.com/test");
}
#[cfg(feature = "http")]
#[test]
fn http_slot_errors_when_not_configured() {
let tools = ToolsBuilder::new().build().expect("空资源集合应构建成功");
assert!(matches!(
tools.http(),
Err(BaseError::HttpClientNotInitialized)
));
}
#[cfg(feature = "http")]
#[test]
fn http_slot_duplicate_registration_is_rejected_at_build_time() {
let result = ToolsBuilder::new()
.http(test_http_client())
.http(test_http_client())
.build();
assert!(
matches!(result, Err(BaseError::ConfigError(message)) if message.contains("重复注册"))
);
}
#[cfg(feature = "http")]
#[tokio::test]
async fn http_slot_errors_after_close() {
let tools = ToolsBuilder::new()
.http(test_http_client())
.build()
.expect("配置 HTTP 客户端后应构建成功");
tools.close().await;
assert!(matches!(
tools.http(),
Err(BaseError::ConfigError(message)) if message == "Tools 已关闭"
));
}
#[cfg(feature = "mysql")]
fn test_mysql_pool() -> yang_db::mysql::Database {
let pool = sqlx::MySqlPool::connect_lazy("mysql://root:test@127.0.0.1:3306/test")
.expect("惰性 MySQL 连接池应创建成功");
yang_db::mysql::Database::from_pool(pool, yang_db::mysql::DatabaseConfig::default())
.expect("默认 MySQL 配置应通过校验")
}
#[cfg(feature = "mysql")]
fn test_mysql_database() -> AnyDatabase {
AnyDatabase::mysql(test_mysql_pool())
}
#[cfg(feature = "postgres")]
fn test_postgres_pool() -> yang_db::postgres::Database {
let pool = sqlx::PgPool::connect_lazy("postgres://postgres:postgres@127.0.0.1:55432/test")
.expect("惰性 PostgreSQL 连接池应创建成功");
yang_db::postgres::Database::from_pool(pool, yang_db::postgres::DatabaseConfig::default())
.expect("默认 PostgreSQL 配置应通过校验")
}
#[cfg(feature = "postgres")]
fn test_postgres_database() -> AnyDatabase {
AnyDatabase::postgres(test_postgres_pool())
}
#[cfg(feature = "mysql")]
#[tokio::test]
async fn mysql_handler_reports_backend_and_pool_status() {
let tools = ToolsBuilder::new()
.mysql(test_mysql_pool())
.build()
.expect("配置 MySQL 后应构建成功");
assert_eq!(
tools.database().expect("数据库应存在").backend(),
yang_db::BackendKind::MySql
);
assert!(tools.mysql().is_ok());
assert!(tools.pool_status().is_some());
assert!(tools.database().expect("数据库应存在").as_mysql().is_some());
}
#[cfg(feature = "postgres")]
#[tokio::test]
async fn postgres_handler_reports_backend_and_pool_status() {
let tools = ToolsBuilder::new()
.database(test_postgres_database())
.build()
.expect("配置 PostgreSQL 后应构建成功");
assert_eq!(
tools.database().expect("数据库应存在").backend(),
yang_db::BackendKind::PostgreSql
);
assert!(tools.pool_status().is_some());
assert!(tools
.database()
.expect("数据库应存在")
.as_postgres()
.is_some());
}
#[cfg(feature = "mysql")]
#[tokio::test]
async fn database_slot_errors_after_close() {
let tools = ToolsBuilder::new()
.database(test_mysql_database())
.build()
.expect("配置数据库后应构建成功");
tools.close().await;
assert!(matches!(
tools.database(),
Err(BaseError::ConfigError(message)) if message == "Tools 已关闭"
));
}
#[cfg(feature = "mysql")]
#[tokio::test]
async fn duplicate_database_registration_is_rejected_at_build_time() {
let result = ToolsBuilder::new()
.database(test_mysql_database())
.database(test_mysql_database())
.build();
assert!(
matches!(result, Err(BaseError::ConfigError(message)) if message.contains("重复注册"))
);
}
#[cfg(all(feature = "mysql", feature = "postgres"))]
#[tokio::test]
async fn mysql_accessor_rejects_postgres_backend() {
let tools = ToolsBuilder::new()
.database(test_postgres_database())
.build()
.expect("配置 PostgreSQL 后应构建成功");
assert_eq!(
tools.database().expect("数据库应存在").backend(),
yang_db::BackendKind::PostgreSql
);
assert!(matches!(
tools.mysql(),
Err(BaseError::DatabaseNotInitialized)
));
assert!(tools
.database()
.expect("数据库应存在")
.as_postgres()
.is_some());
}
}