test: add unit tests for apiCall function to validate retry logic and error handling for network errors

Author: dosco

src/ax/util/apicall.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  apiCall,
+  AxAIServiceNetworkError,
+  type AxAPIConfig,
+} from './apicall.js';
+
+describe('apiCall', () => {
+  describe('retry logic for network errors', () => {
+    it('should retry on raw TypeError from fetch (e.g., TLS connection errors)', async () => {
+      // Simulate TLS connection error like "peer closed connection without sending TLS close_notify"
+      const tlsError = new TypeError(
+        'peer closed connection without sending TLS close_notify'
+      );
+
+      const mockFetch = vi
+        .fn()
+        .mockRejectedValueOnce(tlsError)
+        .mockRejectedValueOnce(tlsError)
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ result: 'success' }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        );
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 3,
+          initialDelayMs: 1, // Use tiny delays for tests
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      const result = await apiCall(config, { test: 'data' });
+
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+      expect(result).toEqual({ result: 'success' });
+    });
+
+    it('should wrap raw TypeError in AxAIServiceNetworkError when all retries exhausted', async () => {
+      const tlsError = new TypeError(
+        'peer closed connection without sending TLS close_notify'
+      );
+
+      const mockFetch = vi.fn().mockRejectedValue(tlsError);
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 2,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      await expect(apiCall(config, { test: 'data' })).rejects.toThrow(
+        AxAIServiceNetworkError
+      );
+      await expect(apiCall(config, { test: 'data' })).rejects.toThrow(
+        /peer closed connection without sending TLS close_notify/
+      );
+    });
+
+    it('should retry on DNS resolution errors', async () => {
+      const dnsError = new TypeError('getaddrinfo ENOTFOUND api.example.com');
+
+      const mockFetch = vi
+        .fn()
+        .mockRejectedValueOnce(dnsError)
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ result: 'success' }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        );
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 3,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      const result = await apiCall(config, { test: 'data' });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result).toEqual({ result: 'success' });
+    });
+
+    it('should retry on connection reset errors', async () => {
+      const connectionError = new Error('socket hang up');
+
+      const mockFetch = vi
+        .fn()
+        .mockRejectedValueOnce(connectionError)
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ result: 'success' }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          })
+        );
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 3,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      const result = await apiCall(config, { test: 'data' });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result).toEqual({ result: 'success' });
+    });
+
+    it('should not retry beyond maxRetries', async () => {
+      const networkError = new TypeError('network error');
+
+      const mockFetch = vi.fn().mockRejectedValue(networkError);
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 1,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      await expect(apiCall(config, { test: 'data' })).rejects.toThrow(
+        AxAIServiceNetworkError
+      );
+
+      // Initial call + 1 retry = 2 total calls
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should preserve original error information in wrapped AxAIServiceNetworkError', async () => {
+      const originalError = new TypeError(
+        'peer closed connection without sending TLS close_notify'
+      );
+
+      const mockFetch = vi.fn().mockRejectedValue(originalError);
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 0,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      try {
+        await apiCall(config, { test: 'data' });
+        expect.fail('Should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(AxAIServiceNetworkError);
+        const networkError = error as AxAIServiceNetworkError;
+        expect(networkError.message).toContain(
+          'peer closed connection without sending TLS close_notify'
+        );
+        expect(networkError.url).toBe('https://api.example.com/test');
+        expect(networkError.context.originalErrorName).toBe('TypeError');
+      }
+    });
+
+    it('should include retry count in metrics', async () => {
+      const networkError = new TypeError('network error');
+
+      const mockFetch = vi.fn().mockRejectedValue(networkError);
+
+      const config: AxAPIConfig = {
+        url: 'https://api.example.com/test',
+        fetch: mockFetch,
+        retry: {
+          maxRetries: 2,
+          initialDelayMs: 1,
+          backoffFactor: 1,
+          maxDelayMs: 10,
+        },
+      };
+
+      try {
+        await apiCall(config, { test: 'data' });
+        expect.fail('Should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(AxAIServiceNetworkError);
+        const networkError = error as AxAIServiceNetworkError;
+        expect(networkError.context.metrics).toBeDefined();
+        const metrics = networkError.context.metrics as {
+          retryCount: number;
+        };
+        expect(metrics.retryCount).toBe(2);
+      }
+    });
+  });
+});

src/ax/util/apicall.ts

@@ -924,8 +924,21 @@ export const apiCall = async <TRequest = unknown, TResponse = unknown>(
         });
       }
 
+      // Wrap raw network errors from fetch() in AxAIServiceNetworkError
+      // This ensures errors like TLS connection failures, DNS errors, etc. are retried
+      let wrappedError: Error = error as Error;
+      if (!(error instanceof AxAIServiceError) && error instanceof Error) {
+        wrappedError = new AxAIServiceNetworkError(
+          error,
+          apiUrl.href,
+          json,
+          undefined,
+          { metrics }
+        );
+      }
+
       if (api.span?.isRecording()) {
-        api.span.recordException(error as Error);
+        api.span.recordException(wrappedError);
         api.span.setAttributes({
           'error.time': Date.now() - metrics.startTime,
           'error.retries': metrics.retryCount,
@@ -934,8 +947,8 @@ export const apiCall = async <TRequest = unknown, TResponse = unknown>(
 
       // Handle retryable network errors
       if (
-        error instanceof AxAIServiceNetworkError &&
-        shouldRetry(error, undefined, attempt, retryConfig)
+        wrappedError instanceof AxAIServiceNetworkError &&
+        shouldRetry(wrappedError, undefined, attempt, retryConfig)
       ) {
         const delay = calculateRetryDelay(attempt, retryConfig);
         attempt++;
@@ -944,7 +957,7 @@ export const apiCall = async <TRequest = unknown, TResponse = unknown>(
         api.span?.addEvent('retry', {
           attempt,
           delay,
-          error: error.message,
+          error: wrappedError.message,
           'metrics.startTime': metrics.startTime,
           'metrics.retryCount': metrics.retryCount,
           'metrics.lastRetryTime': metrics.lastRetryTime,
@@ -954,11 +967,11 @@ export const apiCall = async <TRequest = unknown, TResponse = unknown>(
         continue;
       }
 
-      if (error instanceof AxAIServiceError) {
-        error.context.metrics = metrics;
+      if (wrappedError instanceof AxAIServiceError) {
+        wrappedError.context.metrics = metrics;
       }
 
-      throw error;
+      throw wrappedError;
     } finally {
       if (timeoutId !== undefined) {
         clearTimeout(timeoutId);