rabbitkit 0.9.0__py3-none-any.whl

rabbitkit/core/env_config.py

@@ -0,0 +1,251 @@
+"""Environment-variable driven RabbitMQ configuration.
+
+Requires: ``pip install rabbitkit[settings]``
+
+Maps ``RABBITMQ_*`` environment variables to ``RabbitConfig`` using
+pydantic-settings ``BaseSettings``.  Supports ``.env`` files, environment
+overrides, and type coercion out of the box.
+
+Lazy import — no ``ImportError`` at import time when pydantic-settings is
+absent; a placeholder class is installed instead and raises on instantiation.
+
+Quick start
+-----------
+    # .env (or set as real environment variables)
+    RABBITMQ_HOST=rabbitmq.prod.internal
+    RABBITMQ_PORT=5672
+    RABBITMQ_USER=myapp
+    RABBITMQ_PASSWORD=secret
+    RABBITMQ_VHOST=/production
+    RABBITMQ_PREFETCH_COUNT=20
+    RABBITMQ_TOPOLOGY_MODE=AUTO_DECLARE
+
+    # application code
+    from rabbitkit.core.env_config import RabbitSettings
+    from rabbitkit.async_ import AsyncBroker
+
+    settings = RabbitSettings()           # reads from env / .env automatically
+    config   = settings.to_rabbit_config()
+    broker   = AsyncBroker(config)
+
+Supported environment variables
+--------------------------------
+All variables are prefixed with ``RABBITMQ_`` and case-insensitive:
+
+Connection
+    RABBITMQ_HOST                        (str,   default "localhost")
+    RABBITMQ_PORT                        (int,   default 5672)
+    RABBITMQ_USER                        (str,   default "guest")
+    RABBITMQ_PASSWORD                    (str,   default "guest")
+    RABBITMQ_VHOST                       (str,   default "/")
+    RABBITMQ_HEARTBEAT                   (int,   default 30)
+    RABBITMQ_SOCKET_TIMEOUT              (float, default 10.0)
+    RABBITMQ_BLOCKED_CONNECTION_TIMEOUT  (float, default 60.0)
+    RABBITMQ_CONNECTION_NAME             (str | None, default None)
+    RABBITMQ_RECONNECT_BACKOFF_BASE      (float, default 1.0)
+    RABBITMQ_RECONNECT_BACKOFF_MAX       (float, default 30.0)
+
+Consumer
+    RABBITMQ_PREFETCH_COUNT              (int,   default 10)
+    RABBITMQ_GRACEFUL_TIMEOUT            (float, default 30.0)
+
+Publisher
+    RABBITMQ_CONFIRM_DELIVERY            (bool,  default True)
+    RABBITMQ_CONFIRM_TIMEOUT             (float, default 5.0)
+    RABBITMQ_MANDATORY                   (bool,  default False)
+    RABBITMQ_PERSISTENT                  (bool,  default True)
+    RABBITMQ_DEFAULT_EXCHANGE            (str,   default "")
+
+Pool
+    RABBITMQ_CHANNEL_POOL_SIZE           (int,   default 10)
+    RABBITMQ_PUBLISHER_CONNECTIONS       (int,   default 1)
+    RABBITMQ_CONSUMER_CONNECTIONS        (int,   default 1)
+    RABBITMQ_CHANNEL_ACQUIRE_TIMEOUT     (float, default 10.0)
+
+SSL
+    RABBITMQ_SSL_ENABLED                 (bool,  default False)
+    RABBITMQ_SSL_CERTFILE                (str | None, default None)
+    RABBITMQ_SSL_KEYFILE                 (str | None, default None)
+    RABBITMQ_SSL_CA_CERTS                (str | None, default None)
+    RABBITMQ_SSL_SERVER_HOSTNAME         (str | None, default None)
+
+Retry  (set RABBITMQ_RETRY_MAX_RETRIES > 0 to enable)
+    RABBITMQ_RETRY_MAX_RETRIES           (int,   default 0 — disabled)
+    RABBITMQ_RETRY_DELAYS                (str,   default "5,30,120,600" — comma-separated ints)
+    RABBITMQ_RETRY_JITTER_FACTOR         (float, default 0.1)
+
+Topology
+    RABBITMQ_TOPOLOGY_MODE               (str,   default "AUTO_DECLARE")
+                                         valid: AUTO_DECLARE, PASSIVE_ONLY, MANUAL
+
+Override at runtime
+-------------------
+pydantic-settings respects constructor keyword arguments, so you can mix
+env-file defaults with runtime overrides:
+
+    settings = RabbitSettings(host="staging-rabbit", prefetch_count=5)
+    config   = settings.to_rabbit_config()
+
+Checking availability
+---------------------
+    from rabbitkit.core.env_config import _PYDANTIC_SETTINGS_AVAILABLE
+
+    if _PYDANTIC_SETTINGS_AVAILABLE:
+        settings = RabbitSettings()
+    else:
+        config = RabbitConfig(connection=ConnectionConfig(...))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_PYDANTIC_SETTINGS_AVAILABLE = False
+
+try:
+    from pydantic import Field, SecretStr
+    from pydantic_settings import BaseSettings, SettingsConfigDict
+
+    _PYDANTIC_SETTINGS_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    pass  # pragma: no cover
+
+if _PYDANTIC_SETTINGS_AVAILABLE:
+    from rabbitkit.core.config import (
+        ConnectionConfig,
+        ConsumerConfig,
+        PoolConfig,
+        PublisherConfig,
+        RabbitConfig,
+        RetryConfig,
+        SecurityConfig,
+        SSLConfig,
+    )
+    from rabbitkit.core.types import TopologyMode
+
+    class RabbitSettings(BaseSettings):
+        """Load RabbitMQ config from RABBITMQ_* environment variables.
+
+        Example::
+
+            settings = RabbitSettings()  # reads from env / .env
+            config = settings.to_rabbit_config()
+            broker = AsyncBroker(config)
+        """
+
+        model_config = SettingsConfigDict(
+            env_prefix="RABBITMQ_",
+            case_sensitive=False,
+        )
+
+        # Connection
+        host: str = "localhost"
+        port: int = 5672
+        user: str = Field(default="guest")
+        password: SecretStr = SecretStr("guest")
+        vhost: str = "/"
+        heartbeat: int = 30
+        socket_timeout: float = 10.0
+        blocked_connection_timeout: float = 60.0
+        connection_name: str | None = None
+        reconnect_backoff_base: float = 1.0
+        reconnect_backoff_max: float = 30.0
+
+        # Consumer
+        prefetch_count: int = 10
+        graceful_timeout: float = 30.0
+
+        # Publisher
+        confirm_delivery: bool = True
+        confirm_timeout: float = 5.0
+        mandatory: bool = False
+        persistent: bool = True
+        default_exchange: str = ""
+
+        # Pool
+        channel_pool_size: int = 10
+        publisher_connections: int = 1
+        consumer_connections: int = 1
+        channel_acquire_timeout: float = 10.0
+
+        # SSL
+        ssl_enabled: bool = False
+        ssl_certfile: str | None = None
+        ssl_keyfile: str | None = None
+        ssl_ca_certs: str | None = None
+        ssl_server_hostname: str | None = None
+
+        # Retry (0 = disabled, no RetryConfig created)
+        retry_max_retries: int = 0
+        retry_delays: str = "5,30,120,600"
+        retry_jitter_factor: float = 0.1
+
+        # Topology
+        topology_mode: str = "AUTO_DECLARE"
+
+        def to_rabbit_config(self) -> RabbitConfig:
+            """Convert to a RabbitConfig dataclass."""
+            ssl = SSLConfig(
+                enabled=self.ssl_enabled,
+                certfile=self.ssl_certfile,
+                keyfile=self.ssl_keyfile,
+                ca_certs=self.ssl_ca_certs,
+                server_hostname=self.ssl_server_hostname,
+            )
+            retry: RetryConfig | None = None
+            if self.retry_max_retries > 0:
+                delays = tuple(int(d) for d in self.retry_delays.split(",") if d.strip())
+                retry = RetryConfig(
+                    max_retries=self.retry_max_retries,
+                    delays=delays,
+                    jitter_factor=self.retry_jitter_factor,
+                )
+            return RabbitConfig(
+                connection=ConnectionConfig(
+                    host=self.host,
+                    port=self.port,
+                    username=self.user,
+                    password=self.password.get_secret_value(),
+                    vhost=self.vhost,
+                    heartbeat=self.heartbeat,
+                    socket_timeout=self.socket_timeout,
+                    blocked_connection_timeout=self.blocked_connection_timeout,
+                    connection_name=self.connection_name,
+                    reconnect_backoff_base=self.reconnect_backoff_base,
+                    reconnect_backoff_max=self.reconnect_backoff_max,
+                ),
+                security=SecurityConfig(ssl=ssl),
+                consumer=ConsumerConfig(
+                    prefetch_count=self.prefetch_count,
+                    graceful_timeout=self.graceful_timeout,
+                ),
+                publisher=PublisherConfig(
+                    confirm_delivery=self.confirm_delivery,
+                    confirm_timeout=self.confirm_timeout,
+                    mandatory=self.mandatory,
+                    persistent=self.persistent,
+                    exchange=self.default_exchange,
+                ),
+                pool=PoolConfig(
+                    channel_pool_size=self.channel_pool_size,
+                    publisher_connections=self.publisher_connections,
+                    consumer_connections=self.consumer_connections,
+                    channel_acquire_timeout=self.channel_acquire_timeout,
+                ),
+                topology_mode=TopologyMode[self.topology_mode.upper()],
+                retry=retry,
+            )
+
+else:  # pragma: no cover
+
+    class RabbitSettings:  # type: ignore[no-redef]  # pragma: no cover
+        """Placeholder — pydantic-settings not installed."""
+
+        def __init__(self, **_: Any) -> None:
+            raise ImportError(
+                "RabbitSettings requires pydantic-settings. Install with: pip install rabbitkit[settings]"
+            )
+
+        def to_rabbit_config(self) -> Any:
+            """Not available without pydantic-settings."""
+            raise ImportError("pydantic-settings not installed")

rabbitkit/core/errors.py

@@ -0,0 +1,199 @@
+"""Error classification — transport-agnostic.
+
+Transport-specific exception tuples (pika.exceptions.StreamLostError, etc.)
+live in sync/connection.py and async_/connection.py, NOT here.
+
+This module provides:
+- Generic stdlib exception tuples for classification
+- Pluggable predicate-based classification
+- Configurable unknown_policy (default=PERMANENT)
+
+See Contract 7 in the plan for evaluation order and rationale.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Sequence
+
+from rabbitkit.core.types import ClassifiedError, ErrorSeverity
+
+# ── Missing DI dependency (H10) ──────────────────────────────────────────
+# Defined before PERMANENT_ERRORS below so it can be listed there directly.
+
+
+class MissingDependencyError(Exception):
+    """Raised at message-processing time when a required ``Header()`` /
+    ``Path()`` / ``Context()`` marker's value is absent from the incoming
+    message and no default is available — neither on the marker itself
+    (``Header("x-tenant", default=...)``) nor the handler's own parameter
+    default (``tenant: Annotated[str | None, Header("x-tenant")] = None``).
+
+    Names the specific parameter and marker so the failure is immediately
+    actionable — unlike the bare ``KeyError`` this replaces, which looked
+    identical to a handler bug (e.g. indexing a dict) and gave no indication
+    which DI marker was the culprit. Classified PERMANENT by
+    :func:`classify_error` (see ``PERMANENT_ERRORS`` below), matching the
+    ``KeyError`` classification it replaces: a missing required value means
+    the message itself is malformed for this handler — retrying will not fix
+    it, so it settles straight to the DLQ rather than looping.
+    """
+
+    def __init__(self, marker_repr: str, param_name: str) -> None:
+        super().__init__(
+            f"{marker_repr} for parameter {param_name!r} is required but missing from the "
+            "message, and no default is available (neither on the marker itself nor as a "
+            "Python parameter default)."
+        )
+        self.param_name = param_name
+
+
+# Generic (stdlib) error categories — transport layers extend these
+TRANSIENT_ERRORS: tuple[type[BaseException], ...] = (
+    TimeoutError,
+    EOFError,  # NOT an OSError subclass — must be listed explicitly
+    OSError,  # covers ConnectionResetError, BrokenPipeError, ConnectionAbortedError
+)
+
+PERMANENT_ERRORS: tuple[type[BaseException], ...] = (
+    json.JSONDecodeError,
+    KeyError,
+    ValueError,
+    TypeError,
+    UnicodeDecodeError,
+    AttributeError,
+    MissingDependencyError,
+)
+
+# Type alias for error predicates
+ErrorPredicate = Callable[[BaseException], bool | None]
+
+
+def classify_error(
+    exc: BaseException,
+    *,
+    predicates: Sequence[ErrorPredicate] = (),
+    transient: tuple[type[BaseException], ...] = TRANSIENT_ERRORS,
+    permanent: tuple[type[BaseException], ...] = PERMANENT_ERRORS,
+    unknown_policy: ErrorSeverity = ErrorSeverity.PERMANENT,
+) -> ClassifiedError:
+    """Classify exception severity.
+
+    Evaluation order:
+    1. User predicates (first non-None wins)
+    2. transient tuple (isinstance check)
+    3. permanent tuple (isinstance check)
+    4. unknown_policy (configurable, default=PERMANENT)
+
+    DEFAULT IS PERMANENT, NOT TRANSIENT.
+    Reason: unknown errors include malformed payloads, business validation
+    failures, handler bugs, and schema mismatches. Treating these as
+    transient creates retry storms. Network/connection errors are already
+    in the transient tuple.
+
+    Override per-route: RetryMiddleware accepts unknown_policy to change
+    per route.
+
+    Args:
+        exc: The exception to classify.
+        predicates: User-provided classification functions.
+            Return True=transient, False=permanent, None=no opinion.
+        transient: Exception types considered transient.
+        permanent: Exception types considered permanent.
+        unknown_policy: Severity for unclassified exceptions.
+
+    Returns:
+        ClassifiedError with severity, original exception, and reason.
+    """
+    # 1. User predicates (first non-None wins)
+    for predicate in predicates:
+        result = predicate(exc)
+        if result is True:
+            return ClassifiedError(
+                severity=ErrorSeverity.TRANSIENT,
+                original=exc,
+                reason=f"predicate classified as transient: {type(exc).__name__}",
+            )
+        if result is False:
+            return ClassifiedError(
+                severity=ErrorSeverity.PERMANENT,
+                original=exc,
+                reason=f"predicate classified as permanent: {type(exc).__name__}",
+            )
+
+    # 2. Transient tuple (isinstance check)
+    if isinstance(exc, transient):
+        return ClassifiedError(
+            severity=ErrorSeverity.TRANSIENT,
+            original=exc,
+            reason=f"transient error: {type(exc).__name__}",
+        )
+
+    # 3. Permanent tuple (isinstance check)
+    if isinstance(exc, permanent):
+        return ClassifiedError(
+            severity=ErrorSeverity.PERMANENT,
+            original=exc,
+            reason=f"permanent error: {type(exc).__name__}",
+        )
+
+    # 4. Unknown policy
+    return ClassifiedError(
+        severity=unknown_policy,
+        original=exc,
+        reason=f"unknown error classified as {unknown_policy.value}: {type(exc).__name__}",
+    )
+
+
+# ── Configuration error (single canonical location) ─────────────────────
+
+
+class ConfigurationError(Exception):
+    """Raised for invalid configuration detected at registration time.
+
+    Single canonical class for all registration-time misconfigurations (route
+    conflicts, invalid handler signatures, bad retry/ack combinations). Both
+    ``core/route.py`` and ``di/resolver.py`` raise this; tests/users can catch
+    one type regardless of import source.
+    """
+
+
+# ── Unsafe topology error ────────────────────────────────────────────────
+
+
+class UnsafeTopologyError(ConfigurationError):
+    """Raised at startup when ``RejectWithoutDLXPolicy.ERROR`` is active and a
+    route can ``reject(requeue=False)`` but its queue has no dead-letter
+    exchange — RabbitMQ would silently discard rejected messages.
+
+    Subclasses :class:`ConfigurationError` so existing catch-alls for
+    registration/startup misconfiguration keep working.
+    """
+
+
+# ── Publish error (opt-in) ───────────────────────────────────────────────
+
+
+class PublishError(Exception):
+    """Raised by ``PublishOutcome.raise_for_status()`` on a failed publish.
+
+    ``broker.publish()`` never raises on its own — it returns a
+    ``PublishOutcome`` so callers can decide how to handle NACKED / TIMEOUT /
+    RETURNED / ERROR. Code that prefers exceptions can opt in with
+    ``broker.publish(...).raise_for_status()``. Carries the ``outcome`` for
+    inspection (status, routing_key, underlying error).
+    """
+
+    def __init__(self, outcome: object) -> None:
+        self.outcome = outcome
+        super().__init__(str(outcome))
+
+
+# ── Backpressure error ───────────────────────────────────────────────────
+
+
+class BackpressureError(Exception):
+    """Raised when publish-side flow control blocks a publish attempt.
+
+    Only raised when ``BackpressureConfig.on_blocked == "raise"``.
+    """