easy-faststream 0.2.0__tar.gz

easy_faststream-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.env
+.venv/
+.venv-wheel/
+.venv-testpypi/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.pytest_cache/

easy_faststream-0.2.0/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.

easy_faststream-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,66 @@
+# 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/examples/trip_consumer.py

@@ -0,0 +1,29 @@
+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
+
+
+stream = StreamApp.from_env()
+
+
+@stream.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(f"Processing {event.order_id}; message_id={context.message_id}")
+
+
+app = stream.app

easy_faststream-0.2.0/publish_invalid.py

@@ -0,0 +1,33 @@
+import asyncio
+
+from faststream.rabbit import ExchangeType, RabbitBroker, RabbitExchange
+
+from easy_faststream import StreamSettings
+
+
+async def main() -> None:
+    settings = StreamSettings()
+
+    exchange = RabbitExchange(
+        "ex.easy_faststream.test",
+        type=ExchangeType.TOPIC,
+        durable=True,
+    )
+
+    async with RabbitBroker(settings.rabbitmq_url) as broker:
+        await broker.publish(
+            {
+                "event_id": "retry-001",
+                "message": "This message should retry",
+            },
+            exchange=exchange,
+            routing_key="easy.test",
+            message_id="invalid-message-001",
+            persist=True,
+        )
+
+    print("Invalid message published")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

easy_faststream-0.2.0/publish_test.py

@@ -0,0 +1,32 @@
+import asyncio
+
+from faststream.rabbit import ExchangeType, RabbitBroker, RabbitExchange
+
+from easy_faststream import StreamSettings
+
+
+async def main() -> None:
+    settings = StreamSettings()
+
+    exchange = RabbitExchange(
+        "ex.easy_faststream.test",
+        type=ExchangeType.TOPIC,
+        durable=True,
+    )
+
+    async with RabbitBroker(settings.rabbitmq_url) as broker:
+        await broker.publish(
+            {
+                "event_id": "retry-002",
+                "message": "Testing durable RabbitMQ retry",
+            },
+            exchange=exchange,
+            routing_key="easy.test",
+            message_id="retry-message-001",
+            persist=True,
+        )
+    print("Message published successfully")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

easy_faststream-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "easy-faststream"
+version = "0.2.0"
+description = "A schema-first FastStream framework with automatic retries and dead-letter handling."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Ek" },
+]
+dependencies = [
+    "faststream[rabbit,cli]>=0.7.1,<0.8",
+    "pydantic>=2.7,<3",
+    "pydantic-settings>=2.2,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easy_faststream"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+

easy_faststream-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/test_app.py

@@ -0,0 +1,57 @@
+from pydantic import BaseModel
+from faststream.rabbit import (
+    ExchangeType,
+    RabbitExchange,
+    RabbitQueue,
+)
+
+from easy_faststream import MessageContext, StreamApp
+
+
+class TestEvent(BaseModel):
+    event_id: str
+    message: str
+
+
+stream = StreamApp.from_env()
+
+
+@stream.consumer(
+    event="easy.test",
+    schema=TestEvent,
+    queue="p_q.easy_faststream.test",
+    exchange="ex.easy_faststream.test",
+    routing_key="easy.test",
+)
+async def consume_test(
+    event: TestEvent,
+    context: MessageContext,
+) -> None:
+    print("Processing:", event.event_id)
+
+    if event.event_id.startswith("retry-"):
+        raise RuntimeError("Testing automatic retry")
+
+    print("Processed successfully:", event)
+
+
+dead_exchange = RabbitExchange(
+    "ex.easy_faststream.test.dead",
+    type=ExchangeType.TOPIC,
+    durable=True,
+)
+
+dead_queue = RabbitQueue(
+    "p_q.easy_faststream.test.dead",
+    durable=True,
+    routing_key="easy.test",
+)
+
+
+@stream.broker.subscriber(dead_queue, dead_exchange)
+async def consume_dead_letter(message: dict) -> None:
+    print("Received DLQ message:")
+    print(message)
+
+
+app = stream.app

easy_faststream-0.2.0/tests/test_retry.py

@@ -0,0 +1,25 @@
+import pytest
+
+from easy_faststream.retry import RetryPolicy
+
+
+def test_exponential_retry_delays() -> None:
+    policy = RetryPolicy(max_retries=3, delay_seconds=2, backoff=3)
+
+    assert policy.delay_for(1) == 2
+    assert policy.delay_for(2) == 6
+    assert policy.delay_for(3) == 18
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        ({"max_retries": -1}, "max_retries"),
+        ({"delay_seconds": -1}, "delay_seconds"),
+        ({"backoff": 0.5}, "backoff"),
+    ],
+)
+def test_invalid_retry_policy(kwargs: dict, message: str) -> None:
+    with pytest.raises(ValueError, match=message):
+        RetryPolicy(**kwargs)
+

easy_faststream-0.2.0/tests/test_topology.py

@@ -0,0 +1,63 @@
+from easy_faststream.retry import RetryPolicy
+from easy_faststream.topology import build_retry_destinations
+
+
+def test_builds_durable_exponential_retry_queues() -> None:
+    policy = RetryPolicy(
+        max_retries=3,
+        delay_seconds=1,
+        backoff=2,
+    )
+
+    destinations = build_retry_destinations(
+        source_queue="p_q.easy.test",
+        source_exchange="ex.easy.test",
+        source_routing_key="easy.test",
+        retry_exchange="ex.easy.test.retry",
+        queue_suffix=".retry",
+        policy=policy,
+    )
+
+    assert len(destinations) == 3
+
+    assert [
+        destination.delay_seconds
+        for destination in destinations
+    ] == [1, 2, 4]
+
+    assert [
+        destination.queue.name
+        for destination in destinations
+    ] == [
+        "p_q.easy.test.retry.1",
+        "p_q.easy.test.retry.2",
+        "p_q.easy.test.retry.3",
+    ]
+
+    for destination in destinations:
+        arguments = destination.queue.arguments
+
+        assert arguments["x-message-ttl"] == (
+            int(destination.delay_seconds * 1000)
+        )
+        assert arguments["x-dead-letter-exchange"] == (
+            "ex.easy.test"
+        )
+        assert arguments["x-dead-letter-routing-key"] == (
+            "easy.test"
+        )
+
+
+def test_zero_retries_creates_no_retry_queues() -> None:
+    policy = RetryPolicy(max_retries=0)
+
+    destinations = build_retry_destinations(
+        source_queue="p_q.easy.test",
+        source_exchange="ex.easy.test",
+        source_routing_key="easy.test",
+        retry_exchange="ex.easy.test.retry",
+        queue_suffix=".retry",
+        policy=policy,
+    )
+
+    assert destinations == []