easy-faststream 0.2.0__py3-none-any.whl

easy_faststream/__init__.py

@@ -0,0 +1,17 @@
+from easy_faststream.app import StreamApp
+from easy_faststream.config import StreamSettings
+from easy_faststream.context import MessageContext
+from easy_faststream.exceptions import NonRetryableError, RetryableError
+from easy_faststream.retry import RetryPolicy
+
+__all__ = [
+    "MessageContext",
+    "NonRetryableError",
+    "RetryPolicy",
+    "RetryableError",
+    "StreamApp",
+    "StreamSettings",
+]
+
+__version__ = "0.2.0"
+

easy_faststream/app.py

@@ -0,0 +1,467 @@
+import inspect
+import json
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from faststream import AckPolicy, FastStream
+from faststream.rabbit import (
+    ExchangeType,
+    RabbitBroker,
+    RabbitExchange,
+    RabbitMessage,
+    RabbitQueue,
+)
+from pydantic import ValidationError
+
+from easy_faststream.config import StreamSettings
+from easy_faststream.context import MessageContext
+from easy_faststream.exceptions import NonRetryableError
+from easy_faststream.retry import RetryPolicy
+from easy_faststream.topology import (
+    RetryDestination,
+    build_retry_destinations,
+    declare_retry_topology,
+)
+from easy_faststream.types import ConsumerHandler, SchemaT
+
+logger = logging.getLogger("easy_faststream")
+
+
+class StreamApp:
+    RETRY_COUNT_HEADER = "x-easy-retry-count"
+    RETRY_HISTORY_HEADER = "x-easy-retry-history"
+
+    def __init__(self, settings: StreamSettings | None = None) -> None:
+        self.settings = settings or StreamSettings()
+
+        self.broker = RabbitBroker(
+            self.settings.rabbitmq_url,
+            app_id=self.settings.app_name,
+            graceful_timeout=self.settings.graceful_timeout,
+        )
+        self.app = FastStream(self.broker)
+
+    @classmethod
+    def from_env(cls) -> "StreamApp":
+        return cls(StreamSettings())
+
+    def consumer(
+        self,
+        *,
+        event: str,
+        schema: type[SchemaT],
+        queue: str | None = None,
+        exchange: str | None = None,
+        routing_key: str | None = None,
+        retries: int | None = None,
+        retry_delay: float | None = None,
+        retry_backoff: float | None = None,
+    ):
+        queue_name = queue or event
+        exchange_name = exchange or self.settings.default_exchange
+        route = routing_key or event
+
+        retry_policy = RetryPolicy(
+            max_retries=(
+                self.settings.max_retries
+                if retries is None
+                else retries
+            ),
+            delay_seconds=(
+                self.settings.retry_delay_seconds
+                if retry_delay is None
+                else retry_delay
+            ),
+            backoff=(
+                self.settings.retry_backoff
+                if retry_backoff is None
+                else retry_backoff
+            ),
+        )
+
+        retry_destinations = build_retry_destinations(
+            source_queue=queue_name,
+            source_exchange=exchange_name,
+            source_routing_key=route,
+            retry_exchange=self.settings.retry_exchange,
+            queue_suffix=self.settings.retry_queue_suffix,
+            policy=retry_policy,
+        )
+        retry_map = {
+            destination.retry_number: destination
+            for destination in retry_destinations
+        }
+
+        source_exchange = RabbitExchange(
+            exchange_name,
+            type=ExchangeType.TOPIC,
+            durable=True,
+        )
+        source_queue = RabbitQueue(
+            queue_name,
+            durable=True,
+            routing_key=route,
+        )
+
+        @self.app.after_startup
+        async def setup_retry_topology() -> None:
+            await declare_retry_topology(
+                broker=self.broker,
+                retry_exchange_name=self.settings.retry_exchange,
+                destinations=retry_destinations,
+            )
+
+            logger.info(
+                "retry_topology_declared",
+                extra={
+                    "event": event,
+                    "queue": queue_name,
+                    "retry_queues": len(retry_destinations),
+                },
+            )
+
+        def decorator(handler: ConsumerHandler[SchemaT]):
+            parameter_count = len(inspect.signature(handler).parameters)
+
+            if parameter_count not in (1, 2):
+                raise TypeError(
+                    f"{handler.__name__} must accept "
+                    "(message) or (message, context)"
+                )
+
+            @self.broker.subscriber(
+                source_queue,
+                source_exchange,
+                ack_policy=AckPolicy.MANUAL,
+            )
+            async def wrapped(
+                raw_message: Any,
+                message: RabbitMessage,
+            ) -> None:
+                context = self._make_context(
+                    message=message,
+                    queue=queue_name,
+                    exchange=exchange_name,
+                    routing_key=route,
+                )
+
+                retry_count = self._read_retry_count(
+                    context.headers
+                )
+                retry_history = self._read_retry_history(
+                    context.headers
+                )
+
+                try:
+                    payload = schema.model_validate(raw_message)
+                except ValidationError as error:
+                    await self._dead_letter_or_nack(
+                        raw_message=raw_message,
+                        message=message,
+                        context=context,
+                        error=error,
+                        retry_count=retry_count,
+                        retry_history=retry_history,
+                        error_kind="validation",
+                    )
+                    return
+
+                try:
+                    if parameter_count == 1:
+                        await handler(payload)
+                    else:
+                        await handler(payload, context)
+
+                except NonRetryableError as error:
+                    await self._dead_letter_or_nack(
+                        raw_message=raw_message,
+                        message=message,
+                        context=context,
+                        error=error,
+                        retry_count=retry_count,
+                        retry_history=retry_history,
+                        error_kind="non_retryable",
+                    )
+                    return
+
+                except Exception as error:
+                    if retry_count < retry_policy.max_retries:
+                        next_retry = retry_count + 1
+                        destination = retry_map[next_retry]
+
+                        retry_history.append(
+                            self._retry_record(
+                                retry_number=next_retry,
+                                destination=destination,
+                                error=error,
+                            )
+                        )
+
+                        await self._schedule_retry_or_nack(
+                            raw_message=raw_message,
+                            message=message,
+                            context=context,
+                            error=error,
+                            destination=destination,
+                            retry_history=retry_history,
+                        )
+                        return
+
+                    await self._dead_letter_or_nack(
+                        raw_message=raw_message,
+                        message=message,
+                        context=context,
+                        error=error,
+                        retry_count=retry_count,
+                        retry_history=retry_history,
+                        error_kind="processing",
+                    )
+                    return
+
+                await message.ack()
+
+                logger.info(
+                    "message_processed",
+                    extra={
+                        "event": event,
+                        "message_id": context.message_id,
+                        "retry_count": retry_count,
+                    },
+                )
+
+            return handler
+
+        return decorator
+
+    async def _schedule_retry_or_nack(
+        self,
+        *,
+        raw_message: Any,
+        message: RabbitMessage,
+        context: MessageContext,
+        error: Exception,
+        destination: RetryDestination,
+        retry_history: list[dict[str, Any]],
+    ) -> None:
+        headers = dict(context.headers)
+        headers[self.RETRY_COUNT_HEADER] = (
+            destination.retry_number
+        )
+        headers[self.RETRY_HISTORY_HEADER] = json.dumps(
+            retry_history,
+            ensure_ascii=False,
+            default=str,
+        )
+
+        retry_exchange = RabbitExchange(
+            self.settings.retry_exchange,
+            type=ExchangeType.TOPIC,
+            durable=True,
+        )
+
+        try:
+            await self.broker.publish(
+                raw_message,
+                exchange=retry_exchange,
+                routing_key=destination.routing_key,
+                message_id=context.message_id,
+                correlation_id=context.correlation_id,
+                headers=headers,
+                persist=True,
+            )
+        except Exception:
+            logger.exception(
+                "retry_publish_failed",
+                extra={
+                    "message_id": context.message_id,
+                    "retry_number": destination.retry_number,
+                },
+            )
+            await message.nack(requeue=True)
+            return
+
+        await message.ack()
+
+        logger.warning(
+            "message_scheduled_for_retry",
+            extra={
+                "message_id": context.message_id,
+                "retry_number": destination.retry_number,
+                "delay_seconds": destination.delay_seconds,
+                "error_type": type(error).__name__,
+            },
+        )
+
+    async def _dead_letter_or_nack(
+        self,
+        *,
+        raw_message: Any,
+        message: RabbitMessage,
+        context: MessageContext,
+        error: Exception,
+        retry_count: int,
+        retry_history: list[dict[str, Any]],
+        error_kind: str,
+    ) -> None:
+        envelope = {
+            "original_payload": self._json_safe(raw_message),
+            "failure": {
+                "kind": error_kind,
+                "error_type": type(error).__name__,
+                "error_message": str(error),
+                "retry_count": retry_count,
+                "retry_history": retry_history,
+                "failed_at": datetime.now(UTC).isoformat(),
+            },
+            "source": {
+                "queue": context.queue,
+                "exchange": context.exchange,
+                "routing_key": context.routing_key,
+                "message_id": context.message_id,
+                "correlation_id": context.correlation_id,
+                "headers": self._json_safe(context.headers),
+            },
+        }
+
+        dlq_name = (
+            f"{context.queue}"
+            f"{self.settings.dlq_queue_suffix}"
+        )
+        dlq_exchange = RabbitExchange(
+            self.settings.dlq_exchange,
+            type=ExchangeType.TOPIC,
+            durable=True,
+        )
+        dlq_queue = RabbitQueue(
+            dlq_name,
+            durable=True,
+            routing_key=context.routing_key,
+        )
+
+        try:
+            declared_exchange = (
+                await self.broker.declare_exchange(
+                    dlq_exchange
+                )
+            )
+            declared_queue = await self.broker.declare_queue(
+                dlq_queue
+            )
+            await declared_queue.bind(
+                declared_exchange,
+                routing_key=context.routing_key,
+            )
+
+            await self.broker.publish(
+                envelope,
+                exchange=dlq_exchange,
+                routing_key=context.routing_key,
+                message_id=context.message_id,
+                correlation_id=context.correlation_id,
+                headers={
+                    "x-original-queue": context.queue,
+                    "x-retry-count": retry_count,
+                    "x-error-type": type(error).__name__,
+                },
+                persist=True,
+            )
+        except Exception:
+            logger.exception(
+                "dead_letter_publish_failed",
+                extra={
+                    "message_id": context.message_id,
+                    "queue": context.queue,
+                },
+            )
+            await message.nack(requeue=True)
+            return
+
+        await message.ack()
+
+        logger.error(
+            "message_dead_lettered",
+            extra={
+                "message_id": context.message_id,
+                "queue": dlq_name,
+                "retry_count": retry_count,
+                "error_type": type(error).__name__,
+            },
+        )
+
+    @classmethod
+    def _read_retry_count(
+        cls,
+        headers: dict[str, Any],
+    ) -> int:
+        value = headers.get(cls.RETRY_COUNT_HEADER, 0)
+
+        try:
+            return max(0, int(value))
+        except (TypeError, ValueError):
+            return 0
+
+    @classmethod
+    def _read_retry_history(
+        cls,
+        headers: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        value = headers.get(cls.RETRY_HISTORY_HEADER)
+
+        if value is None:
+            return []
+
+        if isinstance(value, bytes):
+            value = value.decode("utf-8")
+
+        if not isinstance(value, str):
+            return []
+
+        try:
+            history = json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return []
+
+        return history if isinstance(history, list) else []
+
+    @staticmethod
+    def _retry_record(
+        *,
+        retry_number: int,
+        destination: RetryDestination,
+        error: Exception,
+    ) -> dict[str, Any]:
+        return {
+            "retry_number": retry_number,
+            "error_type": type(error).__name__,
+            "error_message": str(error),
+            "delay_seconds": destination.delay_seconds,
+            "failed_at": datetime.now(UTC).isoformat(),
+        }
+
+    @staticmethod
+    def _json_safe(value: Any) -> Any:
+        return json.loads(
+            json.dumps(
+                value,
+                ensure_ascii=False,
+                default=str,
+            )
+        )
+
+    @staticmethod
+    def _make_context(
+        *,
+        message: RabbitMessage,
+        queue: str,
+        exchange: str,
+        routing_key: str,
+    ) -> MessageContext:
+        return MessageContext(
+            message_id=message.message_id,
+            correlation_id=message.correlation_id,
+            headers=dict(message.headers or {}),
+            queue=queue,
+            exchange=exchange,
+            routing_key=routing_key,
+        )

easy_faststream/config.py

@@ -0,0 +1,26 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class StreamSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="EASY_STREAM_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    rabbitmq_url: str = "amqp://guest:guest@localhost:5672/"
+    app_name: str = "easy-faststream-app"
+
+    default_exchange: str = "easy.events"
+    retry_exchange: str = "easy.events.retry"
+    dlq_exchange: str = "easy.events.dead"
+
+    retry_queue_suffix: str = ".retry"
+    dlq_queue_suffix: str = ".dead"
+
+    max_retries: int = Field(default=3, ge=0)
+    retry_delay_seconds: float = Field(default=1.0, ge=0)
+    retry_backoff: float = Field(default=2.0, ge=1)
+
+    graceful_timeout: float = Field(default=30.0, gt=0)

easy_faststream/context.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class MessageContext:
+    message_id: str | None
+    correlation_id: str | None
+    headers: dict[str, Any] = field(default_factory=dict)
+    queue: str = ""
+    exchange: str = ""
+    routing_key: str = ""
+

easy_faststream/exceptions.py

@@ -0,0 +1,11 @@
+class EasyFastStreamError(Exception):
+    """Base exception for easy-faststream."""
+
+
+class RetryableError(EasyFastStreamError):
+    """Raise when processing may succeed on a later attempt."""
+
+
+class NonRetryableError(EasyFastStreamError):
+    """Raise when retrying cannot resolve the failure."""
+

easy_faststream/retry.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    max_retries: int = 3
+    delay_seconds: float = 1.0
+    backoff: float = 2.0
+
+    def __post_init__(self) -> None:
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be at least 0")
+        if self.delay_seconds < 0:
+            raise ValueError("delay_seconds must be at least 0")
+        if self.backoff < 1:
+            raise ValueError("backoff must be at least 1")
+
+    def delay_for(self, retry_number: int) -> float:
+        if retry_number < 1:
+            raise ValueError("retry_number must be at least 1")
+        return self.delay_seconds * (self.backoff ** (retry_number - 1))
+

easy_faststream/topology.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass
+
+from faststream.rabbit import (
+    ExchangeType,
+    RabbitBroker,
+    RabbitExchange,
+    RabbitQueue,
+)
+
+from easy_faststream.retry import RetryPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class RetryDestination:
+    retry_number: int
+    delay_seconds: float
+    routing_key: str
+    queue: RabbitQueue
+
+
+def build_retry_destinations(
+    *,
+    source_queue: str,
+    source_exchange: str,
+    source_routing_key: str,
+    retry_exchange: str,
+    queue_suffix: str,
+    policy: RetryPolicy,
+) -> list[RetryDestination]:
+    destinations: list[RetryDestination] = []
+
+    for retry_number in range(1, policy.max_retries + 1):
+        delay_seconds = policy.delay_for(retry_number)
+        retry_routing_key = (
+            f"{source_queue}{queue_suffix}.{retry_number}"
+        )
+
+        retry_queue = RabbitQueue(
+            name=retry_routing_key,
+            durable=True,
+            routing_key=retry_routing_key,
+            arguments={
+                "x-message-ttl": int(delay_seconds * 1000),
+                "x-dead-letter-exchange": source_exchange,
+                "x-dead-letter-routing-key": source_routing_key,
+            },
+        )
+
+        destinations.append(
+            RetryDestination(
+                retry_number=retry_number,
+                delay_seconds=delay_seconds,
+                routing_key=retry_routing_key,
+                queue=retry_queue,
+            )
+        )
+
+    return destinations
+
+
+async def declare_retry_topology(
+    *,
+    broker: RabbitBroker,
+    retry_exchange_name: str,
+    destinations: list[RetryDestination],
+) -> RabbitExchange:
+    retry_exchange = RabbitExchange(
+        retry_exchange_name,
+        type=ExchangeType.TOPIC,
+        durable=True,
+    )
+
+    declared_exchange = await broker.declare_exchange(retry_exchange)
+
+    for destination in destinations:
+        declared_queue = await broker.declare_queue(destination.queue)
+
+        await declared_queue.bind(
+            declared_exchange,
+            routing_key=destination.routing_key,
+        )
+
+    return retry_exchange

easy_faststream/types.py

@@ -0,0 +1,14 @@
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias, TypeVar
+
+from pydantic import BaseModel
+
+from easy_faststream.context import MessageContext
+
+SchemaT = TypeVar("SchemaT", bound=BaseModel)
+
+ConsumerHandler: TypeAlias = (
+    Callable[[SchemaT], Awaitable[None]]
+    | Callable[[SchemaT, MessageContext], Awaitable[None]]
+)
+

easy_faststream-0.2.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: easy-faststream
+Version: 0.2.0
+Summary: A schema-first FastStream framework with automatic retries and dead-letter handling.
+Author: Ek
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: faststream[cli,rabbit]<0.8,>=0.7.1
+Requires-Dist: pydantic-settings<3,>=2.2
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# easy-faststream
+
+`easy-faststream` is a schema-first wrapper around FastStream for RabbitMQ.
+Application developers define a Pydantic schema and a consumer function; the
+framework handles validation, retry, acknowledgements, and dead-letter routing.
+
+## Example
+
+```python
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from easy_faststream import MessageContext, StreamApp
+
+
+class TripRequested(BaseModel):
+    order_id: UUID
+    passenger_id: UUID | None = None
+    service_type: str
+    event_at: datetime
+
+
+app = StreamApp.from_env()
+
+
+@app.consumer(
+    event="passapp.trip.requested",
+    schema=TripRequested,
+    queue="p_q.passapp.trip.requested",
+    exchange="ex.passapp.event.trip",
+)
+async def consume_trip(
+    event: TripRequested,
+    context: MessageContext,
+) -> None:
+    print(event.order_id, context.message_id)
+```
+
+Run the application through FastStream:
+
+```bash
+faststream run app:app.app
+```
+
+## Environment variables
+
+```env
+EASY_STREAM_RABBITMQ_URL=amqp://guest:guest@localhost:5672/
+EASY_STREAM_APP_NAME=trip-consumer
+EASY_STREAM_DEFAULT_EXCHANGE=easy.events
+EASY_STREAM_DLQ_EXCHANGE=easy.events.dead
+EASY_STREAM_MAX_RETRIES=3
+EASY_STREAM_RETRY_DELAY_SECONDS=1
+EASY_STREAM_RETRY_BACKOFF=2
+```
+
+## Failure behavior
+
+- Invalid schema: publish the original payload and validation details to the DLQ.
+- Processing error: retry according to the configured policy, then publish to DLQ.
+- `NonRetryableError`: skip retries and publish directly to DLQ.
+- DLQ publish error: NACK and requeue the original RabbitMQ message.
+- Success or successful DLQ publish: ACK the original message.
+

easy_faststream-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+easy_faststream/__init__.py,sha256=tHd5_43iPm-fNjYQhFDY2tDM9psFuWKh0_zZ1DnEOQg,428
+easy_faststream/app.py,sha256=jdA-jYOzYt24UxTH_74RUfD8KtDTCFN7QLFrCcOojiE,14350
+easy_faststream/config.py,sha256=-_X51pZc3JesFere4Jsco_11UR2u0pILS-LziD421_U,783
+easy_faststream/context.py,sha256=XjMau6aMZ3d2jD6TB3OZcY58J-BN_qI1jZgX5siSEQk,310
+easy_faststream/exceptions.py,sha256=g4ggg1gHBKDHxq9JDcA9_8b18WdvIzTwkUq3RCSMOGs,300
+easy_faststream/retry.py,sha256=_TgGZYtsWc_c0pHDY-lb78gO8h3Dq_wgcu8jVShG0j0,715
+easy_faststream/topology.py,sha256=vcBJddeCmzmZip0CMdrUFV3FOxdQtMy4KkHGbY9fH1w,2176
+easy_faststream/types.py,sha256=16zoRKgQUOxJzAOiCDll6M1hq_2XW6bt9pGBrC4RzBw,352
+easy_faststream-0.2.0.dist-info/METADATA,sha256=pYrgCxecweJLGs-MwPjSBX5bsF3fgUZXMn0f5GCPbw0,2243
+easy_faststream-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+easy_faststream-0.2.0.dist-info/licenses/LICENSE,sha256=fjl_453_2LoQPw6Pzk0ih3asEJ25c5nf_JPu6ie56oA,1078
+easy_faststream-0.2.0.dist-info/RECORD,,

easy_faststream-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

easy_faststream-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.