[WIP] Add optional rate limiting middleware with provider-level tracking

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original description:

Problem

The FetchClient library currently lacks built-in rate limiting functionality. Users need a way to limit the number of requests made within a specific time window to prevent overwhelming APIs and respect rate limits.

Solution

Implement an optional rate limiting middleware that:

1. Tracks rate limits at the provider level - Rate limiting should be shared across all FetchClient instances created by the same provider
2. Configurable rate limiting options - Allow users to set:
   • Maximum number of requests per time window
   • Time window duration (e.g., per second, per minute)
   • Behavior when rate limit is exceeded (throw error, queue requests, or custom handler)
3. Multiple rate limiting strategies:
   • Sliding window - Track requests over a rolling time period
   • Fixed window - Reset counter at fixed intervals
   • Token bucket - Allow bursts up to a limit with token replenishment
4. Provider-level configuration - Add methods to FetchClientProvider to configure rate limiting
5. Helper functions - Add convenience functions to DefaultHelpers for easy configuration
6. Comprehensive testing - Unit tests covering all rate limiting scenarios

Implementation Requirements

Core Rate Limiting Classes

• Create RateLimiter interface and implementations for different strategies
• Create RateLimitMiddleware that integrates with the existing middleware system
• Add rate limiting options to FetchClientOptions

Provider Integration

• Add rate limiting configuration methods to FetchClientProvider
• Ensure rate limiting state is shared across all FetchClient instances from the same provider
• Add helper functions to DefaultHelpers for convenient configuration

Error Handling

• Define appropriate error types for rate limit exceeded scenarios
• Allow customizable behavior when rate limits are hit

Documentation and Examples

• Add comprehensive JSDoc comments
• Include usage examples in code comments
• Update README with rate limiting examples

Acceptance Criteria

1. ✅ Rate limiting middleware can be configured at the provider level
2. ✅ Multiple rate limiting strategies are supported (sliding window, fixed window, token bucket)
3. ✅ Rate limiting state is shared across all FetchClient instances from the same provider
4. ✅ Configurable behavior when rate limits are exceeded
5. ✅ Helper functions are available for easy configuration
6. ✅ Comprehensive test coverage
7. ✅ Proper TypeScript types and JSDoc documentation
8. ✅ Integration with existing middleware system
9. ✅ Backward compatibility maintained

Technical Notes

• The rate limiting should integrate seamlessly with the existing middleware pipeline
• Use the provider's shared state to track rate limiting across all instances
• Ensure thread safety for concurrent requests
• Consider memory efficiency for long-running applications

This pull request was created as a result of the following prompt from Copilot chat.

Problem

The FetchClient library currently lacks built-in rate limiting functionality. Users need a way to limit the number of requests made within a specific time window to prevent overwhelming APIs and respect rate limits.

Solution

Implement an optional rate limiting middleware that:

1. Tracks rate limits at the provider level - Rate limiting should be shared across all FetchClient instances created by the same provider
2. Configurable rate limiting options - Allow users to set:
   • Maximum number of requests per time window
   • Time window duration (e.g., per second, per minute)
   • Behavior when rate limit is exceeded (throw error, queue requests, or custom handler)
3. Multiple rate limiting strategies:
   • Sliding window - Track requests over a rolling time period
   • Fixed window - Reset counter at fixed intervals
   • Token bucket - Allow bursts up to a limit with token replenishment
4. Provider-level configuration - Add methods to FetchClientProvider to configure rate limiting
5. Helper functions - Add convenience functions to DefaultHelpers for easy configuration
6. Comprehensive testing - Unit tests covering all rate limiting scenarios

Implementation Requirements

Core Rate Limiting Classes

• Create RateLimiter interface and implementations for different strategies
• Create RateLimitMiddleware that integrates with the existing middleware system
• Add rate limiting options to FetchClientOptions

Provider Integration

• Add rate limiting configuration methods to FetchClientProvider
• Ensure rate limiting state is shared across all FetchClient instances from the same provider
• Add helper functions to DefaultHelpers for convenient configuration

Error Handling

• Define appropriate error types for rate limit exceeded scenarios
• Allow customizable behavior when rate limits are hit

Documentation and Examples

• Add comprehensive JSDoc comments
• Include usage examples in code comments
• Update README with rate limiting examples

Acceptance Criteria

1. ✅ Rate limiting middleware can be configured at the provider level
2. ✅ Multiple rate limiting strategies are supported (sliding window, fixed window, token bucket)
3. ✅ Rate limiting state is shared across all FetchClient instances from the same provider
4. ✅ Configurable behavior when rate limits are exceeded
5. ✅ Helper functions are available for easy configuration
6. ✅ Comprehensive test coverage
7. ✅ Proper TypeScript types and JSDoc documentation
8. ✅ Integration with existing middleware system
9. ✅ Backward compatibility maintained

Technical Notes

• The rate limiting should integrate seamlessly with the existing middleware pipeline
• Use the provider's shared state to track rate limiting across all instances
• Ensure thread safety for concurrent requests
• Consider memory efficiency for long-running applications

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}