feat: add regular poll for session token [CLERK_SDK #42] (#43) (#48)

* feat: add regular poll for session token [CLERK_SDK #42]

* feat: add poll mode configuration to clerk_flutter [CLERK_SDK #42]

* fix: pr changes

---------

Co-authored-by: Nic Ford <[email protected]>

Author: slightfoot

packages/clerk_auth/.pubignore

@@ -11,3 +11,6 @@ build/
 
 # Dont need to package this
 build.yaml
+
+# Test environment
+.env.test

packages/clerk_auth/lib/src/clerk_api/api.dart

@@ -8,30 +8,53 @@ import 'package:http/http.dart' as http;
 
 export 'package:clerk_auth/src/models/models.dart';
 
+/// [SessionTokenPollMode] manages how to refresh the [sessionToken]
+///
+enum SessionTokenPollMode {
+  /// Refresh whenever token expires (more http access and power use)
+  regular,
+
+  /// Refresh if expired when accessed (with possible increased latency at that time)
+  onDemand;
+}
+
 /// [Api] manages communication with the Clerk frontend API
 ///
 class Api with Logging {
-  Api._(this._tokenCache, this._domain, this._client);
+  Api._(this._tokenCache, this._domain, this._client, this._pollMode);
 
   /// Create an [Api] object for a given public key, or return the existing one
   /// if such already exists for that key. Requires a [publicKey] and [publishableKey]
-  /// found in the Clerk dashboard for you account. Can also take an optional http [client]
-  /// and [persistor]
+  /// found in the Clerk dashboard for you account. Additional arguments:
+  ///
+  /// [persistor]: an optional instance of a [Persistor] which will keep track of
+  /// tokens and expiry between app activations
+  ///
+  /// [client]: an optional instance of [HttpClient] to manage low-level communications
+  /// with the back end. Injected for e.g. test mocking
+  ///
+  /// [pollMode]: session token poll mode, default on-demand,
+  /// manages how to refresh the [sessionToken].
+  ///
   factory Api({
     required String publishableKey,
     required String publicKey,
+    Persistor persistor = Persistor.none,
+    SessionTokenPollMode pollMode = SessionTokenPollMode.onDemand,
     HttpClient? client,
-    Persistor? persistor,
   }) =>
       _caches[publicKey] ??= Api._(
         TokenCache(publicKey, persistor),
         _deriveDomainFrom(publishableKey),
-        client ?? DefaultHttpClient(),
+        client ?? const DefaultHttpClient(),
+        pollMode,
       );
 
   final TokenCache _tokenCache;
   final String _domain;
   final HttpClient _client;
+  final SessionTokenPollMode _pollMode;
+  Timer? _pollTimer;
 
   static final _caches = <String, Api>{};
 
@@ -44,6 +67,19 @@ class Api with Logging {
   static const _kClientKey = 'client';
   static const _kResponseKey = 'response';
 
+  /// Initialise the API
+  Future<void> initialize() async {
+    await _tokenCache.initialize();
+    if (_pollMode == SessionTokenPollMode.regular) {
+      await _pollForSessionToken();
+    }
+  }
+
+  /// Dispose of the API
+  void terminate() {
+    _pollTimer?.cancel();
+  }
+
   // environment & client
 
   /// the domain of the Clerk front-end API server
@@ -453,6 +489,16 @@ class Api with Logging {
     return _tokenCache.sessionToken;
   }
 
+  Future<void> _pollForSessionToken() async {
+    _pollTimer?.cancel();
+
+    await sessionToken(); // make sure updated
+
+    final diff = _tokenCache.sessionTokenExpiry.difference(DateTime.now());
+    final delay = diff.isNegative ? const Duration(seconds: 55) : diff;
+    _pollTimer = Timer(delay, _pollForSessionToken);
+  }
+
   // Internal
 
   Future<ApiResponse> _fetchApiResponse(

packages/clerk_auth/lib/src/clerk_api/token_cache.dart

@@ -13,12 +13,16 @@ import 'package:logging/logging.dart';
 class TokenCache {
   /// Create a [TokenCache] instance
   ///
-  TokenCache(this._publicKey, this._persistor) {
-    _init();
-  }
+  TokenCache(this._publicKey, this._persistor);
 
   final String _publicKey;
-  final Persistor? _persistor;
+  final Persistor _persistor;
+
+  DateTime _sessionTokenExpiry = DateTime.fromMillisecondsSinceEpoch(0);
+
+  /// the date at which, if in the future, the current [sessionToken]
+  /// is due to expire
+  DateTime get sessionTokenExpiry => _sessionTokenExpiry;
 
   static const _tokenExpiryBuffer = Duration(seconds: 10);
 
@@ -28,14 +32,13 @@ class TokenCache {
   String _sessionId = '';
   String _clientToken = '';
   String _sessionToken = '';
-  DateTime _sessionTokenExpiry = DateTime.fromMillisecondsSinceEpoch(0);
 
   /// Whether or not the [sessionToken] can be refreshed
   bool get canRefreshSessionToken =>
       clientToken.isNotEmpty && sessionId.isNotEmpty;
 
   bool get _sessionTokenHasExpired =>
-      DateTime.now().isAfter(_sessionTokenExpiry);
+      DateTime.now().isAfter(sessionTokenExpiry);
 
   String get _sessionIdKey => '_clerkSessionId_${_publicKey.hashCode}';
 
@@ -53,19 +56,23 @@ class TokenCache {
         _clientTokenKey,
       ];
 
-  Future<void> _init() async {
+  /// Initialise the cache
+  Future<void> initialize() async {
     _rsaKey = RSAPublicKey(_publicKey);
-    if (_persistor case Persistor persistor) {
-      final [sessionId, sessionToken, ms, clientToken] = await Future.wait(
-        _persistorKeys.map(persistor.read),
-      );
-
-      _sessionId = sessionId ?? '';
-      _sessionToken = sessionToken ?? '';
-      _clientToken = clientToken ?? '';
-      _sessionTokenExpiry =
-          DateTime.fromMillisecondsSinceEpoch(int.tryParse(ms ?? '') ?? 0);
-    }
+
+    // Read all stored variables first before assignment
+    final sessionId = await _persistor.read(_sessionIdKey) ?? '';
+    final sessionToken = await _persistor.read(_sessionTokenKey) ?? '';
+    final clientToken = await _persistor.read(_clientTokenKey) ?? '';
+    final milliseconds = await _persistor.read(_sessionTokenExpiryKey) ?? '';
+    final sessionTokenExpiry = DateTime.fromMillisecondsSinceEpoch(
+      int.tryParse(milliseconds) ?? 0,
+    );
+
+    _sessionId = sessionId;
+    _sessionToken = sessionToken;
+    _clientToken = clientToken;
+    _sessionTokenExpiry = sessionTokenExpiry;
   }
 
   /// Reset the [TokenCache]
@@ -76,7 +83,7 @@ class TokenCache {
     _sessionToken = '';
     _sessionTokenExpiry = DateTime.fromMillisecondsSinceEpoch(0);
     for (final key in _persistorKeys) {
-      _persistor?.delete(key);
+      _persistor.delete(key);
     }
   }
 
@@ -86,7 +93,7 @@ class TokenCache {
   /// Set the [sessionId]
   set sessionId(String id) {
     _sessionId = id;
-    _persistor?.write(_sessionIdKey, id);
+    _persistor.write(_sessionIdKey, id);
   }
 
   /// Get the [clientToken]
@@ -99,7 +106,7 @@ class TokenCache {
     try {
       JWT.verify(token, _rsaKey);
       _clientToken = token;
-      _persistor?.write(_clientTokenKey, token);
+      _persistor.write(_clientTokenKey, token);
     } catch (error, stackTrace) {
       _logger.severe('ERROR SETTING CLIENT TOKEN: $error', error, stackTrace);
     }
@@ -117,15 +124,16 @@ class TokenCache {
 
     try {
       final jwt = JWT.verify(token, _rsaKey);
-      final exp = jwt.payload['exp'];
-      if (exp is int) {
-        final expiry = DateTime.fromMillisecondsSinceEpoch(exp * 1000);
+      final expirySeconds = jwt.payload['exp'];
+      if (expirySeconds is int) {
+        final expiry = DateTime.fromMillisecondsSinceEpoch(
+            expirySeconds * Duration.millisecondsPerSecond);
         _sessionTokenExpiry = expiry.subtract(_tokenExpiryBuffer);
         _sessionToken = token;
-        _persistor?.write(_sessionTokenKey, token);
-        _persistor?.write(
+        _persistor.write(_sessionTokenKey, token);
+        _persistor.write(
           _sessionTokenExpiryKey,
-          _sessionTokenExpiry.millisecondsSinceEpoch.toString(),
+          sessionTokenExpiry.millisecondsSinceEpoch.toString(),
         );
       }
     } catch (error, _) {

packages/clerk_auth/lib/src/clerk_auth/auth.dart

@@ -8,18 +8,32 @@ export 'persistor.dart';
 
 /// [Auth] provides more abstracted access to the Clerk API
 ///
+/// Requires a [publicKey] and [publishableKey] found in the Clerk dashboard
+/// for you account. Additional arguments:
+///
+/// [persistor]: an optional instance of a [Persistor] which will keep track of
+/// tokens and expiry between app activations
+///
+/// [client]: an optional instance of [HttpClient] to manage low-level communications
+/// with the back end. Injected for e.g. test mocking
+///
+/// [pollMode]: session token poll mode, default on-demand,
+/// manages how to refresh the [sessionToken].
+///
 class Auth {
   /// Create an [Auth] object using appropriate Clerk credentials
   Auth({
-    required String publishableKey,
     required String publicKey,
-    Persistor? persistor,
+    required String publishableKey,
+    required Persistor persistor,
     HttpClient? client,
+    SessionTokenPollMode pollMode = SessionTokenPollMode.onDemand,
   }) : _api = Api(
           publicKey: publicKey,
           publishableKey: publishableKey,
           persistor: persistor,
           client: client,
+          pollMode: pollMode,
         );
 
   final Api _api;
@@ -64,12 +78,26 @@ class Auth {
 
   /// Initialisation of the [Auth] object
   ///
-  /// [init] must be called before any further use of the [Auth]
+  /// [initialize] must be called before any further use of the [Auth]
   /// object is made
   ///
-  Future<void> init() async {
-    client = await _api.createClient();
-    env = await _api.environment();
+  Future<void> initialize() async {
+    await _api.initialize();
+    final [client, env] = await Future.wait([
+      _api.createClient(),
+      _api.environment(),
+    ]);
+    this.client = client as Client;
+    this.env = env as Environment;
+  }
+
+  /// Disposal of the [Auth] object
+  ///
+  /// Named [terminate] so as not to clash with [ChangeNotifier]'s [dispose]
+  /// method, if that is mixed in e.g. in clerk_flutter
+  ///
+  void terminate() {
+    _api.terminate();
   }
 
   /// Refresh the current [Client]
@@ -147,7 +175,7 @@ class Auth {
     switch (client.signIn) {
       case SignIn signIn when strategy.isOauth == true && token is String:
         await _api
-            .sendOauthToken(signIn, strategy: strategy!, token: token)
+            .sendOauthToken(signIn, strategy: strategy, token: token)
             .then(_housekeeping);
 
       case SignIn signIn
@@ -191,7 +219,7 @@ class Auth {
         final stage = Stage.forStatus(signIn.status);
         if (signIn.verificationFor(stage) is! Verification) {
           await _api
-              .prepareSignIn(signIn, stage: stage, strategy: strategy!)
+              .prepareSignIn(signIn, stage: stage, strategy: strategy)
               .then(_housekeeping);
         }
         if (client.signIn case SignIn signIn

packages/clerk_auth/lib/src/clerk_auth/http_client.dart

@@ -32,6 +32,9 @@ enum HttpMethod {
 /// Clerk back-end over http
 ///
 abstract class HttpClient {
+  /// Constructor
+  const HttpClient();
+
   /// [send] date to the back end, and receive a [Response]
   ///
   Future<Response> send(
@@ -45,6 +48,9 @@ abstract class HttpClient {
 /// Default implementation of [HttpClient]
 ///
 class DefaultHttpClient implements HttpClient {
+  /// Constructor
+  const DefaultHttpClient();
+
   @override
   Future<Response> send(
     HttpMethod method,

packages/clerk_auth/lib/src/clerk_auth/persistor.dart

@@ -2,6 +2,9 @@
 /// required to allow seamless auth across app runs
 ///
 abstract class Persistor {
+  /// Persistor used when no persistence is required
+  static const none = _NonePersistor();
+
   /// Persist a [value] against a [key]
   ///
   Future<void> write(String key, String value);
@@ -14,3 +17,16 @@ abstract class Persistor {
   ///
   Future<void> delete(String key);
 }
+
+final class _NonePersistor implements Persistor {
+  const _NonePersistor();
+
+  @override
+  Future<void> write(String key, String value) async {}
+
+  @override
+  Future<String?> read(String key) => Future.value(null);
+
+  @override
+  Future<void> delete(String key) async {}
+}

packages/clerk_auth/lib/src/models/api_response.dart

@@ -4,6 +4,7 @@ import 'models.dart';
 
 /// [ApiResponse] holds parsed Clerk data from a back-end http response
 class ApiResponse {
+  /// Constructs an instance of [ApiResponse]
   const ApiResponse({
     required this.status,
     this.errors,

packages/clerk_auth/lib/src/models/environment/auth_config.dart

@@ -62,6 +62,7 @@ class AuthConfig {
   @JsonKey(fromJson: toStrategyList)
   final List<Strategy> secondFactors;
 
+  /// email address verification strategy
   @JsonKey(fromJson: toStrategyList)
   final List<Strategy> emailAddressVerificationStrategies;
 

packages/clerk_auth/lib/src/models/environment/display_config.dart

@@ -2,8 +2,11 @@ import 'package:json_annotation/json_annotation.dart';
 
 part 'display_config.g.dart';
 
+/// Display Configuration
+///
 @JsonSerializable()
 class DisplayConfig {
+  /// Constructs an instance of [DisplayConfig]
   const DisplayConfig({
     this.id = '',
     this.applicationName = '',

packages/clerk_auth/lib/src/models/environment/user_settings.dart

@@ -77,8 +77,9 @@ Map<UserAttribute, UserAttributeData> _toAttributeMap(dynamic data) {
     for (final entry in data.entries) {
       final key = UserAttribute.values
           .firstWhereOrNull((a) => a.toString() == entry.key);
-      if (key case UserAttribute key)
+      if (key case UserAttribute key) {
         result[key] = UserAttributeData.fromJson(entry.value);
+      }
     }
   }
   return result;