chore(clerk-js): Improve session refresh retry logic #5397

panteliselef · 2025-03-19T13:01:05Z

Description

This PR performs the following improvements related to how we are refreshing the session token.

Switches from an interval to a timeout. From a parallel behaviour we are switching to a sequential behaviour which allows all retries of particular getToken() call to have concluded before attempting to poll again. Example here.
Clerk.handleUnauthenticated() will set session as null on 500 status code /client response. Avoid infinite request loops, see here.
If /client fails on init, we stop the poller -> create the dummy client -> attempt manual request to /tokens -> start polling again.
retry no longer fires immediately by default.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2025-03-19T13:01:08Z

🦋 Changeset detected

Latest commit: 5b382a3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/shared	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-03-19T13:01:39Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 27, 2025 1:57pm

panteliselef · 2025-03-19T13:01:34Z

packages/clerk-js/src/core/fapiClient.ts

+        response = await retry(() => fetch(urlStr, fetchOpts), {
+          // This retry handles only network errors, not 4xx or 5xx responses,
+          // so we want to try once immediately to handle simple network blips.
+          // Since fapiClient is responsible for the network layer only,
+          // callers need to use their own retry logic where needed.
+          retryImmediately: true,
+          // And then exponentially back off with a max delay of 3 seconds.
+          initialDelay: 700,
+          maxDelayBetweenRetries: 5000,
+          shouldRetry: (_: unknown, iterations: number) => {
+            // We want to retry only GET requests, as other methods are not idempotent.
+            return overwrittenRequestMethod === 'GET' && iterations < maxTries;
+          },
+        });


Credits to @nikosdouvlis

panteliselef · 2025-03-19T13:01:39Z

packages/clerk-js/src/core/resources/Session.ts

+    // This will retry the getToken call if it fails with a non-4xx error
+    // We're going to trigger 8 retries in the span of ~3 minutes,
+    // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
    return retry(() => this._getToken(options), {
-      shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+      factor: 1.55,
+      retryImmediately: false,
+      initialDelay: 3 * 1000,
+      maxDelayBetweenRetries: 50 * 1_000,
+      jitter: false,
+      shouldRetry: (error, iterationsCount) => {
+        return !is4xxError(error) && iterationsCount <= 8;
+      },


Credits to @nikosdouvlis

panteliselef · 2025-03-19T13:02:09Z

packages/clerk-js/src/core/auth/SessionCookiePoller.ts

-    }, INTERVAL_IN_MS);
+    const run = async () => {
+      await this.lock.acquireLockAndRun(cb);
+      this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);


Credits to @nikosdouvlis

panteliselef · 2025-03-19T13:03:40Z

packages/clerk-js/src/core/clerk.ts

+              /**
+               * In most scenarios we want the poller to stop while we are fetching a fresh token during an outage.
+               * We want to avoid having the below `getToken()` retrying at the same time as the poller.
+               */
+              this.#authService?.stopPollingForToken();
+
+              // Attempt to grab a fresh token
+              await this.session
+                ?.getToken({ skipCache: true })
+                // If the token fetch fails, let Clerk be marked as loaded and leave it up to the poller.
+                .catch(() => null)
+                .finally(() => {
+                  this.#authService?.startPollingForToken();
+                });


Avoid parallel retries from this explicit invocation and the poller.

…oller-when-signs-inout

panteliselef · 2025-03-21T16:12:15Z

packages/clerk-js/src/core/auth/SessionCookiePoller.ts

+    const run = async () => {
+      await this.lock.acquireLockAndRun(cb);
+      this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+    };
+
+    void run();


For reviewers:
This change allows for this behaviour

getToken -> 500 -> retry... retry.. retry... -> success/failure -> getToken

Until now, we had this one, which is no longer desired.

getToken -> 500 -> retry... retry.. retry... -> success/failure -> getToken getToken -> 500 -> retry... retry.. retry... -> success/failure -> getToken getToken -> 500 -> retry... retry.. retry... -> success/failure -> getToken

panteliselef · 2025-03-21T16:17:28Z

packages/clerk-js/src/core/clerk.ts

+      // `/client` can fail with either a 401, a 403, 500 or network errors.
+      // 401 is already handled internally in our fetcher.
+      // 403 means that the client is blocked, signing out the user is the only option.
+      // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+      if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {


Why is the needed ?
When /client fails with 500, we attempt to read from __session and call /tokens. If /tokens returns with a 4xx handleUnauthencated gets called which tries to reload client which will fail with 500.

At this point the user cannot really do anything to resolve this, and clerk.js cannot auto recover. We set session: null to stop the poller from falling into an infinite loop.

packages/clerk-js/src/core/fapiClient.ts

…signs-inout

…poller-when-signs-inout' into elef/sdki-949-startstop-session-poller-when-signs-inout

…signs-inout # Conflicts: # packages/clerk-js/bundlewatch.config.json

packages/clerk-js/src/core/resources/Session.ts

nikosdouvlis · 2025-03-27T12:37:40Z

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
   * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
   * The delay for the immediate retry is 100ms.
-   * @default true
+   * @default false


how come we changed the default here?

We settled on it, as the best default to have.

panteliselef · 2025-03-27T15:01:05Z

!snapshot

clerk-cookie · 2025-03-27T15:03:36Z

