Broker Backend God-Class Decomposition Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Decompose RabbitMQEventBus (~3,570-line class) and KafkaEventBus (~2,195-line class) into backend subpackages of state-owning collaborators behind unchanged facades, shipped as 0.7.0.
Architecture: Each backend flat module becomes a package (bus/rabbitmq/, bus/kafka/) whose __init__.py re-exports everything the old module exported. Collaborators (ConnectionManager, Topology, Publisher, Consumer, DLQAdmin, plus pure serialization/death-header modules) own their state; the *EventBus class becomes a facade that composes them and keeps every public signature. Extraction is leaf-first: package conversion β pure modules β stateful collaborators β facade slim-down.
Tech Stack: Python 3.11+, pydantic v2, aio-pika (RabbitMQ), aiokafka (Kafka), pytest + pytest-asyncio, hypothesis, mutmut, uv.
Spec: docs/superpowers/specs/2026-07-29-bus-god-class-decomposition-design.md β read the spec section named in a task before implementing it.
Global Constraints
- Target version 0.7.0. Public breakage limited to exactly three Kafka items: remove
get_handlers_for_event; deprecaterecord_reconnection/record_rebalance(warn + delegate shims, removal slated for 0.8.0);KafkaRebalanceListenermoves tobus/kafka/connection.py(still re-exported from the package__init__). - Every other public method/attribute on
RabbitMQEventBusandKafkaEventBuskeeps its exact signature and behavior. - Collaborators are internal: nothing new exported from
src/eventsource/bus/__init__.pyorsrc/eventsource/__init__.py. - Package
__init__.pyre-exports everything the old flat module's__all__listed β all existing imports keep working verbatim. - The 9-test
EventBusConformanceSuitesubclasses and all public-API integration tests pass unmodified. Only tests that pin private internals may change. - ADR 0011 semantics bit-for-bit: consume paths run ALL handlers, aggregate failures into
HandlerDispatchError, withhold ack on failure; single-failure unwrap before DLQ error recording is preserved. - Optional-dependency guard behavior identical, including
*_AVAILABLE = Falsefallback when the driver is missing. - Old flat modules
bus/rabbitmq.py/bus/kafka.pyare deleted in their conversion tasks; the packages take their import paths. - Every task must leave
uv run mypy src/eventsource/ --config-file=pyproject.toml,uv run ruff check src/ tests/, and the task's targeted unit tests green. mypy is strict β annotate everything. - Test dirs contain
__init__.pyfiles (project convention) β create one in each new test directory. - Async tests use
@pytest.mark.asyncio. Integration tests for brokers carry@pytest.mark.rabbitmq/@pytest.mark.kafkamarkers and need Docker β the orchestrator runs those; implementers run unit tests only unless the task says otherwise. - Commit format:
type: subject(see.claude/rules/commits.md), e.g.refactor: extract rabbitmq topology collaborator.
Task 1: Convert `bus/rabbitmq.py` to a package
Files:
- Move:
src/eventsource/bus/rabbitmq.pyβsrc/eventsource/bus/rabbitmq/bus.py - Create:
src/eventsource/bus/rabbitmq/__init__.py - Create:
tests/unit/bus/rabbitmq/__init__.py - Test:
tests/unit/bus/rabbitmq/test_import_guard.py
Interfaces:
- Consumes: existing flat module; its
__all__(atrabbitmq.py:4216-4228) listsBatchPublishError, DLQMessage, HealthCheckResult, OTEL_AVAILABLE, QueueInfo, RabbitMQEventBus, RabbitMQEventBusConfig, RabbitMQEventBusStats, RabbitMQNotAvailableError, RABBITMQ_AVAILABLE, ShutdownError. - Produces: package
eventsource.bus.rabbitmqwith identical import surface. All later Rabbit tasks split files out ofbus/rabbitmq/bus.py. - [ ] Step 1: Move the module into a package
mkdir -p src/eventsource/bus/rabbitmq
git mv src/eventsource/bus/rabbitmq.py src/eventsource/bus/rabbitmq/bus.py
- [ ] Step 2: Write the package
__init__.py
"""RabbitMQ event bus backend.
Public import surface is identical to the pre-0.7.0 flat module
``eventsource.bus.rabbitmq``. Internal collaborators live in sibling
modules and are not part of the public API.
"""
from eventsource.bus.rabbitmq.bus import (
OTEL_AVAILABLE,
RABBITMQ_AVAILABLE,
BatchPublishError,
DLQMessage,
HealthCheckResult,
QueueInfo,
RabbitMQEventBus,
RabbitMQEventBusConfig,
RabbitMQEventBusStats,
RabbitMQNotAvailableError,
ShutdownError,
)
__all__ = [
"BatchPublishError",
"DLQMessage",
"HealthCheckResult",
"OTEL_AVAILABLE",
"QueueInfo",
"RabbitMQEventBus",
"RabbitMQEventBusConfig",
"RabbitMQEventBusStats",
"RabbitMQNotAvailableError",
"RABBITMQ_AVAILABLE",
"ShutdownError",
]
Keep __all__ in bus.py too for now (it moves out as later tasks strip the file).
- [ ] Step 3: Write the failing import-guard test
tests/unit/bus/rabbitmq/test_import_guard.py (create tests/unit/bus/rabbitmq/__init__.py as an empty file first):
"""The optional-dependency guard must behave identically to the flat module."""
import importlib
import sys
from unittest import mock
import pytest
def _purge(prefix: str) -> None:
for name in [m for m in sys.modules if m == prefix or m.startswith(prefix + ".")]:
del sys.modules[name]
def test_rabbitmq_available_true_with_driver_installed() -> None:
mod = importlib.import_module("eventsource.bus.rabbitmq")
assert mod.RABBITMQ_AVAILABLE is True
def test_import_succeeds_and_flag_false_without_aio_pika() -> None:
saved = {
m: sys.modules[m]
for m in list(sys.modules)
if m == "aio_pika" or m.startswith("aio_pika.")
or m == "eventsource.bus.rabbitmq"
or m.startswith("eventsource.bus.rabbitmq.")
}
try:
_purge("eventsource.bus.rabbitmq")
_purge("aio_pika")
with mock.patch.dict(sys.modules, {"aio_pika": None}):
mod = importlib.import_module("eventsource.bus.rabbitmq")
assert mod.RABBITMQ_AVAILABLE is False
with pytest.raises(mod.RabbitMQNotAvailableError):
mod.RabbitMQEventBus(mod.RabbitMQEventBusConfig(rabbitmq_url="amqp://x"))
finally:
_purge("eventsource.bus.rabbitmq")
_purge("aio_pika")
sys.modules.update(saved)
Note: RabbitMQEventBusConfig may require more constructor args β check its __post_init__ (bus.py:130-377) and pass the minimal valid set. If constructing the config itself requires aio-pika (it should not β it is a plain dataclass), construct it before the patch.
- [ ] Step 4: Run the new test and the existing unit suite
uv run pytest tests/unit/bus/ -x -q
uv run pytest tests/unit/ -q
uv run mypy src/eventsource/ --config-file=pyproject.toml
uv run ruff check src/ tests/
Expected: all pass. If mock.patch.dict on sys.modules proves flaky with pytest plugins, an equivalent approach: insert a importlib.abc.MetaPathFinder that raises ImportError for aio_pika β either is acceptable; the assertion set must not change.
- [ ] Step 5: Commit
git add -A src/eventsource/bus/rabbitmq tests/unit/bus/rabbitmq
git commit -m "refactor: convert bus/rabbitmq.py to a package with identical import surface"
Task 2: Extract `death_headers.py` (pure functions) with property tests
Files:
- Create:
src/eventsource/bus/rabbitmq/death_headers.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(remove the seven static method bodies, lines ~1570-1787; add aliases) - Test:
tests/unit/bus/rabbitmq/test_death_headers.py
Interfaces:
- Consumes: the seven
@staticmethods onRabbitMQEventBus:get_death_count,get_first_death_queue,get_first_death_reason,get_first_death_exchange,get_original_routing_key,is_from_dlq,get_death_info(bus.py:1570-1787). They are pure β they read message headers only. - Produces: module-level functions in
death_headers.pywith the same names and signatures as the current staticmethods (copy each signature verbatim frombus.py, dropping only the implicit staticmethod context).RabbitMQEventBuskeeps permanent static aliases. Task 7 (consumer) calls these functions directly. - [ ] Step 1: Write the test file first
Port any existing death-header assertions from current tests (grep get_death_count\|is_from_dlq\|get_death_info under tests/) and add coverage for every function. Representative shape (adjust arg construction to the real signatures β they take a headers mapping or an AbstractIncomingMessage; mirror what bus.py does):
"""Unit + property tests for the pure death-header functions."""
from hypothesis import given
from hypothesis import strategies as st
from eventsource.bus.rabbitmq import death_headers
def _headers_with_death(count: int, queue: str = "q1", reason: str = "rejected",
exchange: str = "ex", routing_keys: list[str] | None = None) -> dict:
return {
"x-death": [
{
"count": count,
"queue": queue,
"reason": reason,
"exchange": exchange,
"routing-keys": routing_keys or ["events.order.created"],
}
]
}
def test_death_count_zero_when_no_header() -> None:
assert death_headers.get_death_count({}) == 0
def test_death_count_reads_first_entry() -> None:
assert death_headers.get_death_count(_headers_with_death(3)) == 3
def test_is_from_dlq_false_without_header() -> None:
assert death_headers.is_from_dlq({}) is False
@given(count=st.integers(min_value=0, max_value=10_000))
def test_death_count_roundtrips_any_count(count: int) -> None:
assert death_headers.get_death_count(_headers_with_death(count)) == count
@given(queue=st.text(min_size=1, max_size=50))
def test_first_death_queue_returns_recorded_queue(queue: str) -> None:
assert death_headers.get_first_death_queue(_headers_with_death(1, queue=queue)) == queue
Add one test per remaining function (get_first_death_reason, get_first_death_exchange, get_original_routing_key, get_death_info) asserting the happy path and the missing-header default. Match the real return types (int, str | None, dict | None β read the signatures).
- [ ] Step 2: Run to verify failure β
uv run pytest tests/unit/bus/rabbitmq/test_death_headers.py -qβ FAIL (module doesn't exist). - [ ] Step 3: Create
death_headers.pyβ move the seven bodies verbatim frombus.py:1570-1787into module functions (docstrings included). No behavior edits. - [ ] Step 4: Replace the staticmethods on the facade with permanent aliases
In bus.py, delete the seven method bodies and add inside the class body:
# Permanent public aliases: the pure implementations live in death_headers.py.
get_death_count = staticmethod(death_headers.get_death_count)
get_first_death_queue = staticmethod(death_headers.get_first_death_queue)
get_first_death_reason = staticmethod(death_headers.get_first_death_reason)
get_first_death_exchange = staticmethod(death_headers.get_first_death_exchange)
get_original_routing_key = staticmethod(death_headers.get_original_routing_key)
is_from_dlq = staticmethod(death_headers.is_from_dlq)
get_death_info = staticmethod(death_headers.get_death_info)
Update in-class callers (grep self.get_death_count\|self.is_from_dlq etc. in bus.py) β they keep working via the aliases; leave them as-is.
- [ ] Step 5: Run tests, lint, mypy β
uv run pytest tests/unit/bus/ -q && uv run mypy src/eventsource/ --config-file=pyproject.toml && uv run ruff check src/ tests/β PASS. - [ ] Step 6: Commit β
git commit -m "refactor: extract pure death-header functions to bus/rabbitmq/death_headers.py"
Task 3: Extract Rabbit `config.py`, `models.py`, `serialization.py`
Files:
- Create:
src/eventsource/bus/rabbitmq/config.py(βRabbitMQEventBusConfig,bus.py:130-377) - Create:
src/eventsource/bus/rabbitmq/models.py(βRabbitMQNotAvailableError110-128,DLQMessage379-419,RabbitMQEventBusStats420-495,QueueInfo496-528,HealthCheckResult529-578,ShutdownError4153-4172,BatchPublishError4174-4228) - Create:
src/eventsource/bus/rabbitmq/serialization.py(β_get_event_field_default1990,_get_routing_key2016,_serialize_event2035,_create_message2088,_create_message_with_tracing2126,_deserialize_event2170) - Modify:
src/eventsource/bus/rabbitmq/bus.py,src/eventsource/bus/rabbitmq/__init__.py - Test:
tests/unit/bus/rabbitmq/test_serialization.py; repoint the RabbitMQ half oftests/unit/bus/test_serialization_properties.py
Interfaces:
- Produces (
serialization.pymodule functions β private methods become public module functions with explicit params instead ofself): get_event_field_default(event_class: type[DomainEvent], field: str) -> Anyget_routing_key(event: DomainEvent, config: RabbitMQEventBusConfig) -> strserialize_event(event: DomainEvent) -> bytes(keep the exact current payload format β the Redis payload-is-authoritative property test guards the JSON shape)create_message(event: DomainEvent, config: RabbitMQEventBusConfig) -> Messagecreate_message_with_tracing(event: DomainEvent, config: RabbitMQEventBusConfig, tracer: Tracer | None, enable_tracing: bool) -> Messagedeserialize_event(body: bytes, headers: Mapping[str, Any], resolve_event_class: Callable[[str], type[DomainEvent] | None]) -> DomainEvent- Adjust these param lists to whatever the current bodies actually read off
self(self._config,self._tracer,self._enable_tracing,self._resolve_event_class) β everyself.Xread becomes an explicit parameter; no other logic changes. - Facade keeps thin private wrappers (
def _serialize_event(self, event): return serialization.serialize_event(event)) so remainingbus.pycall sites don't all change in this task; wrappers die naturally in Tasks 6-7. config.py/models.py: classes move verbatim;bus.pyimports them; package__init__.pyre-imports the public ones from their new homes instead of from.bus.- [ ] Step 1: Move
RabbitMQEventBusConfigtoconfig.pyand the dataclasses/exceptions tomodels.py, verbatim, carrying their imports. The aio-pika-dependent types used in signatures need the guard-safe import pattern:models.py/config.pymust import only stdlib + eventsource types (check β the config and models should not need aio-pika; if a type hint needs it, useTYPE_CHECKING). - [ ] Step 2: Update
bus.pyto import from the new modules; update__init__.pyto re-exportRabbitMQEventBusConfigfrom.configand the model classes from.models. Runuv run pytest tests/unit/ -qβ PASS. - [ ] Step 3: Write
tests/unit/bus/rabbitmq/test_serialization.pyβ port the assertion style oftests/unit/bus/test_serialization_properties.py(Rabbit section) against the new module functions:
import pytest
from hypothesis import given
from eventsource.bus.rabbitmq import serialization
from eventsource.bus.rabbitmq.config import RabbitMQEventBusConfig
# reuse the event strategies/fixtures test_serialization_properties.py uses
def test_roundtrip_preserves_event_identity(sample_event, config) -> None:
body = serialization.serialize_event(sample_event)
restored = serialization.deserialize_event(
body, headers={}, resolve_event_class=lambda name: type(sample_event)
)
assert restored == sample_event
Drive hypothesis-based async bodies (if any) with asyncio.run from sync tests β @given on async def passes vacuously.
- [ ] Step 4: Move the six method bodies into
serialization.pyper the Interfaces block; add the thin facade wrappers. Repoint the Rabbit assertions intests/unit/bus/test_serialization_properties.pyat the module functions (same assertions, new call target). - [ ] Step 5:
uv run pytest tests/unit/bus/ -q && uv run mypy src/eventsource/ --config-file=pyproject.toml && uv run ruff check src/ tests/β PASS. - [ ] Step 6: Commit β
git commit -m "refactor: extract rabbitmq config, models, and serialization modules"
Task 4: Extract `RabbitMQConnectionManager`
Files:
- Create:
src/eventsource/bus/rabbitmq/connection.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(_create_ssl_context798,connect891,disconnect1006,_sanitize_url1077,_on_reconnect1092,_on_connection_close1161,_on_channel_close1205,_force_disconnect4081 β bodies move; facade methods become delegations) - Test:
tests/unit/bus/rabbitmq/test_connection.py
Interfaces:
- Produces:
class RabbitMQConnectionManager:
def __init__(self, config: RabbitMQEventBusConfig, stats: RabbitMQEventBusStats) -> None: ...
@property
def is_connected(self) -> bool: ...
@property
def is_reconnecting(self) -> bool: ...
@property
def connection(self) -> AbstractRobustConnection | None: ...
@property
def channel(self) -> AbstractChannel | None: ...
def require_channel(self) -> AbstractChannel:
"""Return the live channel or raise RuntimeError('Not connected...')
with the same message the current code uses."""
def on_reconnect(self, callback: Callable[[], Awaitable[None]]) -> None:
"""Register an async callback fired after a successful reconnect,
in registration order."""
async def connect(self) -> None: ...
async def disconnect(self) -> None: ...
async def force_disconnect(self) -> None: ...
- The manager owns
_connection,_channel,_connected,_reconnecting,_lock(the connect lock), SSL context creation, URL sanitizing, and the aio-pika close/reconnect callbacks. The current_on_reconnectbody does two things: re-establish channel state (stays here) and re-declare topology / resume consuming (becomesfor cb in self._reconnect_callbacks: await cb()). - Facade (
RabbitMQEventBus) constructs the manager in__init__, keepsconnect()/disconnect()/is_connectedas delegations, and registers reconnect callbacks in Task 8/9 wiring. Until Tasks 5-8 land, the facade may still reachself._connection_manager.channelwhere it previously usedself._channelβ do a mechanical rename of those reads. - [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_connection.pyfirst β construct the manager with a config and stats, mockaio_pika.connect_robust(patch it insideeventsource.bus.rabbitmq.connection), and assert: connect()setsis_connectedand stores connection/channel from the mocked robust connection,connect()is idempotent under the lock (call twice, one underlying connect),require_channel()raisesRuntimeErrorbefore connect,on_reconnectcallbacks fire in registration order when the reconnect handler runs (invoke the manager's internal reconnect handler directly with a mocked connection),disconnect()clears state and is safe to call twice,- URL sanitizing masks credentials (assert
_sanitize_url("amqp://user:pass@h:5672/") == "amqp://user:***@h:5672/"β match the current implementation's exact masking, read it first).
Full test skeleton:
from unittest import mock
import pytest
from eventsource.bus.rabbitmq.config import RabbitMQEventBusConfig
from eventsource.bus.rabbitmq.connection import RabbitMQConnectionManager
from eventsource.bus.rabbitmq.models import RabbitMQEventBusStats
@pytest.fixture
def manager() -> RabbitMQConnectionManager:
return RabbitMQConnectionManager(
config=RabbitMQEventBusConfig(rabbitmq_url="amqp://guest:guest@localhost:5672/"),
stats=RabbitMQEventBusStats(),
)
@pytest.mark.asyncio
async def test_connect_sets_connected_and_channel(manager) -> None:
fake_channel = mock.AsyncMock()
fake_conn = mock.AsyncMock()
fake_conn.channel.return_value = fake_channel
with mock.patch(
"eventsource.bus.rabbitmq.connection.aio_pika.connect_robust",
new=mock.AsyncMock(return_value=fake_conn),
):
await manager.connect()
assert manager.is_connected
assert manager.channel is fake_channel
@pytest.mark.asyncio
async def test_reconnect_callbacks_fire_in_order(manager) -> None:
calls: list[str] = []
async def cb_a() -> None:
calls.append("a")
async def cb_b() -> None:
calls.append("b")
manager.on_reconnect(cb_a)
manager.on_reconnect(cb_b)
await manager._run_reconnect_callbacks() # the internal hook the aio-pika callback awaits
assert calls == ["a", "b"]
(Adapt mock plumbing to the real connect body β e.g. QoS setup, publisher confirms β after reading it. The assertions above are the contract; add mocks until they hold.)
- [ ] Step 2: Run β FAIL (module missing).
- [ ] Step 3: Create
connection.py, moving the eight bodies. The reconnect handler callsawait self._run_reconnect_callbacks()where the old body re-declared topology/resumed consuming; the old inline logic moves OUT (facade re-registers it as callbacks in this task β register two temporary closures inRabbitMQEventBus.__init__that call the still-facade-resident topology/consumer methods, so behavior is unchanged now and Tasks 5/7 swap the closure targets). - [ ] Step 4: Facade: replace
_connection/_channel/_connected/_reconnectingfield uses with manager access (mechanical). Keep publicconnect()/disconnect()signatures delegating;is_connectedproperty reads the manager. - [ ] Step 5:
uv run pytest tests/unit/bus/ -q && uv run mypy src/eventsource/ --config-file=pyproject.toml && uv run ruff check src/ tests/β PASS. - [ ] Step 6: Commit β
git commit -m "refactor: extract RabbitMQConnectionManager with explicit reconnect hook"
Task 5: Extract `RabbitMQTopology`
Files:
- Create:
src/eventsource/bus/rabbitmq/topology.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(_declare_exchange1247,_declare_queue1293,_bind_queue1330,bind_event_type1389,bind_routing_key1449,_declare_dlq1489 move; facade keepsbind_event_type/bind_routing_keydelegations) - Test:
tests/unit/bus/rabbitmq/test_topology.py - Modify:
tests/integration/bus/test_rabbitmq.py(assertions on_exchange/_dlq_exchange/_consumer_queue/_dlq_queueβ repoint)
Interfaces:
- Produces:
class RabbitMQTopology:
def __init__(self, config: RabbitMQEventBusConfig, connection: RabbitMQConnectionManager) -> None: ...
@property
def exchange(self) -> AbstractExchange | None: ...
@property
def dlq_exchange(self) -> AbstractExchange | None: ...
@property
def consumer_queue(self) -> AbstractQueue | None: ...
@property
def dlq_queue(self) -> AbstractQueue | None: ...
async def declare_all(self) -> None:
"""Declare exchange, consumer queue, bindings, and DLQ per config flags β
exactly what connect() declares today, in the same order."""
async def redeclare(self) -> None:
"""Reconnect path: re-declare everything (current _on_reconnect behavior)."""
async def bind_event_type(self, event_type: type[DomainEvent]) -> None: ...
async def bind_routing_key(self, routing_key: str) -> None: ...
- Consumes:
RabbitMQConnectionManager.require_channel()(Task 4),serialization.get_routing_keyif the bind path derives keys (check the currentbind_event_typebody). - Facade wiring:
RabbitMQEventBus.__init__createsself._topology = RabbitMQTopology(config, self._connection_manager);connect()callsawait self._topology.declare_all()after manager connect (same order as today); the reconnect closure from Task 4 now callsself._topology.redeclare(). Facadebind_event_type/bind_routing_keydelegate with unchanged public signatures. - [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_topology.pyfirst: with a mocked connection manager (require_channelreturns anAsyncMockchannel whosedeclare_exchange/declare_queuereturn mocks), assert:declare_all()declares the main exchange with the configured name/type/durability; declares DLQ exchange+queue only when the config enables DLQ;redeclare()afterdeclare_all()re-issues declarations (call count 2) and rebinding;bind_event_type(OrderCreated)binds the derived routing key; properties return the declared objects. - [ ] Step 2: Run β FAIL. Step 3: Move the six bodies into the class, swapping
self._channelforself._connection.require_channel()and field writes to topology-owned fields. Step 4: Wire the facade per Interfaces; delete the moved fields from the facade. - [ ] Step 5: Update
tests/integration/bus/test_rabbitmq.py: every assertion onbus._exchange,bus._dlq_exchange,bus._consumer_queue,bus._dlq_queuebecomes either (a) a public-surface assertion viaget_queue_info()/health_check()where one exists, or (b)bus._topology.exchangeetc. where the test genuinely verifies declaration happened. Prefer (a)._configassertions βbus.config(public property). Do not weaken what a test proves. - [ ] Step 6:
uv run pytest tests/unit/bus/ -q+ mypy + ruff β PASS. (Orchestrator runs the rabbitmq integration suite after review.) - [ ] Step 7: Commit β
git commit -m "refactor: extract RabbitMQTopology owning exchange and queue declaration"
Task 6: Extract `RabbitMQPublisher`
Files:
- Create:
src/eventsource/bus/rabbitmq/publisher.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(_publish_single2341,_publish_single_no_stats2443,_publish_batch2471,_publish_chunk_concurrent2588,_publish_batch_concurrent2636,_publish_batch_sequential2720 move;publish2242 /publish_batch2289 stay on the facade as thin orchestrators keepingbackgroundsemantics +_track_background) - Test:
tests/unit/bus/rabbitmq/test_publisher.py
Interfaces:
- Produces:
class RabbitMQPublisher:
def __init__(
self,
config: RabbitMQEventBusConfig,
connection: RabbitMQConnectionManager,
topology: RabbitMQTopology,
stats: RabbitMQEventBusStats,
tracer: Tracer | None,
enable_tracing: bool,
) -> None: ...
async def publish_one(self, event: DomainEvent) -> None:
"""Current _publish_single body: build message via serialization.create_message_with_tracing,
publish to topology.exchange with the derived routing key, update stats."""
async def publish_batch(self, events: Sequence[DomainEvent]) -> dict[str, int]:
"""Current batch entry: dispatch to sequential/concurrent strategy per config,
raising BatchPublishError exactly as today."""
(Internal strategy methods _publish_chunk_concurrent etc. move as private methods of the publisher, bodies verbatim.)
- Facade:
publish(events, background=False)keeps itsBaseEventBus-conformant signature; durable path awaitsself._publisher.publish_one(e)per event (or the existing loop structure β preserve current ordering/error behavior exactly);background=Truekeepsself._track_background(...)on the facade.publish_batchpublic signature unchanged, delegates. - [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_publisher.pyfirst: mocked connection/topology (exchange is anAsyncMock); assertpublish_onepublishes exactly one message to the exchange with the routing key fromserialization.get_routing_keyand incrementsstats.events_published(use the real stats field name); assertpublish_batchwith a failing exchange raisesBatchPublishErrorcarrying per-event errors; assert the sequential strategy preserves order (record call order for 5 events). - [ ] Step 2: Run β FAIL. Step 3: Create the publisher; move bodies; facade wires
self._publisher = RabbitMQPublisher(...)in__init__and delegates. Remove the Task 3 serialization wrappers that only the moved code used. - [ ] Step 4:
uv run pytest tests/unit/bus/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor: extract RabbitMQPublisher with batch strategies"
Task 7: Extract `RabbitMQConsumer` (consume loop + retry/DLQ write path)
Files:
- Create:
src/eventsource/bus/rabbitmq/consumer.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(start_consuming2798,stop_consuming2871,start_consuming_in_background2886,_process_message2910,_dispatch_event3104,_calculate_retry_delay1788,_handle_failed_message1802,_republish_for_retry1873,_send_to_dlq1913,_stop_consuming_gracefully3769,_drain_in_flight3818 move) - Test:
tests/unit/bus/rabbitmq/test_consumer.py
Interfaces:
- Produces:
class RabbitMQConsumer:
def __init__(
self,
config: RabbitMQEventBusConfig,
connection: RabbitMQConnectionManager,
topology: RabbitMQTopology,
stats: RabbitMQEventBusStats,
retry_policy: RetryPolicy,
handlers_for: Callable[[type[DomainEvent]], tuple[HandlerAdapter, ...]],
resolve_event_class: Callable[[str], type[DomainEvent] | None],
tracer: Tracer | None,
enable_tracing: bool,
) -> None: ...
@property
def is_consuming(self) -> bool: ...
async def start(self) -> None: ... # current start_consuming body
async def stop(self) -> None: ... # current stop_consuming body
def start_in_background(self) -> asyncio.Task[None]: ...
async def resume_if_was_consuming(self) -> None:
"""Reconnect path: restart consuming iff it was active before the drop
(current _was_consuming logic)."""
async def stop_gracefully(self, timeout: float) -> None: ...
async def drain_in_flight(self, timeout: float) -> None: ...
- The consumer owns
_consumer_task,_consuming,_was_consuming. Dispatch callsself._handlers_for(type(event)); deserialization callsserialization.deserialize_event(body, headers, self._resolve_event_class); retry republish publishes totopology.exchange(as_republish_for_retrydoes today); DLQ writes go totopology.dlq_exchange. Death-count reads usedeath_headers.*module functions. - ADR 0011 invariant (verify, don't redesign):
_dispatch_eventruns ALL handlers, collects failures, raisesHandlerDispatchError(failures);_process_messagetreats that as processing failure (retry β DLQ, no ack); single-failure unwrap (if isinstance(e, HandlerDispatchError) and len(e.failures) == 1: dlq_error = e.failures[0][1]at ~bus.py:3096) moves verbatim. - Facade:
start_consuming/stop_consuming/start_consuming_in_background/is_consumingdelegate with unchanged public signatures; construction passesself._handlers_forandself._resolve_event_classbound methods; the Task 4 reconnect closure now callsself._consumer.resume_if_was_consuming. - [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_consumer.pyfirst. Core cases (mock the incoming message:AsyncMockwith.body,.headers,.ack,.reject, and aprocess()context manager matching how_process_messageconsumes it β read the body first): - all handlers run even when the first fails; failure aggregates and message is NOT acked;
- handler success path acks;
- failure below
retry_policy.max_retriesrepublishes for retry with incremented death/retry count; - failure at max retries goes to the DLQ exchange with error metadata; single-failure unwrap recorded;
resume_if_was_consumingrestarts only if consuming was active before.- [ ] Step 2: Run β FAIL. Step 3: Create
consumer.py, move the eleven bodies, swapself._channelβconnection.require_channel(),self._exchangeβtopology.exchange, static death helpersβdeath_headers.*. - [ ] Step 4: Wire the facade per Interfaces; swap the reconnect closure target. Delete moved fields/methods from
bus.py. - [ ] Step 5:
uv run pytest tests/unit/bus/ -q+ mypy + ruff β PASS. Step 6: Commit βgit commit -m "refactor: extract RabbitMQConsumer owning dispatch and retry/DLQ write path"
Task 8: Extract `RabbitMQDLQAdmin`
Files:
- Create:
src/eventsource/bus/rabbitmq/dlq.py - Modify:
src/eventsource/bus/rabbitmq/bus.py(get_dlq_messages3233,get_dlq_message_count3351,replay_dlq_message3413,_replay_message3526,purge_dlq3603 move; facade delegates) - Test:
tests/unit/bus/rabbitmq/test_dlq_admin.py
Interfaces:
- Produces:
class RabbitMQDLQAdmin:
def __init__(
self,
config: RabbitMQEventBusConfig,
connection: RabbitMQConnectionManager,
topology: RabbitMQTopology,
stats: RabbitMQEventBusStats,
) -> None: ...
async def get_messages(...) -> list[DLQMessage]: ... # copy the exact public signatures
async def get_message_count(self) -> int: ... # from bus.py before moving
async def replay_message(...) -> ...: ...
async def purge(self) -> ...: ...
Copy each public signature verbatim from bus.py (defaults included) β the facade delegations must be signature-identical to today's methods.
- [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_dlq_admin.pyfirst: mocked topologydlq_queue(anAsyncMocksupporting the get/iterator pattern the current body uses β readget_dlq_messagesfirst); assert message paging honors the limit; count returns the queue's declared message count;purgecalls queue purge and returns its count;replay_messagerepublishes to the main exchange and acks the DLQ message. - [ ] Step 2: Run β FAIL. Step 3: Move the five bodies; facade delegates (
async def get_dlq_messages(self, ...): return await self._dlq_admin.get_messages(...)). - [ ] Step 4:
uv run pytest tests/unit/bus/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor: extract RabbitMQDLQAdmin"
Task 9: Slim the Rabbit facade; shutdown/health composition; backfill wiring tests
Files:
- Modify:
src/eventsource/bus/rabbitmq/bus.py(shutdown3672,health_check3934,get_queue_info3850, stats accessors β reorganize in place) - Modify:
src/eventsource/bus/rabbitmq/connection.py,topology.py(add health-slice methods) - Test:
tests/unit/bus/rabbitmq/test_facade_wiring.py
Interfaces:
RabbitMQConnectionManager.health_slice() -> dict[str, Any]β the connection/channel checks currently inline inhealth_check.RabbitMQTopology.queue_health(queue_name: str) -> QueueInfo | Noneβ the passive queue checks (get_queue_infobody moves here; the facade's publicget_queue_infodelegates).- Facade
health_check()assemblesHealthCheckResultfrom the slices + stats β the returned result must be field-for-field identical to today's for the same underlying states. - Facade
shutdown()keeps its public signature and owns ordering:consumer.stop_gracefullyβconsumer.drain_in_flightβself._drain_background()βconnection.disconnect(match the current body's order and timeout handling exactly β read it first; if the current order differs, the current order wins). - After this task
bus.pyshould be roughly:__init__(composition wiring),publish/publish_batchorchestrators, consume/stats/DLQ/health/shutdown delegations, static death-header aliases,__aenter__/__aexit__. Target β€600 lines. - [ ] Step 1: Write
tests/unit/bus/rabbitmq/test_facade_wiring.pyfirst (all against mocks β no broker):
@pytest.mark.asyncio
async def test_reconnect_redeclares_topology_and_resumes_consumer(bus_with_mocks) -> None:
"""Fire the connection manager's reconnect callbacks; assert topology.redeclare
and consumer.resume_if_was_consuming were awaited, in that order."""
@pytest.mark.asyncio
async def test_shutdown_ordering(bus_with_mocks) -> None:
"""shutdown() stops the consumer, drains in-flight, drains background tasks,
then disconnects β assert relative call order via a shared call log."""
@pytest.mark.asyncio
async def test_health_check_composes_slices(bus_with_mocks) -> None:
"""health_check() returns HealthCheckResult reflecting mocked slice values."""
@pytest.mark.asyncio
async def test_stats_accumulate_across_collaborators(bus_with_mocks) -> None:
"""The stats object handed to publisher/consumer is the same object the
facade's get_stats() returns (identity check + counter increment visible)."""
Build bus_with_mocks as a fixture: construct a real RabbitMQEventBus, then replace _connection_manager, _topology, _consumer, _publisher, _dlq_admin with mocks wired to a shared calls: list[str] log. Write the docstring-described assertions as real code.
- [ ] Step 2: Run β FAIL where composition doesn't exist yet. Step 3: Implement the health/queue-info slice moves and shutdown wiring. Step 4: All unit bus tests + mypy + ruff β PASS.
- [ ] Step 5: Verify facade size:
wc -l src/eventsource/bus/rabbitmq/*.pyβbus.pyβ€ ~600 lines; no collaborator > ~900. If a moved cluster silently stayed inbus.py, move it. - [ ] Step 5b: Tracing tests: the facade keeps
_tracer/_enable_tracingattributes (they are constructor wiring inputs), sotests/unit/bus/test_rabbitmq_tracing.py/test_eventbus_tracing_patterns.pyshould pass unmodified β run them (uv run pytest tests/unit/bus/test_rabbitmq_tracing.py tests/unit/bus/test_eventbus_tracing_patterns.py -q). If one reaches an internal that moved, repoint it at the collaborator; keep the assertion identical. - [ ] Step 6: Commit β
git commit -m "refactor: rabbitmq facade composes collaborators; backfill wiring tests"
Task 10: Convert `bus/kafka.py` to a package
Files:
- Move:
src/eventsource/bus/kafka.pyβsrc/eventsource/bus/kafka/bus.py - Create:
src/eventsource/bus/kafka/__init__.py - Create:
tests/unit/bus/kafka/__init__.py - Test:
tests/unit/bus/kafka/test_import_guard.py
Interfaces:
- Old module
__all__(kafka.py:3131-3141):DeserializationError, EventSerializer, KAFKA_AVAILABLE, KafkaEventBus, KafkaEventBusConfig, KafkaEventBusMetrics, KafkaEventBusStats, KafkaNotAvailableError, KafkaRebalanceListener. The package__init__re-exports all of them (yes, includingKafkaRebalanceListenerβ it stays importable fromeventsource.bus.kafkaeven after it moves toconnection.pyin Task 13). - [ ] Step 1:
mkdir -p src/eventsource/bus/kafka && git mv src/eventsource/bus/kafka.py src/eventsource/bus/kafka/bus.py - [ ] Step 2: Write
src/eventsource/bus/kafka/__init__.pyimporting the nine names from.buswith the same__all__(mirror Task 1's structure exactly, Kafka names). - [ ] Step 3: Write
tests/unit/bus/kafka/test_import_guard.pyβ same structure as Task 1's guard test withaiokafkain place ofaio_pika, assertingKAFKA_AVAILABLE is FalseandKafkaEventBus(...)raisesKafkaNotAvailableErrorwhen the import is blocked. - [ ] Step 4:
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. - [ ] Step 5: Commit β
git commit -m "refactor: convert bus/kafka.py to a package with identical import surface"
Task 11: Extract Kafka `config.py`, `models.py`, `serialization.py`
Files:
- Create:
src/eventsource/bus/kafka/config.py(βKafkaEventBusConfig,bus.py:409-786, incl._validate_security_config,get_producer_config,get_consumer_config,_add_security_config,create_ssl_context,get_sanitized_config) - Create:
src/eventsource/bus/kafka/models.py(βKafkaNotAvailableError300-318,DeserializationError320-332,KafkaEventBusStats788-848) - Create:
src/eventsource/bus/kafka/serialization.py(βEventSerializer334-407, verbatim) - Modify:
src/eventsource/bus/kafka/bus.py,src/eventsource/bus/kafka/__init__.py - Test: repoint the Kafka assertions in
tests/unit/bus/test_serialization_properties.pyateventsource.bus.kafka.serialization.EventSerializer(import-path change only; assertions unchanged) - [ ] Step 1: Move the classes verbatim (guard-safe: these modules import stdlib + eventsource only; aiokafka-typed hints go under
TYPE_CHECKING). Updatebus.pyimports and the package__init__re-export sources. - [ ] Step 2: Repoint the serialization property tests' imports.
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. - [ ] Step 3: Commit β
git commit -m "refactor: extract kafka config, models, and serializer modules"
Task 12: Extract Kafka `metrics.py`; move gauge registration out of `connect()`
Files:
- Create:
src/eventsource/bus/kafka/metrics.py(βKafkaEventBusMetrics174-298,_register_connection_gauge1360,_register_consumer_lag_gauge1404) - Modify:
src/eventsource/bus/kafka/bus.py - Test:
tests/unit/bus/kafka/test_metrics.py; repointtests/integration/bus/test_kafka.pyassertions on_metrics/_connection_gauge_registered/_lag_gauge_registered
Interfaces:
- Produces (in
metrics.py):
class KafkaEventBusMetrics: # moved verbatim
...
def register_connection_gauge(
meter: Any, metrics: KafkaEventBusMetrics, is_connected: Callable[[], bool]
) -> bool:
"""Register the connection gauge; return True if registered (current
_connection_gauge_registered semantics). No-op returning False when meter is None."""
def register_consumer_lag_gauge(
meter: Any, metrics: KafkaEventBusMetrics, lag_supplier: Callable[[], Any]
) -> bool: ...
Adjust the callable params to what the current gauge callbacks actually read off self β every self.X becomes an injected callable/value.
- Facade:
connect()no longer registers gauges.KafkaEventBus.connect()completes, then calls a privateself._wire_metrics()that invokes both registration functions and stores the returned flags (facade keeps_connection_gauge_registered/_lag_gauge_registeredas plain bools if integration tests still read them β otherwise move the flags into the metrics module and repoint the tests; prefer repointing). - [ ] Step 1: Write
tests/unit/bus/kafka/test_metrics.pyfirst: registration with a mock meter creates the observable gauge once and returns True;meter=Nonereturns False and registers nothing; calling twice doesn't double-register (mirror current idempotence). - [ ] Step 2: Run β FAIL. Step 3: Move + rewire per Interfaces. Step 4: Repoint the integration-test private reads at the new home. Step 5:
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Step 6: Commit βgit commit -m "refactor: extract kafka metrics module; gauge registration out of connect()"
Task 13: Extract `KafkaConnectionManager`; move `KafkaRebalanceListener`; deprecate `record_*`
Files:
- Create:
src/eventsource/bus/kafka/connection.py - Modify:
src/eventsource/bus/kafka/bus.py(connect1090,disconnect1160,_cleanup_connections1181,_reconnect_consumer2015,_get_security_config2801 move;KafkaRebalanceListener850-944 moves;record_reconnection1308 /record_rebalance1328 become deprecation shims) - Modify:
src/eventsource/bus/kafka/__init__.py(re-exportKafkaRebalanceListenerfrom.connection) - Test:
tests/unit/bus/kafka/test_connection.py
Interfaces:
- Produces:
class KafkaConnectionManager:
def __init__(
self,
config: KafkaEventBusConfig,
stats: KafkaEventBusStats,
metrics: KafkaEventBusMetrics,
) -> None: ...
@property
def producer(self) -> AIOKafkaProducer | None: ...
@property
def consumer(self) -> AIOKafkaConsumer | None: ...
@property
def is_connected(self) -> bool: ...
def require_producer(self) -> AIOKafkaProducer: ...
async def connect(self) -> None: ...
async def disconnect(self) -> None: ...
async def cleanup(self) -> None: ...
async def reconnect_consumer(self) -> None: ...
def record_reconnection(self) -> None: ... # real logic (stats + metrics), moved from the facade
def record_rebalance(self, ...) -> None: ... # copy exact current signature
KafkaRebalanceListenermoves intoconnection.pyand its constructor takes theKafkaConnectionManager(it currently back-references the bus solely to callrecord_rebalance/stats β verify with grep, then re-target). Public re-export patheventsource.bus.kafka.KafkaRebalanceListenerstill works.- Facade shims (public API, deprecated):
def record_reconnection(self) -> None:
"""Deprecated since 0.7.0; scheduled for removal in 0.8.0."""
warnings.warn(
"KafkaEventBus.record_reconnection() is deprecated and will be "
"removed in 0.8.0; it was only ever intended for internal use.",
DeprecationWarning,
stacklevel=2,
)
self._connection_manager.record_reconnection()
(record_rebalance shim mirrors this, forwarding its args.)
- [ ] Step 1: Write
tests/unit/bus/kafka/test_connection.pyfirst: mockedAIOKafkaProducer/AIOKafkaConsumerclasses patched insideeventsource.bus.kafka.connection; assertconnect()starts the producer (and consumer when configured),is_connectedflips,disconnectstops both and is double-call safe,require_producerraises before connect,record_reconnectionincrements the stats counter and metrics. Plus facade shim tests:pytest.warns(DeprecationWarning)on bothrecord_*facade calls, and the call still lands on the manager. - [ ] Step 2: Run β FAIL. Step 3: Move bodies; re-target the rebalance listener; wire facade (
self._connection_manager = KafkaConnectionManager(config, self._stats, self._metrics)), delegations forconnect/disconnect/is_connected. - [ ] Step 4:
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor: extract KafkaConnectionManager; deprecate facade record_* methods"
Task 14: Extract `KafkaPublisher` (split-phase send/ack)
Files:
- Create:
src/eventsource/bus/kafka/publisher.py - Modify:
src/eventsource/bus/kafka/bus.py(_begin_publish_single_event1566,_await_publish_ack1657,_track_background_publish1724,_get_partition_key1813,_serialize_event1827,_create_headers1838 move;publish1484 stays as facade orchestrator) - Test:
tests/unit/bus/kafka/test_publisher.py
Interfaces:
- Produces:
class KafkaPublisher:
def __init__(
self,
config: KafkaEventBusConfig,
connection: KafkaConnectionManager,
serializer: EventSerializer,
stats: KafkaEventBusStats,
metrics: KafkaEventBusMetrics,
tracer: Tracer | None,
enable_tracing: bool,
) -> None: ...
async def publish_all(self, events: Sequence[DomainEvent]) -> None:
"""Split-phase: sequentially hand each event to producer.send() (preserving
per-aggregate ordering via the aggregate_id partition key), then gather acks.
Current publish-path semantics exactly, including the aiokafka plain-Future
handling (add_done_callback with cancelled/exception checks)."""
- Facade
publish(events, background=False): durable pathawait self._publisher.publish_all(events); background pathself._track_background(self._publisher.publish_all(events))β preserve exactly what the current facade does (readpublish1484 first; its structure wins over this description). - [ ] Step 1: Write
tests/unit/bus/kafka/test_publisher.pyfirst: mock producer whosesend()returns a freshasyncio.Future; assert: partition key equals the event'saggregate_idbytes (match current derivation); two events for one aggregate are sent in order before acks are awaited; an ack future failing raises after all sends were handed off; headers carry the event-type name (match_create_headers). - [ ] Step 2: Run β FAIL. Step 3: Move bodies, wire facade. Step 4:
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor: extract KafkaPublisher with split-phase send/ack"
Task 15: Extract `KafkaConsumerLoop`; remove `get_handlers_for_event`
Files:
- Create:
src/eventsource/bus/kafka/consumer.py - Modify:
src/eventsource/bus/kafka/bus.py(start_consuming1903,start_consuming_in_background2039,stop_consuming1265,_process_message2063,_extract_trace_context2143,_process_message_with_span2167,_deserialize_message2282,_get_header_value2308,_get_retry_count2331,_dispatch_to_handlers2348,_handle_processing_error2539,_republish_for_retry2606,_calculate_retry_delay2664,_send_to_dlq2679,_create_dlq_headers2769 move; deleteget_handlers_for_event1874) - Test:
tests/unit/bus/kafka/test_consumer.py; repointtest_serialization_properties.pyif it touches_deserialize_message
Interfaces:
- Produces:
class KafkaConsumerLoop:
def __init__(
self,
config: KafkaEventBusConfig,
connection: KafkaConnectionManager,
serializer: EventSerializer,
stats: KafkaEventBusStats,
metrics: KafkaEventBusMetrics,
retry_policy: RetryPolicy,
handlers_for: Callable[[type[DomainEvent]], tuple[HandlerAdapter, ...]],
resolve_event_class: Callable[[str], type[DomainEvent] | None],
tracer: Tracer | None,
enable_tracing: bool,
shutdown_event: asyncio.Event,
) -> None: ...
@property
def is_consuming(self) -> bool: ...
async def start(self) -> None: ...
async def stop(self) -> None: ...
def start_in_background(self) -> asyncio.Task[None]: ...
- ADR 0011 + class-keyed dispatch invariants:
_dispatch_to_handlerskeepshandlers_for(type(event))keying (the 0.6.0 bug fix), runs ALL handlers, aggregates failures intoHandlerDispatchError, no commit on failure; single-failure unwrap before DLQ error recording moves verbatim. get_handlers_for_event(aDeprecationWarningshim since 0.6.0) is deleted from the facade β grepget_handlers_for_eventacrosssrc/andtests/and remove the stragglers (a test asserting the deprecation shim exists gets deleted too; note it in the commit body).- Facade keeps
start_consuming/stop_consuming/start_consuming_in_background/is_consumingdelegations with unchanged public signatures; passesself._handlers_for/self._resolve_event_classbound methods. - [ ] Step 1: Write
tests/unit/bus/kafka/test_consumer.pyfirst β mirror Task 7's dispatch cases against a mocked aiokafka consumer/message (.value,.headers,.topic,.partition,.offsetβ read_process_messagefor the shape): all-handlers-run isolation,HandlerDispatchErroraggregation, no-commit-on-failure, retry republish below max, DLQ at max with error headers, class-keyed handler lookup (two event classes with the same name string must not cross-dispatch β construct via distinct registries). - [ ] Step 2: Run β FAIL. Step 3: Move the fifteen bodies; delete
get_handlers_for_event+ its references. Step 4:uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor!: extract KafkaConsumerLoop; remove deprecated get_handlers_for_event"
Task 16: Extract `KafkaDLQAdmin`
Files:
- Create:
src/eventsource/bus/kafka/dlq.py - Modify:
src/eventsource/bus/kafka/bus.py(get_dlq_messages2833,replay_dlq_message2948,get_dlq_message_count3082 move; facade delegates) - Test:
tests/unit/bus/kafka/test_dlq_admin.py
Interfaces:
- Produces:
class KafkaDLQAdmin:
def __init__(
self,
config: KafkaEventBusConfig,
connection: KafkaConnectionManager,
serializer: EventSerializer,
stats: KafkaEventBusStats,
) -> None: ...
async def get_messages(...) -> ...: ... # copy exact public signatures from bus.py
async def replay_message(...) -> ...: ...
async def get_message_count(self) -> int: ...
- All three current methods build their own throwaway
AIOKafkaConsumerwith near-identical boilerplate β extract that into one private helperasync def _dlq_consumer(self) -> AsyncIterator[AIOKafkaConsumer](anasynccontextmanagerthat builds, starts, and always stops the consumer), and have the three methods use it. This is the one intentional internal dedup in this plan; observable behavior unchanged. - Facade delegations signature-identical.
- [ ] Step 1: Write
tests/unit/bus/kafka/test_dlq_admin.pyfirst: patchAIOKafkaConsumerinsideeventsource.bus.kafka.dlq; assert count sums end-minus-beginning offsets across partitions (mirrorbus.py:3110-3128);get_messageshonors its limit; replay sends to the main topic viaconnection.require_producer(); the throwaway consumer is always stopped (assertstopawaited even when the body raises β use a raising mock). - [ ] Step 2: Run β FAIL. Step 3: Move + dedup per Interfaces. Step 4:
uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Step 5: Commit βgit commit -m "refactor: extract KafkaDLQAdmin with shared throwaway-consumer helper"
Task 17: Slim the Kafka facade; backfill wiring tests
Files:
- Modify:
src/eventsource/bus/kafka/bus.py(shutdown1228,get_stats_dict1278,get_topic_info1286 reorganized;_shutdown_eventownership; composition wiring in__init__) - Test:
tests/unit/bus/kafka/test_facade_wiring.py
Interfaces:
- Facade
shutdown()keeps its public signature and owns ordering: signal_shutdown_eventβ stop consumer loop βself._drain_background()βconnection.disconnect()(read the current body first β its order wins over this description). - After this task
bus.pyβ__init__wiring,publishorchestrator, delegations, deprecation shims,__aenter__/__aexit__,get_topic_info. Target β€500 lines. - [ ] Step 1: Write
tests/unit/bus/kafka/test_facade_wiring.pyfirst (mirror Task 9's fixture approach with mocked collaborators + shared call log): shutdown ordering; stats identity across collaborators (get_stats_dict()reflects a counter a collaborator incremented); metrics wiring happens after connect (mockregister_connection_gaugeineventsource.bus.kafka.busnamespace, assert called after producer start); background publish goes through_track_background(assertget_background_task_count()rises then drains via_drain_background). - [ ] Step 2: Run β FAIL where wiring is incomplete. Step 3: Finish composition + slim. Step 4:
wc -l src/eventsource/bus/kafka/*.pysanity;uv run pytest tests/unit/ -q+ mypy + ruff β PASS. Tracing tests pass unmodified (facade keeps_tracer/_enable_tracingwiring attributes); if one reaches a moved internal, repoint it, assertion identical. - [ ] Step 5: Commit β
git commit -m "refactor: kafka facade composes collaborators; backfill wiring tests"
Task 18: Release chores β mutmut targets, 0.7.0, CHANGELOG, ADR 0019 renumber + ADR 0020
Files:
- Modify:
pyproject.toml(version, mutmutonly_mutate) - Modify:
CHANGELOG.md - Move:
docs/adrs/0009-postgresql-advisory-locks.mdβdocs/adrs/0019-postgresql-advisory-locks.md - Create:
docs/adrs/0020-broker-backend-collaborator-decomposition.md - Modify:
docs/adrs/index.md - [ ] Step 1: mutmut targets. In
pyproject.toml[tool.mutmut], append toonly_mutate(following the existing entry format):src/eventsource/bus/rabbitmq/death_headers.py,src/eventsource/bus/rabbitmq/serialization.py,src/eventsource/bus/kafka/serialization.py,src/eventsource/bus/rabbitmq/consumer.py,src/eventsource/bus/kafka/consumer.py,src/eventsource/bus/memory.pyβ and extend the paired test-selection config the existing entries use (registry/retry/base pattern) with the matching new test files (tests/unit/bus/rabbitmq/β¦,tests/unit/bus/kafka/β¦,tests/unit/bus/test_memory.py). Sanity:uv run mutmut run --helpexits 0 (config parses); do NOT run the full mutation campaign in-task. - [ ] Step 2: version + changelog.
version = "0.7.0"inpyproject.toml. CHANGELOG 0.7.0 entry: Changed β RabbitMQ/Kafka backends decomposed into internal collaborator packages (imports unchanged); Removed βKafkaEventBus.get_handlers_for_event(deprecated 0.6.0); Deprecated βKafkaEventBus.record_reconnection/record_rebalance(removal 0.8.0). Follow the file's existing entry format. - [ ] Step 3: ADR renumber.
git mv docs/adrs/0009-postgresql-advisory-locks.md docs/adrs/0019-postgresql-advisory-locks.md; update the number in that file's title heading only (# ADR 0009β# ADR 0019) β body otherwise untouched;grep -rn "0009" docs/ src/ README.mdand repoint any references to the advisory-locks ADR (leave subscription-coordination 0009 references alone); updatedocs/adrs/index.md. - [ ] Step 4: ADR 0020. Create
docs/adrs/0020-broker-backend-collaborator-decomposition.md:
# ADR 0020: Broker Backend Collaborator Decomposition
## Status
Accepted (2026-07-29)
## Context
RabbitMQEventBus (~3,570-line class) and KafkaEventBus (~2,195-line class)
each mixed connection lifecycle, topology declaration, serialization,
publish paths, consume/dispatch, retry/DLQ write paths, DLQ administration,
health checks, and stats in one object. Cross-cutting methods
(health_check, _process_message, _dispatch_to_handlers) read state from
four or five responsibility clusters, and ~1,500 lines of logic were
covered only through Docker integration tests.
## Decision
Each broker backend is a package of internal, state-owning collaborators
composed by a facade that keeps the public API:
- ConnectionManager owns broker clients, connected/reconnecting flags, and
an explicit `on_reconnect(callback)` hook; other collaborators request
live clients at call time and never capture them at construction.
- RabbitMQTopology owns exchange/queue objects and declaration; Kafka has
no topology collaborator (config-driven β the asymmetry is real).
- Publisher and Consumer own their paths; the Consumer owns the retry/DLQ
write path and receives `handlers_for` / `resolve_event_class` callables
so the SubscriptionRegistry stays on the facade (ADR 0013, ADR 0010).
- DLQAdmin owns get/count/replay(/purge) administration.
- Pure logic (RabbitMQ death-header introspection, serialization) lives in
plain modules.
- Collaborators are internal: nothing new is exported from
`eventsource.bus` or `eventsource`. Facades keep every public signature;
the only 0.7.0 API changes are removing the already-deprecated
`KafkaEventBus.get_handlers_for_event` and deprecating
`record_reconnection`/`record_rebalance`.
- Shutdown/drain ordering and health-check assembly are facade-owned;
collaborators expose stop/close primitives and health slices.
## Alternatives Considered
- **Mixin split**: files shrink but every mixin still reads shared `self`
state β coupling unchanged, only harder to see. Rejected.
- **Function-module extraction**: logic moves to parameterized functions
but all state stays on one class with 15-20 fields. Rejected.
- **Shared cross-backend contracts** (common DLQAdmin/consumer pipeline
interfaces implemented by Redis too): deferred, not rejected β revisit
once both per-backend decompositions have settled.
## Consequences
- Collaborators are unit-testable with mocked broker objects; reconnect
and shutdown wiring have direct unit coverage instead of Docker-only.
- Delivery, retry, and error-isolation semantics (ADR 0007, ADR 0011) are
unchanged; the conformance suite passes unmodified.
- Internal collaborator APIs may change freely between releases.
- [ ] Step 5:
uv run pytest tests/unit/ -q+uv run ruff check src/ tests/+ mypy β PASS. Docs build if a make target exists (make help | grep -i docs). - [ ] Step 6: Commit β
git commit -m "chore: release chores for 0.7.0 β mutmut targets, changelog, ADR 0019 renumber, ADR 0020"
Post-plan verification (orchestrator, not a task)
- Full suite:
uv run pytest tests/unit/ -q; broker integration via Docker:uv run pytest -m "(kafka or rabbitmq) and not benchmark" --no-cov;make checkfor CI parity. - Grep the tree for stragglers:
grep -rn "bus/rabbitmq.py\|bus/kafka.py" docs/ README.md(stale path references). - Confirm
git log --followstill tracks history through thegit mvs.