RetryConfig class final

The default RetryStrategy: capped exponential backoff with jitter and an idempotency-safe retry decision.

Exponential BackOff Algorithm and Jitter

Simply increasing the wait time exponentially is still not sufficient to distribute retry timing. In addition to simply increasing the interval exponentially, adding a random number called Jitter is effective. This method allows for even greater flexibility in distributing the timing of retries.

import 'package:bluesky/bluesky.dart';

void main() async {
  final bluesky = Bluesky(
    accessJwt: 'YOUR_TOKEN_HERE',
    retryConfig: RetryConfig(
      maxAttempts: 5,
    ),
    timeout: Duration(seconds: 20),
  );
}

The interval, which increases with the number of retries, is then calculated as follows.

(2 ^ (attempt - 1)) + jitter(Random Number between 0 ~ 3)

A server-provided wait (Retry-After / ratelimit-reset) is honored as a lower bound, capped at 60 seconds so a hostile value cannot stall a retry indefinitely.

Idempotency

By default a request with side effects (an XRPC procedure / POST) is not retried after an ambiguous failure—a timeout after the request was sent, or a 5xx—because the server may already have applied it and retrying could duplicate the effect. Queries (GET) and subscriptions are always retried while attempts remain. Set retryProcedureOnAmbiguousFailure to true to restore unconditional retries.

Remarks

Please note that ArgumentError is always raised if a negative number is passed to the maxAttempts field of RetryConfig.

Implemented types

Constructors

RetryConfig({required int maxAttempts, Jitter? jitter, FutureOr<void> onExecute(RetryEvent event)?, bool retryProcedureOnAmbiguousFailure = false})
Returns the new instance of RetryConfig.

Properties

hashCode → int
The hash code for this object.
no setterinherited
jitter → Jitter
The user defined jitter.
final
maxAttempts → int
Maximum number of retry attempts.
final
onExecute → FutureOr<void> Function(RetryEvent event)?
A callback function to be called when the retry is executed.
final
retryProcedureOnAmbiguousFailure → bool
Whether to retry a procedure (POST) even after an ambiguous failure the server may already have processed. Defaults to false (idempotency-safe).
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

nextDelay(RetryContext context) → FutureOr<Duration?>
Returns the delay to wait before the next attempt, or null to stop retrying and let the original error propagate.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited