ResilienceBehavior

Defined in: packages/pipeline-resilience/src/resilience.behavior.ts:125

Pipeline behavior that wraps each command / query / event handler in a cockatiel resilience policy — the layers that make sense around a whole handler: retry, timeout and bulkhead.

A circuit breaker and a fallback belong to an outbound dependency, not to a handler: declare them on a named policy (new ResiliencePolicies({ ... })) and use it in the adapter through ResiliencePolicies. The behavior contract rejects them here.

Resolution of the effective options for a handler where this behavior is attached:

Application-wide defaults, the first constructor argument.
Per-handler options from pipeline.wrap(options, [ResilienceBehavior, { ... }]), shallow-merged on top of the defaults (handler keys win).

Policies are built lazily on first invocation and cached per handler, so a stateful layer (bulkhead) correctly shares state across every request to that handler. When no options resolve, the behavior caches that result and passes subsequent invocations directly to next() without constructing or executing a cockatiel policy.

Replay / error-classification safety

A handler-level retry calls next() again, which means the complete downstream pipeline and handler are replayed. To avoid accidental duplicate side effects, command/event retries must explicitly set retry.replaySafe: true. A retry must also define which errors are transient via handle(error), unless the caller intentionally opts into handleAllErrors: true. An aggressive timeout (the default strategy) on a command/event answers the caller while the handler keeps running, so it requires strategy: 'cooperative' or timeout.replaySafe: true.

Timeout and bulkhead-only policies do not require an error classifier because they do not decide which application errors are retryable. A custom pre-built Cockatiel policy also bypasses the declarative safety checks because the caller owns its semantics directly.