cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/services/infrasrv/domain/hooks/builtin_hooks.py

@@ -0,0 +1,308 @@
+"""
+预注册钩子
+使用预注册钩子机制扩展服务注册功能
+"""
+from typing import (
+    Dict,
+    Any,
+)
+from datetime import (
+    datetime,
+    timezone,
+)
+
+from .pre_registration_hooks import (
+    BaseHook,
+    HookResult,
+    HookPriority,
+    HookContext,
+    HookExecutionResult,
+)
+from .hook_registry import get_hook_manager
+from linglong_web.utils import logger
+
+
+class ServiceNameValidationHook(BaseHook):
+    """服务名称验证钩子
+    
+    验证服务名称是否符合规范
+    """
+
+    def __init__(self):
+        super().__init__("service_name_validation", HookPriority.HIGH)
+
+    async def execute(self, context: HookContext) -> HookExecutionResult:
+        service_name = context.service_name
+
+        # 验证服务名称不为空
+        if not service_name or not service_name.strip():
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message="Service name cannot be empty"
+            )
+
+        # 验证服务名称格式（只允许字母、数字、下划线和连字符）
+        import re
+        if not re.match(r'^[a-zA-Z0-9_-]+$', service_name):
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message="Service name can only contain letters, numbers, underscores and hyphens"
+            )
+
+        # 验证服务名称长度
+        if len(service_name) > 50:
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message="Service name too long (max 50 characters)"
+            )
+
+        return HookExecutionResult(
+            hook_name=self.name,
+            result=HookResult.SUCCESS,
+            message="Service name validation passed"
+        )
+
+
+class HostValidationHook(BaseHook):
+    """主机地址验证钩子
+    
+    验证主机地址是否有效
+    """
+
+    def __init__(self):
+        super().__init__("host_validation", HookPriority.HIGH)
+
+    async def execute(self, context: HookContext) -> HookExecutionResult:
+        host = context.host
+
+        # 验证主机地址不为空
+        if not host or not host.strip():
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message="Host cannot be empty"
+            )
+
+        # 拒绝无效的主机地址
+        invalid_hosts = ["unknown", "localhost", "127.0.0.1", "0.0.0.0"]
+        if host.lower() in invalid_hosts:
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message=f"Invalid host '{host}'. Please configure proper hostname in docker-compose.yml"
+            )
+
+        return HookExecutionResult(
+            hook_name=self.name,
+            result=HookResult.SUCCESS,
+            message="Host validation passed"
+        )
+
+
+class MetadataEnrichmentHook(BaseHook):
+    """元数据增强钩子
+    
+    为服务实例添加额外的元数据
+    """
+
+    def __init__(self):
+        super().__init__("metadata_enrichment", HookPriority.NORMAL)
+
+    async def execute(self, context: HookContext) -> HookExecutionResult:
+        # 获取现有元数据
+        metadata = context.metadata
+        if not isinstance(metadata, dict):
+            metadata = {}
+
+        # 添加注册时间戳
+        metadata["registered_at"] = datetime.now(timezone.utc).isoformat()
+
+        # 添加注册来源标识
+        metadata["registered_by"] = "infrasrv"
+
+        # 添加服务类型标识（根据服务名称推断）
+        service_name = context.service_name
+        if "bff" in service_name.lower():
+            metadata["service_type"] = "backend-for-frontend"
+        elif "srv" in service_name.lower():
+            metadata["service_type"] = "microservice"
+        else:
+            metadata["service_type"] = "unknown"
+
+        # Pydantic models are mutable by default, modifying directly
+        context.metadata = metadata
+
+        return HookExecutionResult(
+            hook_name=self.name,
+            result=HookResult.SUCCESS,
+            message="Metadata enriched successfully"
+        )
+
+
+class PortRangeValidationHook(BaseHook):
+    """端口范围验证钩子
+    
+    验证端口号是否在有效范围内
+    """
+
+    def __init__(self):
+        super().__init__("port_range_validation", HookPriority.NORMAL)
+
+    async def execute(self, context: HookContext) -> HookExecutionResult:
+        port = context.port
+
+        # 验证端口号是否为整数
+        if not isinstance(port, int):
+            try:
+                port = int(port)
+            except (ValueError, TypeError):
+                return HookExecutionResult(
+                    hook_name=self.name,
+                    result=HookResult.FAILURE,
+                    message="Port must be a valid integer"
+                )
+
+        # 验证端口范围
+        if port < 1024 or port > 65535:
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message="Port must be between 1024 and 65535"
+            )
+
+        return HookExecutionResult(
+            hook_name=self.name,
+            result=HookResult.SUCCESS,
+            message="Port validation passed"
+        )
+
+
+class ServiceQuotaHook(BaseHook):
+    """服务配额检查钩子
+    
+    检查服务实例数量是否超过配额限制
+    """
+
+    def __init__(self):
+        super().__init__("service_quota", HookPriority.LOW)
+        # 服务配额配置
+        self.service_quotas = {
+            "default": 10,  # 默认每个服务最多 10 个实例
+        }
+
+    async def execute(self, context: HookContext) -> HookExecutionResult:
+        service_name = context.service_name
+
+        # 获取服务配额
+        quota = self.service_quotas.get(service_name, self.service_quotas["default"])
+
+        # 查询 service registry 中该服务当前已注册的实例数量（真实计数）
+        from cancan_microstack.services.infrasrv.infrastructure.db.operate.service_instance_op import (
+            count_instances_by_service,
+        )
+        current_instances = await count_instances_by_service(service_name)
+
+        if current_instances >= quota:
+            return HookExecutionResult(
+                hook_name=self.name,
+                result=HookResult.FAILURE,
+                message=f"Service '{service_name}' has reached its quota of {quota} instances"
+            )
+
+        return HookExecutionResult(
+            hook_name=self.name,
+            result=HookResult.SUCCESS,
+            message=f"Service quota check passed ({current_instances}/{quota})"
+        )
+
+
+# 函数钩子示例
+def function_based_validation_hook(context: HookContext) -> tuple:
+    """基于函数的验证钩子示例
+    
+    验证实例ID格式
+    """
+    instance_id = context.instance_id
+
+    # 验证实例ID格式
+    if "-" not in instance_id:
+        return HookResult.FAILURE, "Instance ID must contain a hyphen (-)"
+
+    return HookResult.SUCCESS, "Instance ID validation passed"
+
+
+# 注册所有钩子
+def register_all_hooks():
+    """注册所有预注册钩子"""
+    hook_manager = get_hook_manager()
+    hook_manager.register_hook(ServiceNameValidationHook())
+    hook_manager.register_hook(HostValidationHook())
+    hook_manager.register_hook(MetadataEnrichmentHook())
+    hook_manager.register_hook(PortRangeValidationHook())
+    hook_manager.register_hook(ServiceQuotaHook())
+
+    logger.info("All pre-registration hooks registered successfully")
+
+
+def register_default_hooks(hook_manager):
+    """
+    注册默认的预注册钩子
+    
+    Args:
+        hook_manager: 钩子管理器实例
+    """
+    # 注册服务名称验证钩子
+    hook_manager.register_hook(ServiceNameValidationHook())
+
+    # 注册主机地址验证钩子
+    hook_manager.register_hook(HostValidationHook())
+
+    # 注册元数据增强钩子
+    hook_manager.register_hook(MetadataEnrichmentHook())
+
+    # 注册端口范围验证钩子
+    hook_manager.register_hook(PortRangeValidationHook())
+
+    # 注册服务配额检查钩子
+    hook_manager.register_hook(ServiceQuotaHook())
+
+    logger.info("All default pre-registration hooks have been registered")
+
+
+# 示例：动态添加钩子
+def add_custom_validation_hook(hook_manager, validation_func):
+    """
+    动态添加自定义验证钩子
+    
+    Args:
+        hook_manager: 钩子管理器实例
+        validation_func: 验证函数，接收service_info参数，返回(bool, str)元组
+    """
+
+    def custom_hook(context):
+        # 简单示例，实际需要根据validation_func的实现调整
+        return HookResult.SUCCESS, "Custom validation passed"
+
+    hook_manager.register_hook(custom_hook)
+    logger.info("Custom validation hook has been registered")
+
+
+# 示例：动态移除钩子
+def remove_hook_by_type(hook_manager, hook_type):
+    """
+    根据钩子类型移除钩子
+    
+    Args:
+        hook_manager: 钩子管理器实例
+        hook_type: 要移除的钩子类型
+    """
+    hooks = hook_manager.get_hooks()
+    for hook in hooks:
+        if type(hook) == hook_type:
+            hook_manager.unregister_hook(hook.name)
+            logger.info(f"Removed hook of type {hook_type.__name__}")
+            return True
+    return False

