python-cqrs 4.14.0__tar.gz → 4.15.1__tar.gz

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.14.0
+Version: 4.15.1
 Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -49,6 +49,7 @@ Requires-Dist: asyncpg>=0.29.0; extra == "dev"
 Requires-Dist: redis>=5.0.0; extra == "dev"
 Requires-Dist: aiobreaker>=0.3.0; extra == "dev"
 Requires-Dist: dishka>=1.0; extra == "dev"
+Requires-Dist: protobuf>=4.25.8; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: fastapi==0.109.*; extra == "examples"
 Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
@@ -61,6 +62,8 @@ Requires-Dist: dishka>=1.0; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
 Requires-Dist: retry-async==0.1.*; extra == "kafka"
+Provides-Extra: protobuf
+Requires-Dist: protobuf>=4.25.8; extra == "protobuf"
 Provides-Extra: rabbit
 Requires-Dist: aio-pika==9.3.0; extra == "rabbit"
 Provides-Extra: sqlalchemy
@@ -91,9 +94,6 @@ Dynamic: license-file
     <a href="https://codecov.io/gh/vadikko2/python-cqrs">
       <img src="https://img.shields.io/codecov/c/github/vadikko2/python-cqrs?logo=codecov&logoColor=white" alt="Coverage">
     </a>
-    <a href="https://codspeed.io/vadikko2/python-cqrs?utm_source=badge">
-      <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed">
-    </a>
     <a href="https://mkdocs.python-cqrs.dev/">
       <img src="https://img.shields.io/badge/docs-mkdocs-blue?logo=readthedocs" alt="Documentation">
     </a>
@@ -106,11 +106,6 @@ Dynamic: license-file
   </p>
 </div>
 
