explicit-python-dlq 1.0.0__py3-none-any.whl

explicit/dlq/__init__.py

@@ -0,0 +1 @@
+

explicit/dlq/adapters/db.py

@@ -0,0 +1,13 @@
+"""Адаптеры для работы с Dead Letter Queue (DLQ) в базе данных."""
+
+from abc import (
+    ABCMeta,
+)
+
+from explicit.adapters.db import (
+    AbstractRepository,
+)
+
+
+class AbstractDLQRepository(AbstractRepository, metaclass=ABCMeta):
+    """Абстрактный репозиторий для работы с DLQ."""

explicit/dlq/config.py

@@ -0,0 +1,63 @@
+"""Конфигурация DLQ."""
+
+from dataclasses import (
+    dataclass,
+)
+from typing import (
+    TYPE_CHECKING,
+)
+
+from pydantic import (
+    ConfigDict,
+)
+
+from explicit.dlq.domain import (
+    commands,
+)
+from explicit.dlq.services.handlers import (
+    DLQHandlers,
+)
+
+
+if TYPE_CHECKING:
+    from explicit.dlq.adapters.db import (
+        AbstractDLQRepository,
+    )
+    from explicit.dlq.types import (
+        DLQMessageDispatcher,
+    )
+    from explicit.messagebus import (
+        MessageBus,
+    )
+
+
+@dataclass
+class DLQConfig:
+    """Конфигурация DLQ."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    bus: 'MessageBus'
+    repository: 'AbstractDLQRepository'
+    message_dispatcher: 'DLQMessageDispatcher'
+
+
+def configure_dlq(config: DLQConfig):
+    """Настроить DLQ."""
+    config.bus.get_uow().register_repositories(('dead_letters', config.repository))
+
+    handlers = DLQHandlers(bus=config.bus, message_dispatcher=config.message_dispatcher)
+
+    config.bus.add_command_handler(
+        commands.RegisterDeadLetter,
+        handlers.register_dead_letter,  # type: ignore[attr-defined,arg-type]
+    )
+    config.bus.add_command_handler(
+        commands.ProcessDeadLetter,
+        handlers.process_dead_letter,  # type: ignore[attr-defined,arg-type]
+    )
+
+    config.bus.add_command_handler(
+        commands.UpdateDeadLetterRawMessage,
+        handlers.update_raw_message_value,  # type: ignore[attr-defined,arg-type]
+    )

explicit/dlq/contrib/django/README.md

@@ -0,0 +1,40 @@
+## Набор компонентов для интеграции explicit.dlq с Django.
+Содержит реализацию репозитория необработанных сообщений.
+
+## Пример подключения
+testapp/settings.py:
+```python
+INSTALLED_APPS = [
+    # другие приложения
+    'explicit.dlq.contrib.django',  # подключение приложения с моделью DeadLetter
+    'testapp.core',                 # настройка компонентов из explicit.dlq
+]
+```
+
+testapp/dlq/apps.py:
+```python
+
+from datetime import timedelta
+
+from django.apps import AppConfig as AppConfigBase
+
+
+class AppConfig(AppConfigBase):
+    name = __package__
+
+    def ready(self):
+        self._configure_dlq()
+
+    def _configure_dlq(self):
+        from explicit.dlq.config import DLQConfig, configure_dlq
+        
+        # реализация репозитория на базе Django ORM 
+        from explicit.dlq.contrib.django.adapters.db import Repository
+        config = DLQConfig(
+            # ...
+            repository=Repository(),
+            # ...
+        )
+        # регистрация репозитория и регистрация обработчиков команд
+        configure_dlq(config)
+```

explicit/dlq/contrib/django/adapters/db.py

@@ -0,0 +1,104 @@
+"""Адаптеры для работы с Dead Letter Queue (DLQ) в базе данных."""
+
+from typing import (
+    TYPE_CHECKING,
+    Iterator,
+    Union,
+)
+
+from django.core.exceptions import (
+    ObjectDoesNotExist,
+)
+
+from explicit.dlq.adapters.db import (
+    AbstractDLQRepository,
+)
+from explicit.dlq.domain.model import (
+    DeadLetter,
+    DeadLetterNotFound,
+)
+from explicit.domain import (
+    asdict,
+)
+
+
+if TYPE_CHECKING:
+    from uuid import (
+        UUID,
+    )
+
+    from explicit.dlq.contrib.django import (
+        models as db,
+    )
+
+
+class Repository(AbstractDLQRepository):
+    """Репозиторий DeadLetterQueue."""
+
+    @property
+    def _base_qs(self):
+        # pylint: disable-next=import-outside-toplevel
+        from explicit.dlq.contrib.django.models import (
+            DeadLetter as DBDeadLetter,
+        )
+
+        return DBDeadLetter.objects.order_by('_first_attempted_at')
+
+    def _to_domain(self, dbinstance: 'db.DeadLetter') -> DeadLetter:
+        return DeadLetter(
+            id=dbinstance.id,
+            raw_message_value=bytes(dbinstance.raw_message_value),
+            raw_message_key=bytes(dbinstance.raw_message_key) if dbinstance.raw_message_key else None,
+            topic=dbinstance.topic,
+            attempts=tuple(dbinstance.attempts),
+            processed_at=dbinstance.processed_at,
+        )
+
+    def _to_db(self, modelinstance: DeadLetter) -> DeadLetter:
+        # pylint: disable-next=import-outside-toplevel
+        from explicit.dlq.contrib.django.models import (
+            DeadLetter as DBDeadLetter,
+        )
+
+        assert isinstance(modelinstance, DeadLetter)
+        db_instance, _ = DBDeadLetter.objects.update_or_create(
+            pk=modelinstance.id,
+            defaults=asdict(modelinstance, exclude={'id', 'attempts'})
+            | {
+                'attempts': [
+                    asdict(attempt) | {'failed_at': attempt.failed_at.isoformat()} for attempt in modelinstance.attempts
+                ],
+                '_first_attempted_at': modelinstance.attempts[0].failed_at,
+                '_attempts_count': len(modelinstance.attempts),
+            },
+        )
+        return self.get_object_by_id(db_instance.pk)
+
+    def add(self, obj: DeadLetter) -> DeadLetter:
+        """Добавить сообщение."""
+        return self._to_db(obj)
+
+    def update(self, obj: DeadLetter) -> DeadLetter:
+        """Обновить сообщение."""
+        assert isinstance(obj, DeadLetter)
+
+        return self._to_db(obj)
+
+    def delete(self, obj: DeadLetter) -> None:
+        """Удалить сообщение."""
+        assert isinstance(obj, DeadLetter)
+
+        self._base_qs.filter(pk=obj.id).delete()
+
+    def get_all_objects(self) -> Iterator[DeadLetter]:
+        """Получить все сообщения."""
+        for db_instance in self._base_qs.iterator():
+            yield self._to_domain(db_instance)
+
+    def get_object_by_id(self, identifier: 'Union[UUID, str]') -> DeadLetter:
+        """Получить сообщение по идентификатору."""
+        try:
+            db_instance = self._base_qs.get(pk=identifier)
+            return self._to_domain(db_instance)
+        except ObjectDoesNotExist as exc:
+            raise DeadLetterNotFound from exc

explicit/dlq/contrib/django/apps.py

@@ -0,0 +1,12 @@
+"""Конфигурация приложения."""
+
+from django.apps import (
+    AppConfig as AppConfigBase,
+)
+
+
+class AppConfig(AppConfigBase):
+    """Конфигурация приложения."""
+
+    name = __package__
+    label = 'explicit_dlq_django'

explicit/dlq/contrib/django/migrations/0001_initial.py

@@ -0,0 +1,60 @@
+# pylint: disable=missing-module-docstring,invalid-name
+import uuid
+
+from django import (
+    VERSION as DJANGO_VERSION,
+)
+from django.db import (
+    migrations,
+    models,
+)
+
+
+if DJANGO_VERSION >= (4, 0):
+    from django.db.models import (
+        JSONField,
+    )
+else:
+    from django.contrib.postgres.fields import (
+        JSONField,
+    )
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name='DeadLetter',
+            fields=[
+                (
+                    'id',
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name='Идентификатор UUID',
+                    ),
+                ),
+                ('raw_message_value', models.BinaryField(verbose_name='Содержимое сообщения')),
+                ('raw_message_key', models.BinaryField(verbose_name='Ключ сообщения', null=True, blank=True)),
+                ('topic', models.CharField(max_length=256, verbose_name='Топик сообщения')),
+                ('attempts', JSONField(verbose_name='Попытки обработки сообщения')),
+                (
+                    'processed_at',
+                    models.DateTimeField(blank=True, null=True, verbose_name='Время успешной обработки сообщения'),
+                ),
+                ('_first_attempted_at', models.DateTimeField(db_index=True)),
+                ('_attempts_count', models.IntegerField(db_index=True)),
+            ],
+            options={
+                'verbose_name': 'Необработанное сообщение',
+                'verbose_name_plural': 'Необработанные сообщения',
+                'indexes': [models.Index(fields=['_attempts_count', '_first_attempted_at'], name='dlq_attempts_idx')],
+                'db_table': 'dlq_dead_letter',
+            },
+        ),
+    ]

explicit/dlq/contrib/django/models.py

@@ -0,0 +1,45 @@
+"""Модели DLQ."""
+
+from uuid import (
+    uuid4,
+)
+
+from django import (
+    VERSION as DJANGO_VERSION,
+)
+from django.db import (
+    models,
+)
+
+from explicit.dlq.domain.model import (
+    DeadLetter as DomainDeadLetter,
+)
+
+
+if DJANGO_VERSION >= (4, 0):
+    from django.db.models import JSONField  # pylint: disable=ungrouped-imports
+else:
+    from django.contrib.postgres.fields import (
+        JSONField,
+    )
+
+
+class DeadLetter(models.Model):
+    """Недоставленное/необработанное сообщение."""
+
+    id = models.UUIDField(primary_key=True, default=uuid4, editable=False, verbose_name=DomainDeadLetter.id.title)
+    raw_message_value = models.BinaryField(verbose_name=DomainDeadLetter.raw_message_value.title)
+    raw_message_key = models.BinaryField(verbose_name=DomainDeadLetter.raw_message_key.title, null=True, blank=True)
+    topic = models.CharField(verbose_name=DomainDeadLetter.topic.title, max_length=DomainDeadLetter.topic.max_length)
+    attempts = JSONField(verbose_name=DomainDeadLetter.attempts.title)
+    processed_at = models.DateTimeField(verbose_name=DomainDeadLetter.processed_at.title, null=True, blank=True)
+
+    # служебные поля используемые для фильтрации и сортировки, чтобы не лезть в json
+    _first_attempted_at = models.DateTimeField(db_index=True)
+    _attempts_count = models.IntegerField(db_index=True)
+
+    class Meta:  # noqa: D106
+        verbose_name = 'Необработанное сообщение'
+        verbose_name_plural = 'Необработанные сообщения'
+        indexes = [models.Index(fields=['_attempts_count', '_first_attempted_at'], name='dlq_attempts_idx')]
+        db_table = 'dlq_dead_letter'

explicit/dlq/contrib/drf/README.md

@@ -0,0 +1,32 @@
+# Реализация REST эндпоинтов DLQ.
+
+## Пример подключения
+testapp/rest/dlq/views.py:
+```python
+from explicit.dlq.contrib.drf.views import BaseDeadLetterQueueViewSet
+
+
+class DeadLetterQueueViewSet(BaseDeadLetterQueueViewSet):
+    """Необработанные сообщения."""
+
+    def bus_handle(self, command):
+        """Обработчик команды."""
+        from testapp import core
+
+        return core.bus.handle(command)
+
+```
+
+testapp/rest/urls.py:
+```python
+from rest_framework.routers import SimpleRouter
+
+from testapp.rest.dlq.views import DeadLetterQueueViewSet
+
+
+router = SimpleRouter()
+
+router.register('dlq', DeadLetterQueueViewSet, basename='dlq')
+
+urlpatterns = router.urls
+````

explicit/dlq/contrib/drf/serializers.py

@@ -0,0 +1,45 @@
+"""Сериализаторы для работы DeadLetter."""
+
+# pylint: disable=abstract-method
+from rest_framework import (
+    serializers,
+)
+
+from explicit.dlq.contrib.django.models import (
+    DeadLetter,
+)
+
+
+class _AttemptSerializer(serializers.Serializer):
+    """Сериализатор попытки обработки сообщения."""
+
+    failed_at = serializers.DateTimeField(label='Время неудачной попытки')
+    error_message = serializers.CharField(label='Сообщение об ошибке')
+    traceback = serializers.CharField()
+
+
+class DeadLetterSerializer(serializers.ModelSerializer):
+    """Сериализатор необработанного сообщения."""
+
+    raw_message_value = serializers.CharField(allow_blank=False)
+    raw_message_key = serializers.CharField(allow_blank=True, allow_null=True, read_only=True)
+    attempts = _AttemptSerializer(many=True, read_only=True)
+
+    def to_internal_value(self, data):  # noqa: D102
+        ret = super().to_internal_value(data)
+        ret['raw_message_value'] = ret['raw_message_value'].encode()
+        if ret.get('raw_message_key'):
+            ret['raw_message_key'] = ret['raw_message_key'].encode()
+        return ret
+
+    def to_representation(self, instance):  # noqa: D102
+        ret = super().to_representation(instance)
+        ret['raw_message_value'] = bytes(instance.raw_message_value).decode()
+        if instance.raw_message_key:
+            ret['raw_message_key'] = bytes(instance.raw_message_key).decode()
+        return ret
+
+    class Meta:  # noqa: D106
+        model = DeadLetter
+        read_only_fields = ('id', 'raw_message_key', 'topic', 'attempts', 'processed_at')
+        exclude = ('_first_attempted_at', '_attempts_count')

explicit/dlq/contrib/drf/views.py

@@ -0,0 +1,72 @@
+"""Вьюсеты DeadLetterQueue."""
+
+from abc import (
+    abstractmethod,
+)
+
+from rest_framework import (
+    status,
+)
+from rest_framework.decorators import (
+    action,
+)
+from rest_framework.filters import (
+    SearchFilter,
+)
+from rest_framework.response import (
+    Response,
+)
+from rest_framework.viewsets import (
+    ReadOnlyModelViewSet,
+)
+
+from explicit.django.domain.validation.exceptions import (
+    handle_domain_validation_error,
+)
+from explicit.dlq.contrib.django.models import (
+    DeadLetter,
+)
+from explicit.dlq.domain.commands import (
+    ProcessDeadLetter,
+    UpdateDeadLetterRawMessage,
+)
+from explicit.messagebus.commands import (
+    Command,
+)
+
+from .serializers import (
+    DeadLetterSerializer,
+)
+
+
+class BaseDeadLetterQueueViewSet(ReadOnlyModelViewSet):
+    """Необработанные сообщения."""
+
+    queryset = DeadLetter.objects.order_by('_first_attempted_at')
+    serializer_class = DeadLetterSerializer
+    filter_backends = (SearchFilter,)
+
+    @abstractmethod
+    def bus_handle(self, command: Command):
+        """Обработчик команды."""
+
+    @action(detail=True, methods=['post'])
+    @handle_domain_validation_error
+    def process(self, request, *args, **kwargs):  # pylint: disable=unused-argument
+        """Вызвать обработку сообщения."""
+        command = ProcessDeadLetter(id=kwargs.get(self.lookup_field))
+
+        self.bus_handle(command)
+
+        return Response(data=self.get_serializer(self.get_object()).data, status=status.HTTP_200_OK)
+
+    @handle_domain_validation_error
+    def partial_update(self, request, *args, **kwargs):  # pylint: disable=unused-argument
+        """Обновить данные сообщения."""
+        serializer = self.get_serializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        command = UpdateDeadLetterRawMessage(id=kwargs.get(self.lookup_field), **serializer.validated_data)
+
+        self.bus_handle(command)
+
+        return Response(data=self.get_serializer(self.get_object()).data, status=status.HTTP_200_OK)

explicit/dlq/domain/commands.py

@@ -0,0 +1,37 @@
+"""Команды DLQ."""
+
+from typing import (
+    Optional,
+)
+from uuid import (
+    UUID,
+)
+
+from explicit.messagebus.commands import (
+    Command,
+)
+
+
+class RegisterDeadLetter(Command):
+    """Зарегистрировать сообщение, которое не удалось обработать."""
+
+    topic: str
+    raw_message_value: bytes
+    raw_message_key: Optional[bytes] = None
+    exception: Exception
+
+    class Config:  # noqa: D106
+        arbitrary_types_allowed = True
+
+
+class ProcessDeadLetter(Command):
+    """Выполнить попытку обработки сообщения."""
+
+    id: UUID
+
+
+class UpdateDeadLetterRawMessage(ProcessDeadLetter):
+    """Обновить содержимое сообщения в DLQ."""
+
+    id: UUID
+    raw_message_value: bytes

explicit/dlq/domain/factories.py

@@ -0,0 +1,81 @@
+"""DTO и фабрики DLQ."""
+
+import traceback
+from datetime import (
+    datetime,
+    timezone,
+)
+from typing import (
+    Union,
+)
+
+from explicit.domain import (
+    Str,
+    UnsetUUID,
+)
+from explicit.domain.factories import (
+    AbstractDomainFactory,
+    DTOBase,
+)
+from explicit.domain.model import (
+    Unset,
+    unset,
+)
+from explicit.domain.types import (
+    NoneStr,
+)
+
+from .model import (
+    Attempt,
+    DeadLetter,
+)
+
+
+class AttemptDTO(DTOBase):
+    """Объект передачи данных о попытке обработки сообщения."""
+
+    failed_at: Union[datetime, Unset] = unset
+    error_message: Str = unset
+    traceback: Str = unset
+
+
+class DeadLetterDTO(DTOBase):
+    """Объект передачи данных о необработанном сообщении."""
+
+    id: UnsetUUID = unset
+    raw_message_value: Union[bytes, Unset] = unset
+    raw_message_key: NoneStr = unset
+    topic: Str = unset
+    attempts: Union[list[AttemptDTO], Unset] = unset
+    processed_at: Union[datetime, None, Unset] = unset
+
+
+class Factory(AbstractDomainFactory):
+    """Фабрика для создания объектов предметной области DLQ."""
+
+    def create(self, data: DeadLetterDTO) -> DeadLetter:
+        """Создать DLQ из DTO."""
+        params = data.dict()
+
+        return DeadLetter(**params)
+
+    def create_attempt_from_exception(self, exception: Exception) -> Attempt:
+        """Создать запись о попытке обработки из исключения."""
+        return Attempt(
+            failed_at=datetime.now(tz=timezone.utc),
+            error_message=str(exception),
+            traceback=''.join(traceback.format_exception(type(exception), exception, exception.__traceback__)),
+        )
+
+    def create_from_exception(
+        self, raw_message_value: bytes, raw_message_key: Union[bytes, None], topic: str, exception: Exception
+    ) -> DeadLetter:
+        """Создать DLQ из исключения."""
+        attempt = self.create_attempt_from_exception(exception)
+
+        return DeadLetter(
+            raw_message_value=raw_message_value, raw_message_key=raw_message_key, topic=topic, attempts=(attempt,)
+        )
+
+
+factory = Factory()

explicit/dlq/domain/model.py

@@ -0,0 +1,71 @@
+"""Агрегаты и сущности для работы с недоставленными сообщениями."""
+
+import uuid
+from datetime import (
+    datetime,
+    timezone,
+)
+from typing import (
+    TYPE_CHECKING,
+    Optional,
+    Union,
+)
+
+from pydantic import (
+    Field,
+    validator,
+)
+
+from explicit.contrib.domain.model import (
+    uuid_identifier,
+)
+
+
+if TYPE_CHECKING:
+    from dataclasses import dataclass  # noqa
+else:
+    from pydantic.dataclasses import dataclass  # noqa
+
+
+class DeadLetterNotFound(Exception):  # noqa: N818
+    """Необработанное сообщение не найдено."""
+
+    def __init__(self, *args) -> None:
+        super().__init__('Необработанное сообщение не найдено', *args)
+
+
+@dataclass(frozen=True)
+class Attempt:
+    """Попытка обработки сообщения."""
+
+    failed_at: datetime
+    error_message: str
+    traceback: str
+
+
+@dataclass
+class DeadLetter:
+    """Недоставленное/необработанное сообщение."""
+
+    id: uuid.UUID = uuid_identifier()
+    raw_message_value: bytes = Field(title='Содержимое сообщения')
+    raw_message_key: Union[bytes, None] = Field(title='Ключ сообщения', default=None)
+    topic: str = Field(title='Топик сообщения', max_length=256)
+    attempts: tuple[Attempt, ...] = Field(default_factory=tuple, title='Попытки обработки сообщения')
+    processed_at: Optional[datetime] = Field(default=None, title='Время успешной обработки сообщения')
+
+    @validator('attempts', always=True)
+    @classmethod
+    def _validate_attempts(cls, value):
+        if not value:
+            raise ValueError('Должна быть хотя бы одна попытка обработки')
+
+        return value
+
+    def register_attempt(self, attempt: Attempt) -> None:
+        """Добавить информацию о новой попытке обработки."""
+        self.attempts = (*self.attempts, attempt)
+
+    def mark_as_processed(self) -> None:
+        """Отметить сообщение как успешно обработанное."""
+        self.processed_at = datetime.now(tz=timezone.utc)

explicit/dlq/domain/services.py

@@ -0,0 +1,64 @@
+"""Сервисы предметной области для работы с DLQ."""
+
+from typing import (
+    Optional,
+)
+
+from explicit.unit_of_work import (
+    AbstractUnitOfWork,
+)
+
+from .factories import (
+    DeadLetterDTO,
+    factory,
+)
+from .model import (
+    DeadLetter,
+)
+
+
+def register_dead_letter(
+    raw_message_value: bytes,
+    raw_message_key: Optional[bytes],
+    topic: str,
+    exception: Exception,
+    uow: 'AbstractUnitOfWork',
+) -> DeadLetter:
+    """Зарегистрировать сообщение в очереди необработанных сообщений."""
+    dead_letter = uow.dead_letters.add(  # type: ignore[attr-defined]
+        factory.create_from_exception(raw_message_value, raw_message_key, topic, exception)
+    )
+
+    return dead_letter
+
+
+def register_attempt(
+    data: DeadLetterDTO,
+    exception: Exception,
+    uow: 'AbstractUnitOfWork',
+) -> DeadLetter:
+    """Добавить информацию о новой попытке обработки."""
+    dead_letter = uow.dead_letters.get_object_by_id(data.id)  # type: ignore[attr-defined]
+
+    dead_letter.register_attempt(factory.create_attempt_from_exception(exception))
+
+    return uow.dead_letters.update(dead_letter)  # type: ignore[attr-defined]
+
+
+def mark_as_processed(
+    data: DeadLetterDTO,
+    uow: 'AbstractUnitOfWork',
+) -> DeadLetter:
+    """Отметить сообщение как успешно обработанное."""
+    dead_letter = uow.dead_letters.get_object_by_id(data.id)  # type: ignore[attr-defined]
+    dead_letter.mark_as_processed()
+
+    return uow.dead_letters.update(dead_letter)  # type: ignore[attr-defined]
+
+
+def update_raw_message(data, uow: 'AbstractUnitOfWork') -> DeadLetter:
+    """Редактировать содержимое сообщения в DLQ."""
+    dead_letter = uow.dead_letters.get_object_by_id(data.id)  # type: ignore[attr-defined]
+    dead_letter.raw_message_value = data.raw_message_value
+
+    return uow.dead_letters.update(dead_letter)  # type: ignore[attr-defined]

explicit/dlq/infrastructure/handlers.py

@@ -0,0 +1,72 @@
+"""Инфраструктурные компоненты DQL."""
+
+from contextlib import (
+    AbstractContextManager,
+)
+from typing import (
+    Optional,
+)
+
+from explicit.dlq.domain.commands import (
+    RegisterDeadLetter,
+)
+from explicit.messagebus import (
+    MessageBus,
+)
+
+
+class RegisterInDLQOnFailure(AbstractContextManager):
+    """Контекстный менеджер для обработки ошибок при обработке сообщений.
+
+    Перехватывает исключения при обработке сообщения и регистрирует такие сообщения в DLQ.
+
+    Пример использования:
+
+    .. code-block:: python
+        for raw_message_value in adapter.subscribe(*registered_topics):
+            with RegisterInDLQOnFailure(
+                bus=bus,
+                topic=raw_message_value.topic(),
+                raw_message_value=raw_message_value.value(),
+                raw_message_key=raw_message_value.raw_message_key(),
+            ):
+                message = json.loads(raw_message_value.value())
+                if event := event_registry.resolve(Message(...)):
+                    bus.handle(event)
+    """
+
+    def __init__(
+        self,
+        bus: 'MessageBus',
+        topic: str,
+        raw_message_value: bytes,
+        raw_message_key: Optional[bytes] = None,
+    ):
+        self._bus = bus
+        self._topic = topic
+        self._raw_message_value = raw_message_value
+        self._raw_message_key = raw_message_key
+
+    def __enter__(self):
+        """Вход в менеджер контекста."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Зарегистрировать сообщение в DLQ при возникновении исключения."""
+        ret = False
+
+        if exc_val is not None:
+            command = RegisterDeadLetter(
+                topic=self._topic,
+                raw_message_value=self._raw_message_value,
+                raw_message_key=self._raw_message_key,
+                exception=exc_val,
+            )
+            try:
+                self._bus.handle(command)
+            except Exception as registration_exc:
+                raise registration_exc from exc_val
+
+            ret = True
+
+        return ret

