rabbitkit 0.9.0__py3-none-any.whl

rabbitkit/core/logging.py

@@ -0,0 +1,261 @@
+"""Structured logging configuration for rabbitkit.
+
+structlog is a declared dependency but must be explicitly configured.
+``LoggingConfig`` controls rendering (JSON for prod, console for dev).
+Once configured, all rabbitkit internals (pipeline, broker, transport) emit
+structured log events with per-message context automatically bound via
+``structlog.contextvars``.
+
+Usage
+-----
+Pass ``logging=LoggingConfig(...)`` to ``RabbitConfig`` and the broker will
+call ``configure_structlog()`` on ``start()``:
+
+    from rabbitkit import RabbitConfig
+    from rabbitkit.core.logging import LoggingConfig
+    from rabbitkit.async_ import AsyncBroker
+
+    # Development — coloured console output
+    broker = AsyncBroker(
+        RabbitConfig(
+            logging=LoggingConfig(render_json=False, include_caller_info=True)
+        )
+    )
+
+    # Production — JSON lines to stdout (pipe to fluentd / Loki / etc.)
+    broker = AsyncBroker(
+        RabbitConfig(
+            logging=LoggingConfig(render_json=True, timestamper_fmt="iso")
+        )
+    )
+
+Per-message context
+-------------------
+The pipeline automatically binds these keys for every message:
+
+    message_id, routing_key, queue, handler
+
+They appear in every log line emitted while the handler runs and are cleared
+in a ``finally`` block so they never bleed into unrelated events.
+
+Manual configuration
+--------------------
+Call ``configure_structlog()`` directly if you manage the broker lifecycle
+yourself and do not use ``RabbitConfig.logging``:
+
+    from rabbitkit.core.logging import configure_structlog, LoggingConfig
+
+    configure_structlog(LoggingConfig(render_json=True))
+
+Safe to call multiple times — last call wins.
+
+Secrets and message content (L16)
+----------------------------------
+rabbitkit's own structured log events never include the message body or
+the raw ``headers`` dict — only ``message_id``, ``routing_key``, ``queue``,
+and ``handler`` are bound per message. Bodies/headers may legitimately
+carry credentials or PII, so this is deliberate: none of rabbitkit's
+internal logging can leak them.
+
+That guarantee does not extend to log calls YOU write. If your own
+handler code does e.g. ``logger.info("processing", headers=msg.headers)``,
+whatever is in that dict goes out verbatim. Because ``configure_structlog()``
+sets structlog's *global* processor chain, ``LoggingConfig.redact_keys``
+(enabled by default) applies to those calls too: any top-level event field,
+or field one level deep inside a nested dict (e.g. ``headers={...}``),
+whose key case-insensitively matches -- or contains all the underscore-
+separated words of -- an entry in ``redact_keys`` is replaced with a fixed
+redacted marker before rendering. The word-based matching is what catches
+compound key names like ``x-auth-token`` or ``session-token`` against the
+standalone ``token``/``auth`` defaults, without treating a partial word
+from a compound default (e.g. ``key`` from ``api_key``) as a standalone
+matcher -- that would misfire on unrelated fields like ``primary_key``.
+This is a best-effort, key-name-based scrubber — not a PII/content
+scanner, and not a substitute for simply not logging bodies/headers
+containing secrets in the first place. Pass ``redact_keys=None`` to
+disable it, or a custom ``frozenset`` to redact your own key names instead
+of (or in addition to) the defaults.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import structlog
+
+# L16: common credential/secret-bearing key names, matched case-insensitively.
+# Deliberately name-based (not content-based) -- see the module docstring.
+DEFAULT_REDACT_KEYS: frozenset[str] = frozenset(
+    {
+        "password",
+        "passwd",
+        "secret",
+        "token",
+        "api_key",
+        "apikey",
+        "authorization",
+        "auth",
+        "access_token",
+        "refresh_token",
+        "private_key",
+        "client_secret",
+    }
+)
+
+_REDACTED = "***REDACTED***"
+
+
+@dataclass(frozen=True, slots=True)
+class LoggingConfig:
+    """Structured logging configuration.
+
+    Attributes:
+        render_json: True for JSON output (prod), False for console (dev).
+        add_log_level: Include log level in output.
+        timestamper_fmt: Timestamp format ("iso", "unix", or None to disable).
+        include_caller_info: Add filename/line number to log events.
+        redact_keys: Key names to redact from log events -- checked at the
+            top level and one level deep inside nested dict values (e.g. a
+            ``headers={...}`` field). Matching is case-insensitive and
+            normalizes AMQP-style ``x-`` prefixes/hyphens, so ``api_key``
+            also matches ``X-Api-Key``. Defaults to
+            :data:`DEFAULT_REDACT_KEYS`. Pass ``None`` to disable redaction
+            entirely, or your own ``frozenset`` to customize it. See the
+            module docstring ("Secrets and message content") for scope and
+            limitations.
+        capture_warnings: Route Python's ``warnings`` module (used for every
+            rabbitkit safety warning -- topology drift, retry-without-
+            confirms, unsafe TLS, dashboard auth, ...) through the standard
+            ``logging`` module via ``logging.captureWarnings()``. Without
+            this, ``warnings.warn()`` writes directly to ``sys.stderr`` in
+            its own format, completely bypassing whatever log pipeline
+            ``render_json``/handlers were set up for -- a "loud warning" is
+            only actually loud if something is watching raw stderr in dev;
+            in a production JSON-logging deployment it's invisible unless
+            this is enabled. Default ``True``. Set ``False`` if your
+            application already manages ``captureWarnings`` itself.
+    """
+
+    render_json: bool = False
+    add_log_level: bool = True
+    timestamper_fmt: str = "iso"
+    include_caller_info: bool = False
+    redact_keys: frozenset[str] | None = DEFAULT_REDACT_KEYS
+    capture_warnings: bool = True
+
+
+def _normalize_key(key: str) -> str:
+    """Normalize a key for comparison (L16).
+
+    AMQP headers conventionally use a ``x-`` prefix and hyphens (e.g.
+    ``x-api-key``), not the Python-style snake_case of
+    :data:`DEFAULT_REDACT_KEYS` (``api_key``). Stripping the ``x-`` prefix
+    and folding hyphens to underscores lets both spellings match the same
+    default entry.
+    """
+    lowered = key.lower()
+    if lowered.startswith("x-"):
+        lowered = lowered[2:]
+    return lowered.replace("-", "_")
+
+
+def _redact_processor(keys: frozenset[str]) -> Any:
+    """Build a structlog processor that redacts *keys* (L16).
+
+    Checks event-dict keys at the top level and one level deep inside any
+    nested ``dict`` value (covers the common ``headers={...}`` shape),
+    normalized via :func:`_normalize_key`. Not a recursive/deep scan -- see
+    the module docstring for why a shallow, name-based approach is the
+    deliberate scope here.
+
+    Matching a normalized key against *keys* is a word-set match, not an
+    exact-string match: a configured key may itself be a compound
+    (``api_key``, ``access_token``), so a target key matches when it
+    contains ALL of some configured key's underscore-separated words (in
+    any order) -- e.g. ``x-auth-token`` normalizes to ``auth_token``,
+    which contains the words of the standalone ``token`` entry, so it
+    matches even though ``auth_token`` itself isn't literally one of the
+    configured names. Exact-string matching alone let common compound
+    secret-bearing names (``x-auth-token``, ``session-token``,
+    ``x-secret-key``, ``bearer-token``, ...) slip through untouched.
+    Splitting each configured key into its OWN word-set (rather than
+    pooling every word from every configured key into one flat set) is
+    what keeps this from over-matching: naively treating ``api_key``'s
+    ``key`` as a standalone matcher would redact totally benign fields
+    like ``primary_key``/``cache_key``, since neither contains ``api``.
+    """
+    redact_word_sets = [frozenset(_normalize_key(k).split("_")) for k in keys]
+
+    def matches(normalized_key: str) -> bool:
+        key_words = frozenset(normalized_key.split("_"))
+        return any(words <= key_words for words in redact_word_sets)
+
+    def processor(logger: Any, method_name: str, event_dict: dict[str, Any]) -> dict[str, Any]:
+        for key, value in event_dict.items():
+            if matches(_normalize_key(key)):
+                event_dict[key] = _REDACTED
+            elif isinstance(value, dict):
+                event_dict[key] = {
+                    nested_key: (_REDACTED if matches(_normalize_key(nested_key)) else nested_value)
+                    for nested_key, nested_value in value.items()
+                }
+        return event_dict
+
+    return processor
+
+
+def configure_structlog(config: LoggingConfig | None = None) -> None:
+    """One-time structlog configuration.
+
+    Safe to call multiple times — last call wins.
+    If config is None, uses defaults (console renderer, ISO timestamps).
+    """
+    import logging
+
+    import structlog
+
+    if config is None:
+        config = LoggingConfig()
+
+    # L16 follow-up: bridge warnings.warn() (every rabbitkit safety warning)
+    # into the standard logging module -- otherwise it bypasses this whole
+    # pipeline entirely, writing straight to sys.stderr in its own format.
+    logging.captureWarnings(config.capture_warnings)
+
+    processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+    ]
+
+    if config.redact_keys:
+        processors.append(_redact_processor(config.redact_keys))
+
+    if config.add_log_level:
+        processors.append(structlog.stdlib.add_log_level)
+
+    if config.timestamper_fmt:
+        fmt = config.timestamper_fmt if config.timestamper_fmt != "iso" else "iso"
+        processors.append(structlog.processors.TimeStamper(fmt=fmt))
+
+    if config.include_caller_info:
+        processors.append(structlog.processors.CallsiteParameterAdder())
+
+    processors.append(structlog.stdlib.PositionalArgumentsFormatter())
+    processors.append(structlog.processors.StackInfoRenderer())
+    processors.append(structlog.processors.UnicodeDecoder())
+
+    if config.render_json:
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        processors.append(structlog.dev.ConsoleRenderer())
+
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )

rabbitkit/core/message.py

@@ -0,0 +1,235 @@
+"""Rich incoming message with runtime-aware ack/nack/reject.
+
+See Contract 2 in the plan for sync/async ack design.
+
+Sync transport sets _ack_fn. Async transport sets _ack_async_fn.
+Pipeline calls the appropriate variant internally.
+MANUAL mode handlers choose ack() or ack_async() based on their runtime.
+Idempotent: double-ack is a no-op (guarded by _disposition state).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from typing import Any
+
+
+def is_rabbit_message_annotation(ann: Any) -> bool:
+    """True if ``ann`` is/mentions :class:`RabbitMessage`.
+
+    Handles both the resolved class and the string form (``"RabbitMessage"``)
+    produced by ``from __future__ import annotations`` when the hint can't be
+    resolved by ``typing.get_type_hints`` (e.g. a handler in a module that didn't
+    import the name). Recognizing the string form prevents valid
+    ``(body: bytes, msg: RabbitMessage)`` handlers from being mis-classified as
+    having two body-like parameters / wrong body-type detection.
+    """
+    if ann is RabbitMessage:
+        return True
+    if isinstance(ann, str):
+        return ann == "RabbitMessage" or ann.endswith(".RabbitMessage")
+    return False
+
+
+class RabbitMessage:
+    """Rich incoming message with transport-aware settlement.
+
+    The message object wraps raw AMQP delivery data and provides:
+    - Typed access to headers, properties, routing info
+    - Sync and async ack/nack/reject methods
+    - Idempotent settlement (double-ack is a no-op)
+    - Topic wildcard path extraction
+    """
+
+    __slots__ = (
+        "_ack_async_fn",
+        "_ack_fn",
+        "_disposition",
+        "_nack_async_fn",
+        "_nack_fn",
+        "_reject_async_fn",
+        "_reject_fn",
+        "app_id",
+        "body",
+        "consumer_tag",
+        "content_encoding",
+        "content_type",
+        "correlation_id",
+        "delivery_tag",
+        "exchange",
+        "expiration",
+        "headers",
+        "message_id",
+        "path",
+        "priority",
+        "raw_message",
+        "redelivered",
+        "reply_to",
+        "routing_key",
+        "timestamp",
+        "type",
+        "user_id",
+    )
+
+    def __init__(
+        self,
+        *,
+        body: bytes,
+        headers: dict[str, Any] | None = None,
+        message_id: str | None = None,
+        correlation_id: str | None = None,
+        reply_to: str | None = None,
+        content_type: str | None = None,
+        content_encoding: str | None = None,
+        timestamp: datetime | None = None,
+        type: str | None = None,  # noqa: A002 — AMQP property name
+        app_id: str | None = None,
+        priority: int | None = None,
+        expiration: str | None = None,
+        user_id: str | None = None,
+        routing_key: str = "",
+        exchange: str = "",
+        delivery_tag: int | None = None,
+        redelivered: bool = False,
+        consumer_tag: str | None = None,
+        path: dict[str, str] | None = None,
+        raw_message: Any = None,
+    ) -> None:
+        self.body = body
+        self.headers: dict[str, Any] = headers or {}
+        self.message_id = message_id
+        self.correlation_id = correlation_id
+        self.reply_to = reply_to
+        self.content_type = content_type
+        self.content_encoding = content_encoding
+        self.timestamp = timestamp
+        self.type = type
+        self.app_id = app_id
+        self.priority = priority
+        self.expiration = expiration
+        self.user_id = user_id
+        self.routing_key = routing_key
+        self.exchange = exchange
+        self.delivery_tag = delivery_tag
+        self.redelivered = redelivered
+        self.consumer_tag = consumer_tag
+        self.path: dict[str, str] = path or {}
+        self.raw_message = raw_message
+
+        # Transport-injected settlement functions (internal)
+        self._ack_fn: Callable[[], None] | None = None
+        self._ack_async_fn: Callable[[], Awaitable[None]] | None = None
+        self._nack_fn: Callable[[bool], None] | None = None
+        self._nack_async_fn: Callable[[bool], Awaitable[None]] | None = None
+        self._reject_fn: Callable[[bool], None] | None = None
+        self._reject_async_fn: Callable[[bool], Awaitable[None]] | None = None
+        self._disposition: str = "pending"
+
+    @property
+    def is_settled(self) -> bool:
+        """True if the message has been acked, nacked, or rejected."""
+        return self._disposition != "pending"
+
+    @property
+    def disposition(self) -> str:
+        """Final settlement state: "pending", "acked", "nacked", or "rejected" (M2)."""
+        return self._disposition
+
+    # ── Sync settlement ───────────────────────────────────────────────────
+
+    def ack(self) -> None:
+        """Synchronous ack. Raises RuntimeError on async-only transport.
+
+        Sets disposition only after the transport call succeeds, so a failed
+        ack (channel closed, frame error) leaves the message unsettled and the
+        exception propagates to the recovery loop instead of being swallowed.
+        """
+        if self._disposition != "pending":
+            return  # idempotent guard
+        if self._ack_fn is None:
+            msg = "Cannot sync-ack an async transport message. Use await msg.ack_async()."
+            raise RuntimeError(msg)
+        self._ack_fn()  # may raise — disposition stays "pending" on failure
+        self._disposition = "acked"
+
+    def nack(self, requeue: bool = True) -> None:
+        """Synchronous nack. Raises RuntimeError on async-only transport."""
+        if self._disposition != "pending":
+            return
+        if self._nack_fn is None:
+            msg = "Cannot sync-nack an async transport message. Use await msg.nack_async()."
+            raise RuntimeError(msg)
+        self._nack_fn(requeue)
+        self._disposition = "nacked"
+
+    def reject(self, requeue: bool = False) -> None:
+        """Synchronous reject. Raises RuntimeError on async-only transport."""
+        if self._disposition != "pending":
+            return
+        if self._reject_fn is None:
+            msg = "Cannot sync-reject an async transport message. Use await msg.reject_async()."
+            raise RuntimeError(msg)
+        self._reject_fn(requeue)
+        self._disposition = "rejected"
+
+    # ── Async settlement ──────────────────────────────────────────────────
+
+    async def ack_async(self) -> None:
+        """Async ack. Falls back to sync if async fn not set."""
+        if self._disposition != "pending":
+            return
+        if self._ack_async_fn:
+            await self._ack_async_fn()
+        elif self._ack_fn:
+            self._ack_fn()
+        else:
+            raise RuntimeError("Cannot async-ack: no settlement fn set. Use msg.ack() on a sync transport.")
+        self._disposition = "acked"
+
+    async def nack_async(self, requeue: bool = True) -> None:
+        """Async nack. Falls back to sync if async fn not set."""
+        if self._disposition != "pending":
+            return
+        if self._nack_async_fn:
+            await self._nack_async_fn(requeue)
+        elif self._nack_fn:
+            self._nack_fn(requeue)
+        else:
+            raise RuntimeError("Cannot async-nack: no settlement fn set. Use msg.nack() on a sync transport.")
+        self._disposition = "nacked"
+
+    async def reject_async(self, requeue: bool = False) -> None:
+        """Async reject. Falls back to sync if async fn not set."""
+        if self._disposition != "pending":
+            return
+        if self._reject_async_fn:
+            await self._reject_async_fn(requeue)
+        elif self._reject_fn:
+            self._reject_fn(requeue)
+        else:
+            raise RuntimeError("Cannot async-reject: no settlement fn set. Use msg.reject() on a sync transport.")
+        self._disposition = "rejected"
+
+
+# ── Exception-based ack control ──────────────────────────────────────────
+
+
+class AckMessage(Exception):
+    """Raise from handler to ack the message."""
+
+
+class NackMessage(Exception):
+    """Raise from handler to nack the message."""
+
+    def __init__(self, requeue: bool = True) -> None:
+        super().__init__()
+        self.requeue = requeue
+
+
+class RejectMessage(Exception):
+    """Raise from handler to reject the message."""
+
+    def __init__(self, requeue: bool = False) -> None:
+        super().__init__()
+        self.requeue = requeue

