@gitbeaker/rest 39.18.0 → 39.19.0

package/README.md

@@ -76,6 +76,7 @@
 - [API Client](#api-client)
   - [Expanded Payloads](#expanded-payloads)
   - [Pagination](#pagination)
+  - [Rate Limits](#rate-limits)
   - [Error Handling](#error-handling)
 - [Examples](#examples)
 - [Testing](../../docs/TESTING.md)
@@ -155,6 +156,7 @@ Available instantiating options:
 | `queryTimeout`       | Yes      | `300000`                                                                                                                                | Query Timeout in ms                                                                                                |
 | `profileToken`       | Yes      | N/A                                                                                                                                     | [Requests Profiles Token](https://docs.gitlab.com/ee/administration/monitoring/performance/request_profiling.html) |
 | `profileMode`        | Yes      | `execution`                                                                                                                             | [Requests Profiles Token](https://docs.gitlab.com/ee/administration/monitoring/performance/request_profiling.html) |
+| `rateLimits`         | No       | [DEFAULT_RATE_LIMITS](#rate-limits)                                                                                                     | Global and endpoint specific adjustable rate limits                                                                |
 
 > \*One of these options must be supplied.
 
@@ -267,6 +269,72 @@ const { data } = await api.Projects.all({
 });
 ```
 
+### Rate Limits
+
+Rate limits are completely customizable, and are used to limit the request rate between consecutive API requests within the library. By default, all non-specified endpoints use a 3000 rps rate limit, while some endpoints have much smaller rates as dictated by the [Gitlab Docs](https://docs.gitlab.com/ee/security/rate_limits.html). See below for the default values:
+
+```js
+const DEFAULT_RATE_LIMITS = Object.freeze({
+  // Default rate limit
+  '**': 3000,
+
+  // Import/Export
+  'projects/import': 6,
+  'projects/*/export': 6,
+  'projects/*/download': 1,
+  'groups/import': 6,
+  'groups/*/export': 6,
+  'groups/*/download': 1,
+
+  // Note creation
+  'projects/*/issues/*/notes': {
+    method: 'post',
+    limit: 300,
+  },
+  'projects/*/snippets/*/notes': {
+    method: 'post',
+    limit: 300,
+  },
+  'projects/*/merge_requests/*/notes': {
+    method: 'post',
+    limit: 300,
+  },
+  'groups/*/epics/*/notes': {
+    method: 'post',
+    limit: 300,
+  },
+
+  // Repositories - get file archive
+  'projects/*/repository/archive*': 5,
+
+  // Project Jobs
+  'projects/*/jobs': 600,
+
+  // Member deletion
+  'projects/*/members': 60,
+  'groups/*/members': 60,
+});
+```
+
+Rate limits can be overridden when instantiating a API wrapper. For ease of use, these limits are configured using glob patterns, and can be formatted in two ways.
+
+1. The glob for the endpoint with the corresponding rate per second
+2. The glob for the endpoint, with an object specifying the specific method for the endpoint and the corresponding rate limit
+
+```js
+const api = new Gitlab({
+  token: 'token',
+  rateLimits: {
+    '**': 30,
+    'projects/import/*': 40,
+    'projects/*/issues/*/notes': {
+      method: 'post',
+      limit: 300,
+    },
+  },
+});
+```
+
 ### Error Handling
 
 Request errors are returned back within a plain Error instance, using the cause to hold the original response and a text description of the error pulled from the response's error or message fields if JSON, or its plain text value:

package/dist/index.js

@@ -88,7 +88,8 @@ function getConditionalMode(endpoint) {
 async function defaultRequestHandler(endpoint, options) {
   const retryCodes = [429, 502];
   const maxRetries = 10;
-  const { prefixUrl, asStream, searchParams, ...opts } = options || {};
+  const { prefixUrl, asStream, searchParams, rateLimiters, method, ...opts } = options || {};
+  const endpointRateLimit = requesterUtils.getMatchingRateLimiter(endpoint, rateLimiters, method);
   let baseUrl;
   if (prefixUrl)
     baseUrl = prefixUrl.endsWith("/") ? prefixUrl : `${prefixUrl}/`;
@@ -96,7 +97,8 @@ async function defaultRequestHandler(endpoint, options) {
   url.search = searchParams || "";
   const mode = getConditionalMode(endpoint);
   for (let i = 0; i < maxRetries; i += 1) {
-    const request = new Request(url, { ...opts, mode });
+    const request = new Request(url, { ...opts, method, mode });
+    await endpointRateLimit();
     const response = await fetch(request).catch((e) => {
       if (e.name === "TimeoutError" || e.name === "AbortError") {
         throw new Error("Query timeout was reached");

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import * as Resources from '@gitbeaker/core';
-import { createRequesterFn, presetResourceArguments } from '@gitbeaker/requester-utils';
+import { createRequesterFn, presetResourceArguments, getMatchingRateLimiter } from '@gitbeaker/requester-utils';
 
 // src/index.ts
 async function defaultOptionsHandler(resourceOptions, requestOptions) {
@@ -66,7 +66,8 @@ function getConditionalMode(endpoint) {
 async function defaultRequestHandler(endpoint, options) {
   const retryCodes = [429, 502];
   const maxRetries = 10;
-  const { prefixUrl, asStream, searchParams, ...opts } = options || {};
+  const { prefixUrl, asStream, searchParams, rateLimiters, method, ...opts } = options || {};
+  const endpointRateLimit = getMatchingRateLimiter(endpoint, rateLimiters, method);
   let baseUrl;
   if (prefixUrl)
     baseUrl = prefixUrl.endsWith("/") ? prefixUrl : `${prefixUrl}/`;
@@ -74,7 +75,8 @@ async function defaultRequestHandler(endpoint, options) {
   url.search = searchParams || "";
   const mode = getConditionalMode(endpoint);
   for (let i = 0; i < maxRetries; i += 1) {
-    const request = new Request(url, { ...opts, mode });
+    const request = new Request(url, { ...opts, method, mode });
+    await endpointRateLimit();
     const response = await fetch(request).catch((e) => {
       if (e.name === "TimeoutError" || e.name === "AbortError") {
         throw new Error("Query timeout was reached");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitbeaker/rest",
-  "version": "39.18.0",
+  "version": "39.19.0",
   "description": "Cross Platform implementation of the GitLab API",
   "license": "MIT",
   "engines": {
@@ -40,7 +40,7 @@
     "test:types": "tsc",
     "test:e2e:browser": "playwright test",
     "test:e2e": "yarn test:e2e:browser",
-    "test:integration:nodejs": "jest --maxWorkers=50% test/integration/nodejs",
+    "test:integration:nodejs": "jest --maxWorkers=50% test/integration/nodejs/resources/Issues.ts",
     "test:integration": "yarn test:integration:nodejs",
     "test:unit": "jest --maxWorkers=50% test/unit",
     "format:docs": "prettier '**/(*.json|.yml|.js|.md)' --ignore-path ../../.prettierignore",
@@ -56,8 +56,8 @@
     "release": "auto shipit"
   },
   "dependencies": {
-    "@gitbeaker/core": "^39.18.0",
-    "@gitbeaker/requester-utils": "^39.18.0"
+    "@gitbeaker/core": "^39.19.0",
+    "@gitbeaker/requester-utils": "^39.19.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.35.1",
@@ -65,5 +65,5 @@
     "tsup": "^7.1.0",
     "typescript": "^5.1.6"
   },
-  "gitHead": "41b250e761aa15d8605c50b76d8439af827e06b5"
+  "gitHead": "b6ac7ead7ee50ced0f99f66ea0c212d2afcba3c2"
 }