aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/scheduler/task_monitor.py.j2

@@ -0,0 +1,189 @@
+"""Task health monitoring service for scheduler health checks."""
+
+from datetime import datetime
+from typing import Any
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+from app.core.log import logger
+from .models import SchedulerHealthMetadata, UpcomingTask
+
+{% if cookiecutter.scheduler_backend != "memory" %}
+from .scheduled_task_manager import ScheduledTaskManager
+{% endif %}
+
+
+class TaskHealthMonitor:
+    """
+    Service for providing rich task health data for scheduler health checks.
+
+    Works with both persistent and non-persistent scheduler modes:
+    - Persistent mode: Uses ScheduledTaskManager for detailed task info
+    - Non-persistent mode: Uses scheduler.get_jobs() directly
+    """
+    
+    def __init__(self) -> None:
+        {% if cookiecutter.scheduler_backend != "memory" %}
+        self.task_manager = ScheduledTaskManager()
+        {% endif %}
+    
+    async def get_health_metadata(
+        self, scheduler: AsyncIOScheduler | None
+    ) -> SchedulerHealthMetadata:
+        """
+        Get comprehensive health metadata for scheduler component.
+
+        Args:
+            scheduler: The AsyncIOScheduler instance, or None if not available
+
+        Returns:
+            SchedulerHealthMetadata with task statistics and upcoming task information
+        """
+        try:
+            # First, try to get enhanced data if persistence is available
+            {% if cookiecutter.scheduler_backend != "memory" %}
+            if await self.task_manager.has_persistence():
+                return await self._get_persistent_metadata()
+            {% endif %}
+            
+            # If no persistence, we need a scheduler instance for direct inspection
+            if scheduler is None:
+                return SchedulerHealthMetadata(
+                    total_tasks=0,
+                    active_tasks=0,
+                    paused_tasks=0,
+                    upcoming_tasks=[],
+                    scheduler_state="not_initialized"
+                )
+            
+            # Fallback to direct scheduler inspection
+            return await self._get_direct_scheduler_metadata(scheduler)
+            
+        except Exception as e:
+            logger.error("Error getting scheduler health metadata", error=str(e))
+            # Return basic fallback data - only if we have a scheduler instance
+            if scheduler is not None:
+                return await self._get_direct_scheduler_metadata(scheduler)
+            else:
+                return SchedulerHealthMetadata(
+                    total_tasks=0,
+                    active_tasks=0,
+                    paused_tasks=0,
+                    upcoming_tasks=[],
+                    scheduler_state="error"
+                )
+    
+    {% if cookiecutter.scheduler_backend != "memory" %}
+    async def _get_persistent_metadata(self) -> SchedulerHealthMetadata:
+        """Get detailed metadata using ScheduledTaskManager (persistent mode)."""
+        try:
+            # Get statistics
+            stats = await self.task_manager.get_statistics()
+            
+            # Get upcoming tasks (limit to top 5)
+            tasks = await self.task_manager.list_tasks()
+            upcoming_tasks = []
+            
+            for task in tasks:
+                if task.next_run_time and task.status == "active":
+                    upcoming_tasks.append(UpcomingTask(
+                        job_id=task.job_id,
+                        name=task.name,
+                        next_run=task.next_run_time.isoformat(),
+                        schedule=task.schedule
+                    ))
+            
+            # Sort by next run time and take top 5
+            upcoming_tasks.sort(key=lambda x: x.next_run)
+            upcoming_tasks = upcoming_tasks[:5]
+            
+            return SchedulerHealthMetadata(
+                total_tasks=stats.total_tasks,
+                active_tasks=stats.active_tasks,
+                paused_tasks=stats.paused_tasks,
+                upcoming_tasks=upcoming_tasks,
+                scheduler_state="running_persistent"
+            )
+            
+        except Exception as e:
+            logger.error("Error getting persistent metadata", error=str(e))
+            raise
+    {% endif %}
+    
+    async def _get_direct_scheduler_metadata(
+        self, scheduler: AsyncIOScheduler
+    ) -> SchedulerHealthMetadata:
+        """Get basic metadata by inspecting scheduler directly (non-persistent mode)."""
+        try:
+            jobs = scheduler.get_jobs()
+            total_tasks = len(jobs)
+            
+            # Count active jobs (those with next_run_time)
+            active_tasks = sum(1 for job in jobs if job.next_run_time is not None)
+            paused_tasks = total_tasks - active_tasks
+            
+            # Get upcoming tasks (top 5)
+            upcoming_tasks = []
+            active_jobs = [job for job in jobs if job.next_run_time is not None]
+            active_jobs.sort(key=lambda x: x.next_run_time)
+            
+            for job in active_jobs[:5]:
+                upcoming_tasks.append(UpcomingTask(
+                    job_id=job.id,
+                    name=job.name or job.id,
+                    next_run=job.next_run_time.isoformat(),
+                    schedule=self._format_trigger_simple(job.trigger)
+                ))
+            
+            return SchedulerHealthMetadata(
+                total_tasks=total_tasks,
+                active_tasks=active_tasks,
+                paused_tasks=paused_tasks,
+                upcoming_tasks=upcoming_tasks,
+                scheduler_state="running_memory"
+            )
+            
+        except Exception as e:
+            logger.error("Error getting direct scheduler metadata", error=str(e))
+            return SchedulerHealthMetadata(
+                total_tasks=0,
+                active_tasks=0,
+                paused_tasks=0,
+                upcoming_tasks=[],
+                scheduler_state="error"
+            )
+    
+    def _format_trigger_simple(self, trigger: Any) -> str:
+        """Simple trigger formatting for non-persistent mode."""
+        if not trigger:
+            return "Unknown"
+        
+        trigger_type = type(trigger).__name__
+        
+        if trigger_type == "IntervalTrigger":
+            if hasattr(trigger, "interval"):
+                seconds = trigger.interval.total_seconds()
+                if seconds < 60:
+                    return f"Every {int(seconds)}s"
+                elif seconds < 3600:
+                    minutes = int(seconds / 60)
+                    return f"Every {minutes}m"
+                elif seconds < 86400:
+                    hours = seconds / 3600
+                    if hours == int(hours):
+                        return f"Every {int(hours)}h"
+                    else:
+                        return f"Every {hours:.1f}h"
+                else:
+                    days = int(seconds / 86400)
+                    return f"Every {days}d"
+        
+        elif trigger_type == "CronTrigger":
+            # Simple cron description
+            return "Cron schedule"
+        
+        elif trigger_type == "DateTrigger":
+            if hasattr(trigger, "run_date"):
+                return f"Once at {trigger.run_date.strftime('%Y-%m-%d %H:%M')}"
+        
+        return trigger_type.replace("Trigger", "")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/shared/__init__.py

