cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/public/schemas/caddy/analysis.py

@@ -0,0 +1,90 @@
+"""
+Pydantic models for Caddy log analysis.
+"""
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+)
+from pydantic import BaseModel
+
+
+class SuspiciousIP(BaseModel):
+    """Data model for a suspicious IP address."""
+    ip: str
+    count: int
+
+
+class ErrorPatternAnalysis(BaseModel):
+    """Data model for error pattern analysis results."""
+    total_errors: int
+    error_rate: float
+    top_error_paths: List[Tuple[str, int]]
+    error_by_status: Dict[int, int]
+
+
+class RealtimeStatsMetadata(BaseModel):
+    """实时统计元数据
+    Realtime statistics metadata
+    """
+
+    realtime_window_minutes: int
+
+
+class TopCountryStatsMetadata(BaseModel):
+    """Top 国家统计元数据
+    Top country statistics metadata
+    """
+
+    country: str
+    country_name: str
+    country_code: str
+    count: int
+    percentage: float
+
+
+class TopIPStatsMetadata(BaseModel):
+    """Top IP 统计元数据
+    Top IP statistics metadata
+    """
+
+    client_ip: str
+    country: str
+    city: str
+    count: int
+    percentage: float
+
+
+class StatsAggregationPayload(BaseModel):
+    """统计聚合载荷模型
+    Typed payload for CaddyStats numeric fields
+    """
+
+    total_requests: int = 0
+    success_requests: int = 0
+    client_error_requests: int = 0
+    server_error_requests: int = 0
+    total_bytes_sent: int = 0
+    total_bytes_received: int = 0
+    avg_response_time: Optional[int] = 0
+    min_response_time: Optional[int] = 0
+    max_response_time: Optional[int] = 0
+    p50_response_time: Optional[int] = 0
+    p95_response_time: Optional[int] = 0
+    p99_response_time: Optional[int] = 0
+    waf_blocked_requests: int = 0
+    waf_logged_requests: int = 0
+    rate_limited_requests: int = 0
+    tls_requests: int = 0
+    non_tls_requests: int = 0
+    unique_ips: int = 0
+    unique_user_agents: int = 0
+
+    def to_stats_dict(self) -> Dict[str, Any]:
+        """导出 CaddyStats 可用字段字典
+        Export payload as CaddyStats-compatible dict
+        """
+
+        return self.model_dump()

cancan_microstack/public/schemas/caddy/route.py

@@ -0,0 +1,18 @@
+from typing import (
+    Optional,
+)
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+
+
+class ToggleRoutePayload(BaseModel):
+    """切换路由状态请求体 / Toggle route state request payload"""
+
+    enabled: Optional[bool] = Field(
+        default=None,
+        description="目标启用状态，为空时自动取反 / Desired enabled state, auto-toggle when omitted",
+    )

cancan_microstack/public/schemas/common.py

@@ -0,0 +1,79 @@
+"""优化后的标准 API 响应 / Optimized Standard API Response."""
+from typing import (
+    Generic,
+    Optional,
+    TypeVar,
+)
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+T = TypeVar("T")
+
+
+class APIError(BaseModel):
+    """API 错误信息模型 / API error information model"""
+    code: str = Field(default="0", description="错误代码 / Error code")
+    msg: str = Field(default="", description="错误消息 / Error message")
+
+
+class APIResponse(BaseModel, Generic[T]):
+    """标准 API 响应模型 / Standard API response model"""
+
+    success: bool = Field(..., description="操作是否成功 / Whether operation succeeded")
+    error: APIError = Field(default_factory=APIError, description="错误信息 / Error details")
+    data: Optional[T] = Field(default=None, description="响应数据 / Response payload")
+
+    @classmethod
+    def create(
+            cls,
+            data: Optional[T] = None,
+            code: str = "0",
+            msg: str = "",
+            error: Optional[APIError] = None,
+            success: Optional[bool] = None,
+    ) -> "APIResponse[Optional[T]]":
+        """
+        通用构建方法 (替代 build_api_response)
+        """
+        resolved_error = error or APIError(code=str(code), msg=str(msg))
+        # 如果 success 未指定，根据 code 是否为 "0" 自动判断
+        resolved_success = success if success is not None else resolved_error.code == "0"
+
+        return cls(
+            success=resolved_success,
+            error=resolved_error,
+            data=data
+        )
+
+    @classmethod
+    def success_resp(cls, data: Optional[T] = None) -> "APIResponse[Optional[T]]":
+        """
+        快速构建成功响应 (替代 build_success_response)
+        """
+        return cls.create(data=data, code="0", msg="", success=True)
+
+    @classmethod
+    def error_resp(cls, code: str, msg: str) -> "APIResponse[Optional[T]]":
+        """
+        快速构建错误响应 (替代 build_error_response)
+        """
+        return cls.create(data=None, code=code, msg=msg, success=False)
+
+
+class MessageResp(BaseModel):
+    """
+    通用消息响应
+    General message response
+    """
+    message: str = Field(..., description="消息内容 / Message content")
+
+
+class ErrorMessage(BaseModel):
+    """
+    错误消息模型 / Error message model
+    """
+    message: str = Field(..., description="错误消息 / Error message")
+    detail: Optional[str] = Field(default=None, description="错误详情 / Error detail")

