Add fallback documentation

Author: Вадим Козыревский

docs/bootstrap/advanced.md

@@ -12,7 +12,7 @@
 
     Core concepts for commands, queries, and request handlers.
 
-    [:octicons-arrow-right-24: Read More](../request_handler.md)
+    [:octicons-arrow-right-24: Read More](../request_handler/index.md)
 
 </div>
 

docs/bootstrap/index.md

@@ -57,15 +57,15 @@
 The `bootstrap` utilities simplify the initial configuration of your CQRS application. They automatically set up:
 
 - **Dependency Injection Container** — Resolves handlers and their dependencies (see [Dependency Injection](../di.md))
-- **Request Mapping** — Maps commands and queries to their handlers (see [Request Handlers](../request_handler.md))
+- **Request Mapping** — Maps commands and queries to their handlers (see [Request Handlers](../request_handler/index.md))
 - **Event Mapping** — Maps domain events to their handlers (see [Event Handling](../event_handler/index.md))
 - **Saga Mapping** — Maps saga context types to saga classes (see [Saga Pattern](../saga/index.md))
 - **Message Broker** — Configures event publishing (see [Event Producing](../event_producing.md))
 - **Middlewares** — Adds logging and custom middlewares
 - **Event Processing** — Configures parallel event processing
 
 !!! tip "Getting Started"
-    If you're new to `python-cqrs`, start here! Bootstrap is the foundation for all other features. After configuring bootstrap, proceed to [Request Handlers](../request_handler.md) to learn how to create command and query handlers.
+    If you're new to `python-cqrs`, start here! Bootstrap is the foundation for all other features. After configuring bootstrap, proceed to [Request Handlers](../request_handler/index.md) to learn how to create command and query handlers.
 
 !!! note "Navigation"
     Use the navigation menu on the left to explore different mediator types and configuration options. Each section covers a specific aspect of bootstrap configuration.

docs/bootstrap/middlewares.md

@@ -12,7 +12,7 @@
 
     Request pipeline and handler execution where middlewares apply.
 
-    [:octicons-arrow-right-24: Read More](../request_handler.md)
+    [:octicons-arrow-right-24: Read More](../request_handler/index.md)
 
 </div>
 

docs/bootstrap/request_mediator.md

@@ -12,7 +12,7 @@
 
     Commands, queries, handlers, and request/response mapping.
 
-    [:octicons-arrow-right-24: Read More](../request_handler.md)
+    [:octicons-arrow-right-24: Read More](../request_handler/index.md)
 
 </div>
 

docs/chain_of_responsibility/fallback.md

