SS-8172 Add retry on 429 and 502

Author: matthiasreisacher

justfile

@@ -53,6 +53,9 @@ generate version:
         "{{target_dir}}/configuration.ts" \
         "{{target_dir}}/index.ts"
 
+    # Apply manual modifications to the generated DTO files.
+    just _post-generation
+
     # Clean up.
     rm -rf "{{target_dir}}"
 
@@ -74,3 +77,13 @@ test-generator:
         --dry-run \
         -i "{{oas_repo}}/geometry_backend_v2.yaml" \
         -g typescript-axios
+
+# Steps to be executed after the generation of the TypeScript client.
+_post-generation:
+    #!/usr/bin/env bash
+    # Replace client BaseAPI import in api.ts with custom BaseAPI implementation.
+    pattern="^import \{(.*)BaseAPI,?\s?(.*)\} from '.\/base';$"
+    replacement="import \{\1\2\} from '.\/base';"
+    added_line="import \{ BaseAPI \} from '..\/base';"
+    sed -ri "s/${pattern}/${replacement}\n${added_line}/g" \
+        "packages/sdk.geometry-api-sdk-v2/src/client/api.ts"

package.json

@@ -20,6 +20,7 @@
         "downstream": "bash ./scripts/downstream.sh"
     },
     "devDependencies": {
+        "axios-mock-adapter": "~2.1.0",
         "eslint": "~9.12.0",
         "@eslint/js": "~9.12.0",
         "eslint-plugin-jest": "~28.8.3",

packages/sdk.geometry-api-sdk-v2/__tests__/base.test.ts

@@ -0,0 +1,94 @@
+import { Configuration, SessionApi } from '../src';
+import { Configuration as ClientConfig } from '../src/client/configuration';
+import AxiosMockAdapter from 'axios-mock-adapter';
+import axios from 'axios';
+
+describe('constructor', function () {
+    test.each([
+        ['no config', undefined],
+        ['client config', new ClientConfig()],
+        ['sd-config without useCustomAxios', new Configuration()],
+        ['sd-config with useCustomAxios enabled', new Configuration({ useCustomAxios: true })],
+    ])('%s; should be defined', (_, config) => {
+        const session = new SessionApi(config);
+        expect(session.defaultAxios).toBeDefined();
+    });
+
+    test('sd-config with useCustomAxios disabled; should be defined', () => {
+        const config = new Configuration({ useCustomAxios: false });
+        const session = new SessionApi(config);
+        expect(session.defaultAxios).toBeUndefined();
+    });
+});
+
+describe('inceptor', function () {
+    const config = new Configuration({ useCustomAxios: true, maxRetries: 2 }),
+        api = new SessionApi(config), // use actual api instance to test BaseAPI swapping
+        mock = new AxiosMockAdapter(api.defaultAxios!);
+    let spyPost: number;
+
+    beforeEach(() => {
+        mock.resetHandlers();
+        spyPost = 0;
+    });
+
+    test('retry enabled, general error status; should not retry', async () => {
+        mock.onPost().reply(() => {
+            spyPost++;
+            return [400, {}];
+        });
+
+        await expect(api.createSessionByTicket('foobar')).rejects.toThrow(
+            /Request failed with status code 400/
+        );
+        expect(spyPost).toBe(1);
+    });
+
+    test.each([
+        [429, { 'retry-after': '1' }],
+        [502, {}],
+    ])(
+        'retry enabled, status code %s; should retry until failure',
+        async (statusCode, headers) => {
+            mock.onPost().reply(() => {
+                spyPost++;
+                return [statusCode, {}, headers];
+            });
+
+            await expect(api.createSessionByTicket('foobar')).rejects.toThrow(
+                new RegExp(`Request failed with status code ${statusCode}`)
+            );
+            expect(spyPost).toBe(3);
+        }
+    );
+
+    test.each([
+        [429, { 'retry-after': '1' }],
+        [502, {}],
+    ])('retry enabled, status code %s once; should retry once', async (statusCode, headers) => {
+        mock.onPost().reply(() => {
+            if (spyPost++ === 0) return [statusCode, {}, headers];
+            else return [200, {}];
+        });
+
+        await expect(api.createSessionByTicket('foobar')).resolves.toBeDefined();
+        expect(spyPost).toBe(2);
+    });
+
+    test('retry disabled, retry-able error status; should not retry', async () => {
+        const api = new SessionApi(new Configuration({ useCustomAxios: false })),
+            mock = new AxiosMockAdapter(axios); // Mock global Axios
+
+        mock.onPost().reply(() => {
+            spyPost++;
+            return [429, {}];
+        });
+
+        await expect(api.createSessionByTicket('foobar')).rejects.toThrow(
+            /Request failed with status code 429/
+        );
+        expect(spyPost).toBe(1);
+
+        mock.restore();
+    });
+});

packages/sdk.geometry-api-sdk-v2/src/base.ts

@@ -0,0 +1,75 @@
+import { Configuration as ClientConfig } from './client/configuration';
+import { BaseAPI as ClientBaseAPI } from './client/base';
+import { Configuration } from './configuration';
+import globalAxios, { AxiosInstance } from 'axios';
+
+/** Axios singleton instance used by all APIs by default. */
+let AXIOS: AxiosInstance | undefined;
+
+/**
+ * Overrides the `BaseAPI` class that is used by all resource APIs.
+ *
+ * NOTE: The classes are swapped out in `client/base.ts` by a script during generation.
+ *
+ * Extensions:
+ *  - Replace the global Axios instance with a custom instance.
+ *  - Extend the Axios instance by an Interceptor to handle retries on 429 and 502 status codes.
+ */
+export class BaseAPI extends ClientBaseAPI {
+    // Exposed for testing purposes.
+    readonly defaultAxios: AxiosInstance | undefined;
+
+    constructor(config?: Configuration | ClientConfig, basePath?: string) {
+        let axios: AxiosInstance | undefined;
+        if (!config || !('useCustomAxios' in config) || config.useCustomAxios) {
+            if (AXIOS === undefined)
+                AXIOS = createCustomAxiosInstance((config as any)?.maxRetries);
+            axios = AXIOS;
+        }
+        super(config, basePath, axios);
+        this.defaultAxios = axios;
+    }
+}
+
+/**
+ * Creates a custom Axios instance with a response interceptor to automatically retry requests on
+ * `429` and `502` status codes.
+ *
+ * @param {number} maxRetries - Maximum number of retry attempts before failing (default: 5).
+ * @returns A custom Axios instance with retry functionality.
+ */
+function createCustomAxiosInstance(maxRetries = 5): AxiosInstance {
+    const axios = globalAxios.create();
+
+    axios.interceptors.response.use(undefined, async (error) => {
+        const { config, response } = error;
+
+        // Exit early if no response or config is available
+        if (!response || !config) return Promise.reject(error);
+
+        // Check if retry limit is reached
+        config.retryCount = config.retryCount ?? 0;
+        if (config.retryCount >= maxRetries) return Promise.reject(error);
+
+        // Only retry for 429 or 502 status codes
+        if (response.status === 429 || response.status === 502) {
+            config.retryCount += 1;
+
+            const delay =
+                response.status === 429
+                    ? // use retry-after or default to 60s
+                      (parseInt(response.headers['retry-after'], 10) || 60) * 1000
+                    : // 1 second delay for 502 status
+                      1000;
+
+            // Delay retry and send the request again
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            return axios.request(config);
+        }
+
+        // Reject for all other error statuses
+        return Promise.reject(error);
+    });
+
+    return axios;
+}

packages/sdk.geometry-api-sdk-v2/src/client/api.ts

@@ -21,7 +21,8 @@ import globalAxios from 'axios';
 import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, createRequestFunction } from './common';
 import type { RequestArgs } from './base';
 // @ts-ignore
