Add resourceKeyResolver for rate-limit keys

.changeset/slow-poets-clap.md

@@ -0,0 +1,5 @@
+---
+"@http-client-toolkit/core": minor
+---
+
+Add a top-level `resourceKeyResolver` option for rate-limit bucketing, deprecate legacy `rateLimit.resourceExtractor`, and preserve backward-compatible fallback behavior.

docs-site/src/content/docs/api/http-client.mdx

@@ -28,6 +28,7 @@ new HttpClient(options)
 | `cache` | `HttpClientCacheOptions` | — | Cache configuration (see below) |
 | `dedupe` | `DedupeStore<T>` | — | Request deduplication |
 | `rateLimit` | `HttpClientRateLimitOptions` | — | Rate limit configuration (see below) |
+| `resourceKeyResolver` | `(url: string) => string` | URL origin | Resolve the logical rate-limit resource key for a URL |
 | `fetchFn` | `(url: string, init?: RequestInit) => Promise<Response>` | `globalThis.fetch` | Custom fetch implementation |
 | `requestInterceptor` | `(url: string, init: RequestInit) => Promise<RequestInit> \| RequestInit` | — | Pre-request hook to modify the outgoing request |
 | `responseInterceptor` | `(response: Response, url: string) => Promise<Response> \| Response` | — | Post-response hook to inspect/modify the raw Response |
@@ -53,10 +54,12 @@ new HttpClient(options)
 | `throw` | `boolean` | `true` | Throw when rate limited vs. wait |
 | `maxWaitTime` | `number` | `60000` | Max wait time in ms before throwing |
 | `headers` | `RateLimitHeaderConfig` | defaults | Configure standard/custom header names |
-| `resourceExtractor` | `(url: string) => string` | URL origin | Extract rate-limit resource key from URL |
+| `resourceExtractor` | `(url: string) => string` | URL origin | Deprecated. Use `resourceKeyResolver` instead |
 | `configs` | `RateLimitConfigMap` | — | Per-resource rate limit configurations |
 | `defaultConfig` | `RateLimitConfig` | — | Fallback rate limit config when no per-resource config matches |
 
+`resourceKeyResolver` applies everywhere the client performs rate-limit accounting, including store checks and server cooldowns. `rateLimit.resourceExtractor` is deprecated, retained for compatibility, and only used when `resourceKeyResolver` is not provided.
+
 ## Methods
 
 ### `get<T>(url, options?)`

docs-site/src/content/docs/guides/recommended-usage.mdx

@@ -170,7 +170,7 @@ All clients share one database and one set of stores, but cache entries are scop
 |---------|-------------------|---------------|
 | **Cache** | Private — keys prefixed with client name (e.g. `github:hash`) | Set `globalScope: true` to share cache entries across clients |
 | **Dedup** | Shared — uses the raw request hash with no client prefix | Dedup is always shared when clients use the same store, which is usually desirable |
-| **Rate limit** | Shared by resource — tracked per URL origin, not per client | Use `resourceExtractor` to customise how resources are derived from URLs |
+| **Rate limit** | Shared by resource — tracked per URL origin, not per client | Use `resourceKeyResolver` to customise how resources are derived from URLs. `resourceExtractor` is deprecated |
 
 ### Sharing Cache Across Clients
 

packages/core/README.md

@@ -82,21 +82,22 @@ Create a thin wrapper module per third-party API so callers don't configure anyt
 
 **Constructor options:**
 
