Add rate limiting support

.vscode/launch.json

@@ -28,7 +28,7 @@
         "--inspect-wait",
         "--allow-all",
         "--filter",
-        "handles 400 response with non-JSON text"
+        "can use per-domain rate limiting with auto-update from headers"
       ],
       "attachSimplePort": 9229
     }

.vscode/tasks.json

@@ -19,6 +19,10 @@
       "problemMatcher": [
         "$deno"
       ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
       "label": "deno: check",
       "detail": "$ deno check scripts/*.ts *.ts src/*.ts"
     },
@@ -43,7 +47,10 @@
       "problemMatcher": [
         "$deno-test"
       ],
-      "group": "test",
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      },
       "label": "deno: test"
     }
   ]

readme.md

@@ -3,12 +3,18 @@
 
 FetchClient is a library that makes it easier to use the fetch API for JSON APIs. It provides the following features:
 
-* [Makes fetch easier to use for JSON APIs](#typed-response)
-* [Automatic model validation](#model-validator)
-* [Caching](#caching)
-* [Middleware](#middleware)
-* [Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) support
-* Option to parse dates in responses
+- [FetchClient   ](#fetchclient---)
+  - [Install](#install)
+  - [Docs](#docs)
+  - [Usage](#usage)
+    - [Typed Response](#typed-response)
+    - [Typed Response Using a Function](#typed-response-using-a-function)
+    - [Model Validator](#model-validator)
+    - [Caching](#caching)
+    - [Middleware](#middleware)
+    - [Rate Limiting](#rate-limiting)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Install
 
@@ -130,6 +136,23 @@ const response = await client.getJSON<Products>(
 );
 ```
 
+### Rate Limiting
+
+```ts
+import { FetchClient, useRateLimit } from '@exceptionless/fetchclient';
+
+// Enable rate limiting globally with 100 requests per minute
+useRateLimit({
+  maxRequests: 100,
+  windowSeconds: 60,
+});
+
+const client = new FetchClient();
+const response = await client.getJSON(
+  `https://api.example.com/data`,
+);
+```
+
 Also, take a look at the tests:
 
 [FetchClient Tests](src/FetchClient.test.ts)

src/DefaultHelpers.ts

@@ -7,6 +7,7 @@ import {
 } from "./FetchClientProvider.ts";
 import type { FetchClientResponse } from "./FetchClientResponse.ts";
 import type { ProblemDetails } from "./ProblemDetails.ts";
+import type { RateLimitMiddlewareOptions } from "./RateLimitMiddleware.ts";
 import type { GetRequestOptions, RequestOptions } from "./RequestOptions.ts";
 
 let getCurrentProviderFunc: () => FetchClientProvider | null = () => null;
@@ -164,3 +165,23 @@ export function useMiddleware(middleware: FetchClientMiddleware) {
 export function setRequestOptions(options: RequestOptions) {
   getCurrentProvider().applyOptions({ defaultRequestOptions: options });
 }
+
+/**
+ * Enables rate limiting for any FetchClient instances created by the current provider.
+ * @param options - The rate limiting configuration options.
+ */
+export function useRateLimit(
+  options: RateLimitMiddlewareOptions,
+) {
+  getCurrentProvider().useRateLimit(options);
+}
+
+/**
+ * Enables per-domain rate limiting for any FetchClient instances created by the current provider.
+ * @param options - The rate limiting configuration options.
+ */
+export function usePerDomainRateLimit(
+  options: Omit<RateLimitMiddlewareOptions, "getGroupFunc">,
+) {
+  getCurrentProvider().usePerDomainRateLimit(options);
+}

src/FetchClient.test.ts

@@ -16,6 +16,10 @@ import {
 } from "../mod.ts";
 import { FetchClientProvider } from "./FetchClientProvider.ts";
 import { z, type ZodTypeAny } from "zod";
+import {
+  buildRateLimitHeader,
+  buildRateLimitPolicyHeader,
+} from "./RateLimiter.ts";
 
 export const TodoSchema = z.object({
   userId: z.number(),
@@ -970,6 +974,122 @@ Deno.test("handles 400 response with non-JSON text", async () => {
   );
 });
 
+Deno.test("can use per-domain rate limiting with auto-update from headers", async () => {
+  const provider = new FetchClientProvider();
+
+  const groupTracker = new Map<string, number>();
+
+  const startTime = Date.now();
+
+  groupTracker.set("api.example.com", 100);
+  groupTracker.set("slow-api.example.com", 5);
+
+  provider.usePerDomainRateLimit({
+    maxRequests: 50, // Default limit
+    windowSeconds: 60, // 1 minute default window
+    autoUpdateFromHeaders: true,
+    groups: {
+      "api.example.com": {
+        maxRequests: 75, // API will override this with headers
+        windowSeconds: 60,
+      },
+      "slow-api.example.com": {
+        maxRequests: 30, // API will override this with headers
+        windowSeconds: 30,
+      },
+    },
+  });
+
+  provider.fetch = (
+    input: RequestInfo | URL,
+    _init?: RequestInit,
+  ): Promise<Response> => {
+    let url: URL;
+    if (input instanceof Request) {
+      url = new URL(input.url);
+    } else {
+      url = new URL(input.toString());
+    }
+
+    const headers = new Headers({
+      "Content-Type": "application/json",
+    });
+
+    // Simulate different rate limits for different domains
+    if (url.hostname === "api.example.com") {
+      headers.set("X-RateLimit-Limit", "100");
+      let remaining = groupTracker.get("api.example.com") ?? 0;
+      remaining = remaining > 0 ? remaining - 2 : 0;
+      groupTracker.set("api.example.com", remaining);
+      headers.set("X-RateLimit-Remaining", String(remaining));
+    } else if (url.hostname === "slow-api.example.com") {
+      let remaining = groupTracker.get("slow-api.example.com") ?? 0;
+      remaining = remaining > 0 ? remaining - 2 : 0;
+      groupTracker.set("slow-api.example.com", remaining);
+
+      headers.set(
+        "RateLimit-Policy",
+        buildRateLimitPolicyHeader({
+          policy: "slow-api.example.com",
+          limit: 5,
+          windowSeconds: 30,
+        }),
+      );
+      headers.set(
+        "RateLimit",
+        buildRateLimitHeader({
+          policy: "slow-api.example.com",
+          remaining: remaining,
+          resetSeconds: 30 - ((Date.now() - startTime) / 1000),
+        }),
+      );
+    }
+    // other-api.example.com gets no rate limit headers
+
+    return Promise.resolve(
+      new Response(JSON.stringify({ success: true }), {
+        status: 200,
+        statusText: "OK",
+        headers,
+      }),
+    );
+  };
+
+  assert(provider.rateLimiter);
+
+  const client = provider.getFetchClient();
+
+  // check API rate limit
+  let apiOptions = provider.rateLimiter.getGroupOptions("api.example.com");
+  assertEquals(apiOptions.maxRequests, 75);
+  assertEquals(apiOptions.windowSeconds, 60);
+
+  const response1 = await client.getJSON(
+    "https://api.example.com/data",
+  );
+  assertEquals(response1.status, 200);
+
+  apiOptions = provider.rateLimiter.getGroupOptions("api.example.com");
+  assertEquals(apiOptions.maxRequests, 100); // Updated from headers
+
+  // check slow API rate limit
+  let slowApiOptions = provider.rateLimiter.getGroupOptions(
+    "slow-api.example.com",
+  );
+  assertEquals(slowApiOptions.maxRequests, 30);
+  assertEquals(slowApiOptions.windowSeconds, 30);
+
+  const response2 = await client.getJSON(
+    "https://slow-api.example.com/data",
+  );
+  assertEquals(response2.status, 200);
+
+  slowApiOptions = provider.rateLimiter.getGroupOptions(
+    "slow-api.example.com",
+  );
+  assertEquals(slowApiOptions.maxRequests, 5); // Updated from headers
+});
+
 function delay(time: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, time));
 }

src/FetchClientProvider.ts

@@ -5,6 +5,11 @@ import type { ProblemDetails } from "./ProblemDetails.ts";
 import { FetchClientCache } from "./FetchClientCache.ts";
 import type { FetchClientOptions } from "./FetchClientOptions.ts";
 import { type IObjectEvent, ObjectEvent } from "./ObjectEvent.ts";
+import {
+  RateLimitMiddleware,
+  type RateLimitMiddlewareOptions,
+} from "./RateLimitMiddleware.ts";
+import { groupByDomain, type RateLimiter } from "./RateLimiter.ts";
 
 type Fetch = typeof globalThis.fetch;
 
@@ -15,6 +20,7 @@ export class FetchClientProvider {
   #options: FetchClientOptions = {};
   #fetch?: Fetch;
   #cache: FetchClientCache;
+  #rateLimitMiddleware?: RateLimitMiddleware;
   #counter = new Counter();
   #onLoading = new ObjectEvent<boolean>();
 
@@ -187,6 +193,47 @@ export class FetchClientProvider {
       ],
     };
   }
+
+  /**
+   * Enables rate limiting for all FetchClient instances created by this provider.
+   * @param options - The rate limiting configuration options.
+   */
+  public useRateLimit(options: RateLimitMiddlewareOptions) {
+    this.#rateLimitMiddleware = new RateLimitMiddleware(options);
+    this.useMiddleware(this.#rateLimitMiddleware.middleware());
+  }
+
+  /**
+   * Enables rate limiting for all FetchClient instances created by this provider.
+   * @param options - The rate limiting configuration options.
+   */
+  public usePerDomainRateLimit(
+    options: Omit<RateLimitMiddlewareOptions, "getGroupFunc">,
+  ) {
+    this.#rateLimitMiddleware = new RateLimitMiddleware({
+      ...options,
+      getGroupFunc: groupByDomain,
+    });
+    this.useMiddleware(this.#rateLimitMiddleware.middleware());
+  }
+
+  /**
+   * Gets the rate limiter instance used for rate limiting.
+   * @returns The rate limiter instance, or undefined if rate limiting is not enabled.
+   */
+  public get rateLimiter(): RateLimiter | undefined {
+    return this.#rateLimitMiddleware?.rateLimiter;
+  }
+
+  /**
+   * Removes the rate limiting middleware from all FetchClient instances created by this provider.
+   */
+  public removeRateLimit() {
+    this.#rateLimitMiddleware = undefined;
+    this.#options.middleware = this.#options.middleware?.filter(
+      (m) => !(m instanceof RateLimitMiddleware),
+    );
+  }
 }
 
 const provider = new FetchClientProvider();