kstlib 0.0.1a0__py3-none-any.whl → 1.0.1__py3-none-any.whl

kstlib/alerts/models.py

@@ -0,0 +1,142 @@
+"""Data models for the alerts module.
+
+This module defines the core data structures for alert messages, levels,
+and delivery results.
+
+Examples:
+    Creating an alert message::
+
+        from kstlib.alerts.models import AlertLevel, AlertMessage
+
+        alert = AlertMessage(
+            title="Server Down",
+            body="Production server api-1 is not responding",
+            level=AlertLevel.CRITICAL,
+        )
+
+    Checking alert results::
+
+        from kstlib.alerts.models import AlertResult
+
+        result = AlertResult(channel="slack", success=True, message_id="12345")
+        if result.success:
+            print(f"Alert delivered: {result.message_id}")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import IntEnum
+
+
+class AlertLevel(IntEnum):
+    """Severity level for alerts.
+
+    Values are ordered by severity (higher value = more severe).
+    Use these to filter which alerts go to which channels.
+
+    Attributes:
+        INFO: Informational messages (10).
+        WARNING: Warning conditions that need attention (20).
+        CRITICAL: Critical issues requiring immediate action (30).
+
+    Examples:
+        >>> AlertLevel.CRITICAL > AlertLevel.WARNING
+        True
+        >>> AlertLevel.INFO.name
+        'INFO'
+        >>> int(AlertLevel.WARNING)
+        20
+    """
+
+    INFO = 10
+    WARNING = 20
+    CRITICAL = 30
+
+
+@dataclass(frozen=True, slots=True)
+class AlertMessage:
+    """An alert message to be sent via one or more channels.
+
+    Attributes:
+        title: Short summary of the alert (max 150 chars for Slack).
+        body: Detailed message content (max 3000 chars for Slack).
+        level: Severity level of the alert.
+        timestamp: If True, prefix title with send datetime.
+
+    Examples:
+        >>> msg = AlertMessage(title="Disk Full", body="Server disk at 95%")
+        >>> msg.level
+        <AlertLevel.INFO: 10>
+        >>> msg = AlertMessage(
+        ...     title="DB Connection Failed",
+        ...     body="Cannot connect to primary database",
+        ...     level=AlertLevel.CRITICAL,
+        ... )
+        >>> msg.level.name
+        'CRITICAL'
+        >>> msg = AlertMessage(
+        ...     title="Alert",
+        ...     body="With timestamp",
+        ...     timestamp=True,
+        ... )
+        >>> ":::" in msg.formatted_title
+        True
+    """
+
+    title: str
+    body: str
+    level: AlertLevel = AlertLevel.INFO
+    timestamp: bool = False
+
+    @property
+    def formatted_title(self) -> str:
+        """Return title with optional timestamp prefix.
+
+        If timestamp is True, prefixes the title with current datetime
+        in format "YYYY-MM-DD HH:MM:SS ::: ".
+
+        Returns:
+            Title string, optionally prefixed with timestamp.
+
+        Examples:
+            >>> msg = AlertMessage(title="Test", body="Body", timestamp=False)
+            >>> msg.formatted_title
+            'Test'
+            >>> msg = AlertMessage(title="Test", body="Body", timestamp=True)
+            >>> "Test" in msg.formatted_title
+            True
+        """
+        if self.timestamp:
+            now = datetime.now(timezone.utc).astimezone().strftime("%Y-%m-%d %H:%M:%S")
+            return f"{now} ::: {self.title}"
+        return self.title
+
+
+@dataclass(frozen=True, slots=True)
+class AlertResult:
+    """Result of sending an alert to a channel.
+
+    Attributes:
+        channel: Name of the channel that processed this alert.
+        success: Whether the alert was delivered successfully.
+        message_id: ID assigned by the channel (if available).
+        error: Error message if delivery failed.
+
+    Examples:
+        >>> result = AlertResult(channel="slack", success=True, message_id="msg123")
+        >>> result.success
+        True
+        >>> result = AlertResult(channel="email", success=False, error="SMTP timeout")
+        >>> result.error
+        'SMTP timeout'
+    """
+
+    channel: str
+    success: bool
+    message_id: str | None = None
+    error: str | None = None
+
+
+__all__ = ["AlertLevel", "AlertMessage", "AlertResult"]

kstlib/alerts/throttle.py

@@ -0,0 +1,263 @@
+"""Alert throttling using rate limiting.
+
+Provides rate limiting for alerts to prevent flooding channels during
+incident storms. Wraps :class:`kstlib.resilience.rate_limiter.RateLimiter`.
+
+Configuration is read from ``kstlib.conf.yml`` under the ``alerts.throttle``
+section, with hard limits enforced for deep defense.
+
+Examples:
+    Config-driven (recommended)::
+
+        from kstlib.alerts.throttle import AlertThrottle
+
+        # Uses alerts.throttle from kstlib.conf.yml
+        throttle = AlertThrottle()
+
+        if throttle.try_acquire():
+            await channel.send(alert)
+
+    Explicit override::
+
+        # Override config values
+        throttle = AlertThrottle(rate=5, per=30.0)
+
+    With async context::
+
+        throttle = AlertThrottle()
+
+        async with throttle:
+            await channel.send(alert)  # Waits if rate limit hit
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from kstlib.alerts.exceptions import AlertThrottledError
+from kstlib.limits import (
+    HARD_MAX_THROTTLE_PER,
+    HARD_MAX_THROTTLE_RATE,
+    HARD_MIN_THROTTLE_PER,
+    HARD_MIN_THROTTLE_RATE,
+    clamp_with_limits,
+    get_alerts_limits,
+)
+from kstlib.resilience.rate_limiter import RateLimiter
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+__all__ = ["AlertThrottle"]
+
+
+class AlertThrottle:
+    """Rate limiter for alert delivery.
+
+    Wraps :class:`kstlib.resilience.rate_limiter.RateLimiter` with
+    alert-specific behavior and config-driven defaults.
+
+    All parameters are optional. If not provided, values are read from
+    ``kstlib.conf.yml`` under ``alerts.throttle``. Hard limits are enforced
+    for deep defense against misconfiguration.
+
+    Args:
+        rate: Maximum alerts per period. If None, uses config value.
+            Hard limits: [1, 1000].
+        per: Period duration in seconds. If None, uses config value.
+            Hard limits: [1.0, 86400.0] (1 day).
+        burst: Initial capacity. If None, defaults to rate value.
+            Hard limits: [1, rate].
+        name: Optional name for identification.
+
+    Examples:
+        Config-driven (recommended)::
+
+            throttle = AlertThrottle()  # Uses kstlib.conf.yml
+
+        Explicit values::
+
+            throttle = AlertThrottle(rate=10, per=60.0)
+
+        Per-hour limiting with burst::
+
+            throttle = AlertThrottle(rate=100, per=3600.0, burst=20)
+
+        Non-blocking check::
+
+            if throttle.try_acquire():
+                send_alert()
+            else:
+                log.warning("Alert throttled")
+    """
+
+    def __init__(
+        self,
+        rate: float | None = None,
+        per: float | None = None,
+        *,
+        burst: float | None = None,
+        name: str | None = None,
+    ) -> None:
+        """Initialize AlertThrottle.
+
+        Args:
+            rate: Maximum alerts per period. If None, uses config.
+            per: Period duration in seconds. If None, uses config.
+            burst: Initial token count. If None, defaults to rate.
+            name: Optional name for identification.
+        """
+        # Load config defaults
+        limits = get_alerts_limits()
+
+        # Apply kwargs > config > defaults pattern with hard limit clamping
+        resolved_rate = clamp_with_limits(
+            rate if rate is not None else limits.throttle_rate,
+            HARD_MIN_THROTTLE_RATE,
+            HARD_MAX_THROTTLE_RATE,
+        )
+        resolved_per = clamp_with_limits(
+            per if per is not None else limits.throttle_per,
+            HARD_MIN_THROTTLE_PER,
+            HARD_MAX_THROTTLE_PER,
+        )
+
+        # Burst: kwargs > config > rate, clamped to [1, rate]
+        if burst is not None:
+            resolved_burst = clamp_with_limits(burst, 1, resolved_rate)
+        else:
+            resolved_burst = clamp_with_limits(limits.throttle_burst, 1, resolved_rate)
+
+        self._limiter = RateLimiter(
+            rate=resolved_rate,
+            per=resolved_per,
+            burst=resolved_burst,
+            name=name,
+        )
+
+    @property
+    def rate(self) -> float:
+        """Maximum alerts per period."""
+        return self._limiter.rate
+
+    @property
+    def per(self) -> float:
+        """Period duration in seconds."""
+        return self._limiter.per
+
+    @property
+    def available(self) -> float:
+        """Current available tokens (alerts allowed)."""
+        return self._limiter.tokens
+
+    @property
+    def time_until_available(self) -> float:
+        """Seconds until next alert can be sent."""
+        return self._limiter.time_until_token()
+
+    def try_acquire(self) -> bool:
+        """Try to acquire permission to send an alert.
+
+        Returns:
+            True if alert can be sent, False if throttled.
+
+        Examples:
+            >>> throttle = AlertThrottle(rate=2, per=1.0)
+            >>> throttle.try_acquire()
+            True
+            >>> throttle.try_acquire()
+            True
+            >>> throttle.try_acquire()  # Throttled
+            False
+        """
+        return self._limiter.try_acquire()
+
+    def acquire(self, *, timeout: float | None = None) -> None:
+        """Acquire permission to send an alert, blocking if needed.
+
+        Args:
+            timeout: Maximum time to wait in seconds.
+
+        Raises:
+            AlertThrottledError: If timeout exceeded.
+
+        Examples:
+            >>> throttle = AlertThrottle(rate=10, per=60.0)
+            >>> throttle.acquire()  # Blocks if needed
+        """
+        try:
+            self._limiter.acquire(blocking=True, timeout=timeout)
+        except Exception:
+            raise AlertThrottledError(
+                "Alert rate limit exceeded",
+                retry_after=self.time_until_available,
+            ) from None
+
+    async def acquire_async(self, *, timeout: float | None = None) -> None:
+        """Acquire permission asynchronously, waiting if needed.
+
+        Args:
+            timeout: Maximum time to wait in seconds.
+
+        Raises:
+            AlertThrottledError: If timeout exceeded.
+
+        Examples:
+            >>> import asyncio
+            >>> throttle = AlertThrottle(rate=10, per=60.0)
+            >>> asyncio.run(throttle.acquire_async())
+        """
+        try:
+            await self._limiter.acquire_async(timeout=timeout)
+        except Exception:
+            raise AlertThrottledError(
+                "Alert rate limit exceeded",
+                retry_after=self.time_until_available,
+            ) from None
+
+    def reset(self) -> None:
+        """Reset throttle to full capacity.
+
+        Examples:
+            >>> throttle = AlertThrottle(rate=1, per=60.0)
+            >>> throttle.try_acquire()
+            True
+            >>> throttle.try_acquire()
+            False
+            >>> throttle.reset()
+            >>> throttle.try_acquire()
+            True
+        """
+        self._limiter.reset()
+
+    def __enter__(self) -> Self:
+        """Enter context manager, acquiring permission."""
+        self.acquire()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit context manager."""
+        pass
+
+    async def __aenter__(self) -> Self:
+        """Enter async context manager, acquiring permission."""
+        await self.acquire_async()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit async context manager."""
+        pass
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"AlertThrottle(rate={self.rate}, per={self.per})"

