Release Notes - v2.1.0
🔒 Reliability & Resilience Improvements
Enhanced Retry Mechanism with Rate Limiting Support
This release significantly improves the reliability of API calls to Ollama's web services through comprehensive retry logic enhancements.
New Features
- Intelligent Retry Logic: Automatic retry with exponential backoff for transient errors (429, 500, 502, 503, 504)
- Retry-After Header Support: Respects server-provided Retry-After headers in both delay-seconds and HTTP-date formats
- Rate Limit Handling: Graceful handling of 429 Too Many Requests responses with configurable retry strategies
- Request Timeout Management: Built-in timeout support (30s default) with proper AbortController cleanup
- Retry Telemetry: Debug-level logging of retry attempts for production diagnostics
Technical Improvements
- Type Safety: Enhanced error handling with TypeScript unknown type instead of any
- Race Condition Prevention: Documented and tested timeout edge cases
- Exponential Backoff with Full Jitter: Prevents thundering herd problems during rate limiting
- Configurable Retry Options:
- maxRetries - Number of retry attempts (default: 3)
- initialDelay - Initial delay before first retry (default: 1000ms)
- maxDelay - Maximum delay cap (default: 10000ms)
- timeout - Request timeout (default: 30000ms)
New Utilities
- retryWithBackoff() - Wraps any async function with retry logic
- fetchWithTimeout() - Fetch with AbortController-based timeout
- HttpError - Custom error class with status code and Retry-After header support
Web Tool Updates
Both web-search and web-fetch tools now benefit from:
- Automatic retry on rate limiting
- Respect for server-requested retry delays
- Better error messages and failure diagnostics
🧪 Testing Enhancements
- 112 comprehensive tests covering all retry scenarios
- Integration tests with real timing behavior
- Retry-After header parsing tests (seconds and HTTP-date formats)
- Error handling coverage for all HTTP status codes
- Behavior-focused tests avoiding brittle timing assertions
📚 Documentation
- Detailed JSDoc comments explaining retry behavior
- Documented AbortController signal limitations
- Clear examples of retryable vs non-retryable errors
- Telemetry logging documentation
🔧 Internal Improvements
- Reorganized test structure (src/ → tests/ directory)
- Enhanced error messages for debugging
- Better separation of concerns in retry logic
- Improved code maintainability with clear type guards
Full Changelog: See commit history for detailed changes
Upgrade Notes: No breaking changes - this is a backward-compatible enhancement release.