feat(clerk-js,backend,shared): Expose retryAfter header on ClerkAPIResponseError (#5480)

Author: dstaley

.changeset/fair-ants-invent.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/backend': minor
+'@clerk/shared': minor
+---
+
+Expose `retryAfter` value on `ClerkAPIResponseError` for 429 responses.

packages/backend/src/api/__tests__/factory.test.ts

@@ -152,6 +152,38 @@ describe('api.client', () => {
     expect(errResponse.clerkTraceId).toBe('mock_cf_ray');
   });
 
+  it('executes a failed backend API request and includes Retry-After header', async () => {
+    server.use(
+      http.get(
+        `https://api.clerk.test/v1/users/user_deadbeef`,
+        validateHeaders(() => {
+          return HttpResponse.json({ errors: [] }, { status: 429, headers: { 'retry-after': '123' } });
+        }),
+      ),
+    );
+
+    const errResponse = await apiClient.users.getUser('user_deadbeef').catch(err => err);
+
+    expect(errResponse.status).toBe(429);
+    expect(errResponse.retryAfter).toBe(123);
+  });
+
+  it('executes a failed backend API request and ignores invalid Retry-After header', async () => {
+    server.use(
+      http.get(
+        `https://api.clerk.test/v1/users/user_deadbeef`,
+        validateHeaders(() => {
+          return HttpResponse.json({ errors: [] }, { status: 429, headers: { 'retry-after': 'abc' } });
+        }),
+      ),
+    );
+
+    const errResponse = await apiClient.users.getUser('user_deadbeef').catch(err => err);
+
+    expect(errResponse.status).toBe(429);
+    expect(errResponse.retryAfter).toBe(undefined);
+  });
+
   it('executes a successful backend API request to delete a domain', async () => {
     const DOMAIN_ID = 'dmn_123';
     server.use(

packages/backend/src/api/request.ts

@@ -38,6 +38,7 @@ export type ClerkBackendApiResponse<T> =
       clerkTraceId?: string;
       status?: number;
       statusText?: string;
+      retryAfter?: number;
     };
 
 export type RequestFunction = ReturnType<typeof buildRequest>;
@@ -135,6 +136,7 @@ export function buildRequest(options: BuildRequestOptions) {
           status: res?.status,
           statusText: res?.statusText,
           clerkTraceId: getTraceId(responseBody, res?.headers),
+          retryAfter: getRetryAfter(res?.headers),
         };
       }
 
@@ -162,6 +164,7 @@ export function buildRequest(options: BuildRequestOptions) {
         status: res?.status,
         statusText: res?.statusText,
         clerkTraceId: getTraceId(err, res?.headers),
+        retryAfter: getRetryAfter(res?.headers),
       };
     }
   };
@@ -180,6 +183,16 @@ function getTraceId(data: unknown, headers?: Headers): string {
   return cfRay || '';
 }
 
