raxe 0.4.6__py3-none-any.whl

raxe/application/analytics/streak_service.py

@@ -0,0 +1,283 @@
+"""Streak tracking service.
+
+Manages user activity streaks and related achievements.
+
+CRITICAL: This is application layer - orchestrates but doesn't calculate.
+All calculations delegated to domain layer, all I/O to repository.
+"""
+
+import logging
+from datetime import date
+from typing import Any
+
+from raxe.domain.analytics import StreakMetrics, calculate_streaks, compare_streaks
+
+from .repositories import AnalyticsRepository
+
+logger = logging.getLogger(__name__)
+
+
+class StreakService:
+    """Service for tracking and managing user activity streaks.
+
+    This service orchestrates:
+    1. Data loading from repository (infrastructure)
+    2. Streak calculation (domain pure functions)
+    3. Achievement checking and saving
+
+    CRITICAL: This service does NOT perform calculations itself.
+    All business logic is delegated to domain layer functions.
+    """
+
+    def __init__(self, repository: AnalyticsRepository):
+        """Initialize streak service.
+
+        Args:
+            repository: Repository for data access (dependency injection)
+        """
+        self.repository = repository
+
+    def get_user_streak(
+        self,
+        installation_id: str,
+        *,
+        as_of_date: date | None = None
+    ) -> StreakMetrics:
+        """Get current and longest streak for a user.
+
+        Args:
+            installation_id: User's installation identifier
+            as_of_date: Calculate streak as of this date (default: today)
+
+        Returns:
+            StreakMetrics with current and longest streaks
+
+        Example:
+            >>> service = StreakService(repo)
+            >>> metrics = service.get_user_streak("abc123")
+            >>> print(f"Current streak: {metrics.current_streak} days")
+            >>> print(f"Longest streak: {metrics.longest_streak} days")
+        """
+        if as_of_date is None:
+            as_of_date = date.today()
+
+        try:
+            # Step 1: Load user activity from repository (I/O)
+            activity = self.repository.get_user_activity(
+                installation_id=installation_id,
+                end_date=as_of_date
+            )
+
+            if not activity:
+                logger.info(f"No activity found for user {installation_id}")
+                return StreakMetrics(
+                    installation_id=installation_id,
+                    current_streak=0,
+                    longest_streak=0,
+                    total_scan_days=0,
+                    last_scan_date=as_of_date
+                )
+
+            # Step 2: Calculate streak using domain function (pure logic)
+            streak_metrics = calculate_streaks(
+                installation_id=installation_id,
+                scan_dates=activity.scan_dates,
+                reference_date=as_of_date
+            )
+
+            logger.info(
+                f"Calculated streak for {installation_id}: "
+                f"current={streak_metrics.current_streak}, "
+                f"longest={streak_metrics.longest_streak}, "
+                f"total_days={streak_metrics.total_scan_days}"
+            )
+
+            return streak_metrics
+
+        except Exception as e:
+            logger.error(f"Failed to calculate streak for {installation_id}: {e}")
+            raise
+
+    def get_active_streak_users(
+        self,
+        *,
+        min_streak: int = 1,
+        reference_date: date | None = None
+    ) -> list[dict[str, Any]]:
+        """Get users who currently have an active streak.
+
+        Args:
+            min_streak: Minimum streak length to include (default: 1)
+            reference_date: Date to check streaks as of (default: today)
+
+        Returns:
+            List of dictionaries with user streak information
+
+        Example:
+            >>> service = StreakService(repo)
+            >>> active_users = service.get_active_streak_users(min_streak=7)
+            >>> for user in active_users:
+            ...     print(f"{user['installation_id']}: {user['current_streak']} days")
+        """
+        if reference_date is None:
+            reference_date = date.today()
+
+        try:
+            # Step 1: Get all active users in the last 2 days (I/O)
+            # (to find users who might have an active streak)
+            active_user_ids = self.repository.get_active_users(
+                target_date=reference_date,
+                window_days=2
+            )
+
+            if not active_user_ids:
+                logger.info("No active users found for streak check")
+                return []
+
+            # Step 2: Calculate streaks for all active users
+            active_streaks = []
+            for user_id in active_user_ids:
+                streak_metrics = self.get_user_streak(
+                    user_id,
+                    as_of_date=reference_date
+                )
+
+                # Filter by minimum streak length
+                if streak_metrics.current_streak >= min_streak:
+                    active_streaks.append({
+                        "installation_id": user_id,
+                        "current_streak": streak_metrics.current_streak,
+                        "longest_streak": streak_metrics.longest_streak,
+                        "total_scan_days": streak_metrics.total_scan_days,
+                        "last_scan_date": streak_metrics.last_scan_date.isoformat()
+                    })
+
+            # Sort by streak length (descending)
+            active_streaks.sort(
+                key=lambda x: x["current_streak"],
+                reverse=True
+            )
+
+            logger.info(
+                f"Found {len(active_streaks)} users with active streaks >= {min_streak}"
+            )
+
+            return active_streaks
+
+        except Exception as e:
+            logger.error(f"Failed to get active streak users: {e}")
+            raise
+
+    def get_streak_leaderboard(
+        self,
+        *,
+        limit: int = 10,
+        metric: str = "current_streak"
+    ) -> list[dict[str, Any]]:
+        """Get top users by streak length.
+
+        Args:
+            limit: Maximum number of users to return (default: 10)
+            metric: Which metric to rank by: "current_streak" or "longest_streak"
+
+        Returns:
+            List of top users sorted by streak metric
+
+        Raises:
+            ValueError: If metric is not "current_streak" or "longest_streak"
+
+        Example:
+            >>> service = StreakService(repo)
+            >>> leaderboard = service.get_streak_leaderboard(limit=5)
+            >>> for rank, user in enumerate(leaderboard, 1):
+            ...     print(f"{rank}. {user['installation_id']}: {user['current_streak']}")
+        """
+        if metric not in ("current_streak", "longest_streak"):
+            raise ValueError(
+                f"Invalid metric: {metric}. "
+                f"Must be 'current_streak' or 'longest_streak'"
+            )
+
+        try:
+            # Get all active users and calculate their streaks
+            # Note: This is a simplified implementation. For production with
+            # millions of users, we'd want to cache streak metrics or use
+            # materialized views.
+            all_streaks = self.get_active_streak_users(min_streak=1)
+
+            # Sort by requested metric
+            all_streaks.sort(
+                key=lambda x: x[metric],
+                reverse=True
+            )
+
+            # Return top N
+            leaderboard = all_streaks[:limit]
+
+            logger.info(
+                f"Generated streak leaderboard: {len(leaderboard)} users "
+                f"ranked by {metric}"
+            )
+
+            return leaderboard
+
+        except Exception as e:
+            logger.error(f"Failed to generate streak leaderboard: {e}")
+            raise
+
+    def compare_user_streaks(
+        self,
+        installation_id: str,
+        previous_date: date,
+        current_date: date | None = None
+    ) -> dict[str, int]:
+        """Compare user's streaks between two dates.
+
+        Args:
+            installation_id: User's installation identifier
+            previous_date: Earlier date for comparison
+            current_date: Later date for comparison (default: today)
+
+        Returns:
+            Dictionary with delta values for streak metrics
+
+        Example:
+            >>> service = StreakService(repo)
+            >>> deltas = service.compare_user_streaks(
+            ...     "abc123",
+            ...     previous_date=date(2025, 1, 1),
+            ...     current_date=date(2025, 1, 10)
+            ... )
+            >>> print(f"Streak grew by: {deltas['current_streak']} days")
+        """
+        if current_date is None:
+            current_date = date.today()
+
+        try:
+            # Calculate streaks for both dates
+            previous_metrics = self.get_user_streak(
+                installation_id,
+                as_of_date=previous_date
+            )
+
+            current_metrics = self.get_user_streak(
+                installation_id,
+                as_of_date=current_date
+            )
+
+            # Use domain function to calculate deltas (pure logic)
+            deltas = compare_streaks(current_metrics, previous_metrics)
+
+            logger.info(
+                f"Compared streaks for {installation_id}: "
+                f"current_delta={deltas['current_streak']}, "
+                f"longest_delta={deltas['longest_streak']}"
+            )
+
+            return deltas
+
+        except Exception as e:
+            logger.error(
+                f"Failed to compare streaks for {installation_id}: {e}"
+            )
+            raise

