Add basic rate limiting options

package.json

@@ -35,12 +35,12 @@
         "lib": "src"
     },
     "scripts": {
-        "test": "npm-run-all --parallel --race start:mock-server start:unit-tests",
+        "test": "npm-run-all --parallel --race start:test:server start:test:unit",
         "test:coverage": "nyc npm run test",
-        "test:integration": "npm-run-all --parallel --race start:mock-server start:integration-tests",
-        "start:mock-server": "serve -p 8080 --no-request-logging",
-        "start:unit-tests": "mocha --ignore 'test/integration/**/*'",
-        "start:integration-tests": "mocha -- --timeout 180000 --ignore 'src/**/*' --ignore index.spec.ts test/integration",
+        "test:integration": "npm-run-all --parallel --race start:test:server start:test:integration",
+        "start:test:server": "ts-node test/server.ts",
+        "start:test:unit": "mocha --ignore 'test/integration/**/*'",
+        "start:test:integration": "mocha -- --timeout 180000 --ignore 'src/**/*' --ignore index.spec.ts test/integration",
         "build": "tsc --project tsconfigBuild.json && shx cp package.json README.md LICENSE.md CHANGELOG.md dist/",
         "eslint": "eslint src/**/*.ts test/**/*.ts index.ts index.spec.ts"
     },
@@ -81,7 +81,6 @@
         "mocha": "^10.5.2",
         "npm-run-all": "^4.1.5",
         "nyc": "^17.0.0",
-        "serve": "^14.2.3",
         "shx": "^0.3.4",
         "sinon": "^17.0.1",
         "sinon-chai": "^3.7.0",

src/client/https/requests.spec.ts

@@ -2,11 +2,11 @@ import * as BaseAxios from "axios";
 import chai, { expect } from "chai";
 import chaiAsPromised from "chai-as-promised";
 import FormData from "form-data";
-import { Readable } from "node:stream";
+import { createReadStream } from "node:fs";
 import path from "path";
 import { stub, useFakeTimers } from "sinon";
 import { getMockedLogger } from "../../../test/mocks";
-import { LOCAL_SERVER } from "../../../test/server";
+import { LOCAL_SERVER } from "../../../test/server-config";
 import { Level } from "../../util/logging";
 import { AxiosRestClient } from "./requests";
 