-> [!WARNING]
-> **Breaking Changes in v5.0.0**
->
-> Starting with version 5.0.0, Pydantic support will become optional. The default implementations of `Request`, `Response`, `DomainEvent`, and `NotificationEvent` will be migrated to dataclasses-based implementations.
-
 ## Table of Contents
 
 - [Overview](#overview)
@@ -189,6 +184,8 @@ pip install python-cqrs[examples]    # FastAPI, FastStream, uvicorn, etc.
 pip install python-cqrs[aiobreaker]  # Circuit breaker for saga fallbacks
 ```
 
+Starting with **4.15.1**, importing `cqrs` emits a package-level EOL `DeprecationWarning` toward 5.x (plus an optional log). Suppress the log with `CQRS_SUPPRESS_V4_EOL_WARNING=1`. See [SECURITY.md](SECURITY.md) for the 4.x support window and pin guidance.
+
 ## Quick Start
 
 Define a command, a handler, bind them, and run via the mediator:
@@ -923,12 +920,9 @@ A runnable FastAPI flow (route → command → transactional outbox → publishe
 > [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
 > how to register a native type for your own database.
 > [!TIP]
-> For Protobuf events, implement `proto()` / `from_proto()` on the notification
-> event (see [Protobuf messaging](#protobuf-messaging) and the schema assets in
-> [examples/proto/](https://github.com/vadikko2/python-cqrs/tree/master/examples/proto)).
-> Outbox persistence is unchanged — use
-> [save_events_into_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/save_events_into_outbox.py);
-> Protobuf applies when producing to the broker. Full guide:
+> For Protobuf events, implement `proto()` / `from_proto()` and register a
+> `ProtobufEventSerializer` on an `OutboxedEventMap`. JSON stays the default —
+> see [Protobuf messaging](#protobuf-messaging) and the full guide:
 > [Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
 
 ## Producing Events from Outbox to Kafka
@@ -1231,6 +1225,14 @@ class UserJoinedNotificationEvent(cqrs.NotificationEvent[UserJoinedPayload]):
         )
 ```
 
+JSON remains the default. Opt-in Protobuf wiring (`ProtobufEventSerializer` on an
+`OutboxedEventMap`, `Message.payload_bytes`, consume via `ProtobufDeserializer`) is
+documented in the full guide:
+[Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
+Runnable example:
+[protobuf_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/protobuf_outbox.py)
+(`pip install "python-cqrs[protobuf]"`).
+
 ## Contributing
 
 Contributions are welcome. To develop locally:

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/README.md

@@ -20,9 +20,6 @@
     <a href="https://codecov.io/gh/vadikko2/python-cqrs">
       <img src="https://img.shields.io/codecov/c/github/vadikko2/python-cqrs?logo=codecov&logoColor=white" alt="Coverage">
     </a>
-    <a href="https://codspeed.io/vadikko2/python-cqrs?utm_source=badge">
-      <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed">
-    </a>
     <a href="https://mkdocs.python-cqrs.dev/">
       <img src="https://img.shields.io/badge/docs-mkdocs-blue?logo=readthedocs" alt="Documentation">
     </a>
@@ -35,11 +32,6 @@
   </p>
 </div>
 
-> [!WARNING]
-> **Breaking Changes in v5.0.0**
->
-> Starting with version 5.0.0, Pydantic support will become optional. The default implementations of `Request`, `Response`, `DomainEvent`, and `NotificationEvent` will be migrated to dataclasses-based implementations.
-
 ## Table of Contents
 
 - [Overview](#overview)
@@ -118,6 +110,8 @@ pip install python-cqrs[examples]    # FastAPI, FastStream, uvicorn, etc.
 pip install python-cqrs[aiobreaker]  # Circuit breaker for saga fallbacks
 ```
 
+Starting with **4.15.1**, importing `cqrs` emits a package-level EOL `DeprecationWarning` toward 5.x (plus an optional log). Suppress the log with `CQRS_SUPPRESS_V4_EOL_WARNING=1`. See [SECURITY.md](SECURITY.md) for the 4.x support window and pin guidance.
+
 ## Quick Start
 
 Define a command, a handler, bind them, and run via the mediator:
@@ -852,12 +846,9 @@ A runnable FastAPI flow (route → command → transactional outbox → publishe
 > [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
 > how to register a native type for your own database.
 > [!TIP]
-> For Protobuf events, implement `proto()` / `from_proto()` on the notification
-> event (see [Protobuf messaging](#protobuf-messaging) and the schema assets in
-> [examples/proto/](https://github.com/vadikko2/python-cqrs/tree/master/examples/proto)).
-> Outbox persistence is unchanged — use
-> [save_events_into_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/save_events_into_outbox.py);
-> Protobuf applies when producing to the broker. Full guide:
+> For Protobuf events, implement `proto()` / `from_proto()` and register a
+> `ProtobufEventSerializer` on an `OutboxedEventMap`. JSON stays the default —
+> see [Protobuf messaging](#protobuf-messaging) and the full guide:
 > [Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
 
 ## Producing Events from Outbox to Kafka
@@ -1160,6 +1151,14 @@ class UserJoinedNotificationEvent(cqrs.NotificationEvent[UserJoinedPayload]):
         )
 ```
 
+JSON remains the default. Opt-in Protobuf wiring (`ProtobufEventSerializer` on an
+`OutboxedEventMap`, `Message.payload_bytes`, consume via `ProtobufDeserializer`) is
+documented in the full guide:
+[Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
+Runnable example:
+[protobuf_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/protobuf_outbox.py)
+(`pip install "python-cqrs[protobuf]"`).
+
 ## Contributing
 
 Contributions are welcome. To develop locally:

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/pyproject.toml

@@ -31,7 +31,7 @@ maintainers = [{ name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru" }]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "4.14.0"
+version = "4.15.1"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]
@@ -60,6 +60,7 @@ dev = [
   # Circuit breaker for tests
   "aiobreaker>=0.3.0", # from aiobreaker
   "dishka>=1.0",  # scoped-deps dishka adapter tests / examples
+  "protobuf>=4.25.8",  # protobuf codec / deserializer unit tests
 ]
 examples = [
   "fastapi==0.109.*",
@@ -72,6 +73,7 @@ examples = [
   "dishka>=1.0",
 ]
 kafka = ["aiokafka==0.10.0", "retry-async==0.1.*"]
+protobuf = ["protobuf>=4.25.8"]
 rabbit = ["aio-pika==9.3.0"]
 sqlalchemy = ["sqlalchemy[asyncio]==2.0.*"]
 dishka = ["dishka>=1.0"]

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/__init__.py

@@ -1,3 +1,4 @@
+from cqrs._eol import emit_v4_eol_warning
 from cqrs.compressors import Compressor, ZlibCompressor
 from cqrs.container.di import DIContainer
 from cqrs.container.protocol import Container, SupportsScope
@@ -44,6 +45,13 @@ from cqrs.outbox.sqlalchemy import (
     SqlAlchemyOutboxedEventRepository,
 )
 from cqrs.producer import EventProducer
+from cqrs.deserializers import DeserializeProtobufError, ProtobufDeserializer
+from cqrs.serializers import (
+    EventCodec,
+    EventSerializer,
+    JsonEventSerializer,
+    ProtobufEventSerializer,
+)
 from cqrs.requests.fallback import RequestHandlerFallback
 from cqrs.requests.map import RequestMap, SagaMap
 from cqrs.requests.mermaid import CoRMermaid
@@ -111,6 +119,12 @@ __all__ = (
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
     "EventProducer",
+    "EventSerializer",
+    "EventCodec",
+    "JsonEventSerializer",
+    "ProtobufEventSerializer",
+    "ProtobufDeserializer",
+    "DeserializeProtobufError",
     "Container",
     "SupportsScope",
     "DIContainer",
@@ -136,3 +150,5 @@ __all__ = (
     "JSONType",
     "PayloadBinary",
 )
+
+emit_v4_eol_warning()

python_cqrs-4.15.1/src/cqrs/_eol.py

@@ -0,0 +1,30 @@
+"""Package-level EOL notice for the 4.x maintenance line."""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+
+_EOL_MESSAGE = (
+    "python-cqrs 4.x is in maintenance mode after 5.0.0. "
+    "Please migrate to 5.x when ready "
+    "(docs: https://mkdocs.python-cqrs.dev/latest/). "
+    'To stay on 4.x: pip install "python-cqrs>=4,<5". '
+    "Suppress this optional log with CQRS_SUPPRESS_V4_EOL_WARNING=1 "
+    "(DeprecationWarning is still emitted)."
+)
+
+_TRUTHY = frozenset({"1", "true", "yes"})
+
+
+def _suppress_log() -> bool:
+    value = os.environ.get("CQRS_SUPPRESS_V4_EOL_WARNING", "")
+    return value.strip().lower() in _TRUTHY
+
+
+def emit_v4_eol_warning() -> None:
+    """Emit DeprecationWarning always; optional logger warning unless suppressed."""
+    warnings.warn(_EOL_MESSAGE, DeprecationWarning, stacklevel=2)
+    if not _suppress_log():
+        logging.getLogger("cqrs").warning(_EOL_MESSAGE)

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/adapters/kafka.py

@@ -5,7 +5,7 @@ import ssl
 import typing
 
 from cqrs.adapters import protocol
-from cqrs.serializers import default
+from cqrs.serializers.default import passthrough_value_serializer
 
 import aiokafka
 import retry_async
@@ -53,22 +53,41 @@ class KafkaProducer(protocol.KafkaProducer):
         producer: aiokafka.AIOKafkaProducer,
         retry_count: int = 3,
         retry_delay: int = 1,
+        legacy_value_serializer: bool = False,
     ):
         self._producer = producer
         self._retry_count = retry_count
         self._retry_delay = retry_delay
+        # True when kafka_producer_factory got an explicit value_serializer so
+        # KafkaMessageBroker can pass message.payload (dict) on the non-codec path.
+        self.legacy_value_serializer = legacy_value_serializer
 
     async def _check_connection(self):
         node_id = self._producer.client.get_random_node()
         if not await self._producer.client.ready(node_id=node_id):
             await self._producer.start()
 
-    async def _produce(self, topic: typing.Text, message: typing.Any):
+    async def _produce(
+        self,
+        topic: typing.Text,
+        message: typing.Any,
+        headers: dict[str, str] | None = None,
+    ):
         await self._check_connection()
         logger.debug(f"produce message {message} to topic {topic}")
-        await self._producer.send_and_wait(topic, value=message)
-
-    async def produce(self, topic: typing.Text, message: typing.Any):
+        produce_kwargs: dict[str, typing.Any] = {"value": message}
+        if headers is not None:
+            produce_kwargs["headers"] = [
+                (key, value.encode("utf-8") if isinstance(value, str) else value) for key, value in headers.items()
+            ]
+        await self._producer.send_and_wait(topic, **produce_kwargs)
+
+    async def produce(
+        self,
+        topic: typing.Text,
+        message: typing.Any,
+        headers: dict[str, str] | None = None,
+    ):
         """
         Produces event to kafka broker.
         Tries to reconnect if connect has been lost or has not been opened.
@@ -76,6 +95,7 @@ class KafkaProducer(protocol.KafkaProducer):
         await _retry(tries=self._retry_count, delay=self._retry_delay)(self._produce)(
             topic,
             message,
+            headers,
         )
 
 
@@ -95,7 +115,7 @@ def kafka_producer_factory(
 
     producer = aiokafka.AIOKafkaProducer(
         bootstrap_servers=dsn,
-        value_serializer=value_serializer or default.default_serializer,
+        value_serializer=passthrough_value_serializer(value_serializer),
         security_protocol=security_protocol,
         sasl_mechanism=sasl_mechanism,
         sasl_plain_username=user,
@@ -107,4 +127,5 @@ def kafka_producer_factory(
         producer=producer,
         retry_count=retry_count,
         retry_delay=retry_delay,
+        legacy_value_serializer=value_serializer is not None,
     )

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/adapters/protocol.py

@@ -5,10 +5,17 @@ if typing.TYPE_CHECKING:
 
 
 class KafkaProducer(typing.Protocol):
+    """
+    ``legacy_value_serializer`` (optional attribute, default False) is set by
+    ``kafka_producer_factory`` when an explicit ``value_serializer`` is passed.
+    ``KafkaMessageBroker`` uses it to decide whether to forward ``message.payload``.
+    """
+
     async def produce(
         self,
         topic: typing.Text,
         message: typing.Any,
+        headers: dict[str, str] | None = None,
     ) -> None: ...
 
 

python_cqrs-4.15.1/src/cqrs/deserializers/__init__.py

@@ -0,0 +1,11 @@
+from cqrs.deserializers.exceptions import DeserializeJsonError, DeserializeProtobufError
+from cqrs.deserializers.json import Deserializable, JsonDeserializer
+from cqrs.deserializers.protobuf import ProtobufDeserializer
+
+__all__ = (
+    "Deserializable",
+    "JsonDeserializer",
+    "DeserializeJsonError",
+    "ProtobufDeserializer",
+    "DeserializeProtobufError",
+)

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/deserializers/exceptions.py

@@ -2,6 +2,22 @@ import dataclasses
 import typing
 
 
+@dataclasses.dataclass(frozen=True)
+class DeserializeProtobufError:
+    """
+    Error that occurred during protobuf deserialization.
+
+    Args:
+        error_message: Human-readable error message
+        error_type: Type of the exception that occurred
+        message_data: The original message data that failed to deserialize
+    """
+
+    error_message: str
+    error_type: typing.Type[Exception]
+    message_data: str | bytes | None
+
+
 @dataclasses.dataclass(frozen=True)
 class DeserializeJsonError:
     """

python_cqrs-4.15.1/src/cqrs/deserializers/protobuf.py

@@ -0,0 +1,51 @@
+import logging
+import typing
+import sys
+
+from cqrs.deserializers.exceptions import DeserializeProtobufError
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # novm
+else:
+    from typing_extensions import Self
+
+logger = logging.getLogger("cqrs")
+
+
+class ProtoDeserializable(typing.Protocol):
+    """Objects that can be constructed from a protobuf message via ``from_proto``."""
+
+    @classmethod
+    def from_proto(cls, proto: typing.Any) -> Self: ...
+
+
+_T = typing.TypeVar("_T", bound=ProtoDeserializable)
+
+
+class ProtobufDeserializer(typing.Generic[_T]):
+    """
+    Deserializer for protobuf messages.
+
+    Converts protobuf wire bytes into Python objects using the ``from_proto``
+    classmethod of the target model. Duck-typed: this module does not import
+    ``google.protobuf``.
+    """
+
+    def __init__(self, model: type[_T], proto_type: typing.Any) -> None:
+        self._model = model
+        self._proto_type = proto_type
+
+    def __call__(self, data: bytes | None) -> _T | None | DeserializeProtobufError:
+        if data is None:
+            return None
+        try:
+            return self._model.from_proto(self._proto_type.FromString(data))
+        except Exception as e:
+            logger.error(
+                f"Error while deserializing protobuf message: {e}",
+            )
+            return DeserializeProtobufError(
+                error_message=str(e),
+                error_type=type(e),
+                message_data=data,
+            )

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/events/event_emitter.py

@@ -15,6 +15,9 @@ from cqrs.container.scope import (
 from cqrs.events.event import IDomainEvent, IEvent, INotificationEvent
 from cqrs.events import event_handler, map
 from cqrs.events.fallback import EventHandlerFallback
+from cqrs.serializers.default import headers_for_content_type
+from cqrs.serializers.json import JsonEventSerializer
+from cqrs.serializers.protocol import EventSerializer
 
 logger = logging.getLogger("cqrs")
 
@@ -38,6 +41,8 @@ class EventEmitter:
         container: di_container.Container,
         message_broker: message_brokers.MessageBroker | None = None,
         scope_strategy: ScopeStrategy = ScopeStrategy.NONE,
+        *,
+        serializer: EventSerializer | None = None,
     ) -> None:
         """
         Initialize the event emitter.
@@ -48,6 +53,7 @@ class EventEmitter:
             message_broker: Optional broker for notification events; required
                 when emitting :class:`~cqrs.events.event.INotificationEvent`.
             scope_strategy: DI scope boundary; HANDLER opens a scope per handler.
+            serializer: Codec used to fill ``Message.payload_bytes``. Defaults to JSON.
 
         Example::
 
@@ -64,6 +70,7 @@ class EventEmitter:
         self._container = wrap_container(container)
         self._message_broker = message_broker
         self._scope_strategy = scope_strategy
+        self._serializer = serializer or JsonEventSerializer()
 
     @functools.singledispatchmethod
     async def emit(self, event: IEvent) -> typing.Sequence[IEvent]:
@@ -108,11 +115,20 @@ class EventEmitter:
                 f"To send event {event}, message broker must be specified.",
             )
 
+        # payload (dict) and payload_bytes are both intentional: stub brokers /
+        # Message.to_dict() need the structured dict; transport uses wire bytes.
+        content_type, headers = headers_for_content_type(
+            self._serializer.content_type_for(event),
+            event,
+        )
         message = message_brokers.Message(
             message_name=type(event).__name__,
             message_id=event.event_id,
             topic=event.topic,
             payload=event.to_dict(),
+            payload_bytes=self._serializer.serialize(event),
+            content_type=content_type,
+            headers=headers,
         )
 
         logger.debug(

{python_cqrs-4.14.0 → python_cqrs-4.15.1}/src/cqrs/message_brokers/amqp.py

@@ -1,10 +1,10 @@
 import logging
 
 import aio_pika
-import orjson
 
 from cqrs.adapters import protocol as adapters_protocol
 from cqrs.message_brokers import protocol
+from cqrs.serializers.default import message_wire_bytes
 
 
 class AMQPMessageBroker(protocol.MessageBroker):
@@ -20,8 +20,16 @@ class AMQPMessageBroker(protocol.MessageBroker):
         logging.getLogger("aio_pika").setLevel(pika_log_level)
 
     async def send_message(self, message: protocol.Message) -> None:
+        kwargs: dict = {}
+        if message.content_type is not None:
+            kwargs["content_type"] = message.content_type
+        if message.headers is not None:
+            kwargs["headers"] = message.headers
         await self.publisher.publish(
-            message=aio_pika.Message(body=orjson.dumps(message.payload)),
+            message=aio_pika.Message(
+                body=message_wire_bytes(message),
+                **kwargs,
+            ),
             queue_name=message.topic,
             exchange_name=self.exchange_name,
         )

python_cqrs-4.15.1/src/cqrs/message_brokers/kafka.py

@@ -0,0 +1,45 @@
+import logging
+import typing
+
+from cqrs.adapters import protocol as adapters_protocol
+from cqrs.message_brokers import protocol
+from cqrs.serializers.default import message_wire_bytes
+
+
+class KafkaMessageBroker(protocol.MessageBroker):
+    def __init__(
+        self,
+        producer: adapters_protocol.KafkaProducer,
+        aiokafka_log_level: typing.Text = "ERROR",
+    ):
+        self._producer = producer
+        logging.getLogger("aiokafka").setLevel(aiokafka_log_level)
+
+    def _produce_value(self, message: protocol.Message) -> typing.Any:
+        """
+        Choose the value passed to ``KafkaProducer.produce``.
+
+        When a legacy ``value_serializer`` was configured on the producer and the
+        message has no codec wire bytes, forward ``message.payload`` so that
+        serializer can run. Otherwise prefer ``payload_bytes`` / encoded payload
+        so Outbox and EventSerializer bytes are not discarded.
+        """
+        legacy_value_serializer = getattr(
+            self._producer,
+            "legacy_value_serializer",
+            False,
+        )
+        if legacy_value_serializer and message.payload_bytes is None and message.content_type is None:
+            return message.payload
+        return message_wire_bytes(message)
+
+    async def send_message(self, message: protocol.Message) -> None:
+        payload = self._produce_value(message)
+        if message.headers is None:
+            await self._producer.produce(message.topic, payload)
+        else:
+            await self._producer.produce(
+                message.topic,
+                payload,
+                headers=message.headers,
+            )

python_cqrs-4.15.1/src/cqrs/message_brokers/protocol.py

@@ -0,0 +1,74 @@
+import abc
+import base64
+import dataclasses
+import typing
+import uuid
+from dataclass_wizard import asdict
+
+
+@dataclasses.dataclass
+class Message:
+    """
+    Internal message structure for message broker communication.
+
+    Args:
+        message_name: Name of the message type
+        message_id: Unique identifier for the message (auto-generated if not provided)
+        topic: Message broker topic where the message should be sent
+        payload: Structured message payload (typically ``event.to_dict()``)
+        payload_bytes: Optional codec wire-bytes for the transport
+        content_type: Optional MIME type (set only by typed codecs such as Protobuf)
+        headers: Optional broker headers (set only when ``content_type`` is set)
+    """
+
+    message_name: typing.Text
+    topic: typing.Text
+    payload: typing.Any
+    message_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
+    payload_bytes: bytes | None = None
+    content_type: str | None = None
+    headers: dict[str, str] | None = None
+
+    def to_dict(self) -> dict[str, typing.Any]:
+        """
+        Convert the message instance to a dictionary representation.
+
+        Core fields use ``dataclass_wizard.asdict`` camelCase (``messageName``,
+        ``messageId``, …) for JSON-path ``GET /published`` stability. Codec
+        extras (``content_type`` / ``payload_bytes`` / ``headers``) are added
+        only when ``content_type`` is set, in snake_case.
+        """
+        # Rebuild with only the original fields so asdict matches the historical
+        # JSON-path shape (camelCase messageName/messageId). Extra codec fields
+        # still appear as None camelCase keys from defaults — drop them.
+        data = asdict(
+            Message(
+                message_name=self.message_name,
+                topic=self.topic,
+                payload=self.payload,
+                message_id=self.message_id,
+            ),
+        )
+        data.pop("payloadBytes", None)
+        data.pop("contentType", None)
+        data.pop("headers", None)
+        if self.content_type is not None:
+            data["content_type"] = self.content_type
+            if self.payload_bytes is not None:
+                data["payload_bytes"] = base64.b64encode(self.payload_bytes).decode("ascii")
+                data["payload_bytes_encoding"] = "base64"
+            if self.headers is not None:
+                data["headers"] = self.headers
+        return data
+
+
+class MessageBroker(abc.ABC):
+    """
+    The interface over a message broker.
+
+    Used for sending messages to message brokers (currently only redis supported).
+    """
+
+    @abc.abstractmethod
+    async def send_message(self, message: Message) -> None:
+        raise NotImplementedError