Resilience

Titan ships a small set of resilience primitives in @omnitron-dev/titan/utils. They are functions and classes, not decorators — designed to be composed inside your service methods at the call boundary.

Primitive	What it does	Page
computeBackoff	Compute delay between attempts	shared in Retry
retry()	Re-attempt a failed operation	Retry
CircuitBreaker class	Stop calling a backend after failures	Circuit Breaker
withTimeout()	Abandon a call that takes too long	Timeout
FailureTracker	Sliding-window error counting	source: utils/failure-tracker.ts
ResilientHandle	Self-healing cached handle to a flaky external resource (auto-recreate on fatal error)	source: utils/resilience.ts

There is also a @Retry decorator in @omnitron-dev/titan/decorators for simple fixed-delay retry on a method — but it is intentionally minimal (no exponential backoff, no classifier). For sophisticated resilience, use the primitives from utils/.

When you need each

• Retry — for transient failures: network errors, 503s, timeouts. Use isOperationalError(e) to classify.
• Circuit breaker — when retrying a failing dependency makes the problem worse. Open the circuit; let it cool down.
• Timeout — for any external call. A call without a timeout can hang forever, taking a request slot with it.
• FailureTracker — when you need a sliding-window error count for custom logic (e.g. dynamic throttling based on recent error rate).

These compose. A typical "outbound call" pattern:

• Timeout outermost — even retries shouldn't extend the deadline.
• Circuit breaker next — if open, fail fast (no retries).
• Retry — re-attempt on transient failures.

Compose the primitives directly (as in the example below). Note that ResilientHandle is not a retry+breaker+timeout bundle — it is a self-healing cache for a single external resource (a Redis client, the esbuild sidecar, a gRPC channel) that recreates the instance via a factory when a call throws a fatal error. See utils/resilience.ts for its API.

The minimal example

import { retry, withTimeout, CircuitBreaker } from '@omnitron-dev/titan/utils';

@Service({ name: 'Payments' })
class PaymentsService {
  private readonly stripeBreaker = new CircuitBreaker({
    failureThreshold: 5,
    resetTimeout:     60_000,   // ms in Open before a probe
  });

  @Public()
  async charge(req: ChargeRequest) {
    // withTimeout takes a Promise (not a thunk) and a number of ms
    // (or { timeout, errorMessage }).
    return withTimeout(
      this.stripeBreaker.execute(() =>
        retry(() => this.stripe.charge(req), { maxRetries: 3 })
      ),
      5_000,
    );
  }
}

Read on

• Retry — backoff strategies, the retry() function, the @Retry decorator.
• Circuit Breaker — CircuitBreaker class semantics.
• Timeout — withTimeout(), abort signals.

→ Next: Retry.