-import { BASE_PATH, COLLECTION_FORMATS, BaseAPI, RequiredError, operationServerMap } from './base';
+import { BASE_PATH, COLLECTION_FORMATS, RequiredError, operationServerMap } from './base';
+import { BaseAPI } from '../base';
 
 /**
  * Reference to the s-type parameter asset to be used.

packages/sdk.geometry-api-sdk-v2/src/configuration.ts

@@ -1,15 +1,48 @@
+import { RawAxiosRequestConfig } from 'axios';
 import {
     Configuration as ClientConfig,
     ConfigurationParameters as ClientConfigParams,
 } from './client/configuration';
 
-export interface ConfigurationParameters extends ClientConfigParams {}
+export interface ConfigurationParameters
+    extends Pick<ClientConfigParams, 'accessToken' | 'basePath'> {
+    /**
+     * Base options for Axios calls.
+     *
+     * @type {RawAxiosRequestConfig}
+     * @memberof ConfigurationParameters
+     */
+    baseOptions?: RawAxiosRequestConfig;
+
+    /**
+     * Enables the use of a custom Axios instance for all API requests by default, instead of the
+     * global Axios instance. This custom instance includes additional functionality to
+     * automatically retry requests on `429` and `502` status codes.
+     *
+     * Default: `true`.
+     */
+    useCustomAxios?: boolean;
+
+    /**
+     * Specifies the maximum number of automatic HTTP retries for failed requests.
+     *
+     * **Note:** This setting is only applicable when using a custom Axios instance.
+     *
+     * Default: `5`
+     */
+    maxRetries?: number;
+}
 
 export class Configuration extends ClientConfig {
     protected readonly sdkVersion = '2.0.1'; // WARNING: This value is updated automatically!
 
+    public readonly useCustomAxios: boolean;
+    public readonly maxRetries: number;
+
     constructor(param: ConfigurationParameters = {}) {
         super(param);
+        this.useCustomAxios = param.useCustomAxios ?? true;
+        this.maxRetries = param.maxRetries ?? 5;
 
         this.baseOptions = this.baseOptions ?? {};
         this.baseOptions.headers = this.baseOptions.headers ?? {};