explicit/dlq/services/handlers.py

@@ -0,0 +1,95 @@
+"""Обработчики команд DQL."""
+
+from typing import (
+    TYPE_CHECKING,
+)
+
+from explicit.dlq.domain import (
+    commands,
+    factories,
+    model,
+    services,
+)
+from explicit.domain.validation.exceptions import (
+    DomainValidationError,
+    init_messages_dict,
+)
+
+
+if TYPE_CHECKING:
+    from explicit.dlq import (
+        types,
+    )
+    from explicit.messagebus import (
+        MessageBus,
+    )
+    from explicit.unit_of_work import (
+        AbstractUnitOfWork,
+    )
+
+
+class DLQHandlers:
+    """Обработчики команд DLQ."""
+
+    __slots__ = ('_bus', '_retry_strategy', '_message_dispatcher')
+
+    _bus: 'MessageBus'
+    _message_dispatcher: 'types.DLQMessageDispatcher'
+
+    def __init__(
+        self,
+        bus: 'MessageBus',
+        message_dispatcher: 'types.DLQMessageDispatcher',
+    ):
+        self._bus = bus
+        self._message_dispatcher = message_dispatcher
+
+    def register_dead_letter(self, command: commands.RegisterDeadLetter, uow: 'AbstractUnitOfWork') -> model.DeadLetter:
+        """Зарегистрировать сообщение, которое не удалось обработать."""
+        with uow.wrap():
+            return services.register_dead_letter(
+                raw_message_value=command.raw_message_value,
+                topic=command.topic,
+                raw_message_key=command.raw_message_key,
+                exception=command.exception,
+                uow=uow,
+            )
+
+    def process_dead_letter(self, command: commands.ProcessDeadLetter, uow: 'AbstractUnitOfWork') -> model.DeadLetter:
+        """Выполнить обработку сообщения."""
+        with uow.wrap():
+            errors = init_messages_dict()
+
+            data = factories.DeadLetterDTO(id=command.id)
+            try:
+                dead_letter = uow.dead_letters.get_object_by_id(data.id)  # type: ignore[attr-defined]
+            except model.DeadLetterNotFound as dlnf:
+                errors['id'].append(str(dlnf))
+
+            if errors:
+                raise DomainValidationError(errors)
+
+            try:
+                self._message_dispatcher(dead_letter.raw_message_value, dead_letter.topic)
+            except Exception as e:  # pylint: disable=broad-exception-caught
+                # регистрируем неудачную попытку обработки
+                result = services.register_attempt(
+                    data=data,
+                    exception=e,
+                    uow=uow,
+                )
+            else:
+                # регистрируем успешную обработку
+                result = services.mark_as_processed(factories.DeadLetterDTO(id=dead_letter.id), uow)
+
+            return result
+
+    def update_raw_message_value(
+        self, command: commands.UpdateDeadLetterRawMessage, uow: 'AbstractUnitOfWork'
+    ) -> model.DeadLetter:
+        """Редактировать содержимое сообщения в DLQ."""
+        with uow.wrap():
+            data = factories.DeadLetterDTO(id=command.id, raw_message_value=command.raw_message_value)
+            dead_letter = services.update_raw_message(data=data, uow=uow)
+
+            return dead_letter