@@ -0,0 +1,15 @@
+"""
+Shared domain models and utilities.
+
+Common types and models used across multiple domains.
+"""
+
+from .models import (
+    BaseResponse,
+    ErrorResponse,
+)
+
+__all__ = [
+    "BaseResponse",
+    "ErrorResponse",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/shared/models.py

@@ -0,0 +1,26 @@
+"""
+Shared domain models.
+
+Common Pydantic models used across multiple domains and services.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BaseResponse(BaseModel):
+    """Base API response model."""
+
+    success: bool = Field(..., description="Whether operation was successful")
+    message: str = Field(..., description="Response message")
+    data: dict[str, Any] | list[Any] | None = Field(None, description="Response data")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response model."""
+
+    error: str = Field(..., description="Error message")
+    status: str = Field(default="error", description="Status indicator")
+    details: dict[str, Any] | None = Field(None, description="Additional error details")
+    timestamp: str | None = Field(None, description="ISO timestamp when error occurred")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/system/__init__.py

@@ -0,0 +1,52 @@
+"""
+System domain - health monitoring, alerts, and system management.
+
+This domain provides functions for:
+- System health checking and monitoring
+- Component status validation
+- Alert management and notifications
+- System resource monitoring
+
+All functions use Pydantic models for type safety and validation.
+"""
+
+from .alerts import (
+    send_alert,
+    send_critical_alert,
+    send_health_alert,
+)
+from .health import (
+    check_system_status,
+    get_system_status,
+    is_system_healthy,
+    register_health_check,
+)
+from .models import (
+    Alert,
+    AlertSeverity,
+    ComponentStatus,
+    ComponentStatusType,
+    DetailedHealthResponse,
+    HealthResponse,
+    SystemStatus,
+)
+
+__all__ = [
+    # Health functions
+    "check_system_status",
+    "get_system_status",
+    "is_system_healthy",
+    "register_health_check",
+    # Alert functions
+    "send_alert",
+    "send_critical_alert",
+    "send_health_alert",
+    # Models
+    "Alert",
+    "AlertSeverity",
+    "ComponentStatus",
+    "ComponentStatusType",
+    "SystemStatus",
+    "HealthResponse",
+    "DetailedHealthResponse",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/system/alerts.py

@@ -0,0 +1,94 @@
+"""
+System alert management functions.
+
+Pure functions for sending alerts, managing notifications, and rate limiting.
+All functions use Pydantic models for type safety and validation.
+"""
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from app.core.log import logger
+
+from .models import Alert, SystemStatus, alert_severity
+
+if TYPE_CHECKING:
+    pass
+
+
+# Global state for alert rate limiting
+_last_alerts: dict[str, datetime] = {}
+_rate_limit_seconds = 300  # 5 minutes between similar alerts
+
+
+def _should_send_alert(alert_key: str) -> bool:
+    """Check if we should send this alert based on rate limiting."""
+    if alert_key not in _last_alerts:
+        return True
+
+    time_since_last = datetime.now(UTC) - _last_alerts[alert_key]
+    return time_since_last.total_seconds() > _rate_limit_seconds
+
+
+async def send_alert(alert: Alert) -> None:
+    """Send an alert through configured channels."""
+    alert_key = f"{alert.severity}:{alert.title}"
+
+    if not _should_send_alert(alert_key):
+        logger.debug(f"Rate limiting alert: {alert_key}")
+        return
+
+    _last_alerts[alert_key] = datetime.now(UTC)
+
+    # Log-based alerting (always available)
+    log_level = {
+        alert_severity.INFO: logger.info,
+        alert_severity.WARNING: logger.warning,
+        alert_severity.ERROR: logger.error,
+        alert_severity.CRITICAL: logger.critical,
+    }.get(alert.severity, logger.info)
+
+    log_level(
+        f"🚨 ALERT [{alert.severity.upper()}]: {alert.title}",
+        extra={
+            "alert_message": alert.message,
+            "alert_metadata": alert.metadata,
+            "alert_timestamp": alert.timestamp.isoformat(),
+        },
+    )
+
+    # TODO: Add integrations for:
+    # - Slack/Discord webhooks
+    # - Email notifications
+    # - PagerDuty/Opsgenie
+    # - Custom webhook endpoints
+
+
+async def send_health_alert(status: SystemStatus) -> None:
+    """Send health-related alerts."""
+    if not status.overall_healthy:
+        alert = Alert(
+            severity=alert_severity.WARNING,
+            title="System Health Issues Detected",
+            message=(
+                f"{len(status.unhealthy_components)} components unhealthy: "
+                f"{', '.join(status.unhealthy_components)}"
+            ),
+            timestamp=status.timestamp,
+            metadata={
+                "unhealthy_components": status.unhealthy_components,
+                "health_percentage": status.health_percentage,
+            },
+        )
+        await send_alert(alert)
+
+
+async def send_critical_alert(title: str, message: str) -> None:
+    """Send a critical system alert."""
+    alert = Alert(
+        severity=alert_severity.CRITICAL,
+        title=title,
+        message=message,
+        timestamp=datetime.now(UTC),
+    )
+    await send_alert(alert)

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/services/system/backup.py.j2

@@ -0,0 +1,119 @@
+"""
+Database backup service for {{ cookiecutter.project_name }}.
+
+Provides database backup functionality for scheduled backup jobs.
+Included when scheduler and database components are both present.
+"""
+{% if cookiecutter.scheduler_backend != "memory" or (cookiecutter.include_scheduler == "yes" and cookiecutter.include_database == "yes") %}
+
+import asyncio
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+from app.core.db import DATABASE_PATH
+from app.core.log import logger
+
+# Backup file naming pattern
+BACKUP_FILE_PATTERN = "database_backup_*.db"
+BACKUP_FILE_PREFIX = "database_backup_"
+
+
+async def backup_database_job() -> None:
+    """
+    Scheduled database backup job.
+
+    Creates a backup of the SQLite database file with timestamp.
+    Keeps the last 7 daily backups to prevent disk space issues.
+    """
+    try:
+        # Ensure backup directory exists
+        backup_dir = Path("backups")
+        backup_dir.mkdir(exist_ok=True)
+
+        # Create timestamped backup filename
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_filename = f"{BACKUP_FILE_PREFIX}{timestamp}.db"
+        backup_path = backup_dir / backup_filename
+
+        # Copy database file
+        if Path(DATABASE_PATH).exists():
+            shutil.copy2(DATABASE_PATH, backup_path)
+            logger.info(f"💾 Database backup created: {backup_path}")
+        else:
+            logger.warning(f"⚠️  Database file not found for backup: {DATABASE_PATH}")
+
+        # Clean up old backups (keep last 7) - always run regardless of backup success
+        await _cleanup_old_backups(backup_dir)
+
+    except Exception as e:
+        logger.error(f"❌ Database backup failed: {e}")
+
+
+async def _cleanup_old_backups(backup_dir: Path, keep_count: int = 7) -> None:
+    """
+    Remove old backup files, keeping only the most recent ones.
+
+    Args:
+        backup_dir: Directory containing backup files
+        keep_count: Number of recent backups to keep
+    """
+    try:
+        # Get all backup files sorted by modification time (newest first)
+        backup_files = [
+            f for f in backup_dir.glob(BACKUP_FILE_PATTERN)
+            if f.is_file()
+        ]
+        backup_files.sort(key=lambda x: x.stat().st_mtime, reverse=True)
+
+        # Remove old backups beyond keep_count
+        old_backups = backup_files[keep_count:]
+        for old_backup in old_backups:
+            old_backup.unlink()
+            logger.info(f"🗑️  Removed old backup: {old_backup.name}")
+
+        if old_backups:
+            kept_count = min(len(backup_files), keep_count)
+            logger.info(
+                f"✅ Cleaned up {len(old_backups)} old backups, kept {kept_count}"
+            )
+
+    except Exception as e:
+        logger.error(f"❌ Backup cleanup failed: {e}")
+
+
+async def restore_database_from_backup(backup_filename: str) -> bool:
+    """
+    Restore database from a backup file.
+
+    Args:
+        backup_filename: Name of the backup file to restore from
+
+    Returns:
+        True if restore was successful, False otherwise
+    """
+    try:
+        backup_dir = Path("backups")
+        backup_path = backup_dir / backup_filename
+
+        if not backup_path.exists():
+            logger.error(f"❌ Backup file not found: {backup_path}")
+            return False
+
+        # Create backup of current database before restore
+        current_db = Path(DATABASE_PATH)
+        if current_db.exists():
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            current_backup = backup_dir / f"pre_restore_backup_{timestamp}.db"
+            shutil.copy2(current_db, current_backup)
+            logger.info(f"💾 Created pre-restore backup: {current_backup}")
+
+        # Restore from backup
+        shutil.copy2(backup_path, DATABASE_PATH)
+        logger.info(f"✅ Database restored from backup: {backup_filename}")
+        return True
+
+    except Exception as e:
+        logger.error(f"❌ Database restore failed: {e}")
+        return False
+{% endif %}