feat(client): add handle429Backoff method for intelligent rate limit handling

changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2025-07-29 - 4.2.0 - feat(client)
+Add handle429Backoff method for intelligent rate limit handling
+
+**Features:**
+- Added `handle429Backoff()` method to SmartRequest class for automatic HTTP 429 handling
+- Respects `Retry-After` headers with support for both seconds and HTTP date formats
+- Configurable exponential backoff when no Retry-After header is present
+- Added `RateLimitConfig` interface with customizable retry behavior
+- Optional callback for monitoring rate limit events
+- Maximum wait time capping to prevent excessive delays
+
+**Improvements:**
+- Updated test endpoints to use more reliable services (jsonplaceholder, echo.zuplo.io)
+- Added timeout parameter to test script for better CI/CD compatibility
+
+**Documentation:**
+- Added comprehensive rate limiting section to README with examples
+- Documented all configuration options for handle429Backoff
+
 ## 2025-07-29 - 4.1.0 - feat(client)
 Add missing options() method to SmartRequest client
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartrequest",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": false,
   "description": "A module for modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, streams, and more.",
   "exports": {
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "scripts": {
-    "test": "(tstest test/ --verbose)",
+    "test": "(tstest test/ --verbose --timeout 60)",
     "build": "(tsbuild --web)",
     "buildDocs": "tsdoc"
   },

readme.md

@@ -361,6 +361,69 @@ async function performMultipleRequests() {
 }
 ```
 
+### Rate Limiting (429 Too Many Requests) Handling
+
+The library includes built-in support for handling HTTP 429 (Too Many Requests) responses with intelligent backoff:
+
+```typescript
+import { SmartRequest } from '@push.rocks/smartrequest';
+
+// Simple usage - handle 429 with defaults
+async function fetchWithRateLimitHandling() {
+  const response = await SmartRequest.create()
+    .url('https://api.example.com/data')
+    .handle429Backoff()  // Automatically retry on 429
+    .get();
+
+  return await response.json();
+}
+
+// Advanced usage with custom configuration
+async function fetchWithCustomRateLimiting() {
+  const response = await SmartRequest.create()
+    .url('https://api.example.com/data')
+    .handle429Backoff({
+      maxRetries: 5,              // Try up to 5 times (default: 3)
+      respectRetryAfter: true,    // Honor Retry-After header (default: true)
+      maxWaitTime: 30000,         // Max 30 seconds wait (default: 60000)
+      fallbackDelay: 2000,        // 2s initial delay if no Retry-After (default: 1000)
+      backoffFactor: 2,           // Exponential backoff multiplier (default: 2)
+      onRateLimit: (attempt, waitTime) => {
+        console.log(`Rate limited. Attempt ${attempt}, waiting ${waitTime}ms`);
+      }
+    })
+    .get();
+
+  return await response.json();
+}
+
+// Example: API client with rate limit handling
+class RateLimitedApiClient {
+  private async request(path: string) {
+    return SmartRequest.create()
+      .url(`https://api.example.com${path}`)
+      .handle429Backoff({
+        maxRetries: 3,
+        onRateLimit: (attempt, waitTime) => {
+          console.log(`API rate limit hit. Waiting ${waitTime}ms before retry ${attempt}`);
+        }
+      });
+  }
+
+  async fetchData(id: string) {
+    const response = await this.request(`/data/${id}`).get();
+    return response.json();
+  }
+}
+```
+
+The rate limiting feature:
+- Automatically detects 429 responses and retries with backoff
+- Respects the `Retry-After` header when present (supports both seconds and HTTP date formats)
+- Uses exponential backoff when no `Retry-After` header is provided
+- Allows custom callbacks for monitoring rate limit events
+- Caps maximum wait time to prevent excessive delays
+
 ## Platform-Specific Features
 
 ### Browser-Specific Options

test/test.browser.ts

@@ -41,15 +41,17 @@ tap.test('browser: should handle request timeouts', async () => {
   let timedOut = false;
   
   const options: ICoreRequestOptions = {
-    timeout: 1000
+    timeout: 100 // Very short timeout
   };
   
   try {
-    const request = new CoreRequest('https://httpbin.org/delay/10', options);
+    // Use a URL that will likely take longer than 100ms
+    const request = new CoreRequest('https://jsonplaceholder.typicode.com/photos', options);
     await request.fire();
   } catch (error) {
     timedOut = true;
-    expect(error.message).toContain('timed out');
+    // Different browsers might have different timeout error messages
+    expect(error.message.toLowerCase()).toMatch(/timeout|timed out|aborted/i);
   }
   
   expect(timedOut).toEqual(true);
@@ -82,21 +84,22 @@ tap.test('browser: should handle POST requests with JSON', async () => {
 tap.test('browser: should handle query parameters', async () => {
   const options: ICoreRequestOptions = {
     queryParams: {
-      foo: 'bar',
-      baz: 'qux'
+      userId: '2'
     }
   };
   
-  const request = new CoreRequest('https://httpbin.org/get', options);
+  const request = new CoreRequest('https://jsonplaceholder.typicode.com/posts', options);
   const response = await request.fire();
     
   expect(response.status).toEqual(200);
   
   const data = await response.json();
-  expect(data.args).toHaveProperty('foo');
-  expect(data.args.foo).toEqual('bar');
-  expect(data.args).toHaveProperty('baz');
-  expect(data.args.baz).toEqual('qux');
+  expect(Array.isArray(data)).toBeTrue();
+  // Verify we got posts filtered by userId 2
+  if (data.length > 0) {
+    expect(data[0]).toHaveProperty('userId');
+    expect(data[0].userId).toEqual(2);
+  }
 });
 
 export default tap.start();

test/test.node.ts

@@ -25,16 +25,16 @@ tap.test('client: should request a JSON document over https', async () => {
 });
 
 tap.test('client: should post a JSON document over http', async () => {
-  const testData = { text: 'example_text' };
+  const testData = { title: 'example_text', body: 'test body', userId: 1 };
   const response = await SmartRequest.create()
-    .url('https://httpbin.org/post')
+    .url('https://jsonplaceholder.typicode.com/posts')
     .json(testData)
     .post();
 
   const body = await response.json();
-  expect(body).toHaveProperty('json');
-  expect(body.json).toHaveProperty('text');
-  expect(body.json.text).toEqual('example_text');
+  expect(body).toHaveProperty('title');
+  expect(body.title).toEqual('example_text');
+  expect(body).toHaveProperty('id'); // jsonplaceholder returns an id for created posts
 });
 
 tap.test('client: should set headers correctly', async () => {
@@ -42,32 +42,34 @@ tap.test('client: should set headers correctly', async () => {
   const headerValue = 'test-value';
 
   const response = await SmartRequest.create()
-    .url('https://httpbin.org/headers')
+    .url('https://echo.zuplo.io/')
     .header(customHeader, headerValue)
     .get();
 
   const body = await response.json();
   expect(body).toHaveProperty('headers');
 
-  // Check if the header exists (case-sensitive)
-  expect(body.headers).toHaveProperty(customHeader);
-  expect(body.headers[customHeader]).toEqual(headerValue);
+  // Check if the header exists (headers might be lowercase)
+  const headers = body.headers;
+  const headerFound = headers[customHeader] || headers[customHeader.toLowerCase()] || headers['x-custom-header'];
+  expect(headerFound).toEqual(headerValue);
 });
 
 tap.test('client: should handle query parameters', async () => {
-  const params = { param1: 'value1', param2: 'value2' };
+  const params = { userId: '1' };
 
   const response = await SmartRequest.create()
-    .url('https://httpbin.org/get')
+    .url('https://jsonplaceholder.typicode.com/posts')
     .query(params)
     .get();
 
   const body = await response.json();
-  expect(body).toHaveProperty('args');
-  expect(body.args).toHaveProperty('param1');
-  expect(body.args.param1).toEqual('value1');
-  expect(body.args).toHaveProperty('param2');
-  expect(body.args.param2).toEqual('value2');
+  expect(Array.isArray(body)).toBeTrue();
+  // Check that we got posts for userId 1
+  if (body.length > 0) {
+    expect(body[0]).toHaveProperty('userId');
+    expect(body[0].userId).toEqual(1);
+  }
 });
 
 tap.test('client: should handle timeout configuration', async () => {