rabbitkit/core/path.py

@@ -0,0 +1,53 @@
+"""Named routing-key segments for ``Path()`` dependency injection.
+
+AMQP topic wildcards (``*`` one word, ``#`` zero+ words) are anonymous, so there
+is no way to bind ``Path("level")`` to a position. rabbitkit lets a route name a
+single-word segment with ``{name}`` in its routing key, e.g.::
+
+    @broker.subscriber(queue="events", routing_key="events.{level}.#")
+    def handle(body: bytes, level: Annotated[str, Path("level")]) -> None: ...
+
+``{name}`` binds to AMQP as ``*`` (one word). On each delivery the named segments
+are extracted from the message's actual routing key into ``message.path``, which
+is what the ``Path()`` resolver reads.
+"""
+
+from __future__ import annotations
+
+
+def _is_named(segment: str) -> bool:
+    return len(segment) > 2 and segment[0] == "{" and segment[-1] == "}"
+
+
+def to_binding_key(routing_key: str) -> str:
+    """Translate ``{name}`` segments to the AMQP single-word wildcard ``*``.
+
+    Routing keys without named segments are returned unchanged (fast path), so
+    existing topic/direct routes are completely unaffected.
+    """
+    if "{" not in routing_key:
+        return routing_key
+    return ".".join("*" if _is_named(s) else s for s in routing_key.split("."))
+
+
+def extract_path(actual_routing_key: str, pattern: str) -> dict[str, str]:
+    """Extract named segments from a delivered routing key given the route pattern.
+
+    Positional: each ``{name}`` in the pattern maps to the same-index segment of
+    the actual key. Stops at a ``#`` (which spans a variable number of words, so
+    nothing after it has a fixed position). Returns ``{}`` when the pattern has no
+    named segments — the broker already matched the binding, so no validation is
+    needed here.
+    """
+    if "{" not in pattern:
+        return {}
+    actual = actual_routing_key.split(".")
+    out: dict[str, str] = {}
+    for i, seg in enumerate(pattern.split(".")):
+        if seg == "#":
+            break
+        if i >= len(actual):
+            break
+        if _is_named(seg):
+            out[seg[1:-1]] = actual[i]
+    return out