kstlib/auth/__init__.py

@@ -0,0 +1,139 @@
+# pylint: disable=duplicate-code
+"""OAuth2/OIDC authentication module for kstlib.
+
+This module provides a config-driven authentication layer supporting:
+- OAuth2 Authorization Code flow
+- OIDC with PKCE extension
+- Automatic token refresh
+- Secure token storage (SOPS encrypted or memory)
+- Preflight validation for IdP configuration
+
+Example (explicit configuration):
+    >>> from kstlib.auth import AuthSession, OIDCProvider, AuthProviderConfig  # doctest: +SKIP
+    >>> from kstlib.auth import MemoryTokenStorage  # doctest: +SKIP
+    >>>
+    >>> config = AuthProviderConfig(  # doctest: +SKIP
+    ...     client_id="my-app",
+    ...     issuer="https://auth.example.com",
+    ...     scopes=["openid", "profile"],
+    ... )
+    >>> provider = OIDCProvider("example", config, MemoryTokenStorage())  # doctest: +SKIP
+    >>> with AuthSession(provider) as session:  # doctest: +SKIP
+    ...     resp = session.get("https://api.example.com/users/me")
+
+Example (config-driven):
+    >>> # Configure in kstlib.conf.yml:
+    >>> # auth:
+    >>> #   providers:
+    >>> #     corporate:
+    >>> #       type: oidc
+    >>> #       issuer: https://idp.corp.local/realms/main
+    >>> #       client_id: my-app
+    >>> #       pkce: true
+    >>> from kstlib.auth import OIDCProvider, AuthSession
+    >>> provider = OIDCProvider.from_config("corporate")  # doctest: +SKIP
+    >>> with AuthSession(provider) as session:  # doctest: +SKIP
+    ...     resp = session.get("https://api.corp.local/users/me")
+
+See Also:
+    - :mod:`kstlib.auth.config` for config loading helpers
+    - :mod:`kstlib.auth.models` for data models
+    - :mod:`kstlib.auth.errors` for exception hierarchy
+    - :mod:`kstlib.auth.providers` for provider implementations
+"""
+
+from __future__ import annotations
+
+from kstlib.auth.callback import CallbackResult, CallbackServer
+from kstlib.auth.config import (
+    build_provider_config,
+    get_auth_config,
+    get_callback_server_config,
+    get_default_provider_name,
+    get_provider_config,
+    get_token_storage_from_config,
+    list_configured_providers,
+)
+from kstlib.auth.errors import (
+    AuthError,
+    AuthorizationError,
+    CallbackServerError,
+    ConfigurationError,
+    DiscoveryError,
+    PreflightError,
+    ProviderNotFoundError,
+    TokenError,
+    TokenExchangeError,
+    TokenExpiredError,
+    TokenRefreshError,
+    TokenStorageError,
+    TokenValidationError,
+)
+from kstlib.auth.models import (
+    AuthFlow,
+    PreflightReport,
+    PreflightResult,
+    PreflightStatus,
+    Token,
+    TokenType,
+)
+from kstlib.auth.providers import (
+    AbstractAuthProvider,
+    AuthProviderConfig,
+    OAuth2Provider,
+    OIDCProvider,
+)
+from kstlib.auth.session import AuthSession
+from kstlib.auth.token import (
+    AbstractTokenStorage,
+    MemoryTokenStorage,
+    SOPSTokenStorage,
+    get_token_storage,
+)
+
+__all__ = [
+    # Providers
+    "AbstractAuthProvider",
+    # Token storage
+    "AbstractTokenStorage",
+    # Errors
+    "AuthError",
+    # Models
+    "AuthFlow",
+    "AuthProviderConfig",
+    # Session
+    "AuthSession",
+    "AuthorizationError",
+    # Callback server
+    "CallbackResult",
+    "CallbackServer",
+    "CallbackServerError",
+    "ConfigurationError",
+    "DiscoveryError",
+    "MemoryTokenStorage",
+    "OAuth2Provider",
+    "OIDCProvider",
+    "PreflightError",
+    "PreflightReport",
+    "PreflightResult",
+    "PreflightStatus",
+    "ProviderNotFoundError",
+    "SOPSTokenStorage",
+    "Token",
+    "TokenError",
+    "TokenExchangeError",
+    "TokenExpiredError",
+    "TokenRefreshError",
+    "TokenStorageError",
+    "TokenType",
+    "TokenValidationError",
+    # Config helpers
+    "build_provider_config",
+    "get_auth_config",
+    "get_callback_server_config",
+    "get_default_provider_name",
+    "get_provider_config",
+    "get_token_storage",
+    "get_token_storage_from_config",
+    "list_configured_providers",
+]