@@ -0,0 +1,144 @@
+# Chain of Responsibility Fallback
+
+<div class="grid cards" markdown>
+
+-   :material-home: **Back to Chain of Responsibility Overview**
+
+    Return to the Chain of Responsibility overview page with all topics.
+
+    [:octicons-arrow-left-24: Back to Overview](index.md)
+
+</div>
+
+---
+
+## Overview
+
+You can combine **Chain of Responsibility** with **Request Handler Fallback**: the primary handler is a `RequestHandler` that delegates to a COR chain; when the chain raises (e.g. downstream failure), the fallback handler is invoked. This is useful when a request is first tried through a chain (e.g. cache → DB → external API) and you want a default/cached response if the whole chain fails.
+
+| Concept | Description |
+|---------|-------------|
+| **Primary** | A `RequestHandler` that runs the COR chain (e.g. injects chain entry via DI) |
+| **Fallback** | A `RequestHandler` used when the chain raises |
+| **Flow** | `mediator.send(request)` dispatches to primary; primary calls the chain; on exception, fallback runs |
+
+!!! tip "When to Use"
+    Use COR + Fallback when you have a chain of strategies (CoR) and a clear fallback path if the entire chain fails (e.g. connection errors to the last handler).
+
+## Registration
+
+Bind the request type to `RequestHandlerFallback` with a **wrapper** handler as primary (the one that runs the chain) and a simple handler as fallback:
+
+```python
+import cqrs
+from cqrs.requests.cor_request_handler import CORRequestHandler, build_chain
+
+def commands_mapper(mapper: cqrs.RequestMap) -> None:
+    mapper.bind(
+        FetchDataCommand,
+        cqrs.RequestHandlerFallback(
+            primary=CORChainWrapperHandler,   # RequestHandler that delegates to chain
+            fallback=FallbackFetchDataHandler,
+            failure_exceptions=(ConnectionError, TimeoutError),
+        ),
+    )
+```
+
+Build the chain and inject the chain entry (first handler) so the wrapper receives it:
+
+```python
+source_a = SourceAHandler()
+source_b = SourceBHandler()
+default = DefaultChainHandler()
+build_chain([source_a, source_b, default])
+
+di_container.bind(
+    di.bind_by_type(
+        dependent.Dependent(lambda: source_a, scope="request"),
+        SourceAHandler,
+    ),
+)
+
+mediator = bootstrap.bootstrap(
+    di_container=di_container,
+    commands_mapper=commands_mapper,
+)
+```
+
+## Wrapper Handler
+
+The primary handler is a normal `RequestHandler` that holds the chain entry and delegates:
+
+```python
+class CORChainWrapperHandler(
+    cqrs.RequestHandler[FetchDataCommand, FetchDataResult],
+):
+    """Primary handler: runs the COR chain; chain entry injected via DI."""
+
+    def __init__(self, chain_entry: SourceAHandler) -> None:
+        self._chain_entry = chain_entry
+
+    @property
+    def events(self) -> list[cqrs.Event]:
+        return []
+
+    async def handle(self, request: FetchDataCommand) -> FetchDataResult:
+        result = await self._chain_entry.handle(request)
+        if result is None:
+            raise ValueError("COR chain did not handle the request")
+        return result
+```
+
+When any handler in the chain raises (e.g. `ConnectionError`), the dispatcher catches it and invokes the fallback handler. Use `failure_exceptions` to restrict fallback to specific exception types.
+
+## Fallback Handler
+
+The fallback is a simple `RequestHandler` that returns a default or cached response:
+
+```python
+class FallbackFetchDataHandler(
+    cqrs.RequestHandler[FetchDataCommand, FetchDataResult],
+):
+    @property
+    def events(self) -> list[cqrs.Event]:
+        return []
+
+    async def handle(self, request: FetchDataCommand) -> FetchDataResult:
+        return FetchDataResult(
+            data="cached_or_default",
+            source="fallback",
+        )
+```
+
+## Circuit Breaker configuration
+
+CoR + Fallback uses `RequestHandlerFallback`, so Circuit Breaker is configured the same way as for [Request Handler Fallback](../request_handler/fallback.md#circuit-breaker-optional).
+
+- **Adapter:** `AioBreakerAdapter` from `cqrs.adapters.circuit_breaker`.
+- **Parameters:** `fail_max` (default `5`), `timeout_duration` (seconds, default `60`), `exclude` (exceptions that do not open the circuit), optional `storage_factory` for distributed state.
+- **One instance per domain** — e.g. one adapter for request fallbacks (including COR wrapper); the adapter creates an isolated circuit per handler type.
+
+Example:
+
+```python
+from cqrs.adapters.circuit_breaker import AioBreakerAdapter
+
+request_cb = AioBreakerAdapter(fail_max=5, timeout_duration=60)
+mapper.bind(
+    FetchDataCommand,
+    cqrs.RequestHandlerFallback(
+        primary=CORChainWrapperHandler,
+        fallback=FallbackFetchDataHandler,
+        failure_exceptions=(ConnectionError, TimeoutError),
+        circuit_breaker=request_cb,
+    ),
+)
+```
+
+Full configuration (exclude, storage_factory, failure_exceptions) is described in [Request Handler Fallback — Circuit Breaker configuration](../request_handler/fallback.md#circuit-breaker-configuration) and [Saga Fallback — Circuit Breaker](../saga/fallback/circuit_breaker.md).
+
+## Related
+
+- [Request Handler Fallback](../request_handler/fallback.md) — Fallback for command/query handlers
+- [Chain of Responsibility Examples](examples.md) — Registering and building COR chains
+- [Saga Fallback Pattern](../saga/fallback/index.md) — Fallback for saga steps

docs/chain_of_responsibility/index.md

@@ -24,6 +24,12 @@ The Chain of Responsibility pattern allows multiple handlers to process a reques
 
     [:octicons-arrow-right-24: Read More](../mermaid/chain_of_responsibility.md)
 
+-   :material-backup-restore: **Fallback**
+
+    Combine CoR with Request Handler Fallback when the chain raises.
+
+    [:octicons-arrow-right-24: Read More](fallback.md)
+
 </div>
 
 `CORRequestHandler` implements the Chain of Responsibility pattern, allowing multiple handlers to process a request sequentially. Each handler decides whether to process the request or pass it to the next handler in the chain. The chain stops when a handler successfully processes the request or when all handlers have been exhausted.
@@ -36,10 +42,10 @@ The Chain of Responsibility pattern allows multiple handlers to process a reques
 - **Easy to extend** — Add new handlers without modifying existing ones
 
 !!! note "Prerequisites"
-    Understanding of [Request Handlers](../request_handler.md) and [Bootstrap](../bootstrap/index.md) is recommended.
+    Understanding of [Request Handlers](../request_handler/index.md) and [Bootstrap](../bootstrap/index.md) is recommended.
 
 !!! tip "When to Use"
-    Use Chain of Responsibility when you have multiple processing strategies or need fallback mechanisms. For standard request handling, use regular [Request Handlers](../request_handler.md).
+    Use Chain of Responsibility when you have multiple processing strategies or need fallback mechanisms. For standard request handling, use regular [Request Handlers](../request_handler/index.md).
 
 ## Pattern Description
 

docs/di.md

@@ -15,7 +15,7 @@ Both libraries allow you to bind implementations to interfaces and automatically
     This section assumes you've already configured [Bootstrap](bootstrap/index.md). The DI container is passed to bootstrap functions to resolve handlers and their dependencies.
 
 !!! tip "Next Steps"
-    After understanding DI, proceed to [Request Handlers](request_handler.md) to learn how handlers use dependency injection.
+    After understanding DI, proceed to [Request Handlers](request_handler/index.md) to learn how handlers use dependency injection.
 
 ## Supported Libraries
 

docs/event_handler/fallback.md

@@ -0,0 +1,146 @@
+# Event Handler Fallback
+
+<div class="grid cards" markdown>
+
+-   :material-home: **Back to Event Handling Overview**
+
+    Return to the Event Handling overview page with all topics.
+
+    [:octicons-arrow-left-24: Back to Overview](index.md)
+
+</div>
+
+---
+
+## Overview
+
+The **Event Handler Fallback** pattern allows you to register an alternative event handler that runs when the primary event handler fails (or when the circuit breaker is open). This provides resilience for side effects such as sending notifications or updating read models when the primary path (e.g. external API) is unavailable.
+
+| Concept | Description |
+|---------|-------------|
+| **Primary handler** | Main event handler that executes first |
+| **Fallback handler** | Alternative handler invoked on primary failure or circuit open |
+| **failure_exceptions** | Optional tuple of exception types that trigger fallback; if empty, any exception |
+| **Circuit Breaker** | Optional; after threshold failures, primary is not called, fallback runs immediately |
+
+!!! tip "When to Use"
+    Use Event Handler Fallback when domain event side effects (notifications, read model updates, integrations) must degrade gracefully: e.g. enqueue for later or log when the primary handler (e.g. external notification API) fails.
+
+## Registration
+
+Bind the event type to `EventHandlerFallback(primary, fallback, ...)` in your domain events mapper:
+
+```python
+import cqrs
+
+def events_mapper(mapper: cqrs.EventMap) -> None:
+    mapper.bind(
+        NotificationSent,
+        cqrs.EventHandlerFallback(
+            primary=PrimaryNotificationSentHandler,
+            fallback=FallbackNotificationSentHandler,
+            failure_exceptions=(ConnectionError, TimeoutError),  # optional
+            circuit_breaker=event_cb,  # optional
+        ),
+    )
+```
+
+- **primary** — The primary event handler class (`EventHandler[EventType]`).
+- **fallback** — The fallback event handler class; must handle the same event type.
+- **failure_exceptions** — If non-empty, only these exception types trigger fallback; otherwise any exception triggers fallback.
+- **circuit_breaker** — Optional `ICircuitBreaker` instance (e.g. `AioBreakerAdapter`). Use one instance per domain (e.g. one for events). When the circuit is open, the primary handler is not called and the fallback runs immediately.
+
+## Basic Example
+
+```python
+class NotificationSent(cqrs.DomainEvent, frozen=True):
+    user_id: str
+    message: str
+
+class PrimaryNotificationSentHandler(cqrs.EventHandler[NotificationSent]):
+    async def handle(self, event: NotificationSent) -> None:
+        # e.g. call external notification API
+        raise RuntimeError("External notification service unavailable")
+
+class FallbackNotificationSentHandler(cqrs.EventHandler[NotificationSent]):
+    async def handle(self, event: NotificationSent) -> None:
+        # e.g. enqueue for later or log
+        logger.info("Enqueue notification for user %s: %s", event.user_id, event.message)
+
+# In events mapper:
+mapper.bind(
+    NotificationSent,
+    cqrs.EventHandlerFallback(
+        primary=PrimaryNotificationSentHandler,
+        fallback=FallbackNotificationSentHandler,
+    ),
+)
+```
+
+When a command handler emits `NotificationSent`, the event emitter runs the primary handler first. On exception (or when the circuit is open), the fallback handler is invoked. Events from the handler that actually ran are collected and processed.
+
+## Circuit Breaker (optional)
+
+To use a circuit breaker with event handlers:
+
+```bash
+pip install aiobreaker
+# or: pip install python-cqrs[aiobreaker]
+```
+
+```python
+from cqrs.adapters.circuit_breaker import AioBreakerAdapter
+
+event_cb = AioBreakerAdapter(fail_max=5, timeout_duration=60)
+mapper.bind(
+    NotificationSent,
+    cqrs.EventHandlerFallback(
+        primary=PrimaryNotificationSentHandler,
+        fallback=FallbackNotificationSentHandler,
+        circuit_breaker=event_cb,
+    ),
+)
+```
+
+After `fail_max` failures, the circuit opens and the fallback runs without calling the primary handler. See [Saga Fallback — Circuit Breaker](../saga/fallback/circuit_breaker.md) for the three-state pattern (CLOSED / OPEN / HALF_OPEN).
+
+### Circuit Breaker configuration
+
+Use the same `AioBreakerAdapter` as for request handlers. Parameters:
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `fail_max` | Number of failures before opening the circuit | `5` |
+| `timeout_duration` | Seconds to wait before attempting HALF_OPEN (retry) | `60` |
+| `exclude` | Exception types that **do not** count as failures (e.g. business/validation errors) | `[]` |
+| `storage_factory` | Factory `(name: str) -> storage` for circuit state; default is in-memory | in-memory |
+
+**Example with `exclude`** — e.g. invalid payload should not open the circuit:
+
+```python
+event_cb = AioBreakerAdapter(
+    fail_max=5,
+    timeout_duration=60,
+    exclude=[ValidationError],  # invalid events don't open the circuit
+)
+mapper.bind(
+    NotificationSent,
+    cqrs.EventHandlerFallback(
+        primary=PrimaryNotificationSentHandler,
+        fallback=FallbackNotificationSentHandler,
+        circuit_breaker=event_cb,
+    ),
+)
+```
+
+**One instance per domain** — use one `AioBreakerAdapter` for all event handler fallbacks that share the same policy. The adapter creates an isolated circuit per handler type.
+
+**Storage:** Default is in-memory. For multiple instances (e.g. several workers), pass a `storage_factory` that returns Redis storage so the circuit state is shared. See [Saga Fallback — Circuit Breaker: Storage Configuration](../saga/fallback/circuit_breaker.md#storage-configuration-memory-vs-redis).
+
+**Failure filtering:** Use `failure_exceptions` on `EventHandlerFallback` to restrict which exceptions trigger fallback; use `exclude` on `AioBreakerAdapter` so certain exceptions do not open the circuit. See [Saga Fallback — Circuit Breaker](../saga/fallback/circuit_breaker.md#failure-exception-filtering).
+
+## Related
+
+- [Request Handler Fallback](../request_handler/fallback.md) — Fallback for command/query handlers
+- [Stream Handling Fallback](../stream_handling/fallback.md) — Fallback for streaming handlers
+- [Saga Fallback Pattern](../saga/fallback/index.md) — Fallback for saga steps

docs/event_handler/index.md

@@ -40,6 +40,12 @@
 
     [:octicons-arrow-right-24: Read More](best_practices.md)
 
+-   :material-backup-restore: **Fallback**
+
+    Fallback handler when primary event handler fails or circuit breaker is open.
+
+    [:octicons-arrow-right-24: Read More](fallback.md)
+
 </div>
 
 Event handlers process domain events that are emitted from command handlers. These events represent something that happened in the domain and trigger side effects like sending notifications, updating read models, or triggering other workflows.
@@ -55,7 +61,7 @@ When a command handler processes a request, it can emit domain events through th
 | **Side Effects** | Event handlers perform side effects without blocking the main command flow |
 
 !!! note "Prerequisites"
-    Understanding of [Request Handlers](../request_handler.md) and [Bootstrap](../bootstrap/index.md) is required. Events are emitted by command handlers and processed by event handlers.
+    Understanding of [Request Handlers](../request_handler/index.md) and [Bootstrap](../bootstrap/index.md) is required. Events are emitted by command handlers and processed by event handlers.
 
 !!! tip "Related Topics"
     - [Transaction Outbox](../outbox/index.md) — For reliable event delivery to message brokers