firefeed-core 1.0.0__py3-none-any.whl

firefeed_core/__init__.py

@@ -0,0 +1,52 @@
+"""
+FireFeed Core - Core utilities and models for FireFeed microservices
+
+This package contains shared components used across all FireFeed microservices:
+- Common Pydantic models
+- Exceptions and error handling
+- API clients for inter-service communication
+- Authentication and authorization utilities
+- Configuration management
+- Interface definitions
+"""
+
+from . import models
+from . import exceptions
+from . import config
+from . import auth
+from . import api_client
+from . import interfaces
+from . import utils
+
+# Version
+__version__ = "1.0.0"
+
+# Main exports
+from .api_client import APIClient
+from .auth.token_manager import ServiceTokenManager
+from .config.settings import FireFeedSettings
+from .exceptions import FireFeedException, APIException, AuthenticationException
+
+__all__ = [
+    # Version
+    "__version__",
+    
+    # Core components
+    "APIClient",
+    "ServiceTokenManager", 
+    "FireFeedSettings",
+    
+    # Exceptions
+    "FireFeedException",
+    "APIException", 
+    "AuthenticationException",
+    
+    # Submodules
+    "models",
+    "exceptions",
+    "config", 
+    "auth",
+    "api_client",
+    "interfaces",
+    "utils",
+]

firefeed_core/api_client/__init__.py

@@ -0,0 +1,17 @@
+"""
+FireFeed Core API Client
+
+Provides HTTP client functionality for inter-service communication.
+"""
+
+from .client import APIClient
+from .circuit_breaker import CircuitBreaker
+from .retry import RetryPolicy
+from .rate_limiter import RateLimiter
+
+__all__ = [
+    "APIClient",
+    "CircuitBreaker", 
+    "RetryPolicy",
+    "RateLimiter",
+]

firefeed_core/api_client/circuit_breaker.py

@@ -0,0 +1,141 @@
+"""
+Circuit Breaker implementation for FireFeed Core
+
+Provides fault tolerance by preventing requests to failing services.
+"""
+
+import time
+from enum import Enum
+from typing import Dict, Any
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Blocking requests
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker implementation to prevent cascading failures.
+    
+    States:
+    - CLOSED: Normal operation, all requests pass through
+    - OPEN: Service is failing, block all requests
+    - HALF_OPEN: Allow limited requests to test recovery
+    """
+    
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        timeout: int = 60,
+        recovery_timeout: int = 30,
+        success_threshold: int = 3
+    ):
+        """
+        Initialize circuit breaker.
+        
+        Args:
+            failure_threshold: Number of failures to open circuit
+            timeout: Time in seconds before trying to close circuit
+            recovery_timeout: Time in half-open state before returning to closed
+            success_threshold: Number of successes needed to close circuit from half-open
+        """
+        self.failure_threshold = failure_threshold
+        self.timeout = timeout
+        self.recovery_timeout = recovery_timeout
+        self.success_threshold = success_threshold
+        
+        self.state = CircuitState.CLOSED
+        self.failure_count = 0
+        self.success_count = 0
+        self.last_failure_time = None
+        self.last_success_time = None
+        self.last_state_change = time.time()
+    
+    def allow_request(self) -> bool:
+        """
+        Check if request should be allowed based on circuit state.
+        
+        Returns:
+            True if request should be allowed, False otherwise
+        """
+        current_time = time.time()
+        
+        # State transitions
+        if self.state == CircuitState.OPEN:
+            # Check if timeout has passed, move to half-open
+            if current_time - self.last_state_change >= self.timeout:
+                self.state = CircuitState.HALF_OPEN
+                self.success_count = 0
+                self.last_state_change = current_time
+                return True
+            return False
+        
+        elif self.state == CircuitState.HALF_OPEN:
+            # Allow request in half-open state
+            return True
+        
+        else:  # CLOSED
+            return True
+    
+    def record_success(self):
+        """Record successful request."""
+        current_time = time.time()
+        self.last_success_time = current_time
+        
+        if self.state == CircuitState.HALF_OPEN:
+            self.success_count += 1
+            if self.success_count >= self.success_threshold:
+                self.state = CircuitState.CLOSED
+                self.failure_count = 0
+                self.last_state_change = current_time
+        elif self.state == CircuitState.CLOSED:
+            # Reset failure count on success
+            self.failure_count = max(0, self.failure_count - 1)
+    
+    def record_failure(self):
+        """Record failed request."""
+        current_time = time.time()
+        self.last_failure_time = current_time
+        self.failure_count += 1
+        
+        if self.state == CircuitState.CLOSED:
+            if self.failure_count >= self.failure_threshold:
+                self.state = CircuitState.OPEN
+                self.last_state_change = current_time
+        
+        elif self.state == CircuitState.HALF_OPEN:
+            # Return to open state on failure in half-open
+            self.state = CircuitState.OPEN
+            self.last_state_change = current_time
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get circuit breaker statistics.
+        
+        Returns:
+            Dictionary with circuit breaker stats
+        """
+        return {
+            "state": self.state.value,
+            "failure_count": self.failure_count,
+            "success_count": self.success_count,
+            "last_failure_time": self.last_failure_time,
+            "last_success_time": self.last_success_time,
+            "last_state_change": self.last_state_change,
+            "failure_threshold": self.failure_threshold,
+            "timeout": self.timeout,
+            "recovery_timeout": self.recovery_timeout,
+            "success_threshold": self.success_threshold,
+        }
+    
+    def reset(self):
+        """Reset circuit breaker to initial state."""
+        self.state = CircuitState.CLOSED
+        self.failure_count = 0
+        self.success_count = 0
+        self.last_failure_time = None
+        self.last_success_time = None
+        self.last_state_change = time.time()