-| Property              | Type                                       | Default  | Description                             |
-| --------------------- | ------------------------------------------ | -------- | --------------------------------------- |
-| `name`                | `string`                                   | required | Name for the client instance            |
-| `cache`               | `CacheStore`                               | -        | Response caching                        |
-| `dedupe`              | `DedupeStore`                              | -        | Request deduplication                   |
-| `rateLimit`           | `RateLimitStore \| AdaptiveRateLimitStore` | -        | Rate limiting                           |
-| `cacheTTL`            | `number`                                   | `3600`   | Cache TTL when response has no headers  |
-| `throwOnRateLimit`    | `boolean`                                  | `true`   | Throw when rate limited vs. wait        |
-| `maxWaitTime`         | `number`                                   | `60000`  | Max wait time (ms) before throwing      |
-| `responseTransformer` | `(data: unknown) => unknown`               | -        | Transform raw response data             |
-| `responseHandler`     | `(data: unknown) => unknown`               | -        | Validate/process transformed data       |
-| `errorHandler`        | `(error: unknown) => Error`                | -        | Convert errors to domain-specific types |
-| `cacheOverrides`      | `CacheOverrideOptions`                     | -        | Override cache header behaviors         |
-| `retry`               | `RetryOptions \| false`                    | -        | Retry config; `false` disables globally |
-| `rateLimitHeaders`    | `RateLimitHeaderConfig`                    | defaults | Configure standard/custom header names  |
+| Property              | Type                                       | Default    | Description                                        |
+| --------------------- | ------------------------------------------ | ---------- | -------------------------------------------------- |
+| `name`                | `string`                                   | required   | Name for the client instance                       |
+| `cache`               | `CacheStore`                               | -          | Response caching                                   |
+| `dedupe`              | `DedupeStore`                              | -          | Request deduplication                              |
+| `rateLimit`           | `RateLimitStore \| AdaptiveRateLimitStore` | -          | Rate limiting                                      |
+| `cacheTTL`            | `number`                                   | `3600`     | Cache TTL when response has no headers             |
+| `throwOnRateLimit`    | `boolean`                                  | `true`     | Throw when rate limited vs. wait                   |
+| `maxWaitTime`         | `number`                                   | `60000`    | Max wait time (ms) before throwing                 |
+| `responseTransformer` | `(data: unknown) => unknown`               | -          | Transform raw response data                        |
+| `responseHandler`     | `(data: unknown) => unknown`               | -          | Validate/process transformed data                  |
+| `errorHandler`        | `(error: unknown) => Error`                | -          | Convert errors to domain-specific types            |
+| `cacheOverrides`      | `CacheOverrideOptions`                     | -          | Override cache header behaviors                    |
+| `retry`               | `RetryOptions \| false`                    | -          | Retry config; `false` disables globally            |
+| `rateLimitHeaders`    | `RateLimitHeaderConfig`                    | defaults   | Configure standard/custom header names             |
+| `resourceKeyResolver` | `(url: string) => string`                  | URL origin | Customize how rate-limit resource keys are derived |
 
 ### Request Flow
 
