cloneloop 0.1.0__py3-none-any.whl

mcp_ai_supervisor/web/utils/session_cleanup_manager.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+"""
+會話清理管理器
+==============
+
+統一管理 Web 會話的清理策略、統計和性能監控。
+與內存監控系統深度集成，提供智能清理決策。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from ...debug import web_debug_log as debug_log
+from ...log_writer import get_logger as _get_struct_logger
+from ...utils.error_handler import ErrorHandler, ErrorType
+from ..models.feedback_session import CleanupReason, SessionStatus
+
+if TYPE_CHECKING:
+    from ..models.feedback_session import WebFeedbackSession
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    """会话存储接口 — SessionCleanupManager 仅通过此接口操作会话。
+
+    Phase 0 引入，为 Phase 4（WebUIManager 拆分）解耦做准备。
+    """
+
+    def session_items(self) -> list[tuple[str, WebFeedbackSession]]:
+        """返回 [(session_id, session), ...] 快照"""
+        ...
+
+    def session_get(self, session_id: str) -> WebFeedbackSession | None:
+        """按 session_id 获取会话"""
+        ...
+
+    def session_remove(self, session_id: str) -> None:
+        """移除会话（同时清理 active_sessions 和 desktop_app_instances）"""
+        ...
+
+    def session_count(self) -> int:
+        """当前会话总数"""
+        ...
+
+    @property
+    def current_session_id(self) -> str | None:
+        """当前最新活跃会话的 ID（用于保护不被清理）"""
+        ...
+
+    def session_clear_all(self) -> int:
+        """清空全部会话，返回清理数量"""
+        ...
+
+
+@dataclass
+class CleanupPolicy:
+    """清理策略配置"""
+
+    max_idle_time: int = 1800  # 最大空閒時間（秒）
+    max_session_age: int = 7200  # 最大會話年齡（秒）
+    max_sessions: int = 10  # 最大會話數量
+    cleanup_interval: int = 300  # 清理間隔（秒）
+    memory_pressure_threshold: float = 0.8  # 內存壓力閾值
+    enable_auto_cleanup: bool = True  # 啟用自動清理
+    preserve_active_session: bool = True  # 保護活躍會話
+
+
+@dataclass
+class CleanupStats:
+    """清理統計數據"""
+
+    total_cleanups: int = 0
+    expired_cleanups: int = 0
+    memory_pressure_cleanups: int = 0
+    manual_cleanups: int = 0
+    auto_cleanups: int = 0
+    total_sessions_cleaned: int = 0
+    total_cleanup_time: float = 0.0
+    average_cleanup_time: float = 0.0
+    last_cleanup_time: datetime | None = None
+    cleanup_efficiency: float = 0.0  # 清理效率（清理的會話數/總會話數）
+
+
+class CleanupTrigger(Enum):
+    """清理觸發器類型"""
+
+    AUTO = "auto"  # 自動清理
+    MEMORY_PRESSURE = "memory_pressure"  # 內存壓力
+    MANUAL = "manual"  # 手動清理
+    EXPIRED = "expired"  # 過期清理
+    CAPACITY = "capacity"  # 容量限制
+
+
+class SessionCleanupManager:
+    """會話清理管理器"""
+
+    def __init__(self, web_ui_manager, policy: CleanupPolicy | None = None):
+        """
+        初始化會話清理管理器
+
+        Args:
+            web_ui_manager: WebUIManager 實例（须实现 SessionStore 协议）
+            policy: 清理策略配置
+        """
+        self.web_ui_manager = web_ui_manager
+        self._store: SessionStore = web_ui_manager
+        self.policy = policy or CleanupPolicy()
+        self.stats = CleanupStats()
+
+        # 清理狀態
+        self.is_running = False
+        self.cleanup_thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+        # 回調函數
+        self.cleanup_callbacks: list[Callable] = []
+        self.stats_callbacks: list[Callable] = []
+
+        # 清理歷史記錄
+        self.cleanup_history: list[dict[str, Any]] = []
+        self.max_history = 100
+
+        debug_log("SessionCleanupManager 初始化完成")
+
+    def start_auto_cleanup(self) -> bool:
+        """啟動自動清理"""
+        if not self.policy.enable_auto_cleanup:
+            debug_log("自動清理已禁用")
+            return False
+
+        if self.is_running:
+            debug_log("自動清理已在運行")
+            return True
+
+        try:
+            self.is_running = True
+            self._stop_event.clear()
+
+            self.cleanup_thread = threading.Thread(
+                target=self._auto_cleanup_loop,
+                name="SessionCleanupManager",
+                daemon=True,
+            )
+            self.cleanup_thread.start()
+
+            debug_log(f"自動清理已啟動，間隔 {self.policy.cleanup_interval} 秒")
+            return True
+
+        except Exception as e:
+            self.is_running = False
+            error_id = ErrorHandler.log_error_with_context(
+                e, context={"operation": "啟動自動清理"}, error_type=ErrorType.SYSTEM
+            )
+            debug_log(f"啟動自動清理失敗 [錯誤ID: {error_id}]: {e}")
+            return False
+
+    def stop_auto_cleanup(self) -> bool:
+        """停止自動清理"""
+        if not self.is_running:
+            debug_log("自動清理未在運行")
+            return True
+
+        try:
+            self.is_running = False
+            self._stop_event.set()
+
+            if self.cleanup_thread and self.cleanup_thread.is_alive():
+                self.cleanup_thread.join(timeout=5)
+
+            debug_log("自動清理已停止")
+            return True
+
+        except Exception as e:
+            error_id = ErrorHandler.log_error_with_context(
+                e, context={"operation": "停止自動清理"}, error_type=ErrorType.SYSTEM
+            )
+            debug_log(f"停止自動清理失敗 [錯誤ID: {error_id}]: {e}")
+            return False
+
+    def _auto_cleanup_loop(self):
+        """自動清理主循環"""
+        debug_log("自動清理循環開始")
+
+        while not self._stop_event.is_set():
+            try:
+                # 執行清理檢查
+                self._perform_auto_cleanup()
+
+                # 等待下次清理
+                if self._stop_event.wait(self.policy.cleanup_interval):
+                    break
+
+            except Exception as e:
+                error_id = ErrorHandler.log_error_with_context(
+                    e,
+                    context={"operation": "自動清理循環"},
+                    error_type=ErrorType.SYSTEM,
+                )
+                debug_log(f"自動清理循環錯誤 [錯誤ID: {error_id}]: {e}")
+
+                # 發生錯誤時等待較短時間後重試
+                if self._stop_event.wait(30):
+                    break
+
+        debug_log("自動清理循環結束")
+
+    def _perform_auto_cleanup(self):
+        """執行自動清理"""
+        cleanup_start_time = time.time()
+        cleaned_sessions = 0
+
+        try:
+            total = self._store.session_count()
+            _get_struct_logger("workbench").info(
+                f"total_sessions={total}",
+                "[CLEANUP_SCAN] 开始扫描过期会话",
+            )
+            if total > self.policy.max_sessions:
+                cleaned = self._cleanup_by_capacity()
+                cleaned_sessions += cleaned
+                debug_log(f"容量限制清理了 {cleaned} 個會話")
+
+            # 2. 清理過期會話
+            cleaned = self._cleanup_expired_sessions()
+            cleaned_sessions += cleaned
+
+            # 3. 清理空閒會話
+            cleaned = self._cleanup_idle_sessions()
+            cleaned_sessions += cleaned
+
+            # 4. 更新統計
+            cleanup_duration = time.time() - cleanup_start_time
+            self._update_cleanup_stats(
+                CleanupTrigger.AUTO, cleaned_sessions, cleanup_duration
+            )
+
+            if cleaned_sessions > 0:
+                debug_log(
+                    f"自動清理完成，清理了 {cleaned_sessions} 個會話，耗時: {cleanup_duration:.2f}秒"
+                )
+
+        except Exception as e:
+            error_id = ErrorHandler.log_error_with_context(
+                e, context={"operation": "執行自動清理"}, error_type=ErrorType.SYSTEM
+            )
+            debug_log(f"執行自動清理失敗 [錯誤ID: {error_id}]: {e}")
+
+    def trigger_cleanup(self, trigger: CleanupTrigger, force: bool = False) -> int:
+        """觸發清理操作"""
+        cleanup_start_time = time.time()
+        cleaned_sessions = 0
+
+        try:
+            debug_log(f"觸發清理操作，觸發器: {trigger.value}，強制: {force}")
+
+            if trigger == CleanupTrigger.MEMORY_PRESSURE:
+                cleaned_sessions = (
+                    self.web_ui_manager.cleanup_sessions_by_memory_pressure(force)  # type: ignore[attr-defined]
+                )
+            elif trigger == CleanupTrigger.EXPIRED:
+                cleaned_sessions = self._cleanup_expired_sessions()
+            elif trigger == CleanupTrigger.CAPACITY:
+                cleaned_sessions = self._cleanup_by_capacity()
+            elif trigger == CleanupTrigger.MANUAL:
+                cleaned_sessions += self._cleanup_expired_sessions()
+                if force:
+                    cleaned_sessions += (
+                        self.web_ui_manager.cleanup_sessions_by_memory_pressure(force)  # type: ignore[attr-defined]
+                    )
+            else:
+                # 自動清理
+                self._perform_auto_cleanup()
+                return 0  # 統計已在 _perform_auto_cleanup 中更新
+
+            # 更新統計
+            cleanup_duration = time.time() - cleanup_start_time
+            self._update_cleanup_stats(trigger, cleaned_sessions, cleanup_duration)
+
+            debug_log(
+                f"清理操作完成，清理了 {cleaned_sessions} 個會話，耗時: {cleanup_duration:.2f}秒"
+            )
+            return cleaned_sessions
+
+        except Exception as e:
+            error_id = ErrorHandler.log_error_with_context(
+                e,
+                context={
+                    "operation": "觸發清理",
+                    "trigger": trigger.value,
+                    "force": force,
+                },
+                error_type=ErrorType.SYSTEM,
+            )
+            debug_log(f"觸發清理操作失敗 [錯誤ID: {error_id}]: {e}")
+            return 0
+
+    def _cleanup_by_capacity(self) -> int:
+        """根據容量限制清理會話"""
+        count = self._store.session_count()
+        if count <= self.policy.max_sessions:
+            return 0
+
+        excess_count = count - self.policy.max_sessions
+        current_id = self._store.current_session_id
+
+        session_priorities: list[tuple[str, Any, float]] = []
+        for session_id, session in self._store.session_items():
+            if (
+                self.policy.preserve_active_session
+                and current_id
+                and session.session_id == current_id
+            ):
+                continue
+
+            priority_score = 0.0
+
+            if session.status in [
+                SessionStatus.COMPLETED,
+                SessionStatus.ERROR,
+                SessionStatus.TIMEOUT,
+            ]:
+                priority_score += 100
+            elif session.status == SessionStatus.FEEDBACK_SUBMITTED:
+                priority_score += 50
+
+            priority_score += session.get_age() / 60
+            priority_score += session.get_idle_time() / 30
+
+            session_priorities.append((session_id, session, priority_score))
+
+        session_priorities.sort(key=lambda x: x[2], reverse=True)
+        cleaned_count = 0
+
+        for i in range(min(excess_count, len(session_priorities))):
+            session_id, session, _ = session_priorities[i]
+            try:
+                session._cleanup_sync_enhanced(CleanupReason.MANUAL)
+                self._store.session_remove(session_id)
+                cleaned_count += 1
+            except Exception as e:
+                debug_log(f"容量清理會話 {session_id} 失敗: {e}")
+
+        return cleaned_count
+
+    def _cleanup_expired_sessions(self) -> int:
+        """清理過期會話"""
+        expired_ids: list[str] = []
+
+        for session_id, session in self._store.session_items():
+            if session.is_expired() or session.get_age() > self.policy.max_session_age:
+                expired_ids.append(session_id)
+
+        cleaned_count = 0
+        for session_id in expired_ids:
+            try:
+                session = self._store.session_get(session_id)
+                if session:
+                    _age = session.get_age()
+                    _get_struct_logger("workbench").info(
+                        f"session={session_id} age_seconds={_age:.0f} reason=expired",
+                        "[CLEANUP_SESSION] 清理过期会话",
+                    )
+                    session._cleanup_sync_enhanced(CleanupReason.EXPIRED)
+                    self._store.session_remove(session_id)
+                    cleaned_count += 1
+            except Exception as e:
+                debug_log(f"清理過期會話 {session_id} 失敗: {e}")
+
+        return cleaned_count
+
+    def _cleanup_idle_sessions(self) -> int:
+        """清理空閒會話"""
+        current_id = self._store.current_session_id
+        idle_ids: list[str] = []
+
+        for session_id, session in self._store.session_items():
+            if (
+                self.policy.preserve_active_session
+                and current_id
+                and session.session_id == current_id
+            ):
+                continue
+
+            if session.get_idle_time() > self.policy.max_idle_time:
+                idle_ids.append(session_id)
+
+        cleaned_count = 0
+        for session_id in idle_ids:
+            try:
+                session = self._store.session_get(session_id)
+                if session:
+                    session._cleanup_sync_enhanced(CleanupReason.EXPIRED)
+                    self._store.session_remove(session_id)
+                    cleaned_count += 1
+            except Exception as e:
+                debug_log(f"清理空閒會話 {session_id} 失敗: {e}")
+
+        return cleaned_count
+
+    def _update_cleanup_stats(
+        self, trigger: CleanupTrigger, cleaned_count: int, duration: float
+    ):
+        """更新清理統計"""
+        self.stats.total_cleanups += 1
+        self.stats.total_sessions_cleaned += cleaned_count
+        self.stats.total_cleanup_time += duration
+        self.stats.last_cleanup_time = datetime.now()
+
+        # 更新平均清理時間
+        if self.stats.total_cleanups > 0:
+            self.stats.average_cleanup_time = (
+                self.stats.total_cleanup_time / self.stats.total_cleanups
+            )
+
+        total_sessions = self._store.session_count() + cleaned_count
+        if total_sessions > 0:
+            self.stats.cleanup_efficiency = cleaned_count / total_sessions
+
+        # 根據觸發器類型更新統計
+        if trigger == CleanupTrigger.AUTO:
+            self.stats.auto_cleanups += 1
+        elif trigger == CleanupTrigger.MEMORY_PRESSURE:
+            self.stats.memory_pressure_cleanups += 1
+        elif trigger == CleanupTrigger.EXPIRED:
+            self.stats.expired_cleanups += 1
+        elif trigger == CleanupTrigger.MANUAL:
+            self.stats.manual_cleanups += 1
+
+        # 記錄清理歷史
+        cleanup_record = {
+            "timestamp": datetime.now().isoformat(),
+            "trigger": trigger.value,
+            "cleaned_count": cleaned_count,
+            "duration": duration,
+            "total_sessions_before": total_sessions,
+            "total_sessions_after": self._store.session_count(),
+        }
+
+        self.cleanup_history.append(cleanup_record)
+
+        # 限制歷史記錄數量
+        if len(self.cleanup_history) > self.max_history:
+            self.cleanup_history = self.cleanup_history[-self.max_history :]
+
+        # 調用統計回調
+        for callback in self.stats_callbacks:
+            try:
+                callback(self.stats, cleanup_record)
+            except Exception as e:
+                debug_log(f"統計回調執行失敗: {e}")
+
+    def get_cleanup_statistics(self) -> dict[str, Any]:
+        """獲取清理統計數據"""
+        stats_dict = {
+            "total_cleanups": self.stats.total_cleanups,
+            "expired_cleanups": self.stats.expired_cleanups,
+            "memory_pressure_cleanups": self.stats.memory_pressure_cleanups,
+            "manual_cleanups": self.stats.manual_cleanups,
+            "auto_cleanups": self.stats.auto_cleanups,
+            "total_sessions_cleaned": self.stats.total_sessions_cleaned,
+            "total_cleanup_time": round(self.stats.total_cleanup_time, 2),
+            "average_cleanup_time": round(self.stats.average_cleanup_time, 2),
+            "cleanup_efficiency": round(self.stats.cleanup_efficiency, 3),
+            "last_cleanup_time": self.stats.last_cleanup_time.isoformat()
+            if self.stats.last_cleanup_time
+            else None,
+            "is_auto_cleanup_running": self.is_running,
+            "current_sessions": self._store.session_count(),
+            "policy": {
+                "max_idle_time": self.policy.max_idle_time,
+                "max_session_age": self.policy.max_session_age,
+                "max_sessions": self.policy.max_sessions,
+                "cleanup_interval": self.policy.cleanup_interval,
+                "enable_auto_cleanup": self.policy.enable_auto_cleanup,
+                "preserve_active_session": self.policy.preserve_active_session,
+            },
+        }
+
+        return stats_dict
+
+    def get_cleanup_history(self, limit: int = 20) -> list[dict[str, Any]]:
+        """獲取清理歷史記錄"""
+        return self.cleanup_history[-limit:] if self.cleanup_history else []
+
+    def add_cleanup_callback(self, callback: Callable):
+        """添加清理回調函數"""
+        if callback not in self.cleanup_callbacks:
+            self.cleanup_callbacks.append(callback)
+            debug_log("添加清理回調函數")
+
+    def add_stats_callback(self, callback: Callable):
+        """添加統計回調函數"""
+        if callback not in self.stats_callbacks:
+            self.stats_callbacks.append(callback)
+            debug_log("添加統計回調函數")
+
+    def update_policy(self, **kwargs):
+        """更新清理策略"""
+        for key, value in kwargs.items():
+            if hasattr(self.policy, key):
+                setattr(self.policy, key, value)
+                debug_log(f"更新清理策略 {key} = {value}")
+            else:
+                debug_log(f"未知的策略參數: {key}")
+
+    def reset_stats(self):
+        """重置統計數據"""
+        self.stats = CleanupStats()
+        self.cleanup_history.clear()
+        debug_log("清理統計數據已重置")
+
+    def force_cleanup_all(self, exclude_current: bool = True) -> int:
+        """強制清理所有會話"""
+        current_id = self._store.current_session_id if exclude_current else None
+        ids_to_clean: list[str] = []
+
+        for session_id, session in self._store.session_items():
+            if current_id and session.session_id == current_id:
+                continue
+            ids_to_clean.append(session_id)
+
+        cleaned_count = 0
+        for session_id in ids_to_clean:
+            try:
+                session = self._store.session_get(session_id)
+                if session:
+                    session._cleanup_sync_enhanced(CleanupReason.MANUAL)
+                    self._store.session_remove(session_id)
+                    cleaned_count += 1
+            except Exception as e:
+                debug_log(f"強制清理會話 {session_id} 失敗: {e}")
+
+        self._update_cleanup_stats(CleanupTrigger.MANUAL, cleaned_count, 0.0)
+
+        debug_log(f"強制清理完成，清理了 {cleaned_count} 個會話")
+        return cleaned_count