firefeed_core/api_client/client.py

@@ -0,0 +1,434 @@
+"""
+FireFeed Core API Client
+
+A robust HTTP client for inter-service communication with authentication,
+retry policies, circuit breaker pattern, and rate limiting.
+"""
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urljoin
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from ..auth.token_manager import ServiceTokenManager
+from ..exceptions.api_exceptions import (
+    APIException,
+    AuthenticationException,
+    AuthorizationException,
+    RateLimitException,
+    ServiceUnavailableException,
+    CircuitBreakerOpenException,
+    BadRequestException,
+    NotFoundException,
+    ConflictException,
+)
+from .circuit_breaker import CircuitBreaker
+from .retry import RetryPolicy
+from .rate_limiter import RateLimiter
+
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    """
+    HTTP client for FireFeed microservices communication.
+    
+    Features:
+    - JWT token authentication
+    - Automatic retry with exponential backoff
+    - Circuit breaker pattern for fault tolerance
+    - Rate limiting to prevent abuse
+    - Request/response logging
+    - Timeout management
+    """
+    
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        service_id: str,
+        timeout: int = 30,
+        max_retries: int = 3,
+        circuit_breaker_failure_threshold: int = 5,
+        circuit_breaker_timeout: int = 60,
+        rate_limit_requests: int = 100,
+        rate_limit_window: int = 60,
+        **httpx_kwargs
+    ):
+        """
+        Initialize API Client.
+        
+        Args:
+            base_url: Base URL for the API (e.g., http://firefeed-api:8000)
+            token: JWT token for authentication
+            service_id: Unique identifier for this service
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+            circuit_breaker_failure_threshold: Number of failures to open circuit
+            circuit_breaker_timeout: Time in seconds before trying again
+            rate_limit_requests: Maximum requests per window
+            rate_limit_window: Time window in seconds for rate limiting
+            **httpx_kwargs: Additional arguments for httpx.AsyncClient
+        """
+        self.base_url = base_url.rstrip('/')
+        self.token = token
+        self.service_id = service_id
+        self.timeout = timeout
+        
+        # Initialize components
+        self.token_manager = ServiceTokenManager(secret_key="", issuer="")  # Will be set by validator
+        self.circuit_breaker = CircuitBreaker(
+            failure_threshold=circuit_breaker_failure_threshold,
+            timeout=circuit_breaker_timeout
+        )
+        self.retry_policy = RetryPolicy(max_retries=max_retries)
+        self.rate_limiter = RateLimiter(
+            max_requests=rate_limit_requests,
+            window_seconds=rate_limit_window
+        )
+        
+        # HTTP client configuration
+        self.httpx_kwargs = {
+            "timeout": httpx.Timeout(timeout),
+            "headers": {
+                "User-Agent": f"firefeed-{service_id}/1.0.0",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            **httpx_kwargs
+        }
+        
+        # Create HTTP client
+        self.client = httpx.AsyncClient(**self.httpx_kwargs)
+        
+        logger.info(f"Initialized APIClient for {service_id} -> {base_url}")
+    
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+    
+    async def close(self):
+        """Close the HTTP client."""
+        await self.client.aclose()
+        logger.info("APIClient closed")
+    
+    def _validate_token(self) -> str:
+        """
+        Validate and refresh token if needed.
+        
+        Returns:
+            Valid JWT token string
+            
+        Raises:
+            AuthenticationException: If token is invalid or expired
+        """
+        try:
+            # For now, assume token is valid if it exists
+            # In production, you would validate JWT signature and expiry
+            if not self.token:
+                raise AuthenticationException("No authentication token provided")
+            
+            # TODO: Add JWT validation logic here
+            # decoded_token = self.token_manager.verify_token(self.token)
+            # Check expiry, issuer, etc.
+            
+            return self.token
+            
+        except Exception as e:
+            raise AuthenticationException(f"Token validation failed: {str(e)}")
+    
+    def _get_headers(self) -> Dict[str, str]:
+        """
+        Get request headers including authentication.
+        
+        Returns:
+            Dictionary of headers
+        """
+        token = self._validate_token()
+        
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "X-Service-ID": self.service_id,
+            "X-Request-ID": f"{self.service_id}-{int(time.time() * 1000000)}",
+        }
+        
+        return headers
+    
+    def _handle_response(self, response: httpx.Response) -> Any:
+        """
+        Handle HTTP response and convert to appropriate exceptions.
+        
+        Args:
+            response: httpx.Response object
+            
+        Returns:
+            Parsed JSON response data
+            
+        Raises:
+            APIException: For various HTTP error codes
+        """
+        # Log response
+        logger.debug(
+            f"Response: {response.status_code} {response.request.url} "
+            f"({len(response.content)} bytes)"
+        )
+        
+        try:
+            response_data = response.json() if response.content else {}
+        except Exception:
+            response_data = {"message": response.text}
+        
+        # Handle HTTP status codes
+        if response.status_code == 200:
+            return response_data
+        
+        elif response.status_code == 201:
+            return response_data
+        
+        elif response.status_code == 400:
+            error_details = response_data.get("details", [])
+            raise BadRequestException(
+                message=response_data.get("error", {}).get("message", "Bad request"),
+                validation_errors=error_details
+            )
+        
+        elif response.status_code == 401:
+            raise AuthenticationException(
+                message=response_data.get("error", {}).get("message", "Authentication failed")
+            )
+        
+        elif response.status_code == 403:
+            raise AuthorizationException(
+                message=response_data.get("error", {}).get("message", "Forbidden")
+            )
+        
+        elif response.status_code == 404:
+            raise NotFoundException(
+                message=response_data.get("error", {}).get("message", "Not found")
+            )
+        
+        elif response.status_code == 409:
+            raise ConflictException(
+                message=response_data.get("error", {}).get("message", "Conflict")
+            )
+        
+        elif response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitException(
+                message=response_data.get("error", {}).get("message", "Rate limit exceeded"),
+                retry_after=int(retry_after) if retry_after else None
+            )
+        
+        elif response.status_code >= 500:
+            raise ServiceUnavailableException(
+                message=response_data.get("error", {}).get("message", "Service unavailable")
+            )
+        
+        else:
+            raise APIException(
+                message=f"Unexpected response: {response.status_code}",
+                status_code=response.status_code,
+                response_data=response_data
+            )
+    
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """
+        Make HTTP request with retry and circuit breaker logic.
+        
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            endpoint: API endpoint (will be joined with base_url)
+            params: Query parameters
+            data: Form data
+            json_data: JSON data
+            **kwargs: Additional arguments for httpx request
+            
+        Returns:
+            Parsed response data
+            
+        Raises:
+            APIException: For various HTTP and network errors
+        """
+        url = urljoin(self.base_url + "/", endpoint.lstrip("/"))
+        headers = self._get_headers()
+        
+        # Prepare request arguments
+        request_kwargs = {
+            "headers": headers,
+            "params": params or {},
+            **kwargs
+        }
+        
+        if json_data is not None:
+            request_kwargs["json"] = json_data
+        elif data is not None:
+            request_kwargs["data"] = data
+        
+        # Check rate limiting
+        if not self.rate_limiter.allow_request():
+            retry_after = self.rate_limiter.get_retry_after()
+            raise RateLimitException(
+                message="Rate limit exceeded",
+                retry_after=retry_after
+            )
+        
+        # Check circuit breaker
+        if not self.circuit_breaker.allow_request():
+            raise CircuitBreakerOpenException(
+                message="Circuit breaker is open"
+            )
+        
+        # Retry logic
+        last_exception = None
+        for attempt in range(self.retry_policy.max_retries + 1):
+            try:
+                logger.debug(f"Making request: {method} {url} (attempt {attempt + 1})")
+                
+                response = await self.client.request(method, url, **request_kwargs)
+                
+                # Record success for circuit breaker
+                self.circuit_breaker.record_success()
+                
+                # Record rate limit usage
+                self.rate_limiter.record_request()
+                
+                return self._handle_response(response)
+            
+            except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as e:
+                last_exception = e
+                self.circuit_breaker.record_failure()
+                
+                if attempt < self.retry_policy.max_retries:
+                    delay = self.retry_policy.get_delay(attempt)
+                    logger.warning(
+                        f"Request failed (attempt {attempt + 1}): {str(e)}. "
+                        f"Retrying in {delay}s..."
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+                else:
+                    break
+            
+            except APIException as e:
+                # Don't retry on client errors (4xx)
+                if 400 <= e.status_code < 500:
+                    self.circuit_breaker.record_failure()
+                    raise
+                else:
+                    # Retry on server errors (5xx)
+                    last_exception = e
+                    self.circuit_breaker.record_failure()
+                    
+                    if attempt < self.retry_policy.max_retries:
+                        delay = self.retry_policy.get_delay(attempt)
+                        logger.warning(
+                            f"Request failed (attempt {attempt + 1}): {str(e)}. "
+                            f"Retrying in {delay}s..."
+                        )
+                        await asyncio.sleep(delay)
+                        continue
+                    else:
+                        break
+        
+        # All retries failed
+        if last_exception:
+            raise ServiceUnavailableException(
+                f"Request failed after {self.retry_policy.max_retries + 1} attempts: {str(last_exception)}"
+            )
+    
+    # HTTP method wrappers
+    
+    async def get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """Make GET request."""
+        return await self._make_request("GET", endpoint, params=params, **kwargs)
+    
+    async def post(
+        self,
+        endpoint: str,
+        json_data: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """Make POST request."""
+        return await self._make_request("POST", endpoint, json_data=json_data, data=data, **kwargs)
+    
+    async def put(
+        self,
+        endpoint: str,
+        json_data: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """Make PUT request."""
+        return await self._make_request("PUT", endpoint, json_data=json_data, data=data, **kwargs)
+    
+    async def patch(
+        self,
+        endpoint: str,
+        json_data: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """Make PATCH request."""
+        return await self._make_request("PATCH", endpoint, json_data=json_data, data=data, **kwargs)
+    
+    async def delete(
+        self,
+        endpoint: str,
+        **kwargs
+    ) -> Any:
+        """Make DELETE request."""
+        return await self._make_request("DELETE", endpoint, **kwargs)
+    
+    # Utility methods
+    
+    async def health_check(self) -> bool:
+        """
+        Perform health check against the service.
+        
+        Returns:
+            True if service is healthy, False otherwise
+        """
+        try:
+            response = await self.get("/health")
+            return response.get("status") == "healthy"
+        except Exception as e:
+            logger.warning(f"Health check failed: {str(e)}")
+            return False
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get client statistics.
+        
+        Returns:
+            Dictionary with client statistics
+        """
+        return {
+            "service_id": self.service_id,
+            "base_url": self.base_url,
+            "circuit_breaker": self.circuit_breaker.get_stats(),
+            "rate_limiter": self.rate_limiter.get_stats(),
+            "retry_policy": self.retry_policy.get_stats(),
+        }