Add generateJitter utility function and update QBORepository to use it

- Introduced `generateJitter` function in `utils.ts` to create cryptographically secure random jitter for retry delays, enhancing the reliability of retry logic.
- Updated `QBORepository` to utilize the new `generateJitter` function instead of a manual jitter calculation, improving code clarity and maintainability.
- Added unit tests for `generateJitter` to ensure it generates values within the expected range and behaves consistently across multiple calls.

These changes enhance the utility functions available for managing delays in API calls, contributing to a more robust integration with QuickBooks Online.

Author: anatolyshipitz

workers/main/src/common/utils.test.ts

@@ -5,7 +5,7 @@ vi.mock('../configs', () => ({
 }));
 
 import * as configs from '../configs';
-import { formatDateToISOString, validateEnv } from './utils';
+import { formatDateToISOString, generateJitter, validateEnv } from './utils';
 
 type ValidationResult = {
   success: boolean;
@@ -20,7 +20,7 @@ describe('validateEnv', () => {
   let exitSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
-    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
     exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('exit');
     }) as unknown as ReturnType<typeof vi.spyOn>;
@@ -51,7 +51,7 @@ describe('validateEnv', () => {
     expect(() => validateEnv()).toThrow('exit');
     expect(errorSpy).toHaveBeenCalledWith(
       'Missing or invalid environment variable: FOO (is required)\n' +
-        'Missing or invalid environment variable: (unknown variable) (unknown)',
+      'Missing or invalid environment variable: (unknown variable) (unknown)',
     );
     expect(exitSpy).toHaveBeenCalledWith(1);
   });
@@ -79,3 +79,39 @@ describe('formatDateToISOString', () => {
     expect(result).toBe('2024-12-31');
   });
 });
+
+describe('generateJitter', () => {
+  it('generates jitter within expected range', () => {
+    const baseDelay = 1000;
+    const jitter = generateJitter(baseDelay);
+
+    // Jitter should be between 0 and 10% of baseDelay
+    expect(jitter).toBeGreaterThanOrEqual(0);
+    expect(jitter).toBeLessThanOrEqual(0.1 * baseDelay);
+    expect(jitter).toBeLessThan(100); // 10% of 1000ms
+  });
+
+  it('generates different jitter values on multiple calls', () => {
+    const baseDelay = 2000;
+    const jitter1 = generateJitter(baseDelay);
+    const jitter2 = generateJitter(baseDelay);
+
+    // Values should be different (cryptographically random)
+    expect(jitter1).not.toBe(jitter2);
+  });
+
+  it('scales jitter proportionally with base delay', () => {
+    const smallDelay = 500;
+    const largeDelay = 2000;
+
+    const smallJitter = generateJitter(smallDelay);
+    const largeJitter = generateJitter(largeDelay);
+
+    // Large delay should produce larger jitter
+    expect(largeJitter).toBeGreaterThan(smallJitter);
+
+    // Both should be within 10% of their respective base delays
+    expect(smallJitter).toBeLessThanOrEqual(0.1 * smallDelay);
+    expect(largeJitter).toBeLessThanOrEqual(0.1 * largeDelay);
+  });
+});

workers/main/src/common/utils.ts

@@ -1,3 +1,5 @@
+import crypto from 'crypto';
+
 import { validationResult } from '../configs';
 
 export function validateEnv() {
@@ -21,3 +23,15 @@ export function formatDateToISOString(date: Date): string {
 
   return `${year}-${month}-${day}`;
 }
+
+/**
+ * Generates cryptographically secure random jitter for retry delays
+ * @param baseDelay - The base delay in milliseconds
+ * @returns A random jitter value between 0 and 10% of the base delay
+ */
+export function generateJitter(baseDelay: number): number {
+  const randomBytes = crypto.randomBytes(4);
+  const randomValue = randomBytes.readUInt32BE(0) / 0xffffffff; // Convert to 0-1 range
+
+  return randomValue * 0.1 * baseDelay;
+}

workers/main/src/services/QBO/QBORepository.ts

@@ -2,7 +2,7 @@ import axios from 'axios';
 import axiosRetry from 'axios-retry';
 
 import { QuickBooksRepositoryError } from '../../common/errors';
-import { formatDateToISOString } from '../../common/utils';
+import { formatDateToISOString, generateJitter } from '../../common/utils';
 import { axiosConfig } from '../../configs/axios';
 import { qboConfig } from '../../configs/qbo';
 import { OAuth2Manager } from '../OAuth2';
@@ -72,7 +72,7 @@ export class QBORepository implements IQBORepository {
       if (retryAfter) return parseInt(retryAfter) * 1000;
     }
     const baseDelay = Math.pow(2, attempt) * 1000;
-    const jitter = Math.random() * 0.1 * baseDelay;
+    const jitter = generateJitter(baseDelay);
     const maxDelay = error.response?.status === 502 ? 60000 : 30000;
 
     return Math.min(baseDelay + jitter, maxDelay);