Resilience Patterns

Retry transient failures with a configurable backoff strategy. Three flavors: Retry (transient-only via xerr.IsTransient), RetryIf (custom predicate), RetryAll (any non-nil error — idempotent jobs only).

Four backoff functions passed to Retry / RetryIf / RetryAll. Constant, Linear, Exponential, and Exponential Jitter (the default for SmartResilience, with ±30% crypto-rand jitter to prevent thundering herd).

Token-bucket admission control built on golang.org/x/time/rate. Three flavors: global limiter, per-key LRU-bounded limiter (per-tenant or per-user), and distributed limiter (Redis/etcd via your own implementation).

Lock-free atomic-counter ceiling. Rejects excess calls with ErrConcurrencyLimit before any retry or circuit-breaker logic runs. Use to protect handlers from being overwhelmed by their own callers.

Idempotency-Key contract: claim → execute → complete/release with leased in-progress locks and SHA-256 request-hash validation. Concurrent identical requests collapse into a single execution; reused keys with different payloads return Conflict (not silent replay).

Execute an action concurrently for each item in a slice, preserving input order in the returned slice. Bounded concurrency via semaphore channel. Respects context cancellation for both launch and result collection.

Read-through cache with singleflight stampede protection and automatic L1 back-fill on L2 hits. Layers are checked in order: L1 (fast, local) → L2 (shared, e.g. Redis). On miss, the handler runs once and the result is written to all layers.

Per-action request deduplication. Concurrent identical requests collapse into a single execution; all waiters share the result. Cancellation of a waiter cancels the in-flight call (contrast with Coalesce).

Cross-action request coalescing via a shared *Coalescer. Identical to Dedup but: (1) one coalescer can span multiple actions, (2) a canceled waiter exits cleanly while the in-flight call KEEPS RUNNING for other waiters.

Auto-wired composite: circuit breaker + exponential jitter retry driven entirely by xerr.Kind. Fast-fails 4xx without consuming retries. Use InferredResilient() for zero-config sensible defaults.

Distributed lock with monotonically increasing fence counter. Background goroutine renews the lease at ttl/3; if renewal fails, the action context is canceled immediately to abort in-flight work. The handler can retrieve the lease and pass the fence to downstream storage.

Distributed-transaction coordinator with LIFO compensating rollback. Each step has Do + Undo. If a mandatory step fails, all prior Undo functions run in reverse order under an uncanceled context. Optional steps may fail without aborting the saga.

Three-state circuit breaker: Closed → Open (after FailureThreshold consecutive failures) → Half-Open (after ResetTimeout, one probe allowed) → Closed (on success). Dynamic timeout scaling. Never trips on permanent 4xx errors.

Priority-tiered load shedding based on live system stats (CPU percentage + goroutine count). Lower-priority traffic is dropped earlier than critical traffic. The server actively sheds load to preserve stability instead of failing slowly.

Hedged execution: run N variants concurrently, the first success wins, losing attempts are cancelled. If all fail, returns the last error. Useful for hedged requests against read replicas or multi-region endpoints.

Entity lifecycle transition guard. The middleware runs AFTER the handler — handlers don't need to know the rules. If the handler mutates state to an invalid transition, the middleware rolls back the mutation before returning xerr.Conflict.