http library
Sub-library providing robust, enterprise-grade integration between
retry_with_connectivity and http.Client.
Example usage:
final client = RetryHttpClient(
policy: RetryPolicy.aggressive,
httpConfig: HttpRetryConfig.standard,
);
final response = await client.get(Uri.parse('https://api.example.com/data'));
Classes
- BackoffStrategy
- Defines the contract for computing the delay duration before the next retry attempt.
- CancelRetry
- Decision to cancel the ongoing retry process.
- CircuitBreaker
- A stateful resilience component that tracks failures and prevents cascading system outages by fast-failing operations when downstream services are unhealthy.
- CircuitBreakerConfig
- Immutable configuration object defining thresholds and timeouts for a CircuitBreaker.
- CompositeHttpResponseExtractor
- Composes multiple HttpResponseExtractor instances and returns the first valid snapshot extracted.
- CompositeReachabilityChecker
- Composes multiple ReachabilityChecker instances.
- ConnectivityConfig
- Immutable configuration object governing dual-layer connectivity detection and active reachability verification.
- ConnectivityMonitor
- Service responsible for monitoring dual-layer connectivity and notifying listeners when internet access is lost or restored.
- ConnectivityPlusDetector
-
Layer 1 detector implementation using the official
connectivity_plusplugin. - ConnectivityState
- Immutable snapshot representing the current connectivity state of the device.
- CustomBackoff
- A strategy that delegates delay computation to a developer-provided callback.
- CustomReachabilityChecker
- Allows developers to provide custom reachability verification callbacks.
- A strategy implementing Decorrelated Jitter as popularized by AWS and Polly.
- DnsReachabilityChecker
- Verifies reachability by resolving domain names via DNS.
- DuckTypedHttpResponseExtractor
-
A flexible extractor that attempts to extract HTTP metadata by safely checking
common duck-typed properties (
statusCode,headers,method) on any object. - ExponentialBackoff
- A strategy where the delay increases exponentially with the attempt number.
- ExponentialWithJitterBackoff
- A strategy applying exponential backoff with full jitter to prevent retry storms.
- FibonacciBackoff
- A strategy where the delay scales according to the Fibonacci sequence.
- FixedBackoff
- A strategy that applies a constant delay between retry attempts.
- GiveUp
- Decision to stop retrying and propagate the failure.
- HttpHeadReachabilityChecker
- Verifies reachability by making a lightweight HTTP HEAD or GET request to a known status endpoint (e.g., captive portal detection URLs).
- HttpResponseExtractor
-
Contract for extracting framework-agnostic HttpResponseSnapshot details from
third-party HTTP client exceptions (e.g.,
DioException,http.ClientException). - HttpResponseSnapshot
- Snapshot representing critical HTTP response metadata extracted from a client-specific error or response object.
- HttpRetryCondition
- Factory and utilities for building framework-agnostic HTTP RetryCondition instances.
- HttpRetryConfig
-
Immutable configuration object governing intelligent HTTP retry behaviors,
status code filtering, and
Retry-Afterheader handling. - HttpRetryDecisionEngine
-
Factory for building a RetryDecisionEngine that inspects HTTP status codes and
Retry-Afterheaders. - InMemoryOfflineQueue
- A fast, thread-safe, in-memory implementation of OfflineQueue.
- LinearBackoff
- A strategy where the delay increases linearly with the attempt number.
- NetworkInterfaceDetector
- Contract for detecting available network interfaces (Layer 1 of dual-layer reachability).
- OfflineQueue
- Defines the storage and manipulation contract for an offline retry queue.
- PackageHttpResponseExtractor
-
An HttpResponseExtractor specialized for extracting HTTP metadata from
HttpRetryResponseException or
http.ClientException. -
QueuedTask<
T> - Represents an asynchronous operation stored in an OfflineQueue awaiting execution.
- QueueProcessingSummary
- Summary report returned after completing a queue processing cycle.
- QueueProcessor
- Automates the processing and replay of tasks stored in an OfflineQueue.
- ReachabilityChecker
- Contract for verifying actual internet reachability beyond network interface checks.
- ReachabilityResult
- Result of an active reachability check (Layer 2).
- RespectRetryAfter
-
Decision to wait according to a server-specified
Retry-Afterduration. - RetryAfterDelay
- Decision to retry after a computed delay.
- RetryAfterParser
-
Utility parser for the HTTP
Retry-Afterresponse header according to RFC 7231 (Section 7.1.3). -
RetryCallbacks<
T> - Lifecycle callbacks triggered during various stages of retry execution.
- RetryConditions
- Built-in factory methods for common RetryCondition implementations.
- RetryContext
- Runtime metadata and context associated with an ongoing retry execution.
- RetryDecision
- Represents the decision made by a RetryCondition or decision engine after an operation fails.
-
RetryExecutor<
T> - The core execution engine responsible for executing tasks with retry, backoff, timeout, and cancellation semantics.
-
RetryFailure<
T> - Represents an unsuccessful outcome after retrying stopped or was exhausted.
- RetryHttpClient
-
A drop-in replacement for
http.Clientthat transparently wraps an inner client with intelligent retry, backoff, and dual-layer connectivity resilience. - RetryLogger
- Defines the logging contract for observing internal retry events.
- RetryNow
- Decision to retry immediately without delay.
- RetryPolicy
- Immutable configuration object defining the rules and behavior of retries.
-
RetryResult<
T> - Sealed result hierarchy representing the outcome of a retry execution.
-
RetrySuccess<
T> - Represents a successful outcome from the retry engine.
- RetryToken
- A token used to cancel ongoing retry operations.
- SmartRetry
- Static facade providing simple and ergonomic entry points into the execution framework.
- SocketReachabilityChecker
- Verifies reachability by establishing a TCP socket connection to a target host and port.
- WaitForConnectivity
- Decision to wait for network/internet connectivity to be restored before resuming.
Enums
- CircuitState
- Represents the operating states of a CircuitBreaker.
- ConnectivityStatus
- The primary status of network and internet connectivity.
- FailureReason
- Represents the reason why retrying terminated unsuccessfully.
- NetworkInterfaceType
- Types of network interfaces available on the device.
Typedefs
-
ConnectivityWaiter
= Future<
bool> Function(RetryContext context, RetryToken? token, RetryCallbacks? callbacks) - Function signature for waiting until connectivity is restored.
- CustomBackoffCalculator = Duration Function(int attemptNumber, Duration baseDelay, Duration? previousDelay)
- Function signature for computing custom backoff delay durations.
-
RetryCondition
= FutureOr<
bool> Function(Object error, RetryContext context) - A function signature for evaluating whether an error should trigger a retry.
-
RetryDecisionEngine
= FutureOr<
RetryDecision?> Function(Object error, RetryContext context) - A function signature for rich decision engines that return a RetryDecision directly rather than a boolean.
Exceptions / Errors
- CircuitOpenException
- Exception thrown when an operation is attempted while the CircuitBreaker is in CircuitState.open or saturated CircuitState.halfOpen.
- HttpRetryResponseException
-
Internal exception used by RetryHttpClient to trigger retry loop when a retryable
HTTP status code is received in a
http.StreamedResponse. - RetryCancelledException
- Exception thrown when a retry operation is cancelled via RetryToken.