cancan_microstack/public/schemas/controllersrv/__init__.py

@@ -0,0 +1,3 @@
+"""
+controllersrv API 类型定义
+"""

cancan_microstack/public/schemas/controllersrv/async_requests.py

@@ -0,0 +1,30 @@
+"""
+controllersrv 异步 API 请求模型
+"""
+from typing import (
+    Optional,
+)
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+from cancan_microstack.public.const.operation_consts import (
+    InitiatedBy,
+    InitiatedFrom,
+)
+
+
+class AsyncOperationParams(BaseModel):
+    """异步操作参数"""
+    instance_id: Optional[str] = Field(default=None, description="实例ID")
+    reason: str = Field(..., description="操作原因")
+
+
+class AsyncServiceOperationPayload(BaseModel):
+    """异步服务操作请求体"""
+    service_name: str = Field(..., description="服务名称, e.g., 'infrasrv.service'")
+    operation_params: AsyncOperationParams = Field(..., description="操作参数")
+    initiated_by: InitiatedBy = Field(..., description="操作发起者")
+    initiated_from: InitiatedFrom = Field(..., description="发起来源")

cancan_microstack/public/schemas/controllersrv/compose_models.py

@@ -0,0 +1,47 @@
+"""
+Docker Compose 相关的模型
+
+定义了与 Docker Compose 操作相关的数据模型，用于 controllersrv 的领域层。
+"""
+from typing import List
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+from cancan_microstack.public.schemas.controllersrv.docker_models import ContainerHealthDetail
+
+
+class CommandResult(BaseModel):
+    """表示已执行的 shell 命令的结果。"""
+    success: bool
+    output: str = ""
+    error: str = ""
+    returncode: int
+
+
+class ServiceListResult(BaseModel):
+    """表示服务列表，用于状态和配置列表。"""
+    success: bool
+    services: List[str] = Field(default_factory=list)
+    error: str = ""
+
+
+class ContainerHealthResult(BaseModel):
+    """表示服务的容器健康状态。"""
+    success: bool
+    containers: List[ContainerHealthDetail] = Field(default_factory=list)
+    error: str = ""
+
+
+class ComposeStatusResult(BaseModel):
+    """表示 Docker Compose 项目的整体状态。"""
+    success: bool = True
+    is_running: bool
+    project_name: str
+    compose_file: str
+    engine_type: str
+    available_services: List[str] = Field(default_factory=list)
+    running_services: List[str] = Field(default_factory=list)
+    error: str = ""

cancan_microstack/public/schemas/controllersrv/const.py

@@ -0,0 +1,24 @@
+"""
+controllersrv API 常量定义
+"""
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """错误代码枚举"""
+    SUCCESS = "0"
+    INVALID_PARAMETER = "1001"
+    MISSING_PARAMETER = "1002"
+    INVALID_SERVICE_NAME = "1003"
+    DUPLICATE_SERIAL_NUMBER = "1004"
+    OPERATION_FAILED = "1005"
+    SERVICE_NOT_FOUND = "1006"
+    INTERNAL_ERROR = "1999"
+
+
+class ValidationResultKey(str, Enum):
+    """验证结果键枚举"""
+    VALID = "valid"
+    INVALID_SERVICES = "invalid_services"
+    NON_OPERABLE_SERVICES = "non_operable_services"
+    VALID_SERVICES = "valid_services"

cancan_microstack/public/schemas/controllersrv/docker_models.py

@@ -0,0 +1,45 @@
+"""
+Docker-specific domain models for controllersrv.
+"""
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+
+class HealthCheck(BaseModel):
+    """Container health check status."""
+    status: str = Field(..., alias='Status')
+    failing_streak: int = Field(..., alias='FailingStreak')
+    log: List[Dict[str, Any]] = Field(..., alias='Log')
+
+
+class ContainerState(BaseModel):
+    """Container state information."""
+    status: str = Field(..., alias='Status')
+    running: bool = Field(..., alias='Running')
+    paused: bool = Field(..., alias='Paused')
+    restarting: bool = Field(..., alias='Restarting')
+    oom_killed: bool = Field(..., alias='OOMKilled')
+    dead: bool = Field(..., alias='Dead')
+    pid: int = Field(..., alias='Pid')
+    exit_code: int = Field(..., alias='ExitCode')
+    error: str = Field(..., alias='Error')
+    started_at: str = Field(..., alias='StartedAt')
+    finished_at: str = Field(..., alias='FinishedAt')
+    health: Optional[HealthCheck] = Field(None, alias='Health')
+
+
+class ContainerHealthDetail(BaseModel):
+    """Detailed container health information."""
+    id: str
+    name: str
+    state: Optional[ContainerState] = None
+    health: Optional[HealthCheck] = None

cancan_microstack/public/schemas/controllersrv/docker_responses.py

@@ -0,0 +1,104 @@
+"""
+Docker 操作相关的 API 响应模型
+"""
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+
+from pydantic import BaseModel
+
+
+class ContainerInfo(BaseModel):
+    """容器基本信息"""
+    id: str
+    name: str
+    status: str
+    image: Any
+    created: Optional[str] = None
+    ports: Any
+    labels: Dict[str, str]
+
+
+class ContainerListResponse(BaseModel):
+    """容器列表响应"""
+    success: bool
+    containers: Optional[List[ContainerInfo]] = None
+    error: Optional[str] = None
+
+
+class ContainerDetailResponse(BaseModel):
+    """容器详情响应"""
+    success: bool
+    container: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+class ContainerLogsResponse(BaseModel):
+    """容器日志响应"""
+    success: bool
+    logs: Optional[Any] = None
+    error: Optional[str] = None
+
+
+class ImageInfo(BaseModel):
+    """镜像基本信息"""
+    id: str
+    tags: List[str]
+    size: int
+    created: Optional[str] = None
+
+
+class ImageListResponse(BaseModel):
+    """镜像列表响应"""
+    success: bool
+    images: Optional[List[ImageInfo]] = None
+    error: Optional[str] = None
+
+
+class NetworkInfo(BaseModel):
+    """网络基本信息"""
+    id: str
+    name: str
+    driver: str
+    scope: str
+    containers: List[Any]
+
+
+class NetworkListResponse(BaseModel):
+    """网络列表响应"""
+    success: bool
+    networks: Optional[List[NetworkInfo]] = None
+    error: Optional[str] = None
+
+
+class VolumeInfo(BaseModel):
+    """卷基本信息"""
+    name: str
+    driver: str
+    mountpoint: str
+
+
+class VolumeListResponse(BaseModel):
+    """卷列表响应"""
+    success: bool
+    volumes: Optional[List[VolumeInfo]] = None
+    error: Optional[str] = None
+
+
+class EngineInfo(BaseModel):
+    """引擎信息"""
+    version: str
+    api_version: str
+    os_type: str
+    architecture: str
+
+
+class EngineHealthResponse(BaseModel):
+    """引擎健康状态响应"""
+    success: bool
+    healthy: Optional[bool] = None
+    engine_info: Optional[EngineInfo] = None
+    error: Optional[str] = None

cancan_microstack/public/schemas/controllersrv/requests.py

@@ -0,0 +1,54 @@
+"""
+controllersrv API 请求模型
+
+定义了 controllersrv API 的请求模型，以确保一致性和类型安全。
+"""
+from typing import (
+    Optional,
+    List,
+    Dict,
+    Any,
+)
+from pydantic import (
+    BaseModel,
+    Field,
+    field_validator,
+)
+
+
+class ServiceOperationRequest(BaseModel):
+    """服务操作请求模型"""
+    serial_number: str = Field(..., description="流水号，用于防重", min_length=1)
+    service_names: List[str] = Field(..., description="服务名称列表", min_length=1)
+    params: Optional[Dict[str, Any]] = Field(default_factory=dict, description="额外参数")
+
+    @field_validator('service_names')
+    @classmethod
+    def validate_service_names(cls, v):
+        """验证服务名称列表"""
+        if not v:
+            raise ValueError("service_names must not be empty")
+        for name in v:
+            if not name or not isinstance(name, str) or not name.strip():
+                raise ValueError(f"Invalid service name: {name}")
+        return v
+
+    @field_validator('serial_number')
+    @classmethod
+    def validate_serial_number(cls, v):
+        """验证流水号并去除首尾空格"""
+        if not v or not v.strip():
+            raise ValueError("serial_number must not be empty")
+        return v.strip()
+
+
+class TaskQueryRequest(BaseModel):
+    """任务查询请求模型"""
+    serial_number: Optional[str] = Field(None, description="流水号")
+    status: Optional[str] = Field(None, description="任务状态过滤")
+    limit: int = Field(100, description="最大返回数量", ge=1, le=1000)
+
+
+class ServiceStatusRequest(BaseModel):
+    """服务状态查询请求模型"""
+    service_names: Optional[List[str]] = Field(None, description="服务名称列表")