+function getRetryAfter(headers?: Headers): number | undefined {
+  const retryAfter = headers?.get('Retry-After');
+  if (!retryAfter) return;
+
+  const value = parseInt(retryAfter, 10);
+  if (isNaN(value)) return;
+
+  return value;
+}
+
 function parseErrors(data: unknown): ClerkAPIError[] {
   if (!!data && typeof data === 'object' && 'errors' in data) {
     const errors = data.errors as ClerkAPIErrorJSON[];
@@ -193,7 +206,7 @@ type LegacyRequestFunction = <T>(requestOptions: ClerkBackendApiRequestOptions)
 // TODO(dimkl): Will be probably be dropped in next major version
 function withLegacyRequestReturn(cb: any): LegacyRequestFunction {
   return async (...args) => {
-    const { data, errors, totalCount, status, statusText, clerkTraceId } = await cb(...args);
+    const { data, errors, totalCount, status, statusText, clerkTraceId, retryAfter } = await cb(...args);
     if (errors) {
       // instead of passing `data: errors`, we have set the `error.errors` because
       // the errors returned from callback is already parsed and passing them as `data`
@@ -202,6 +215,7 @@ function withLegacyRequestReturn(cb: any): LegacyRequestFunction {
         data: [],
         status,
         clerkTraceId,
+        retryAfter,
       });
       error.errors = errors;
       throw error;

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
   "files": [
     { "path": "./dist/clerk.js", "maxSize": "582.6kB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "79.9kB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "80kB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
     { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -127,10 +127,18 @@ export abstract class BaseResource {
 
       assertProductionKeysOnDev(status, errors);
 
-      throw new ClerkAPIResponseError(message || statusText, {
-        data: errors,
-        status: status,
-      });
+      const apiResponseOptions: ConstructorParameters<typeof ClerkAPIResponseError>[1] = { data: errors, status };
+      if (status === 429 && headers) {
+        const retryAfter = headers.get('retry-after');
+        if (retryAfter) {
+          const value = parseInt(retryAfter, 10);
+          if (!isNaN(value)) {
+            apiResponseOptions.retryAfter = value;
+          }
+        }
+      }
+
+      throw new ClerkAPIResponseError(message || statusText, apiResponseOptions);
     }
 
     return null;

packages/clerk-js/src/core/resources/__tests__/Base.test.ts

@@ -0,0 +1,59 @@
+import { BaseResource } from '../internal';
+
+class TestResource extends BaseResource {
+  constructor() {
+    super();
+  }
+
+  fetch() {
+    return this._baseGet();
+  }
+
+  fromJSON() {
+    return this;
+  }
+}
+
+describe('BaseResource', () => {
+  it('populates retryAfter on 429 error responses', async () => {
+    BaseResource.clerk = {
+      // @ts-expect-error - We're not about to mock the entire FapiClient
+      getFapiClient: () => {
+        return {
+          request: jest.fn().mockResolvedValue({
+            payload: {},
+            status: 429,
+            statusText: 'Too Many Requests',
+            headers: new Headers({ 'Retry-After': '60' }),
+          }),
+        };
+      },
+      __internal_setCountry: jest.fn(),
+    };
+    const resource = new TestResource();
+    const errResponse = await resource.fetch().catch(err => err);
+    console.dir(errResponse);
+    expect(errResponse.retryAfter).toBe(60);
+  });
+
+  it('does not populate retryAfter on invalid header', async () => {
+    BaseResource.clerk = {
+      // @ts-expect-error - We're not about to mock the entire FapiClient
+      getFapiClient: () => {
+        return {
+          request: jest.fn().mockResolvedValue({
+            payload: {},
+            status: 429,
+            statusText: 'Too Many Requests',
+            headers: new Headers({ 'Retry-After': 'abcd' }),
+          }),
+        };
+      },
+      __internal_setCountry: jest.fn(),
+    };
+    const resource = new TestResource();
+    const errResponse = await resource.fetch().catch(err => err);
+    console.dir(errResponse);
+    expect(errResponse.retryAfter).toBe(undefined);
+  });
+});

packages/shared/src/error.ts

@@ -25,6 +25,7 @@ interface ClerkAPIResponseOptions {
   data: ClerkAPIErrorJSON[];
   status: number;
   clerkTraceId?: string;
+  retryAfter?: number;
 }
 
 // For a comprehensive Metamask error list, please see
@@ -119,17 +120,19 @@ export class ClerkAPIResponseError extends Error {
   status: number;
   message: string;
   clerkTraceId?: string;
+  retryAfter?: number;
 
   errors: ClerkAPIError[];
 
-  constructor(message: string, { data, status, clerkTraceId }: ClerkAPIResponseOptions) {
+  constructor(message: string, { data, status, clerkTraceId, retryAfter }: ClerkAPIResponseOptions) {
     super(message);
 
     Object.setPrototypeOf(this, ClerkAPIResponseError.prototype);
 
     this.status = status;
     this.message = message;
     this.clerkTraceId = clerkTraceId;
+    this.retryAfter = retryAfter;
     this.clerkError = true;
     this.errors = parseErrors(data);
   }