explicit/dlq/types.py

@@ -0,0 +1,15 @@
+"""Типы для работы с DLQ."""
+
+from typing import (
+    Protocol,
+)
+
+
+class DLQMessageDispatcher(Protocol):
+    """Протокол обработчика сообщений DLQ.
+
+    Получает сырое сообщение и топик, трансформирует его в событие предметной области и направляет в шину на обработку.
+    """
+
+    def __call__(self, raw_message_value: bytes, topic: str) -> None:
+        """Обработать сообщение."""

explicit_python_dlq-1.0.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: explicit-python-dlq
+Version: 1.0.0
+Summary: Набор компонентов реализующих DQL для систем на базе explicit
+Author-email: "АО \"БАРС Груп\"" <education_dev@bars-open.ru>
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Web Environment
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: explicit-python<3,>=2.2.1
+Provides-Extra: dev
+Requires-Dist: freezegun; extra == "dev"
+Provides-Extra: django
+Requires-Dist: explicit-python-django<2.0,>=1.0.2; extra == "django"
+Provides-Extra: rest
+Requires-Dist: djangorestframework>=3.13.0; extra == "rest"
+Requires-Dist: django_filter>=23.3; extra == "rest"
+
+# Набор компонентов реализующих очередь необработанных сообщений (Dead Letter Queue).
+
+## Пример подключения
+testapp/dlq/apps.py:
+```python
+from django.apps import AppConfig as AppConfigBase
+
+
+class AppConfig(AppConfigBase):
+    name = __package__
+
+    def ready(self):
+        self._configure_dlq()
+
+    def _configure_dlq(self):
+        from testapp.core import bus
+        from explicit.dlq.config import DLQConfig, configure_dlq
+        # реализация репозитория специфичная для используемого слоя хранения данных
+        from testapp.dlq.adapters.db import Repository
+        
+        # реализация обработчика сообщений, специфичного для приложения
+        from testapp.dlq.services.dispatch import dispatch_message
+
+        config = DLQConfig(
+            bus=bus,
+            repository=Repository(),
+            message_dispatcher=dispatch_message
+        )
+        # регистрация репозитория и регистрация обработчиков команд
+        configure_dlq(config)
+```
+
+testapp/dlq/services/dispatch.py:
+```python
+import json
+from explicit.contrib.messagebus.event_registry import Message
+
+from testapp.core import bus
+from testapp.core import event_registry
+
+def dispatch_message(raw_message_value: bytes, topic: str):
+    """Преобразует сообщение в событие и отправляет его в шину."""
+    message = json.loads(raw_message_value)
+
+    if event := event_registry.resolve(
+        Message(
+            topic=topic,
+            type=message.get('type'),
+            body=message
+        )
+    ):
+        bus.handle(event)
+
+````
+
+testapp/entrypoints/kafka.py:
+
+```python
+def bootstrap() -> None:
+    from explicit.dlq.infrastructure.handlers import RegisterInDLQOnFailure
+
+    from testapp.core import bus
+
+    from testapp.dlq.services.dispatch import dispatch_message
+    topics = ('test.foo.topic',)
+
+    for raw_message in adapter.subscribe(*topics):
+        with RegisterInDLQOnFailure(
+            bus=bus,
+            topic=raw_message.topic(),
+            raw_message_value=raw_message.value(),
+            raw_message_key=raw_message.key
+        ):
+            dispatch_message(raw_message.value(), raw_message.topic())
+```
+## Готовые компоненты (contrib)
+
+В пакете реализованы готовые к использованию компоненты:
+* Реализация абстрактного [хранилища сообщений](./src/explicit/dlq/contrib/django/README.md) на базе Django ORM
+* [REST API](./src/explicit/dlq/contrib/drf/README.md) для работы с хранилищем сообщений. Предназначен для совместной работы с реализацией хранилища сообщений django ORM.

explicit_python_dlq-1.0.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+explicit/dlq/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+explicit/dlq/config.py,sha256=zpZrXqpIWPNzr6TBqvZ5Gs2tDwRVh0U43E1nIRGCm-E,1488
+explicit/dlq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/types.py,sha256=aVqdsdKZ-U_5TD3dpLtzksyL3jVedIhJnu7IihW3vh4,544
+explicit/dlq/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/adapters/db.py,sha256=c0j_dU3IRjm-7rx3S7nqE61vKjGsH8TYXiChbUQJoIU,346
+explicit/dlq/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/contrib/django/README.md,sha256=kpTW0GzYP8QV5ld7UI0ly-TWNbm3pbV7HWbdTpOGYAs,1290
+explicit/dlq/contrib/django/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/contrib/django/apps.py,sha256=WDloauYls-krHbJOp_brpS8WifMyK8O59eUTSQDZROU,263
+explicit/dlq/contrib/django/models.py,sha256=Zh9MTkkXaL1Pt5kwh9IFYnE29HXrd6QJxYWClxtyz6o,1772
+explicit/dlq/contrib/django/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/contrib/django/adapters/db.py,sha256=6ta3IRLknO_J5vwvF1mJWVZqCziqmy7cfbhiiM8cjDk,3309
+explicit/dlq/contrib/django/migrations/0001_initial.py,sha256=sDjCDZl1RvR_oOhBvftbW3LvRf6FbuLmRF_eQ-dauhM,2133
+explicit/dlq/contrib/django/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/contrib/drf/README.md,sha256=9eQlgFEWIwrFhrWvLVL8_Br_-3wU2kAoLxHoBUY5PS8,748
+explicit/dlq/contrib/drf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/contrib/drf/serializers.py,sha256=zNASKGtXbw5unWqMJgDaqITwtVAsW54liJsXoK4FRBU,1774
+explicit/dlq/contrib/drf/views.py,sha256=xBRUSzBbZ10PL8bHktZLosR-Tw-Q9jgN1n76oQmqLa4,2099
+explicit/dlq/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/domain/commands.py,sha256=v94uHQvGd-rX08_Paq9FEC-RSmsBaZMS9qxu6dHfzTo,803
+explicit/dlq/domain/factories.py,sha256=5tNLTTggBA4JGm66wtiSjGrUGvvdh9ZZB6DXp5ax0pY,2270
+explicit/dlq/domain/model.py,sha256=GBiDRGk4wpDZQqawZwNEtpHwS25YL_idvvkFNpajFvA,2291
+explicit/dlq/domain/services.py,sha256=2HUZb3aL3ZAH01_lpvRcGLffVjdmiB0VV-ZxX5m8x60,2051
+explicit/dlq/infrastructure/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/infrastructure/handlers.py,sha256=_1ZP8XtxkKgtDvLFZHVePHMkwtz1vhzNQJv2611pgfQ,2324
+explicit/dlq/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explicit/dlq/services/handlers.py,sha256=U6y4ElqXi1VocS3SE3SvwK69MMApAXILJes-xDbk_Ps,3232
+explicit_python_dlq-1.0.0.dist-info/METADATA,sha256=QhLrBWGXg6ZTS92CcW6Frpa581Sf7FyAT9n3am5MtiY,4069
+explicit_python_dlq-1.0.0.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+explicit_python_dlq-1.0.0.dist-info/top_level.txt,sha256=tt6T8l4Yji4ww87qZQcD4CbcwTIHy7NAPmU7QAfMcpY,9
+explicit_python_dlq-1.0.0.dist-info/RECORD,,

explicit_python_dlq-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (77.0.3)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

explicit_python_dlq-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+explicit