chore(backend,shared): Include clerkTraceId for backend api errors

.changeset/sour-comics-stare.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': patch
+'@clerk/shared': patch
+---
+
+Add clerkTraceId to ClerkBackendApiResponse and ClerkAPIResponseError to allow for better tracing and debugging API error responses. 
+Uses `clerk_trace_id` when available in a response and defaults to [`cf-ray` identifier](https://developers.cloudflare.com/fundamentals/reference/cloudflare-ray-id/) if missing. 

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

@@ -4,7 +4,7 @@ import sinon from 'sinon';
 import emailJson from '../fixtures/responses/email.json';
 import userJson from '../fixtures/responses/user.json';
 import runtime from '../runtime';
-import { jsonNotOk, jsonOk } from '../util/mockFetch';
+import { jsonError, jsonNotOk, jsonOk } from '../util/mockFetch';
 import { createBackendApiClient } from './factory';
 
 export default (QUnit: QUnit) => {
@@ -151,12 +151,14 @@ export default (QUnit: QUnit) => {
 
  test('executes a failed backend API request and parses the error response', async assert => {
  const mockErrorPayload = { code: 'whatever_error', message: 'whatever error', meta: {} };
+ const traceId = 'trace_id_123';
  fakeFetch = sinon.stub(runtime, 'fetch');
- fakeFetch.onCall(0).returns(jsonNotOk({ errors: [mockErrorPayload] }));
+ fakeFetch.onCall(0).returns(jsonNotOk({ errors: [mockErrorPayload], clerk_trace_id: traceId }));
 
  try {
  await apiClient.users.getUser('user_deadbeef');
  } catch (e: any) {
+ assert.equal(e.clerkTraceId, traceId);
  assert.equal(e.clerkError, true);
  assert.equal(e.status, 422);
  assert.equal(e.errors[0].code, 'whatever_error');
@@ -174,6 +176,30 @@ export default (QUnit: QUnit) => {
  );
  });
 
+ test('executes a failed backend API request and include cf ray id when trace not present', async assert => {
+ fakeFetch = sinon.stub(runtime, 'fetch');
+ fakeFetch.onCall(0).returns(jsonError({ errors: [] }));
+
+ try {
+ await apiClient.users.getUser('user_deadbeef');
+ } catch (e: any) {
+ assert.equal(e.clerkError, true);
+ assert.equal(e.status, 500);
+ assert.equal(e.clerkTraceId, 'mock_cf_ray');
+ }
+
+ assert.ok(
+ fakeFetch.calledOnceWith('https://api.clerk.test/v1/users/user_deadbeef', {
+ method: 'GET',
+ headers: {
+ Authorization: 'Bearer deadbeef',
+ 'Content-Type': 'application/json',
+ 'Clerk-Backend-SDK': '@clerk/backend',
+ },
+ }),
+ );
+ });
+
  test('executes a successful backend API request to delete a domain', async assert => {
  const domainId = 'dmn_123';
  const fakeResponse = {

packages/backend/src/api/request.ts

@@ -1,3 +1,4 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
 import type { ClerkAPIError, ClerkAPIErrorJSON } from '@clerk/types';
 import deepmerge from 'deepmerge';
 import snakecaseKeys from 'snakecase-keys';
@@ -37,6 +38,7 @@ export type ClerkBackendApiResponse<T> =
  | {
  data: null;
  errors: ClerkAPIError[];
+ clerkTraceId?: string;
  };
 
 export type RequestFunction = ReturnType<typeof buildRequest>;
@@ -52,13 +54,14 @@ const withLegacyReturn =
  (cb: any): LegacyRequestFunction =>
  async (...args) => {
  // @ts-ignore
- const { data, errors, status, statusText } = await cb<T>(...args);
+ const { data, errors, status, statusText, clerkTraceId } = await cb<T>(...args);
  if (errors === null) {
  return data;
  } else {
  throw new ClerkAPIResponseError(statusText || '', {
  data: errors,
  status: status || '',
+ clerkTraceId,
  });
  }
  };
@@ -161,6 +164,7 @@ export function buildRequest(options: CreateBackendApiOptions) {
  message: err.message || 'Unexpected error',
  },
  ],
+ clerkTraceId: getTraceId(err, res?.headers),
  };
  }
 
@@ -171,13 +175,25 @@ export function buildRequest(options: CreateBackendApiOptions) {
  // @ts-expect-error
  status: res?.status,
  statusText: res?.statusText,
+ clerkTraceId: getTraceId(err, res?.headers),
  };
  }
  };
 
  return withLegacyReturn(request);
 }
 
+// Returns either clerk_trace_id if present in response json, otherwise defaults to CF-Ray header
+// If the request failed before receiving a response, returns undefined
+function getTraceId(data: unknown, headers?: Headers): string {
+ if (data && typeof data === 'object' && 'clerk_trace_id' in data && typeof data.clerk_trace_id === 'string') {
+ return data.clerk_trace_id;
+ }
+
+ const cfRay = headers?.get('cf-ray');
+ return cfRay || '';
+}
+
 function parseErrors(data: unknown): ClerkAPIError[] {
  if (!!data && typeof data === 'object' && 'errors' in data) {
  const errors = data.errors as ClerkAPIErrorJSON[];
@@ -197,23 +213,3 @@ function parseError(error: ClerkAPIErrorJSON): ClerkAPIError {
  },
  };
 }
-
-class ClerkAPIResponseError extends Error {
- clerkError: true;
-
- status: number;
- message: string;
-
- errors: ClerkAPIError[];
-
- constructor(message: string, { data, status }: { data: ClerkAPIError[]; status: number }) {
- super(message);
-
- Object.setPrototypeOf(this, ClerkAPIResponseError.prototype);
-
- this.clerkError = true;
- this.message = message;
- this.status = status;
- this.errors = data;
- }
-}

packages/backend/src/util/mockFetch.ts

@@ -42,4 +42,14 @@ export function jsonError(body: unknown, status = 500) {
  return Promise.resolve(mockResponse);
 }
 
-const mockHeadersGet = (key: string) => (key === constants.Headers.ContentType ? constants.ContentTypes.Json : null);
+const mockHeadersGet = (key: string) => {
+ if (key === constants.Headers.ContentType) {
+ return constants.ContentTypes.Json;
+ }
+
+ if (key === 'cf-ray') {
+ return 'mock_cf_ray';
+ }
+
+ return null;
+};

packages/shared/src/error.ts

@@ -22,6 +22,7 @@ export function isNetworkError(e: any): boolean {
 interface ClerkAPIResponseOptions {
  data: ClerkAPIErrorJSON[];
  status: number;
+ clerkTraceId?: string;
 }
 
 // For a comprehensive Metamask error list, please see
@@ -88,24 +89,32 @@ export class ClerkAPIResponseError extends Error {
 
  status: number;
  message: string;
+ clerkTraceId?: string;
 
  errors: ClerkAPIError[];
 
- constructor(message: string, { data, status }: ClerkAPIResponseOptions) {
+ constructor(message: string, { data, status, clerkTraceId }: ClerkAPIResponseOptions) {
  super(message);
 
  Object.setPrototypeOf(this, ClerkAPIResponseError.prototype);
 
  this.status = status;
  this.message = message;
+ this.clerkTraceId = clerkTraceId;
  this.clerkError = true;
  this.errors = parseErrors(data);
  }
 
  public toString = () => {
-return `[${this.name}]\nMessage:${this.message}\nStatus:${this.status}\nSerialized errors: ${this.errors.map(e =>
- JSON.stringify(e),
+let message = `[${this.name}]\nMessage:${this.message}\nStatus:${this.status}\nSerialized errors: ${this.errors.map(
+e => JSON.stringify(e),
  )}`;
+
+ if (this.clerkTraceId) {
+ message += `\nClerk Trace ID: ${this.clerkTraceId}`;
+ }
+
+ return message;
  };
 }