cancan_microstack/public/schemas/controllersrv/responses.py

@@ -0,0 +1,124 @@
+"""
+controllersrv API 响应模型
+
+定义了 controllersrv API 的标准响应模型，以确保一致性和类型安全。
+"""
+from typing import (
+    Dict,
+    Any,
+    Optional,
+    List,
+)
+from enum import Enum
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+from cancan_microstack.public.const.operation_consts import (
+    OperationStatus,
+)
+
+
+class ApiResponseKey(str, Enum):
+    """API 响应字典的 Key"""
+    SUCCESS = "success"
+    STATUS = "status"
+    SERIAL_NUMBER = "serial_number"
+    OPERATION = "operation"
+    SERVICE_NAMES = "service_names"
+    MESSAGE = "message"
+    TASK = "task"
+    TASKS = "tasks"
+    COUNT = "count"
+    STATS = "stats"
+
+
+class EnqueueSuccessResponse(BaseModel):
+    """任务入队成功响应"""
+    success: bool = Field(default=True, description="是否成功")
+    status: str = Field(default=OperationStatus.PENDING, description="任务状态")
+    serial_number: str = Field(..., description="流水号")
+    operation: str = Field(..., description="操作类型")
+    service_names: List[str] = Field(..., description="服务名称列表")
+    message: str = Field(default="Task enqueued successfully", description="响应消息")
+
+
+class EnqueueErrorResponse(BaseModel):
+    """任务入队失败响应"""
+    success: bool = Field(default=False, description="是否成功")
+    status: str = Field(default="error", description="任务状态")
+    serial_number: Optional[str] = Field(None, description="流水号")
+    message: str = Field(..., description="错误消息")
+
+
+class TaskNotFoundResponse(BaseModel):
+    """任务未找到响应"""
+    success: bool = Field(False, description="是否成功")
+    message: str = Field(..., description="响应消息")
+
+
+class TaskStatusResponse(BaseModel):
+    """任务状态查询成功响应"""
+    success: bool = Field(default=True, description="是否成功")
+    task: Dict[str, Any] = Field(..., description="任务详情")
+
+
+class TaskListResponse(BaseModel):
+    """任务列表响应"""
+    success: bool = Field(default=True, description="是否成功")
+    tasks: List[Dict[str, Any]] = Field(..., description="任务列表")
+    count: int = Field(..., description="任务数量")
+
+
+class TaskQueueStats(BaseModel):
+    """任务队列统计信息"""
+    queue_size: int = Field(..., description="当前队列中的任务数")
+    total_tasks: int = Field(..., description="历史总任务数（包括已完成）")
+    active_serial_numbers: int = Field(..., description="活跃流水号数量")
+    status_counts: Dict[str, int] = Field(..., description="按状态统计的任务数量")
+    max_queue_size: int = Field(..., description="队列最大容量")
+
+
+class QueueStatsResponse(BaseModel):
+    """队列统计信息响应"""
+    success: bool = Field(default=True, description="是否成功")
+    stats: TaskQueueStats = Field(..., description="统计信息")
+    error: Optional[str] = Field(default=None, description="错误信息")
+
+
+class ServiceStatusResponse(BaseModel):
+    """服务状态响应"""
+    success: bool = Field(..., description="是否成功")
+    services: List[str] = Field(default_factory=list, description="服务列表")
+    error: Optional[str] = Field(default=None, description="错误信息")
+
+
+class ServiceListResponse(BaseModel):
+    """服务列表响应"""
+    success: bool = Field(..., description="是否成功")
+    services: List[str] = Field(default_factory=list, description="服务列表")
+    error: Optional[str] = Field(default=None, description="错误信息")
+
+
+class ContainerHealthResponse(BaseModel):
+    """容器健康状态响应"""
+    success: bool = Field(..., description="是否成功")
+    service_name: Optional[str] = Field(default=None, description="服务名称")
+    containers: List[Dict[str, Any]] = Field(default_factory=list, description="容器健康详情列表")
+    error: Optional[str] = Field(default=None, description="错误信息")
+
+
+class ComposeStatusResponse(BaseModel):
+    """Docker Compose 状态响应"""
+    success: bool = Field(..., description="是否成功")
+    is_running: bool = Field(default=False, description="是否运行中")
+    service_count: Optional[int] = Field(default=None, description="服务数量")
+    services: List[str] = Field(default_factory=list, description="服务列表")
+    error: Optional[str] = Field(default=None, description="错误信息")
+
+
+class ComposeStatusRequest(BaseModel):
+    """Compose 状态查询请求（预留扩展）"""
+    # 当前 get_compose_status() 不需要参数，此模型预留供未来使用
+    pass