@@ -155,6 +156,30 @@ const client = new HttpClient({
 });
 ```
 
+### Custom Rate-Limit Buckets
+
+Use `resourceKeyResolver` when list and retrieve routes should share the same
+rate-limit bucket:
+
+```typescript
+const client = new HttpClient({
+  name: 'issues-api',
+  resourceKeyResolver: (url) => {
+    const path = new URL(url).pathname;
+    if (path === '/api/issues' || path.startsWith('/api/issue/')) {
+      return 'issues';
+    }
+    return new URL(url).origin;
+  },
+  rateLimit: {
+    store: rateLimitStore,
+  },
+});
+```
+
+`rateLimit.resourceExtractor` is deprecated and kept temporarily for backward
+compatibility.
+
 ### Exports
 
 - `HttpClient` - Main client class

packages/core/src/http-client/http-client.test.ts

@@ -302,7 +302,7 @@ describe('HttpClient', () => {
     );
 
     await expect(client.get(`${baseUrl}/blocked-by-cooldown`)).rejects.toThrow(
-      /Rate limit exceeded for origin/,
+      /Rate limit exceeded for resource/,
     );
   });
 
@@ -322,7 +322,7 @@ describe('HttpClient', () => {
     expect(result.ok).toBe(true);
 
     await expect(client.get(`${baseUrl}/cooldown-active`)).rejects.toThrow(
-      /Rate limit exceeded for origin/,
+      /Rate limit exceeded for resource/,
     );
   });
 
@@ -352,7 +352,7 @@ describe('HttpClient', () => {
     expect(result.ok).toBe(true);
 
     await expect(client.get(`${baseUrl}/custom-cooldown`)).rejects.toThrow(
-      /Rate limit exceeded for origin/,
+      /Rate limit exceeded for resource/,
     );
   });
 
@@ -907,8 +907,7 @@ describe('HttpClient', () => {
         remaining?: number;
         resetMs?: number;
       };
-      getOriginScope: (url: string) => string;
-      getResource: (url: string) => string;
+      resolveRateLimitKey: (url: string) => string;
     };
 
     expect(privateClient.normalizeHeaderNames(undefined, ['x-a'])).toEqual([
@@ -958,9 +957,11 @@ describe('HttpClient', () => {
     });
     expect(privateClient.parseCombinedRateLimitHeader(undefined)).toEqual({});
 
-    expect(privateClient.getOriginScope('not-a-url')).toBe('unknown');
-    expect(privateClient.getResource('/still-not-a-url')).toBe('unknown');
-    expect(privateClient.getResource(`${baseUrl}/`)).toBe(baseUrl);
+    expect(privateClient.resolveRateLimitKey('not-a-url')).toBe('unknown');
+    expect(privateClient.resolveRateLimitKey('/still-not-a-url')).toBe(
+      'unknown',
+    );
+    expect(privateClient.resolveRateLimitKey(`${baseUrl}/`)).toBe(baseUrl);
 
     const privateApplyClient = client as unknown as {
       applyServerRateLimitHints: (
@@ -1003,7 +1004,7 @@ describe('HttpClient', () => {
 
     const privateClient = client as unknown as {
       serverCooldowns: Map<string, number>;
-      getOriginScope: (url: string) => string;
+      resolveRateLimitKey: (url: string) => string;
       enforceServerCooldown: (
         url: string,
         signal?: AbortSignal,
@@ -1015,7 +1016,7 @@ describe('HttpClient', () => {
       ) => Promise<boolean>;
     };
 
-    const scope = privateClient.getOriginScope(baseUrl);
+    const scope = privateClient.resolveRateLimitKey(baseUrl);
     privateClient.serverCooldowns.set(scope, Date.now() + 1);
     await expect(
       privateClient.enforceServerCooldown(`${baseUrl}/cooldown-wait`),
@@ -1127,11 +1128,11 @@ describe('HttpClient', () => {
 
     const waitingPrivate = waitingClient as unknown as {
       serverCooldowns: Map<string, number>;
-      getOriginScope: (url: string) => string;
+      resolveRateLimitKey: (url: string) => string;
       enforceServerCooldown: (url: string) => Promise<void>;
     };
 
-    const scope = waitingPrivate.getOriginScope(baseUrl);
+    const scope = waitingPrivate.resolveRateLimitKey(baseUrl);
     waitingPrivate.serverCooldowns.set(scope, Date.now() + 50);
 
     await expect(
@@ -3700,64 +3701,160 @@ describe('HttpClient', () => {
       });
     });
 
-    describe('resourceExtractor', () => {
-      test('overrides default origin-based resource extraction', async () => {
-        let recordedResource: string | undefined;
+    describe('resourceKeyResolver', () => {
+      test('uses the origin by default', () => {
+        const client = new HttpClient({ name: 'test' });
+        const privateClient = client as unknown as {
+          resolveRateLimitKey: (url: string) => string;
+        };
+
+        expect(privateClient.resolveRateLimitKey(`${baseUrl}/items`)).toBe(
+          baseUrl,
+        );
+      });
+
+      test('uses HttpClientOptions.resourceKeyResolver when provided', () => {
+        const client = new HttpClient({
+          name: 'test',
+          resourceKeyResolver: (url) => `custom:${new URL(url).pathname}`,
+        });
+        const privateClient = client as unknown as {
+          resolveRateLimitKey: (url: string) => string;
+        };
+
+        expect(privateClient.resolveRateLimitKey(`${baseUrl}/items`)).toBe(
+          'custom:/items',
+        );
+      });
+
+      test('falls back to legacy rateLimit.resourceExtractor', () => {
+        const client = new HttpClient({
+          name: 'test',
+          rateLimit: {
+            resourceExtractor: (url) => `legacy:${new URL(url).pathname}`,
+          },
+        });
+        const privateClient = client as unknown as {
+          resolveRateLimitKey: (url: string) => string;
+        };
+
+        expect(privateClient.resolveRateLimitKey(`${baseUrl}/items`)).toBe(
+          'legacy:/items',
+        );
+      });
+
+      test('prefers resourceKeyResolver over legacy resourceExtractor', () => {
+        const client = new HttpClient({
+          name: 'test',
+          resourceKeyResolver: () => 'top-level',
+          rateLimit: {
+            resourceExtractor: () => 'legacy',
+          },
+        });
+        const privateClient = client as unknown as {
+          resolveRateLimitKey: (url: string) => string;
+        };
+
+        expect(privateClient.resolveRateLimitKey(`${baseUrl}/items`)).toBe(
+          'top-level',
+        );
+      });
+
+      test('uses the custom resolver for canProceed, getWaitTime, and record', async () => {
+        nock(baseUrl).get('/api/issues').reply(200, { ok: true });
+
+        const calls = {
+          canProceed: [] as Array<string>,
+          getWaitTime: [] as Array<string>,
+          record: [] as Array<string>,
+        };
+        let canProceedChecks = 0;
+
         const rateLimitStub = {
           async canProceed(resource: string) {
-            recordedResource = resource;
-            return true;
+            calls.canProceed.push(resource);
+            canProceedChecks += 1;
+            return canProceedChecks > 1;
+          },
+          async record(resource: string) {
+            calls.record.push(resource);
           },
-          async record() {},
           async getStatus() {
             return { remaining: 1, resetTime: new Date(), limit: 60 };
           },
           async reset() {},
-          async getWaitTime() {
+          async getWaitTime(resource: string) {
+            calls.getWaitTime.push(resource);
             return 0;
           },
         } as const;
 
         const client = new HttpClient({
           name: 'test',
-          rateLimit: {
-            store: rateLimitStub,
-            resourceExtractor: (url) => {
-              const u = new URL(url);
-              return `${u.origin}${u.pathname}`;
-            },
-          },
+          resourceKeyResolver: (url) =>
+            new URL(url).pathname.startsWith('/api/issue/')
+              ? 'issues'
+              : (new URL(url).pathname.split('/').filter(Boolean).at(-1) ??
+                'unknown'),
+          rateLimit: { store: rateLimitStub, throw: false },
         });
 
-        nock(baseUrl).get('/items/42').reply(200, { id: 42 });
-
-        await client.get(`${baseUrl}/items/42`);
+        await client.get(`${baseUrl}/api/issues`);
 
-        expect(recordedResource).toBe(`${baseUrl}/items/42`);
+        expect(calls.canProceed).toEqual(['issues', 'issues']);
+        expect(calls.getWaitTime).toEqual(['issues']);
+        expect(calls.record).toEqual(['issues']);
       });
 
-      test('getResource uses origin by default', () => {
-        const client = new HttpClient({ name: 'test' });
-        const privateClient = client as unknown as {
-          getResource: (url: string) => string;
-        };
+      test('normalizes retrieve and list URLs into the same rate-limit bucket', async () => {
+        nock(baseUrl)
+          .get('/api/issue/4000-123')
+          .reply(429, { message: 'slow down' }, { 'Retry-After': '1' });
 
-        expect(privateClient.getResource(`${baseUrl}/items`)).toBe(baseUrl);
-      });
+        const cooldowns = new Map<string, number>();
+        const rateLimitStub = {
+          async canProceed() {
+            return true;
+          },
+          async record() {},
+          async getStatus() {
+            return { remaining: 1, resetTime: new Date(), limit: 60 };
+          },
+          async reset() {},
+          async getWaitTime() {
+            return 0;
+          },
+          async setCooldown(resource: string, cooldownUntilMs: number) {
+            cooldowns.set(resource, cooldownUntilMs);
+          },
+          async getCooldown(resource: string) {
+            return cooldowns.get(resource);
+          },
+          async clearCooldown(resource: string) {
+            cooldowns.delete(resource);
+          },
+        };
 
-      test('getResource uses resourceExtractor when provided', () => {
         const client = new HttpClient({
           name: 'test',
-          rateLimit: {
-            resourceExtractor: (url) => `custom:${new URL(url).pathname}`,
+          resourceKeyResolver: (url) => {
+            const path = new URL(url).pathname;
+            if (path === '/api/issues' || path.startsWith('/api/issue/')) {
+              return 'issues';
+            }
+            return path.split('/').filter(Boolean).at(-1) ?? 'unknown';
           },
+          rateLimit: { store: rateLimitStub, throw: true },
         });
-        const privateClient = client as unknown as {
-          getResource: (url: string) => string;
-        };
 
-        expect(privateClient.getResource(`${baseUrl}/items`)).toBe(
-          'custom:/items',
+        await expect(
+          client.get(`${baseUrl}/api/issue/4000-123`),
+        ).rejects.toThrow(HttpClientError);
+
+        expect(cooldowns.has('issues')).toBe(true);
+
+        await expect(client.get(`${baseUrl}/api/issues`)).rejects.toThrow(
+          /Rate limit exceeded for resource 'issues'/,
         );
       });
     });