smart_refresh_token 0.2.0
smart_refresh_token: ^0.2.0 copied to clipboard
Race-free automatic access/refresh token handling for Dio. Single-flight refresh, request replay, proactive JWT expiry refresh, logout-safe, and pluggable secure storage on every platform.
0.2.0 - 2026-11-10 #
A rewrite of the refresh engine focused on correctness under concurrency. Breaking: see "Migrating from 0.1.x" in the README.
Fixed #
- Concurrent 401s triggered one refresh per request (serialised by a lock); now exactly one refresh runs and all waiting requests share its result.
- A request sent with an old token after a refresh had already finished triggered another refresh; it is now just replayed with the current token.
- Any refresh error (offline, timeout, 5xx) deleted the tokens and logged the
user out; only a rejected refresh token (400/401/403,
null,InvalidRefreshTokenException) ends the session now. - Passing the intercepted Dio as
refreshDiodeadlocked until the refresh timeout; refresher requests now bypass the interceptor automatically. - Logout during a refresh could be undone when the refresh completed.
- Retries used a brand-new
Dio(), losing the app's adapter, interceptors and certificate pinning; replays now go through the same Dio. - Requests made while logged out were rejected with a misleading
cancelerror and calledonAuthFailureevery time. import 'dart:io'broke Flutter web; the package now has nodart:io.- The refresh timeout timer leaked, and a late refresh result after a timeout was lost (fatal with refresh-token rotation); it is now adopted.
RetryConfigretried non-idempotent requests (e.g. POST) and kept retrying after cancellation;RetryPolicyignored itsshouldRetryargument.- A
FormDatabody could not be replayed. Credentials.toString()printed the first 10 characters of each token.refreshHeaderspermanently mutated the user'srefreshDio.- A failing
TokenStorage.writeafter a refresh lost the new tokens.
Added #
authStatusstream (AuthStatus.unknown/authenticated/unauthenticated) forStreamBuilder, pluscurrentAuthStatusandisRefreshing.setCredentials,validCredentials,refreshIfNeeded,dispose.TokenRefreshLifecycleObserver: refresh on app resume.Credentials.fromOAuthJson(RFC 6749 responses, rotation-aware),tokenType, JWTexpfallback (expiresAt),accessTokenClaims, nullablerefreshTokenfor cookie-based refresh.Jwt.tryDecodeClaims/Jwt.tryReadExpiry.RefreshConfig.isAuthFailure,isRefreshTokenRejected,headerBuilder.RefreshTokenExceptionwithRefreshFailureType,isSessionEnded,isTransient;InvalidRefreshTokenException.Options().skipAuth()extension.- Cancellation support while waiting for a refresh.
RetryConfig.retryableMethods,RetryConfig.none().- Logger
outputsink;clockinjection for tests. - Platforms declared in pubspec; 67 tests including concurrency and race tests.
Changed #
RefreshTokenInterceptorrequiresdio;tokenStorage(in-memory default) andonAuthFailureare optional.TokenRefresheris now(Credentials current, Dio client).OnAuthFailurereceives theRefreshTokenException.- Default
expirationBufferis 1 minute (capped at half a token's lifetime); default header key isAuthorization. - Network retries are opt-in.
- Removed
parallelRefresh,refreshHeaders,enableLogging,retryDio,RetryPolicy,TokenStorage.hasCredentials. - Dropped the
synchronizedandequatabledependencies. - Minimum SDK lowered to Dart 3.5 / Flutter 3.24.
0.1.2 - 2026-07-01 #
- Updated to latest Flutter and Dart versions.
- Upgraded dependencies:
dio,synchronized,equatable. - Exported
logger.dartfor public use. - Fixed various linting issues and improved code quality.
0.1.1 - 2026-02-20 #
- Compatible with latest Dart version
0.1.0 - 2026-02-05 #
Added #
- Added
InMemoryTokenStoragefor quick starts and tests. - Added
RefreshTokenInterceptor.skipAuthKeysupport to bypass auth injection/refresh for public endpoints. - Added
retryDiooption so retries can use a dedicated Dio instance.
Improved #
- Improved refresh lock behavior:
parallelRefreshnow controls whether requests share the refresh lock. - Improved retry delay calculation to true exponential backoff with optional jitter.
- Safer
Credentials.toString()for short token strings.
Fixed #
- Fixed README/API mismatch for refresh configuration and skip-auth usage.
- Fixed metadata parsing in
Credentials.fromJsonfor loosely typed maps.
0.0.3 - 2025-11-27 #
Added #
- Dynamic retry logic (configurable backoff, max attempts).
- Comprehensive examples demonstrating refresh + retry flows.
- New
RetryConfigfor runtime retry customization.
Improved #
- More stable token refresh interceptor.
- Clearer documentation and example structure.
Fixed #
- Missing platform folders in example project.