Automatic retry & per-listener failure tracking, with composable dispatch

[jcviljoen]

Summary

Adds durable per-(event, listener) retries to the outbox, an audit trail and crash-recovery for in-flight rows, and refactors event processing into a small set of composable building blocks. Existing wiring keeps its old behaviour: retries are opt-in, the new dispatch composition has sensible defaults.

Per-listener retries

• RedeliveryStore interface (in-memory + SQL) persists per-(event, listener) retry state.
• Fully async: a listener throw is written straight to the redelivery table; the main outbox worker moves on.
• RetryPolicy (default NoRetryPolicy, plus a five-attempt ExponentialBackoffRetryPolicy) is consulted only by the redelivery processor — the event processor never decides whether to retry.
• retryNow(eventId, listener) on the store for admin-driven immediate retries; attempt count is preserved so the policy's ceiling still applies.

Composable dispatch

• New ListenerDispatcher interface in src/Dispatch/.
  • DefaultListenerDispatcher resolves the handler, hydrates the payload, dispatches; swallows configured ignoredExceptions, rethrows the rest.
  • RedeliveringListenerDispatcher is a decorator that catches a listener throw and schedules a fresh redelivery row.
• New RedeliveryProcessor interface mirroring EventProcessor. SequentialRedeliveryProcessor owns the RetryPolicy and decides per row whether to reschedule, mark succeeded, or mark failed permanently.
• SilentSequentialEventProcessor becomes SilentEventProcessor — a generic decorator wrapping any EventProcessor. A matching SilentRedeliveryProcessor exists for the redelivery side.
• New ListenerKey utility normalises a callable|string subscriber to a single string identifier (class name or 'Closure').

The result: dev wires the bare SequentialEventProcessor + DefaultListenerDispatcher and gets fail-fast behaviour. Prod wraps with SilentEventProcessor and uses RedeliveringListenerDispatcher for durable per-listener failures.

Outbox lifecycle + crash recovery

• Events transition pending → processing → processed; redeliveries transition pending_retry → dispatching → succeeded | failed. Two symmetric state machines; next() claims atomically.
• Worker-safe: MySQL claim uses FOR UPDATE SKIP LOCKED; mark/update calls are guarded by the claimed status so a stale worker cannot overwrite a row a sweeper has already reset.
• EventStore::recoverStuckEvents(CarbonInterval) and SqlRedeliveryStore::recoverStuckRedeliveries(CarbonInterval) sweep rows wedged by crashed workers back to the pending state. Disjoint by status filter from the main drain loops, so the sweepers and processors do not contend.
• README's Scheduled jobs section documents the four cron tasks (event drain, redelivery drain, two sweepers) and how they avoid contention.

Audit trail

• Every event status transition writes a row to the previously-unused event_outbox_status table.
• EventStore::markProcessed() now takes a RawEvent (was string $eventId) so the processor and the store share the same claimed entity end-to-end.

Namespace reorganisation

• Redelivery types moved to Vesper\Tool\Event\Redelivery\* (Redelivery, RedeliveryStatus, RedeliveryStore, RedeliveryProcessor).
• Redelivery infra moved to src/Infrastructure/Redelivery/*; dispatch infra at src/Infrastructure/Dispatch/*.

Docs

• README rewritten around the composition pattern and the per-environment wiring tables.
• ROADMAP entries for metering and batch claim updated to fit the new shape (metering becomes a ListenerDispatcher decorator, batch claim becomes next(int $batchSize): list<...> on both stores).

🤖 Generated with Claude Code