dio_resilience

Injects Authorization: Bearer <token> (or custom scheme), runs single-flight token refresh on 401, supports multi-account storage, and streams AuthState transitions.

ResiliencePipeline.builder()
  .auth(
    // Use a SEPARATE Dio inside refreshToken — don't recurse through the
    // pipeline you're configuring. Common pattern: a top-level
    // `final _refreshDio = Dio(BaseOptions(baseUrl: 'https://auth.example.com'));`
    refreshToken: (current) async {
      final res = await _refreshDio.post(
        '/token/refresh',
        data: {'refresh_token': current?.refresh},
      );
      return TokenPair(
        access: res.data['access_token'] as String,
        refresh: res.data['refresh_token'] as String,
      );
    },
    tokenStorage: MemoryTokenStorage(),
    scheme: 'Bearer',
    preemptiveRefreshWindow: const Duration(minutes: 1),
    onRefreshFailed: () => navigator.go('/sign-in'),
    isRefreshRequest: (req) => req.path == '/token/refresh',
    shouldRefresh: (err) => err.response?.statusCode == 401,
  )
  .build()
  .attachTo(dio);

Per-call overrides

Auth state stream

pipeline.authStateStream.listen((state) {
  // AuthState.idle | authenticated | refreshing | unauthenticated | forcedLogout
});
await pipeline.signOut();

Throws typed RefreshFailedException (a DioException subtype) when refresh fails terminally; storage is cleared and onRefreshFailed fires.

Local client-side throttle. Token bucket allows bursts; sliding window enforces strict N-per-window. wait mode blocks until a token is available (respecting the pipeline's total budget); fail mode throws immediately.

// Token bucket: 10 req/s steady state, 20-request burst capacity.
ResiliencePipeline.builder()
  .rateLimit(
    algorithm: RateLimitAlgorithm.tokenBucket(ratePerSecond: 10, burst: 20),
    mode: RateLimitMode.wait,
    keyExtractor: (req) => req.uri.host, // default — per-host bucket
  )
  .build();

// Sliding window: at most 5 requests in any rolling 1-second window.
ResiliencePipeline.builder()
  .rateLimit(
    algorithm: RateLimitAlgorithm.slidingWindow(
      requests: 5,
      window: const Duration(seconds: 1),
    ),
    mode: RateLimitMode.fail,
  )
  .build();

Per-call overrides

Throws RateLimitExceededException in fail mode, or in wait mode when the wait would exceed the request's remaining total-timeout budget.

Trips open after failureThreshold failures inside a rolling windowDuration. Stays open for cooldown, then transitions to half-open and lets halfOpenProbes requests through; success closes the circuit, failure reopens it.

ResiliencePipeline.builder()
  .circuitBreaker(
    failureThreshold: 5,
    windowDuration: const Duration(seconds: 60),
    cooldown: const Duration(seconds: 30),
    halfOpenProbes: 1,
    keyExtractor: (req) => req.uri.host, // default — separate breaker per host
  )
  .build();

Per-call overrides

Throws CircuitOpenException (a DioException subtype) when the breaker short-circuits a call. Retry strategy never replays a CircuitOpenException — short-circuited calls are terminal.

Fires up to maxParallel parallel requests with delay between each launch. The first success resolves the call and cancels losers via CancelToken. Defaults to GET/HEAD only — override shouldHedge for idempotent POSTs.

ResiliencePipeline.builder()
  .hedging(
    maxParallel: 2,
    delay: const Duration(milliseconds: 100),
    shouldHedge: (req) => req.method == 'GET',
  )
  .build();

Per-call overrides

A hedging round (all branches) counts as a single attempt for the retry strategy, so retry still fires after a fully-failed hedging round.

ResiliencePipeline.builder()
  .retry(
    maxAttempts: 3,
    backoff: const Backoff.exponentialJitter(
      initial: Duration(milliseconds: 200),
      multiplier: 2.0,
      maxDelay: Duration(seconds: 10),
    ),
    retryOn: const [
      RetryCondition.statusBetween(500, 599),
      RetryCondition.networkError(),
      RetryCondition.timeout(),
    ],
    doNotRetryOn: const [
      RetryCondition.status(409),
    ],
  )
  .build();

Backoff variants: Backoff.constant(d), Backoff.linear(initial, increment), Backoff.exponential(initial, multiplier, maxDelay), Backoff.exponentialJitter(...). Retry-After headers (seconds or HTTP-date) override computed delay.

Per-call overrides

RetryCondition matchers

Combine with .or(...), .and(...), .negated(). Retry never replays DioResilienceException (circuit-open / refresh-failed / pipeline-timeout / rate-limit-exceeded) — those are terminal decisions made by sibling strategies.

ResiliencePipeline.builder()
  .timeout(
    total: const Duration(seconds: 30),
    perAttempt: const Duration(seconds: 10),
  )
  .build();

perAttempt is applied to Dio's per-request connectTimeout / sendTimeout / receiveTimeout (only shortened, never extended). total is enforced by the pipeline across all attempts (initial + retries + auth replays). When the total budget is exceeded, the pipeline raises PipelineTimeoutException from onError — the underlying transport error is replaced with the typed exception so callers can pattern-match the deadline.

Per-call overrides

Walks an ordered handler list on terminal error; first match wins. Runs last in the pipeline, only when no other strategy resolved the call.

ResiliencePipeline.builder()
  .fallback(handlers: [
    // Try a cached/alternate endpoint first when the primary returns 503.
    FallbackHandler.predicate(
      (e) => e.response?.statusCode == 503,
      FallbackHandler.endpoint('/cached/users/me'),
    ),
    // Otherwise return a canned empty payload so the UI keeps rendering.
    FallbackHandler.response((e, req) => Response(
      requestOptions: req,
      statusCode: 200,
      data: const <String, dynamic>{},
    )),
  ])
  .build();

Endpoint fallback re-fires through the same Dio (so other strategies still apply on the alt request) but a guard flag prevents recursive fallback if the alt endpoint also fails.

Per-call overrides