@cqrs-ddd/pipeline-resilience
Fault tolerance and reliability policies built on cockatiel, applied at two distinct architectural levels:
- Operation-Level Resilience (
ResilienceBehavior): Wraps whole handlers or operations with retry, timeout, and bulkhead isolation. - Outbound Dependency Policies (
ResiliencePolicies): A centralized registry of named resilience policies (circuit breakers, retry, bulkhead, timeout, fallback) applied around outbound RPC calls, payment APIs, database queries, and third-party webhooks.
Enforces strict compile- and startup-time invariants to prevent dangerous side-effect replays.
Installation
Section titled “Installation”Requires Node.js 22.12 or later. cockatiel 4 comes as a dependency.
Two Architectural Scopes
Section titled “Two Architectural Scopes”Operation-Level Usage (ResilienceBehavior)
Section titled “Operation-Level Usage (ResilienceBehavior)”Safety Invariants & Diagnostics
Section titled “Safety Invariants & Diagnostics”Because retries re-execute everything inside the behavior, ResilienceBehavior validates strict safety rules:
- Selective Failure Filter (
handle): Retries require an explicithandle: (error) => booleanpredicate selecting transient errors (network drops, deadlocks). To intentionally retry all errors, sethandleAllErrors: true. - Replay Safety on Commands/Events (
retry.replaySafe): Commands and events mutate state. Attempting to configure retries on a command without explicitly settingretry: { replaySafe: true }fails at startup withPipelineConfigurationError. - Timeout Strategy & Safety (
timeout.strategy):'aggressive'(default): Immediately answers the caller with a timeout rejection while the underlying handler continues running in the background. On commands or events, requirestimeout: { replaySafe: true }.'cooperative': Aborts theAbortSignalreturned bygetResilienceAbortSignal()and waits for the handler to settle before answering.
- No Circuit Breakers on Use Cases: Declaring a circuit breaker directly on an operation handler is rejected. Circuit breakers track external dependency health, not domain use cases; declare them on
ResiliencePolicies.
Outbound Dependency Policies (ResiliencePolicies)
Section titled “Outbound Dependency Policies (ResiliencePolicies)”Create a shared registry of named policies for downstream external systems:
All callers across all handlers share the same circuit breaker state for 'paymentGateway', protecting downstream APIs from cascading failures.
NestJS Integration (@cqrs-ddd/nestjs)
Section titled “NestJS Integration (@cqrs-ddd/nestjs)”Provide ResiliencePolicies as an injectable service:
Decorate @CommandHandler with resilience():
Layer Ordering
Section titled “Layer Ordering”ResilienceBehavior composes policies in the following default order (outermost to innermost):
Customize the execution order via order:
Error Types & Guards
Section titled “Error Types & Guards”Re-exports Cockatiel error classes and predicate guards:
BrokenCircuitError/isBrokenCircuitError(err): Thrown when a remote call is blocked by an open circuit breaker.BulkheadRejectedError/isBulkheadRejectedError(err): Thrown when concurrency limits and queue capacity are exhausted.TaskCancelledError/isTaskCancelledError(err): Thrown when execution exceeds configured timeout.