@@ -336,14 +336,15 @@ describe(path.relative(process.cwd(), __filename), () => {
 
     it("logs formdata only up to a certain length", async () => {
         const logger = getMockedLogger();
-        const restClient = new AxiosRestClient({ debug: true, fileSizeLimit: 1 });
-        const buffer = Buffer.alloc(1024 * 1024 * 1, ".");
+        const restClient = new AxiosRestClient({ debug: true, fileSizeLimit: 0.5 });
         const formdata = new FormData();
-        formdata.append("long.txt", Readable.from(buffer));
+        formdata.append("long.txt", createReadStream("./test/resources/big.txt"));
         await restClient.post(`http://${LOCAL_SERVER.url}`, formdata, {
             headers: { ...formdata.getHeaders() },
         });
-        expect(logger.logToFile.firstCall.args[0]).to.contain("[... omitted due to file size]");
+        // The 'end' event is emitted after the response has arrived.
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        expect(logger.logToFile.secondCall.args[0]).to.contain("[... omitted due to file size]");
     });
 
     it("logs requests happening at the same time", async () => {
@@ -363,4 +364,63 @@ describe(path.relative(process.cwd(), __filename), () => {
             `0${date.getHours().toString()}_00_12_GET_http_localhost_8080_request_1.json`
         );
     });
+
+    it("does not rate limit requests by default", async () => {
+        const restClient = new AxiosRestClient();
+        const responses = await Promise.all([
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+        ]);
+        /* eslint-disable @typescript-eslint/no-unsafe-argument */
+        const dateHeader0 = new Date(Number.parseInt(responses[0].headers["x-response-time"]));
+        const dateHeader1 = new Date(Number.parseInt(responses[1].headers["x-response-time"]));
+        const dateHeader2 = new Date(Number.parseInt(responses[2].headers["x-response-time"]));
+        const dateHeader3 = new Date(Number.parseInt(responses[3].headers["x-response-time"]));
+        const dateHeader4 = new Date(Number.parseInt(responses[4].headers["x-response-time"]));
+        const dateHeader5 = new Date(Number.parseInt(responses[5].headers["x-response-time"]));
+        const dateHeader6 = new Date(Number.parseInt(responses[6].headers["x-response-time"]));
+        const dateHeader7 = new Date(Number.parseInt(responses[7].headers["x-response-time"]));
+        const dateHeader8 = new Date(Number.parseInt(responses[8].headers["x-response-time"]));
+        const dateHeader9 = new Date(Number.parseInt(responses[9].headers["x-response-time"]));
+        /* eslint-enable @typescript-eslint/no-unsafe-argument */
+        expect(dateHeader1.getTime() - dateHeader0.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader2.getTime() - dateHeader1.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader3.getTime() - dateHeader2.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader4.getTime() - dateHeader3.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader5.getTime() - dateHeader4.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader6.getTime() - dateHeader5.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader7.getTime() - dateHeader6.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader8.getTime() - dateHeader7.getTime()).to.be.approximately(0, 50);
+        expect(dateHeader9.getTime() - dateHeader8.getTime()).to.be.approximately(0, 50);
+    }).timeout(3000);
+
+    it("rate limits requests", async () => {
+        const restClient = new AxiosRestClient({ rateLimiting: { requestsPerSecond: 2 } });
+        const responses = await Promise.all([
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+            restClient.get(`http://${LOCAL_SERVER.url}`),
+        ]);
+        /* eslint-disable @typescript-eslint/no-unsafe-argument */
+        const dateHeader0 = new Date(Number.parseInt(responses[0].headers["x-response-time"]));
+        const dateHeader1 = new Date(Number.parseInt(responses[1].headers["x-response-time"]));
+        const dateHeader2 = new Date(Number.parseInt(responses[2].headers["x-response-time"]));
+        const dateHeader3 = new Date(Number.parseInt(responses[3].headers["x-response-time"]));
+        const dateHeader4 = new Date(Number.parseInt(responses[4].headers["x-response-time"]));
+        /* eslint-enable @typescript-eslint/no-unsafe-argument */
+        expect(dateHeader1.getTime() - dateHeader0.getTime()).to.be.approximately(500, 50);
+        expect(dateHeader2.getTime() - dateHeader1.getTime()).to.be.approximately(500, 50);
+        expect(dateHeader3.getTime() - dateHeader2.getTime()).to.be.approximately(500, 50);
+        expect(dateHeader4.getTime() - dateHeader3.getTime()).to.be.approximately(500, 50);
+    }).timeout(3000);
 });

src/client/https/requests.ts

@@ -36,6 +36,38 @@ export interface RequestsOptions {
      * Additional options for controlling HTTP behaviour.
      */
     http?: AxiosRequestConfig;
+    /**
+     * Request rate limiting options for this client. If configured, each of the client's requests
+     * can be delayed by a certain amount of time depending on the configured rate limiting scheme.
+     */
+    rateLimiting?: {
+        /**
+         * Avoids rate limits by delaying requests if sending them would exceed the specified
+         * requests per second.
+         *
+         * @example
+         *
+         *
+         * ```ts
+         * // Will send a request at most every 500 milliseconds.
+         * {
+         *   rateLimiting: {
+         *     requestsPerSecond: 2
+         *   }
+         * }
+         * ```
+         *
+         * ```ts
+         * // Will send a request at most every 5 seconds.
+         * {
+         *   rateLimiting: {
+         *     requestsPerSecond: 0.2
+         *   }
+         * }
+         * ```
+         */
+        requestsPerSecond?: number;
+    };
 }
 
 /**
@@ -62,19 +94,22 @@ export interface LoggedRequest {
 
 export class AxiosRestClient {
     private readonly options: RequestsOptions | undefined;
-
-    private axios: AxiosInstance | undefined = undefined;
     private readonly createdLogFiles: Map<string, number>;
+    private axios: AxiosInstance | undefined;
+    private lastRequestTime: number | undefined;
 
     constructor(options?: RequestsOptions) {
         this.options = options;
         this.createdLogFiles = new Map();
+        this.axios = undefined;
+        this.lastRequestTime = undefined;
     }
 
     public async get<R>(
         url: string,
         config?: AxiosRequestConfig<unknown>
     ): Promise<AxiosResponse<R>> {
+        await this.delayIfNeeded();
         const progressInterval = this.startResponseInterval(url);
         try {
             return await this.getAxios().get(url, {
@@ -91,6 +126,7 @@ export class AxiosRestClient {
         data?: D,
         config?: AxiosRequestConfig<D>
     ): Promise<AxiosResponse<R>> {
+        await this.delayIfNeeded();
         const progressInterval = this.startResponseInterval(url);
         try {
             return await this.getAxios().post(url, data, {
@@ -107,6 +143,7 @@ export class AxiosRestClient {
         data?: D,
         config?: AxiosRequestConfig<D>
     ): Promise<AxiosResponse<R>> {
+        await this.delayIfNeeded();
         const progressInterval = this.startResponseInterval(url);
         try {
             return await this.getAxios().put(url, data, {
@@ -196,9 +233,6 @@ export class AxiosRestClient {
                 );
                 LOG.message(Level.DEBUG, `Request:  ${resolvedFilename}`);
             });
-            formData.on("error", (error) => {
-                throw error;
-            });
         } else {
             const resolvedFilename = LOG.logToFile(
                 JSON.stringify(
@@ -290,6 +324,23 @@ export class AxiosRestClient {
             return filename;
         }
     }
+
+    private async delayIfNeeded(): Promise<void> {
+        // We specifically do not use axios interceptors here because we would need to handle
+        // connection timeouts, ECONNRESET etc. otherwise (I think).
+        if (this.options?.rateLimiting?.requestsPerSecond) {
+            const interval = 1000 / this.options.rateLimiting.requestsPerSecond;
+            const now = Date.now();
+            const nextRequestTime = this.lastRequestTime ? this.lastRequestTime + interval : now;
+            this.lastRequestTime = nextRequestTime;
+            const delay = nextRequestTime - now;
+            if (delay > 0) {
+                await new Promise((resolve) => {
+                    setTimeout(resolve, delay);
+                });
+            }
+        }
+    }
 }
 
 function dateToTimestamp(date: Date): string {

src/context.spec.ts

@@ -1275,7 +1275,11 @@ describe(path.relative(process.cwd(), __filename), () => {
                 const httpClients = initHttpClients(undefined, {});
                 expect(httpClients.jira).to.eq(httpClients.xray);
                 expect(httpClients.jira).to.deep.eq(
-                    new AxiosRestClient({ debug: undefined, http: {} })
+                    new AxiosRestClient({
+                        debug: undefined,
+                        http: {},
+                        rateLimiting: undefined,
+                    })
                 );
             });
             it("creates a single client using a single config", () => {
@@ -1296,6 +1300,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                                 port: 12345,
                             },
                         },
+                        rateLimiting: undefined,
                     })
                 );
             });
@@ -1319,16 +1324,18 @@ describe(path.relative(process.cwd(), __filename), () => {
                                 port: 12345,
                             },
                         },
+                        rateLimiting: undefined,
                     })
                 );
                 expect(httpClients.xray).to.deep.eq(
                     new AxiosRestClient({
                         debug: undefined,
                         http: {},
+                        rateLimiting: undefined,
                     })
                 );
             });
-            it("creates a different xray client if a xray config is passed", () => {
+            it("creates a different xray client if an xray config is passed", () => {
                 const httpOptions: InternalHttpOptions = {
                     xray: {
                         proxy: {
@@ -1343,6 +1350,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                     new AxiosRestClient({
                         debug: undefined,
                         http: {},
+                        rateLimiting: undefined,
                     })
                 );
                 expect(httpClients.xray).to.deep.eq(
@@ -1354,10 +1362,11 @@ describe(path.relative(process.cwd(), __filename), () => {
                                 port: 12345,
                             },
                         },
+                        rateLimiting: undefined,
                     })
                 );
             });
-            it("creates different client if individual configs are passed", () => {
+            it("creates different clients if individual configs are passed", () => {
                 const httpOptions: InternalHttpOptions = {
                     jira: {
                         proxy: {
@@ -1383,6 +1392,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                                 port: 98765,
                             },
                         },
+                        rateLimiting: undefined,
                     })
                 );
                 expect(httpClients.xray).to.deep.eq(
@@ -1394,6 +1404,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                                 port: 12345,
                             },
                         },
+                        rateLimiting: undefined,
                     })
                 );
             });
@@ -1405,6 +1416,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                             port: 98765,
                         },
                     },
+                    rateLimiting: { requestsPerSecond: 5 },
                     timeout: 42,
                     xray: {
                         proxy: {
@@ -1425,6 +1437,7 @@ describe(path.relative(process.cwd(), __filename), () => {
                             },
                             timeout: 42,
                         },
+                        rateLimiting: { requestsPerSecond: 5 },
                     })
                 );
                 expect(httpClients.xray).to.deep.eq(
@@ -1437,6 +1450,60 @@ describe(path.relative(process.cwd(), __filename), () => {
                             },
                             timeout: 42,
                         },
+                        rateLimiting: { requestsPerSecond: 5 },
+                    })
+                );
+            });
+            it("prefers individual http options to common ones", () => {
+                const httpOptions: InternalHttpOptions = {
+                    jira: {
+                        proxy: {
+                            host: "http://localhost1",
+                            port: 9999,
+                        },
+                        rateLimiting: { requestsPerSecond: 20 },
+                        timeout: 500,
+                    },
+                    proxy: {
+                        host: "http://localhost2",
+                        port: 5555,
+                    },
+                    rateLimiting: { requestsPerSecond: 10 },
+                    timeout: 42,
+                    xray: {
+                        proxy: {
+                            host: "http://localhost3",
+                            port: 1111,
+                        },
+                        rateLimiting: { requestsPerSecond: 1 },
+                        timeout: 10000,
+                    },
+                };
+                const httpClients = initHttpClients(undefined, httpOptions);
+                expect(httpClients.jira).to.deep.eq(
+                    new AxiosRestClient({
+                        debug: undefined,
+                        http: {
+                            proxy: {
+                                host: "http://localhost1",
+                                port: 9999,
+                            },
+                            timeout: 500,
+                        },
+                        rateLimiting: { requestsPerSecond: 20 },
+                    })
+                );
+                expect(httpClients.xray).to.deep.eq(
+                    new AxiosRestClient({
+                        debug: undefined,
+                        http: {
+                            proxy: {
+                                host: "http://localhost3",
+                                port: 1111,
+                            },
+                            timeout: 10000,
+                        },
+                        rateLimiting: { requestsPerSecond: 1 },
                     })
                 );
             });