cancan_microstack/services/infrasrv/domain/hooks/hook_registry.py

@@ -0,0 +1,43 @@
+"""
+钩子注册表 (Hook Registry)
+
+提供全局唯一的 HookManager 实例和钩子注册功能。
+这是整个 Hook 机制的入口点和管理中心。
+"""
+
+from typing import (
+    Optional,
+)
+from .pre_registration_hooks import HookManager
+
+# 全局唯一的 HookManager 实例变量。
+# 使用 Optional 类型，并初始化为 None，以支持懒加载（lazy loading）。
+_hook_manager: Optional[HookManager] = None
+
+
+def get_hook_manager() -> HookManager:
+    """
+    获取全局唯一的 HookManager 实例。
+
+    采用单例模式（Singleton Pattern），确保在整个应用生命周期中，
+    只有一个 HookManager 实例存在。
+    如果实例不存在，则会创建一个新的实例。
+
+    :return: 返回 HookManager 的全局实例。
+    """
+    global _hook_manager
+    if _hook_manager is None:
+        _hook_manager = HookManager()
+    return _hook_manager
+
+
+def reset_hook_manager():
+    """
+    重置全局的 HookManager 实例。
+
+    这个函数主要用于测试目的。在单元测试或集成测试中，
+    可能需要在不同的测试用例之间隔离状态，
+    通过重置 HookManager 可以确保每个测试用例都有一个干净的钩子环境。
+    """
+    global _hook_manager
+    _hook_manager = None

