Add configuration for how eagerly to refresh auth tokens (#30588)

I would like this to be configurable so some things like Next.js + Convex Auth can refresh more eagerly than the default.

I made it so that if the configured period is shorter than the token lifetime, we'll just refetch immediately, but we'll log a warning since repeatedly fetching immediately is probably a misconfiguration.

GitOrigin-RevId: 10a9efbeaac3f91ef75f42923ce126e8730eeb41

Author: sshader

src/browser/sync/authentication_manager.ts

@@ -91,35 +91,31 @@ export class AuthenticationManager {
   // Passed down by BaseClient, sends a message to the server
   private readonly clearAuth: () => void;
   private readonly logger: Logger;
-
+  private readonly refreshTokenLeewaySeconds: number;
   constructor(
     syncState: LocalSyncState,
-    {
-      authenticate,
-      stopSocket,
-      restartSocket,
-      pauseSocket,
-      resumeSocket,
-      clearAuth,
-      logger,
-    }: {
+    callbacks: {
       authenticate: (token: string) => void;
       stopSocket: () => Promise<void>;
       restartSocket: () => void;
       pauseSocket: () => void;
       resumeSocket: () => void;
       clearAuth: () => void;
+    },
+    config: {
+      refreshTokenLeewaySeconds: number;
       logger: Logger;
     },
   ) {
     this.syncState = syncState;
-    this.authenticate = authenticate;
-    this.stopSocket = stopSocket;
-    this.restartSocket = restartSocket;
-    this.pauseSocket = pauseSocket;
-    this.resumeSocket = resumeSocket;
-    this.clearAuth = clearAuth;
-    this.logger = logger;
+    this.authenticate = callbacks.authenticate;
+    this.stopSocket = callbacks.stopSocket;
+    this.restartSocket = callbacks.restartSocket;
+    this.pauseSocket = callbacks.pauseSocket;
+    this.resumeSocket = callbacks.resumeSocket;
+    this.clearAuth = callbacks.clearAuth;
+    this.logger = config.logger;
+    this.refreshTokenLeewaySeconds = config.refreshTokenLeewaySeconds;
   }
 
   async setConfig(
@@ -331,21 +327,31 @@ export class AuthenticationManager {
       );
       return;
     }
-    const leewaySeconds = 2;
     // Because the client and server clocks may be out of sync,
     // we only know that the token will expire after `exp - iat`,
     // and since we just fetched a fresh one we know when that
     // will happen.
-    const delay = Math.min(
-      MAXIMUM_REFRESH_DELAY,
-      (exp - iat - leewaySeconds) * 1000,
-    );
-    if (delay <= 0) {
+    const tokenValiditySeconds = exp - iat;
+    if (tokenValiditySeconds <= 2) {
       this.logger.error(
         "Auth token does not live long enough, cannot refetch the token",
       );
       return;
     }
+    // Attempt to refresh the token `refreshTokenLeewaySeconds` before it expires,
+    // or immediately if the token is already expiring soon.
+    let delay = Math.min(
+      MAXIMUM_REFRESH_DELAY,
+      (tokenValiditySeconds - this.refreshTokenLeewaySeconds) * 1000,
+    );
+    if (delay <= 0) {
+      // Refetch immediately, but this might be due to configuring a `refreshTokenLeewaySeconds`
+      // that is too large compared to the token's actual lifetime.
+      this.logger.warn(
+        `Refetching auth token immediately, configured leeway ${this.refreshTokenLeewaySeconds}s is larger than the token's lifetime ${tokenValiditySeconds}s`,
+      );
+      delay = 0;
+    }
     const refetchTokenTimeoutId = setTimeout(() => {
       void this.refetchToken();
     }, delay);

src/browser/sync/client.ts

@@ -92,6 +92,12 @@ export interface BaseConvexClientOptions {
    * The default value is `false`
    */
   skipConvexDeploymentUrlCheck?: boolean;
+  /**
+   * If using auth, the number of seconds before a token expires that we should refresh it.
+   *
+   * The default value is `2`.
+   */
+  authRefreshTokenLeewaySeconds?: number;
 }
 
 /**
@@ -187,6 +193,8 @@ export class BaseConvexClient {
       validateDeploymentUrl(address);
     }
     options = { ...options };
+    const authRefreshTokenLeewaySeconds =
+      options.authRefreshTokenLeewaySeconds ?? 2;
     let webSocketConstructor = options.webSocketConstructor;
     if (!webSocketConstructor && typeof WebSocket === "undefined") {
       throw new Error(
@@ -222,23 +230,29 @@ export class BaseConvexClient {
       this.logger,
     );
     this.requestManager = new RequestManager(this.logger);
-    this.authenticationManager = new AuthenticationManager(this.state, {
-      authenticate: (token) => {
-        const message = this.state.setAuth(token);
-        this.webSocketManager.sendMessage(message);
-      },
-      stopSocket: () => this.webSocketManager.stop(),
-      restartSocket: () => this.webSocketManager.restart(),
-      pauseSocket: () => {
-        this.webSocketManager.pause();
-        this.state.pause();
+    this.authenticationManager = new AuthenticationManager(
+      this.state,
+      {
+        authenticate: (token) => {
+          const message = this.state.setAuth(token);
+          this.webSocketManager.sendMessage(message);
+        },
+        stopSocket: () => this.webSocketManager.stop(),
+        restartSocket: () => this.webSocketManager.restart(),
+        pauseSocket: () => {
+          this.webSocketManager.pause();
+          this.state.pause();
+        },
+        resumeSocket: () => this.webSocketManager.resume(),
+        clearAuth: () => {
+          this.clearAuth();
+        },
       },
-      resumeSocket: () => this.webSocketManager.resume(),
-      clearAuth: () => {
-        this.clearAuth();
+      {
+        logger: this.logger,
+        refreshTokenLeewaySeconds: authRefreshTokenLeewaySeconds,
       },
-      logger: this.logger,
-    });
+    );
     this.optimisticQueryResults = new OptimisticQueryResults();
     this.onTransition = onTransition;
     this._nextRequestId = 0;