marqetive-lib 0.1.0__py3-none-any.whl

marqetive/utils/retry.py

@@ -0,0 +1,239 @@
+"""Retry utilities for handling transient failures in API calls.
+
+This module provides decorators and utilities for implementing retry logic
+with exponential backoff for async functions.
+"""
+
+import asyncio
+import functools
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Type variable for function return types
+T = TypeVar("T")
+
+
+@dataclass
+class BackoffConfig:
+    """Configuration for exponential backoff retry logic.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts (including first try).
+        base_delay: Initial delay between retries in seconds.
+        max_delay: Maximum delay between retries in seconds.
+        exponential_base: Base for exponential backoff calculation.
+        jitter: Whether to add random jitter to delay times.
+
+    Example:
+        >>> config = BackoffConfig(max_attempts=5, base_delay=2, max_delay=30)
+        >>> print(config.calculate_delay(attempt=2))
+        4.0
+    """
+
+    max_attempts: int = 3
+    base_delay: float = 1.0
+    max_delay: float = 10.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for given attempt number.
+
+        Args:
+            attempt: The attempt number (0-indexed).
+
+        Returns:
+            Delay in seconds.
+        """
+        import random
+
+        delay = min(
+            self.base_delay * (self.exponential_base**attempt),
+            self.max_delay,
+        )
+
+        if self.jitter:
+            # Add random jitter (0-25% of delay)
+            jitter_amount = delay * random.uniform(0, 0.25)
+            delay += jitter_amount
+
+        return delay
+
+
+# Standard backoff configuration used across the library
+STANDARD_BACKOFF = BackoffConfig(
+    max_attempts=3,
+    base_delay=1.0,
+    max_delay=10.0,
+    exponential_base=2.0,
+    jitter=True,
+)
+
+
+def is_retryable_error(error: Exception) -> bool:
+    """Determine if an error is retryable.
+
+    Args:
+        error: The exception to check.
+
+    Returns:
+        True if error is retryable, False otherwise.
+    """
+    # HTTP errors that are retryable
+    if isinstance(error, httpx.HTTPStatusError):
+        # Retry on 5xx server errors and 429 rate limit
+        return bool(
+            error.response.status_code >= 500 or error.response.status_code == 429
+        )
+
+    # Network/connection errors are retryable
+    if isinstance(
+        error, (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError)
+    ):
+        return True
+
+    # Any other httpx error (or not retryable)
+    return isinstance(error, httpx.HTTPError)
+
+
+def retry_async(
+    config: BackoffConfig | None = None,
+    retryable_exceptions: tuple[type[Exception], ...] | None = None,
+    error_classifier: Callable[[Exception], bool] | None = None,
+) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
+    """Decorator for retrying async functions with exponential backoff.
+
+    Args:
+        config: Backoff configuration (uses STANDARD_BACKOFF if None).
+        retryable_exceptions: Tuple of exception types to retry.
+                             If None, uses is_retryable_error().
+        error_classifier: Custom function to determine if error is retryable.
+                         Overrides retryable_exceptions if provided.
+
+    Returns:
+        Decorator function.
+
+    Example:
+        >>> @retry_async(config=BackoffConfig(max_attempts=5))
+        ... async def fetch_data(url: str) -> dict:
+        ...     async with httpx.AsyncClient() as client:
+        ...         response = await client.get(url)
+        ...         response.raise_for_status()
+        ...         return response.json()
+    """
+    if config is None:
+        config = STANDARD_BACKOFF
+
+    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
+            last_exception: Exception | None = None
+
+            for attempt in range(config.max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+
+                except Exception as e:
+                    last_exception = e
+
+                    # Determine if error is retryable
+                    should_retry = False
+                    if error_classifier is not None:
+                        should_retry = error_classifier(e)
+                    elif retryable_exceptions is not None:
+                        should_retry = isinstance(e, retryable_exceptions)
+                    else:
+                        should_retry = is_retryable_error(e)
+
+                    if not should_retry:
+                        raise
+
+                    # Check if we should retry
+                    if attempt < config.max_attempts - 1:
+                        delay = config.calculate_delay(attempt)
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{config.max_attempts} failed "
+                            f"for {func.__name__}: {str(e)}. "
+                            f"Retrying in {delay:.2f}s..."
+                        )
+                        await asyncio.sleep(delay)
+                    else:
+                        logger.error(
+                            f"All {config.max_attempts} attempts failed "
+                            f"for {func.__name__}: {str(e)}"
+                        )
+                        raise
+
+            # Should never reach here, but just in case
+            if last_exception:
+                raise last_exception
+            raise RuntimeError("Retry logic failed unexpectedly")
+
+        return wrapper
+
+    return decorator
+
+
+async def retry_async_func[T](
+    func: Callable[..., Awaitable[T]],
+    *args: Any,
+    config: BackoffConfig | None = None,
+    **kwargs: Any,
+) -> T:
+    """Retry an async function with exponential backoff.
+
+    Alternative to the decorator for cases where you can't use decorators.
+
+    Args:
+        func: Async function to retry.
+        *args: Positional arguments to pass to function.
+        config: Backoff configuration (uses STANDARD_BACKOFF if None).
+        **kwargs: Keyword arguments to pass to function.
+
+    Returns:
+        Function return value.
+
+    Example:
+        >>> async def fetch_data(url: str) -> dict:
+        ...     async with httpx.AsyncClient() as client:
+        ...         response = await client.get(url)
+        ...         response.raise_for_status()
+        ...         return response.json()
+        >>>
+        >>> data = await retry_async_func(fetch_data, "https://api.example.com")
+    """
+    if config is None:
+        config = STANDARD_BACKOFF
+
+    last_exception: Exception | None = None
+
+    for attempt in range(config.max_attempts):
+        try:
+            return await func(*args, **kwargs)
+
+        except Exception as e:
+            last_exception = e
+
+            if not is_retryable_error(e):
+                raise
+
+            if attempt < config.max_attempts - 1:
+                delay = config.calculate_delay(attempt)
+                logger.warning(
+                    f"Attempt {attempt + 1}/{config.max_attempts} failed: {str(e)}. "
+                    f"Retrying in {delay:.2f}s..."
+                )
+                await asyncio.sleep(delay)
+            else:
+                logger.error(f"All {config.max_attempts} attempts failed: {str(e)}")
+                raise
+
+    if last_exception:
+        raise last_exception
+    raise RuntimeError("Retry logic failed unexpectedly")

marqetive/utils/token_validator.py

@@ -0,0 +1,240 @@
+"""Token validation utilities for checking credential validity.
+
+This module provides utilities for validating OAuth tokens and determining
+if they need to be refreshed.
+"""
+
+import re
+from datetime import datetime, timedelta
+from typing import Any
+
+from marqetive.platforms.models import AuthCredentials
+
+
+def is_token_expired(
+    expires_at: datetime | None,
+    threshold_minutes: int = 5,
+) -> bool:
+    """Check if a token has expired or will expire soon.
+
+    Args:
+        expires_at: Token expiration timestamp.
+        threshold_minutes: Consider expired if expires within this many minutes.
+
+    Returns:
+        True if token is expired or will expire soon, False otherwise.
+
+    Example:
+        >>> from datetime import datetime, timedelta
+        >>> expires = datetime.now() + timedelta(minutes=3)
+        >>> is_token_expired(expires, threshold_minutes=5)
+        True
+        >>> expires = datetime.now() + timedelta(hours=1)
+        >>> is_token_expired(expires, threshold_minutes=5)
+        False
+    """
+    if expires_at is None:
+        # No expiry means token doesn't expire
+        return False
+
+    threshold = datetime.now() + timedelta(minutes=threshold_minutes)
+    return expires_at <= threshold
+
+
+def needs_refresh(
+    credentials: AuthCredentials,
+    threshold_minutes: int = 5,  # noqa: ARG001
+) -> bool:
+    """Check if credentials need to be refreshed.
+
+    Args:
+        credentials: Credentials to check.
+        threshold_minutes: Expiry threshold in minutes.
+
+    Returns:
+        True if refresh is needed, False otherwise.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     expires_at=datetime.now() + timedelta(minutes=2)
+        ... )
+        >>> needs_refresh(creds)
+        True
+    """
+    return credentials.needs_refresh()
+
+
+def validate_token_format(token: str, min_length: int = 10) -> bool:
+    """Validate basic token format.
+
+    Checks if token looks valid (not empty, meets minimum length).
+
+    Args:
+        token: Token string to validate.
+        min_length: Minimum acceptable token length.
+
+    Returns:
+        True if token format is valid, False otherwise.
+
+    Example:
+        >>> validate_token_format("abc123xyz")
+        False
+        >>> validate_token_format("a" * 50)
+        True
+    """
+    if not token or not isinstance(token, str):
+        return False
+
+    # Remove whitespace
+    token = token.strip()
+
+    # Check minimum length
+    if len(token) < min_length:
+        return False
+
+    # Check for obviously invalid tokens
+    return token.lower() not in ["none", "null", "undefined", ""]
+
+
+def validate_bearer_token(token: str) -> bool:
+    """Validate Bearer token format.
+
+    Args:
+        token: Bearer token to validate.
+
+    Returns:
+        True if token appears valid, False otherwise.
+
+    Example:
+        >>> validate_bearer_token("ya29.a0AfH6SMB...")
+        True
+        >>> validate_bearer_token("invalid")
+        False
+    """
+    # Bearer tokens are typically base64-like strings
+    if not validate_token_format(token, min_length=20):
+        return False
+
+    # Check for suspicious patterns
+    return not re.search(r"[<>\"']", token)
+
+
+def calculate_token_ttl(expires_at: datetime | None) -> timedelta | None:
+    """Calculate time-to-live for a token.
+
+    Args:
+        expires_at: Token expiration timestamp.
+
+    Returns:
+        Time remaining until expiration, or None if no expiry.
+
+    Example:
+        >>> from datetime import datetime, timedelta
+        >>> expires = datetime.now() + timedelta(hours=1)
+        >>> ttl = calculate_token_ttl(expires)
+        >>> ttl.total_seconds() > 3500  # Approximately 1 hour
+        True
+    """
+    if expires_at is None:
+        return None
+
+    now = datetime.now()
+    if expires_at <= now:
+        return timedelta(0)
+
+    return expires_at - now
+
+
+def should_proactively_refresh(
+    credentials: AuthCredentials,
+    refresh_threshold_minutes: int = 5,
+) -> bool:
+    """Determine if token should be proactively refreshed.
+
+    Checks if token will expire soon and if refresh token is available.
+
+    Args:
+        credentials: Credentials to check.
+        refresh_threshold_minutes: Refresh if expires within this many minutes.
+
+    Returns:
+        True if should proactively refresh, False otherwise.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     refresh_token="refresh",
+        ...     expires_at=datetime.now() + timedelta(minutes=3)
+        ... )
+        >>> should_proactively_refresh(creds)
+        True
+    """
+    # Need refresh token to refresh
+    if not credentials.refresh_token:
+        return False
+
+    # Check if expiring soon
+    return is_token_expired(credentials.expires_at, refresh_threshold_minutes)
+
+
+def is_credentials_complete(credentials: AuthCredentials) -> bool:
+    """Check if credentials have all required fields.
+
+    Args:
+        credentials: Credentials to validate.
+
+    Returns:
+        True if credentials are complete, False otherwise.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token"
+        ... )
+        >>> is_credentials_complete(creds)
+        True
+    """
+    # Must have platform and access token
+    if not credentials.platform or not credentials.access_token:
+        return False
+
+    # Access token must be valid format
+    return validate_token_format(credentials.access_token)
+
+
+def get_token_health_status(credentials: AuthCredentials) -> dict[str, Any]:
+    """Get comprehensive health status of credentials.
+
+    Args:
+        credentials: Credentials to analyze.
+
+    Returns:
+        Dictionary with health information.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     expires_at=datetime.now() + timedelta(hours=1)
+        ... )
+        >>> status = get_token_health_status(creds)
+        >>> status["is_valid"]
+        True
+        >>> status["needs_refresh"]
+        False
+    """
+    ttl = calculate_token_ttl(credentials.expires_at)
+
+    return {
+        "is_valid": credentials.is_valid(),
+        "is_expired": credentials.is_expired(),
+        "needs_refresh": credentials.needs_refresh(),
+        "has_refresh_token": credentials.refresh_token is not None,
+        "time_to_expiry_seconds": ttl.total_seconds() if ttl else None,
+        "should_proactively_refresh": should_proactively_refresh(credentials),
+        "status": credentials.status.value,
+        "is_complete": is_credentials_complete(credentials),
+    }