raxe/application/apply_policy.py

@@ -0,0 +1,291 @@
+"""Apply policy use case.
+
+Orchestrates policy loading, validation, and evaluation.
+Coordinates between infrastructure (loading) and domain (evaluation).
+"""
+from enum import Enum
+from pathlib import Path
+
+from raxe.domain.engine.executor import Detection, ScanResult
+from raxe.domain.policies.evaluator import evaluate_policies, filter_policies_by_customer
+from raxe.domain.policies.models import Policy, PolicyDecision
+from raxe.infrastructure.policies.api_client import PolicyAPIClient
+from raxe.infrastructure.policies.validator import PolicyValidator
+from raxe.infrastructure.policies.yaml_loader import YAMLPolicyLoader
+from raxe.infrastructure.security.auth import APIKey
+
+
+class PolicySource(Enum):
+    """Source of policy configuration."""
+    LOCAL_FILE = "local_file"      # .raxe/policies.yaml
+    API = "api"                      # Cloud API download
+    INLINE = "inline"                # Programmatic policies
+
+
+class ApplyPolicyUseCase:
+    """Apply policies to scan results.
+
+    Orchestrates the complete policy workflow:
+    1. Load policies from configured source
+    2. Validate policies (signatures, customer ID)
+    3. Evaluate policies against detections
+    4. Return decisions for enforcement
+
+    Application layer - coordinates domain + infrastructure.
+    """
+
+    def __init__(
+        self,
+        yaml_loader: YAMLPolicyLoader | None = None,
+        api_client: PolicyAPIClient | None = None,
+        validator: PolicyValidator | None = None,
+    ) -> None:
+        """Initialize use case with dependencies.
+
+        Args:
+            yaml_loader: YAML policy loader (None = create default)
+            api_client: API client (None = create default)
+            validator: Policy validator (None = create default)
+        """
+        self.yaml_loader = yaml_loader or YAMLPolicyLoader()
+        self.api_client = api_client or PolicyAPIClient()
+        self.validator = validator or PolicyValidator()
+
+    def apply_to_detection(
+        self,
+        detection: Detection,
+        *,
+        policy_source: PolicySource = PolicySource.LOCAL_FILE,
+        policy_file: Path | None = None,
+        api_key: APIKey | None = None,
+        inline_policies: list[Policy] | None = None,
+    ) -> PolicyDecision:
+        """Apply policies to a single detection.
+
+        Args:
+            detection: Detection to evaluate
+            policy_source: Where to load policies from
+            policy_file: Path to local policy file (for LOCAL_FILE source)
+            api_key: API key (for API source or customer filtering)
+            inline_policies: Policies to use (for INLINE source)
+
+        Returns:
+            PolicyDecision with final action and metadata
+
+        Raises:
+            ValueError: If required parameters missing for source
+        """
+        # Load policies based on source
+        policies = self._load_policies(
+            policy_source=policy_source,
+            policy_file=policy_file,
+            api_key=api_key,
+            inline_policies=inline_policies,
+        )
+
+        # Evaluate policies (pure domain logic)
+        return evaluate_policies(detection, policies)
+
+    def apply_to_scan_result(
+        self,
+        scan_result: ScanResult,
+        *,
+        policy_source: PolicySource = PolicySource.LOCAL_FILE,
+        policy_file: Path | None = None,
+        api_key: APIKey | None = None,
+        inline_policies: list[Policy] | None = None,
+    ) -> dict[str, PolicyDecision]:
+        """Apply policies to all detections in scan result.
+
+        Args:
+            scan_result: Scan result with detections
+            policy_source: Where to load policies from
+            policy_file: Path to local policy file (for LOCAL_FILE source)
+            api_key: API key (for API source or customer filtering)
+            inline_policies: Policies to use (for INLINE source)
+
+        Returns:
+            Dict mapping detection versioned_rule_id to PolicyDecision
+
+        Raises:
+            ValueError: If required parameters missing for source
+        """
+        # Load policies once
+        policies = self._load_policies(
+            policy_source=policy_source,
+            policy_file=policy_file,
+            api_key=api_key,
+            inline_policies=inline_policies,
+        )
+
+        # Evaluate each detection
+        decisions: dict[str, PolicyDecision] = {}
+        for detection in scan_result.detections:
+            decision = evaluate_policies(detection, policies)
+            decisions[detection.versioned_rule_id] = decision
+
+        return decisions
+
+    def load_policies_from_file(
+        self,
+        policy_file: Path,
+        api_key: APIKey | None = None,
+    ) -> list[Policy]:
+        """Load and validate policies from YAML file.
+
+        Public helper method for loading policies separately.
+
+        Args:
+            policy_file: Path to policy YAML file
+            api_key: Optional API key for customer filtering
+
+        Returns:
+            List of validated policies
+
+        Raises:
+            PolicyLoadError: If file invalid
+            PolicyValidationError: If validation fails
+        """
+        # Load from file (infrastructure)
+        policies = self.yaml_loader.load_from_file(policy_file)
+
+        # Validate (infrastructure)
+        validated = self.validator.validate_local_policies(
+            policies,
+            api_key=api_key,
+        )
+
+        return validated
+
+    def load_policies_from_api(
+        self,
+        api_key: APIKey,
+        *,
+        use_cache_on_error: bool = True,
+    ) -> list[Policy]:
+        """Load and validate policies from cloud API.
+
+        Public helper method for loading policies separately.
+
+        Args:
+            api_key: API key for authentication
+            use_cache_on_error: Fall back to cache on API error
+
+        Returns:
+            List of validated policies
+
+        Raises:
+            PolicyAPIError: If API call fails and no cache
+            PolicyValidationError: If validation fails
+        """
+        # Fetch from API (infrastructure)
+        policies = self.api_client.fetch_policies(
+            api_key,
+            use_cache_on_error=use_cache_on_error,
+        )
+
+        # Validate (infrastructure)
+        # Note: API policies don't require signature validation here
+        # because they're already validated server-side
+        validated = self.validator.validate_policies(
+            policies,
+            api_key=api_key,
+            require_signature=False,
+        )
+
+        return validated
+
+    def _load_policies(
+        self,
+        *,
+        policy_source: PolicySource,
+        policy_file: Path | None = None,
+        api_key: APIKey | None = None,
+        inline_policies: list[Policy] | None = None,
+    ) -> list[Policy]:
+        """Load policies from configured source.
+
+        Args:
+            policy_source: Where to load from
+            policy_file: Path to local file
+            api_key: API key for cloud/filtering
+            inline_policies: Inline policies
+
+        Returns:
+            List of loaded and validated policies
+
+        Raises:
+            ValueError: If required parameters missing
+        """
+        if policy_source == PolicySource.LOCAL_FILE:
+            if not policy_file:
+                # Default location
+                policy_file = Path.home() / ".raxe" / "policies.yaml"
+
+            # File might not exist - return empty policies
+            if not policy_file.exists():
+                return []
+
+            return self.load_policies_from_file(policy_file, api_key=api_key)
+
+        elif policy_source == PolicySource.API:
+            if not api_key:
+                raise ValueError("api_key required for API policy source")
+
+            return self.load_policies_from_api(api_key)
+
+        elif policy_source == PolicySource.INLINE:
+            if inline_policies is None:
+                return []
+
+            # Validate inline policies
+            if api_key:
+                # Filter by customer
+                return filter_policies_by_customer(
+                    inline_policies,
+                    api_key.customer_id,
+                )
+
+            return inline_policies
+
+        else:
+            raise ValueError(f"Unknown policy source: {policy_source}")
+
+
+# Convenience functions for common use cases
+
+def apply_policies_to_detection(
+    detection: Detection,
+    policies: list[Policy],
+) -> PolicyDecision:
+    """Apply policies to detection (simple interface).
+
+    Convenience wrapper for direct policy evaluation.
+
+    Args:
+        detection: Detection to evaluate
+        policies: Policies to apply
+
+    Returns:
+        PolicyDecision
+    """
+    return evaluate_policies(detection, policies)
+
+
+def should_block_detection(
+    detection: Detection,
+    policies: list[Policy],
+) -> bool:
+    """Determine if detection should be blocked by policies.
+
+    Convenience helper for enforcement.
+
+    Args:
+        detection: Detection to check
+        policies: Policies to apply
+
+    Returns:
+        True if detection should be blocked
+    """
+    decision = evaluate_policies(detection, policies)
+    return decision.should_block