Hey @panteliselef - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.0.16-snapshot.v20250327150215
@clerk/astro	2.4.5-snapshot.v20250327150215
@clerk/backend	1.25.8-snapshot.v20250327150215
@clerk/chrome-extension	2.2.23-snapshot.v20250327150215
@clerk/clerk-js	5.59.0-snapshot.v20250327150215
@clerk/elements	0.23.8-snapshot.v20250327150215
@clerk/clerk-expo	2.9.6-snapshot.v20250327150215
@clerk/expo-passkeys	0.2.0-snapshot.v20250327150215
@clerk/express	1.3.59-snapshot.v20250327150215
@clerk/fastify	2.1.32-snapshot.v20250327150215
@clerk/localizations	3.13.4-snapshot.v20250327150215
@clerk/nextjs	6.12.12-snapshot.v20250327150215
@clerk/nuxt	1.4.6-snapshot.v20250327150215
@clerk/clerk-react	5.25.5-snapshot.v20250327150215
@clerk/react-router	1.1.11-snapshot.v20250327150215
@clerk/remix	4.5.11-snapshot.v20250327150215
@clerk/shared	3.3.0-snapshot.v20250327150215
@clerk/tanstack-react-start	0.12.2-snapshot.v20250327150215
@clerk/testing	1.4.33-snapshot.v20250327150215
@clerk/themes	2.2.26-snapshot.v20250327150215
@clerk/types	4.50.1-snapshot.v20250327150215
@clerk/vue	1.4.5-snapshot.v20250327150215

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

chore(clerk-js): Improve session refresh retry logic

28880dc

panteliselef self-assigned this Mar 19, 2025

clerk-cookie added the clerk-js label Mar 19, 2025

vercel bot deployed to Preview March 19, 2025 13:02 View deployment

panteliselef commented Mar 19, 2025

View reviewed changes

panteliselef added 2 commits March 20, 2025 15:47

Merge branch 'refs/heads/main' into elef/sdki-949-startstop-session-p…

64b4fdf

…oller-when-signs-inout

improve handleUnauthenticated catch

5a4f823

vercel bot deployed to Preview March 20, 2025 13:48 View deployment

panteliselef commented Mar 21, 2025

View reviewed changes

panteliselef added 2 commits March 21, 2025 18:18

Update packages/clerk-js/src/core/fapiClient.ts

be509e9

Merge branch 'main' into elef/sdki-949-startstop-session-poller-when-…

742e717

…signs-inout

vercel bot deployed to Preview March 21, 2025 16:19 View deployment

Merge remote-tracking branch 'origin/elef/sdki-949-startstop-session-…

1dbce8b

…poller-when-signs-inout' into elef/sdki-949-startstop-session-poller-when-signs-inout

vercel bot deployed to Preview March 21, 2025 16:20 View deployment

update bundlewatch

49200e1

panteliselef marked this pull request as ready for review March 21, 2025 16:30

panteliselef requested a review from a team March 21, 2025 16:30

vercel bot deployed to Preview March 21, 2025 16:31 View deployment

panteliselef added 2 commits March 21, 2025 18:34

update changeset

05fb33e

update changeset

24c3735

vercel bot deployed to Preview March 21, 2025 16:38 View deployment

brkalow approved these changes Mar 25, 2025

View reviewed changes

Merge branch 'main' into elef/sdki-949-startstop-session-poller-when-…

8a4b7bf

…signs-inout # Conflicts: # packages/clerk-js/bundlewatch.config.json

vercel bot deployed to Preview March 27, 2025 11:23 View deployment

noop on network errors

a295c09

vercel bot deployed to Preview March 27, 2025 11:38 View deployment

nikosdouvlis approved these changes Mar 27, 2025

View reviewed changes

address comment

28fe068

protect from multiple invocations until timerId is populated.

5b382a3

vercel bot deployed to Preview March 27, 2025 13:57 View deployment

panteliselef merged commit e984494 into main Mar 27, 2025
30 checks passed

panteliselef deleted the elef/sdki-949-startstop-session-poller-when-signs-inout branch March 27, 2025 16:45

clerk-cookie mentioned this pull request Mar 27, 2025

ci(repo): Version packages #5466

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(clerk-js): Improve session refresh retry logic #5397

chore(clerk-js): Improve session refresh retry logic #5397

panteliselef commented Mar 19, 2025 •

edited

Loading

changeset-bot bot commented Mar 19, 2025 •

edited

Loading

vercel bot commented Mar 19, 2025 •

edited

Loading

panteliselef Mar 19, 2025

panteliselef Mar 19, 2025

panteliselef Mar 19, 2025

panteliselef Mar 19, 2025

panteliselef Mar 21, 2025

panteliselef Mar 21, 2025

nikosdouvlis Mar 27, 2025

panteliselef Mar 27, 2025

panteliselef commented Mar 27, 2025

clerk-cookie commented Mar 27, 2025

chore(clerk-js): Improve session refresh retry logic #5397

chore(clerk-js): Improve session refresh retry logic #5397

Conversation

panteliselef commented Mar 19, 2025 • edited Loading

Description

Checklist

Type of change

changeset-bot bot commented Mar 19, 2025 • edited Loading

🦋 Changeset detected

vercel bot commented Mar 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

panteliselef commented Mar 27, 2025

clerk-cookie commented Mar 27, 2025

panteliselef commented Mar 19, 2025 •

edited

Loading

changeset-bot bot commented Mar 19, 2025 •

edited

Loading

vercel bot commented Mar 19, 2025 •

edited

Loading