cancan_microstack/services/infrasrv/domain/hooks/hooks_log_utils.py

@@ -0,0 +1,275 @@
+"""
+Hooks 日志工具函数
+
+提供与钩子相关的日志格式化功能，用于在 hooks 领域层中处理日志输出。
+"""
+from typing import (
+    Optional,
+    Dict,
+    Any,
+)
+import logging
+from datetime import (
+    datetime,
+    timezone,
+)
+
+from cancan_microstack.public.schemas.infra.hook_log import (
+    HookLogData,
+    HookInfo,
+)
+from cancan_microstack.public.const.hook_enums import HookLogAction, SensitiveFieldKey
+
+
+def _sanitize_context(context_data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """
+    清洗上下文数据，移除敏感信息和限制字段长度
+    Sanitize context data, remove sensitive info and limit field length
+    
+    Args:
+        context_data: 原始上下文数据 / Original context data
+        
+    Returns:
+        清洗后的上下文数据 / Sanitized context data
+    """
+    if not context_data:
+        return None
+
+    sanitized_context = {}
+    for key, value in context_data.items():
+        # 检查是否为敏感字段 / Check if sensitive field
+        if key.lower() in [field.value for field in SensitiveFieldKey]:
+            sanitized_context[key] = "***REDACTED***"
+        else:
+            # 限制值的长度，防止日志过大 / Limit value length to prevent large logs
+            if isinstance(value, str) and len(value) > 100:
+                sanitized_context[key] = value[:97] + "..."
+            else:
+                sanitized_context[key] = value
+
+    return sanitized_context
+
+
+def create_hook_log_data(
+        hook_name: str,
+        hook_type: str,
+        message: str,
+        priority: Optional[str] = None,
+        context_data: Optional[Dict[str, Any]] = None,
+        execution_time: Optional[float] = None,
+        error: Optional[str] = None,
+        rejection_reason: Optional[str] = None,
+        modifications: Optional[Dict[str, Any]] = None
+) -> HookLogData:
+    """
+    创建钩子日志数据模型
+    Create hook log data model
+    
+    Args:
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        message: 日志消息 / Log message
+        priority: 钩子优先级（可选）/ Hook priority (optional)
+        context_data: 上下文数据（可选）/ Context data (optional)
+        execution_time: 执行时间（可选）/ Execution time (optional)
+        error: 错误信息（可选）/ Error message (optional)
+        rejection_reason: 拒绝原因（可选）/ Rejection reason (optional)
+        modifications: 修改内容（可选）/ Modifications (optional)
+        
+    Returns:
+        HookLogData: 钩子日志数据模型实例 / Hook log data model instance
+    """
+    hook_info = HookInfo(name=hook_name, type=hook_type, priority=priority)
+
+    return HookLogData(
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        hook=hook_info,
+        message=message,
+        context=_sanitize_context(context_data),
+        execution_time=execution_time,
+        error=error,
+        rejection_reason=rejection_reason,
+        modifications=modifications
+    )
+
+
+def log_hook_registration(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str
+) -> None:
+    """
+    记录钩子注册日志 / Log hook registration
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.REGISTERED
+    )
+    logger.info(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_deregistration(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str
+) -> None:
+    """
+    记录钩子注销日志 / Log hook deregistration
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.DEREGISTERED
+    )
+    logger.info(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_execution_start(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str,
+        metadata: Dict[str, Any]
+) -> None:
+    """
+    记录钩子执行开始日志 / Log hook execution start
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        metadata: 元数据 / Metadata
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.EXECUTION_STARTED,
+        context_data=metadata
+    )
+    logger.info(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_execution_success(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str,
+        execution_time: float,
+        metadata: Dict[str, Any]
+) -> None:
+    """
+    记录钩子执行成功日志 / Log hook execution success
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        execution_time: 执行时间（秒）/ Execution time (seconds)
+        metadata: 元数据 / Metadata
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.EXECUTION_SUCCESS,
+        context_data=metadata,
+        execution_time=execution_time
+    )
+    logger.info(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_execution_failure(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str,
+        execution_time: float,
+        error_msg: str,
+        metadata: Dict[str, Any],
+        exception: Optional[Exception] = None
+) -> None:
+    """
+    记录钩子执行失败日志 / Log hook execution failure
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        execution_time: 执行时间（秒）/ Execution time (seconds)
+        error_msg: 错误信息 / Error message
+        metadata: 元数据 / Metadata
+        exception: 异常对象（可选）/ Exception object (optional)
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.EXECUTION_FAILURE,
+        context_data=metadata,
+        execution_time=execution_time,
+        error=error_msg
+    )
+    if exception:
+        logger.error(log_data.model_dump_json(exclude_none=True), exc_info=exception)
+    else:
+        logger.error(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_rejection(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str,
+        reason: str,
+        metadata: Dict[str, Any]
+) -> None:
+    """
+    记录钩子拒绝服务注册日志 / Log hook rejection
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        reason: 拒绝原因 / Rejection reason
+        metadata: 元数据 / Metadata
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.REJECTION,
+        context_data=metadata,
+        rejection_reason=reason
+    )
+    logger.warning(log_data.model_dump_json(exclude_none=True))
+
+
+def log_hook_service_modification(
+        logger: logging.Logger,
+        hook_name: str,
+        hook_type: str,
+        modifications: Dict[str, Any],
+        metadata: Dict[str, Any]
+) -> None:
+    """
+    记录钩子修改服务信息日志 / Log hook service modification
+    
+    Args:
+        logger: 日志记录器实例 / Logger instance
+        hook_name: 钩子名称 / Hook name
+        hook_type: 钩子类型 / Hook type
+        modifications: 修改的内容 / Modifications
+        metadata: 元数据 / Metadata
+    """
+    log_data = create_hook_log_data(
+        hook_name=hook_name,
+        hook_type=hook_type,
+        message=HookLogAction.MODIFICATION,
+        context_data=metadata,
+        modifications=modifications
+    )
+    logger.info(log_data.model_dump_json(exclude_none=True))

cancan_microstack/services/infrasrv/domain/hooks/init.py

@@ -0,0 +1,17 @@
+"""
+钩子初始化模块
+负责在服务启动时注册所有预定义的钩子
+"""
+from .builtin_hooks import register_all_hooks
+
+from linglong_web.utils import logger
+
+
+def initialize_hooks():
+    """初始化所有钩子"""
+    try:
+        register_all_hooks()
+        logger.info("Hooks initialization completed successfully")
+    except Exception as e:
+        logger.error(f"Failed to initialize hooks: {e}")
+        raise