@autofleet/rapido-http-client 0.0.1

package/README.md

@@ -0,0 +1,780 @@
+# @autofleet/rapido-http-client
+
+> [!TIP]
+> TL;DR - Modern, high-performance HTTP client built on [undici](https://github.com/nodejs/undici) - Node.js's official modern HTTP client.
+
+**Rapido HTTP Client** is a high-performance, type-safe HTTP client for Node.js applications, built on top of [undici](https://github.com/nodejs/undici). It offers advanced features like automatic retries, caching, schema validation with Zod, and seamless integration with service discovery systems.
+
+## Why Rapido HTTP Client?
+
+Rapido HTTP Client is the next-generation replacement for `@autofleet/network`, designed from the ground up for modern Node.js applications:
+### Key Advantages Over @autofleet/network
+
+| Feature | Rapido HTTP Client (undici) | Network (axios) |
+|---------|-------------------|-----------------|
+| **Performance** | ✅ Undici by Node.js, nearly 200x faster | ❌ Axios is not optimized for speed |
+| **Modern APIs** | ✅ Built-in caching, retry interceptors | ❌ Requires plugins |
+| **Type Safety** | ✅ Full TypeScript + Opt-in Zod validation | ⚠️ Only type casting (with generics) |
+| **Memory Efficiency** | ✅ Connection pooling | ⚠️ No pooling, slower connections |
+| **Maintenance** | ✅ Official Node.js project | ⚠️ Unmaintained version of Axios (0.x) |
+
+### Performance Benchmarks
+
+Benchmarks comparing Rapido HTTP Client (undici) vs Network (axios):
+
+| Operation | Rapido HTTP Client (ops/sec) | Network (ops/sec) | **Performance Gain** |
+|-----------|---------------------|-------------------|----------------------|
+| Initialization | 1,173,118 | 60,947 | **19.2x faster** ⚡ |
+| Simple GET | 61,916 | 319 | **194x faster** ⚡ |
+| POST with body | 61,459 | 334 | **184x faster** ⚡ |
+| GET with params | 58,347 | 270 | **216x faster** ⚡ |
+| PUT request | 64,213 | 349 | **184x faster** ⚡ |
+| DELETE request | 111,402 | 624 | **178x faster** ⚡ |
+| With Zod schema | 58,860 | 289 | **204x faster** ⚡ |
+| getAllPages | 20,654 | 119 | **173x faster** ⚡ |
+| With retries | 827 | 146 | **5.7x faster** ⚡ |
+
+**Rapido HTTP Client is 170-200x faster** than Network for most operations, especially in happy-paths!
+
+Take into account that these benchmarks are run in ideal conditions - no actual network latency. In real-world scenarios, the performance gap may be even larger due to Rapido HTTP Client's efficient connection pooling and lower overhead.
+It might also become smaller in high-latency networks, where network time dominates processing time.
+
+## Installation
+
+```bash
+npm i @autofleet/rapido-http-client
+```
+
+### Optional Dependencies
+
+For schema validation support:
+```bash
+npm i zod
+```
+
+## Quick Start
+
+<details>
+<summary><b>Basic Usage</b></summary>
+
+```typescript
+import RapidoHttpClient from '@autofleet/rapido-http-client';
+import { logger } from '@autofleet/logger';
+
+const client = new RapidoHttpClient({
+  logger,
+  serviceUrl: 'https://api.example.com',
+});
+
+// Simple GET request
+const { data, status } = await client.get('/users');
+
+// POST with body
+const response = await client.post('/users', {
+  name: 'John Doe',
+  email: 'john@example.com',
+});
+
+// Clean up when done
+await client.close();
+```
+
+</details>
+
+<details>
+<summary><b>With Service Discovery (Kubernetes)</b></summary>
+
+```typescript
+const client = new RapidoHttpClient({
+  logger,
+  serviceName: 'USER', // Reads from USER_SERVICE_HOST env var
+});
+
+const { data } = await client.get('/profile');
+```
+
+</details>
+
+<details>
+<summary><b>With Retry Logic</b></summary>
+
+```typescript
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+  retries: {
+    maxRetries: 3,
+    minTimeout: 100,
+    timeoutFactor: 2, // Exponential backoff
+    statusCodes: [429, 500, 502, 503], // Retry on these status codes
+  },
+});
+
+// Automatically retries on failure
+const { data } = await client.get('/flaky-endpoint');
+```
+
+</details>
+
+<details>
+<summary><b>With HTTP Caching</b></summary>
+
+```typescript
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+  cache: {
+    maxCount: 1000,       // Max cached responses
+    maxSize: 10 * 1024 * 1024, // 10MB cache size
+  },
+});
+
+// First request hits network
+const response1 = await client.get('/data');
+
+// Second request returns from cache (if cache-control headers permit)
+const response2 = await client.get('/data');
+```
+
+</details>
+
+<details>
+<summary><b>With Zod Schema Validation</b></summary>
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+});
+
+// Type is automatically inferred from schema!
+const { data } = await client.get('/user/123', {
+  responseSchema: UserSchema,
+});
+
+// TypeScript knows: data is { id: number; name: string; email: string; role: 'admin' | 'user' }
+console.log(data.name); // ✅ Type-safe & Runtime-validated!
+
+// Throws ZodError if response doesn't match schema
+```
+
+</details>
+
+<details>
+<summary><b>Request Timeouts & Cancellation</b></summary>
+
+```typescript
+// Global timeout for all requests
+const client = new RapidoHttpClient({
+  logger,
+  timeout: 5_000, // 5 seconds
+  serviceUrl: 'https://api.example.com',
+});
+
+// Override timeout per request
+await client.get('/slow-endpoint', { timeout: 10_000 });
+
+// Manual cancellation with AbortSignal
+try {
+  await client.get('/data', { signal: AbortSignal.timeout(3_000) });
+} catch (error) {
+  // RequestAbortedError thrown when cancelled
+}
+```
+
+</details>
+
+<details>
+<summary><b>Query Parameters</b></summary>
+
+```typescript
+// Simple params
+await client.get('/search', {
+  params: { q: 'nodejs', limit: 10 },
+});
+// → GET /search?q=nodejs&limit=10
+
+// Array params (auto-formatted with [])
+await client.get('/filter', {
+  params: { tags: ['typescript', 'nodejs'] },
+});
+// → GET /filter?tags[]=typescript&tags[]=nodejs
+```
+
+</details>
+
+<details>
+<summary><b>Custom Headers & Outbreak Tracing</b></summary>
+
+```typescript
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+  headers: {
+    'X-API-Key': 'secret-key',
+    'X-Custom-Header': 'value',
+  },
+});
+
+// Outbreak trace headers are automatically injected
+// from the current context (x-trace-id, x-correlation-id, etc.)
+await client.get('/data');
+
+// Override headers per request
+await client.get('/data', {
+  headers: { 'X-Request-Specific': 'value' },
+});
+```
+
+</details>
+
+<details>
+<summary><b>Pagination Helpers</b></summary>
+
+```typescript
+// Fetch all pages from a paginated GET endpoint
+const allItems = await client.getAllPages<Item>('/api/items');
+// Automatically fetches pages until no more data
+
+// Fetch all pages from a POST query endpoint
+const allResults = await client.getAllPagesFromQueryEndpoint<Result>(
+  '/api/query',
+  { filter: 'active' }, // Additional query parameters
+  100 // Max pages (default: 100, -1 for unlimited)
+);
+```
+
+</details>
+
+<details>
+<summary><b>Async Disposal (Node.js 20+)</b></summary>
+
+```typescript
+// Automatic cleanup with async using
+{
+  await using client = new RapidoHttpClient({
+    serviceUrl: 'https://api.example.com',
+    logger,
+  });
+
+  await client.get('/data');
+
+  // client.close() called automatically when scope exits
+}
+```
+
+</details>
+
+<details>
+<summary><b>Automatic Response Decompression</b></summary>
+
+```typescript
+// Enable automatic decompression of gzip, brotli, deflate, and zstd responses
+const client = new RapidoHttpClient({
+  logger,
+  autoDecompress: true,
+  serviceUrl: 'https://api.example.com',
+});
+
+// Automatically decompresses compressed responses
+// Sets Accept-Encoding header to: zstd, br, gzip (or br, gzip if Node version is lacking zstd support)
+const { data } = await client.get('/data');
+
+// Works with both success and error responses
+// No need to manually handle content-encoding headers
+```
+
+</details>
+
+## Compression Support
+
+Rapido HTTP Client supports automatic decompression of compressed HTTP responses through the `autoDecompress` option.
+
+### Enabling Auto-Decompression
+
+```typescript
+const client = new RapidoHttpClient({
+  logger,
+  serviceUrl: 'https://api.example.com',
+  autoDecompress: true,
+});
+```
+
+### What It Does
+
+When `autoDecompress: true` is enabled:
+
+1. **Sets Accept-Encoding Header**: Automatically adds the `Accept-Encoding` header to advertise supported compression formats:
+   - **Node.js 22+**: `zstd, br, gzip` (includes zstd support)
+   - **Node.js < 22**: `br, gzip` (zstd not supported in older versions)
+
+2. **Automatic Decompression**: Transparently decompresses responses with the following `content-encoding` values:
+   - `gzip` - GZIP compression
+   - `br` - Brotli compression
+   - `deflate` - Deflate compression
+   - `zstd` - Zstandard compression (Node.js 22+ only)
+
+3. **Works for All Responses**: Handles both successful responses and error responses (4xx, 5xx)
+
+### Example Usage
+
+```typescript
+const client = new RapidoHttpClient({
+  logger,
+  serviceUrl: 'https://api.example.com',
+  autoDecompress: true,
+});
+
+// Server responds with gzipped JSON and content-encoding: gzip
+const { data } = await client.get('/data');
+
+// Rapido HTTP Client automatically decompresses the response
+// You receive the parsed JSON object directly
+console.log(data); // { ... } - already decompressed and parsed
+```
+
+### When to Use
+
+Enable `autoDecompress` when:
+- Communicating with external APIs that send compressed responses
+- Optimizing bandwidth usage with servers that support compression
+- Working with CDNs or services that automatically compress responses
+
+### When Not to Use
+
+Leave `autoDecompress` disabled (default) when:
+- Internal microservice communication where responses aren't compressed (at least at the time of writing this)
+- You need to handle raw compressed data yourself
+- The overhead of checking and decompressing isn't worth the bandwidth savings
+
+### Error Handling
+
+Decompression works transparently for error responses too:
+
+```typescript
+try {
+  await client.get('/api/endpoint');
+} catch (error) {
+  if (error instanceof errors.RapidoHttpClientError) {
+    // error.data is already decompressed, even if the server
+    // sent a compressed 4xx/5xx response
+    console.log(error.data);
+  }
+}
+```
+
+## API Reference
+
+### HTTP Methods
+
+All methods return `Promise<RapidoHttpClientResponse<T>>`:
+
+- `get<T>(url, config?)` - GET request
+- `post<T>(url, body?, config?)` - POST request
+- `put<T>(url, body?, config?)` - PUT request
+- `patch<T>(url, body?, config?)` - PATCH request
+- `delete<T>(url, config?)` - DELETE request
+- `head<T>(url, config?)` - HEAD request
+- `options<T>(url, config?)` - OPTIONS request
+- `query<T>(url, body?, config?)` - QUERY request
+
+### Request Config
+
+```typescript
+interface RequestConfig {
+  params?: Record<string, any>;    // Query parameters
+  headers?: Record<string, string>;// Request headers
+  timeout?: number;                // Override timeout
+  signal?: AbortSignal;            // Cancellation signal
+  responseSchema?: ZodType;        // Response validation schema
+}
+```
+
+### Response Format
+
+```typescript
+interface RapidoHttpClientResponse<T> {
+  data: T;                        // Parsed response body
+  status: number;                 // HTTP status code
+  statusText: string;             // Status text
+  headers: Record<string, string | string[]>; // Response headers
+  config: {                       // Request metadata
+    url: string;
+    method: string;
+    baseURL?: string;
+  };
+}
+```
+
+## Testing
+
+Rapido HTTP Client provides a simple, nock-like testing API that allows you to mock HTTP responses without having to change how you instantiate your client.
+
+This mock API only mocks the network layer, so your Rapido HTTP Client instances are created normally - no special test parameters are needed, while all features (retries, caching, schema validation) work as expected.
+
+### Quick Start
+
+```typescript
+import { setupRapidoHttpClientMock } from '@autofleet/rapido-http-client/testing';
+import RapidoHttpClient from '@autofleet/rapido-http-client';
+
+describe('My Service Tests', () => {
+  let mock: ReturnType<typeof setupRapidoHttpClientMock>;
+
+  beforeAll(() => {
+    // Set up the global mock
+    mock = setupRapidoHttpClientMock();
+  });
+
+  afterAll(async () => {
+    // Clean up after each test
+    await mock.cleanup();
+  });
+
+  it('should fetch users', async () => {
+    // Set up mock responses
+    mock.intercept('https://api.example.com')
+      .get('/users')
+      .reply(200, { users: [{ id: 1, name: 'John' }] }, {
+        headers: { 'content-type': 'application/json' }
+      });
+
+    // Create your client normally - no special parameters needed!
+    const client = new RapidoHttpClient({
+      serviceUrl: 'https://api.example.com',
+      logger: mockLogger,
+    });
+
+    // Make requests - they automatically use the mocks
+    const response = await client.get('/users');
+
+    expect(response.data).toEqual({ users: [{ id: 1, name: 'John' }] });
+  });
+});
+```
+
+### API Reference
+
+#### `setupRapidoHttpClientMock()`
+
+Creates a global mock that is automatically used by all Rapido HTTP Client instances.
+
+> [!IMPORTANT]
+> The `setupRapidoHttpClientMock()` function must be called **before** creating the Rapido HTTP Client instance, so the instantiation picks up the global mock agent.
+> This means you should typically call it in `beforeAll` hooks, and after that dynamically import the module creating the Rapido HTTP Client instance. 
+
+##### `intercept(target)`
+
+Set up mocks for a specific origin. Accepts either a URL string or an object with `serviceName` or `serviceUrl`. Returns an instance of unici's `MockInterceptor` object. See [the docs](https://undici.nodejs.org/#/docs/api/MockPool?id=return-mockinterceptor) for details.
+
+###### Some examples:
+
+```typescript
+const mock = setupRapidoHttpClientMock();
+
+// Simple path matching
+mock.intercept('https://api.example.com')
+  .get('/users')
+  .reply(200, { users: [] }, { headers: { 'content-type': 'application/json' } });
+
+// Advanced: Match specific request body
+mock.intercept('https://api.example.com')
+  .post({ path: '/users', body: JSON.stringify({ name: 'Jane' }) })
+  .reply(201, { id: 2, name: 'Jane' }, { headers: { 'content-type': 'application/json' } });
+
+// Advanced: Match query parameters
+mock.intercept('https://api.example.com')
+  .get({ path: '/users', query: { page: '1', limit: '10' } })
+  .reply(200, { users: [], page: 1 }, { headers: { 'content-type': 'application/json' } });
+
+// Using serviceName (reads from env variable)
+mock.intercept({ serviceName: 'USER' })
+  .get('/profile')
+  .reply(200, { id: 1, name: 'Alice' }, { headers: { 'content-type': 'application/json' } });
+
+// Using serviceUrl
+mock.intercept({ serviceUrl: 'https://api.example.com' })
+  .delete('/users/1')
+  .reply(204);
+
+// Mock for a specific number of requests
+mock.intercept('https://api.example.com')
+  .get('/data')
+  .reply(200, { value: 1 }, { headers: { 'content-type': 'application/json' } })
+  .times(3); // Only mock the first 3 requests
+
+// Mock indefinitely
+mock.intercept('https://api.example.com')
+  .get('/data')
+  .reply(200, { value: 1 }, { headers: { 'content-type': 'application/json' } })
+  .persist(); // Always return this response
+
+// Mock a network error
+const error = new Error('ECONNREFUSED: Connection refused');
+error.code = 'ECONNREFUSED';
+
+mock.intercept('https://api.example.com')
+  .get('/failing-endpoint')
+  .replyWithError(error)
+  .persist(); // Always throw this error
+
+// Mock timeout errors
+const timeoutError = new Error('Request timeout');
+timeoutError.code = 'UND_ERR_TIMEOUT';
+
+mock.intercept('https://api.example.com')
+  .get('/slow-endpoint')
+  .replyWithError(timeoutError)
+  .times(2); // First 2 requests fail, then succeeds
+
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+});
+
+// This will throw the error
+await expect(client.get('/failing-endpoint')).rejects.toThrow('ECONNREFUSED');
+```
+
+##### `getPool(origin: string): MockPool`
+
+Get the underlying [undici `MockPool`](https://undici.nodejs.org/#/docs/api/MockPool?id=instance-methods) for advanced usage:
+
+```typescript
+const pool = mock.getPool('https://api.example.com');
+
+// Use undici's full API
+pool.intercept({
+  path: '/complex',
+  method: 'GET',
+  headers: { 'x-custom': 'value' }
+})
+.reply(200, { advanced: true }, { headers: { 'content-type': 'application/json' } });
+```
+
+##### `cleanup(): Promise<void>`
+
+Clean up the global mock. **Should be called** after tests complete (typically in `afterAll`):
+
+```typescript
+afterAll(async () => {
+  await mock.cleanup();
+});
+```
+
+### Testing Examples
+
+<details>
+<summary><b>Mocking Multiple Services</b></summary>
+
+```typescript
+it('works with multiple services', async () => {
+  mock.intercept('https://api1.example.com')
+    .get('/data')
+    .reply(200, { service: 'api1' }, { headers: { 'content-type': 'application/json' } });
+
+  mock.intercept('https://api2.example.com')
+    .get('/data')
+    .reply(200, { service: 'api2' }, { headers: { 'content-type': 'application/json' } });
+
+  const client1 = new RapidoHttpClient({
+    serviceUrl: 'https://api1.example.com',
+    logger: mockLogger,
+  });
+
+  const client2 = new RapidoHttpClient({
+    serviceUrl: 'https://api2.example.com',
+    logger: mockLogger,
+  });
+
+  const response1 = await client1.get('/data');
+  const response2 = await client2.get('/data');
+
+  expect(response1.data).toEqual({ service: 'api1' });
+  expect(response2.data).toEqual({ service: 'api2' });
+});
+```
+
+</details>
+
+<details>
+<summary><b>Error Responses</b></summary>
+
+```typescript
+it('handles error responses', async () => {
+  mock.intercept('https://api.example.com')
+    .get('/users/999')
+    .reply(404, { error: 'Not Found' }, { headers: { 'content-type': 'application/json' } });
+
+  const client = new RapidoHttpClient({
+    serviceUrl: 'https://api.example.com',
+    logger: mockLogger,
+  });
+
+  await expect(client.get('/users/999')).rejects.toThrow();
+});
+```
+
+</details>
+
+<details>
+<summary><b>Advanced `MockPool` Usage</b></summary>
+
+For full control, use `getPool()` to access the undici `MockPool` directly:
+
+```typescript
+it('uses advanced pool features', async () => {
+  const pool = mock.getPool('https://api.example.com');
+
+  pool.intercept({
+    path: '/data',
+    method: 'POST',
+    body: (body) => {
+      // Custom body matching logic
+      const data = JSON.parse(body as string);
+      return data.name === 'test';
+    },
+    headers: {
+      'x-api-key': 'secret'
+    }
+  })
+  .reply(201, { created: true }, { headers: { 'content-type': 'application/json' } });
+
+  const client = new RapidoHttpClient({
+    serviceUrl: 'https://api.example.com',
+    logger: mockLogger,
+    headers: { 'x-api-key': 'secret' }
+  });
+
+  const response = await client.post('/data', { name: 'test' });
+  expect(response.status).toBe(201);
+});
+```
+
+</details>
+
+### How It Works
+
+When you call `setupRapidoHttpClientMock()`, it creates a global MockAgent that is stored in `globalThis`. The Rapido HTTP Client constructor automatically checks for this global mock agent and uses it instead of creating a real HTTP client.
+
+This means:
+- ✅ No need to pass special test parameters to your Rapido HTTP Client instances
+- ✅ Your production code remains unchanged
+- ✅ Works with any testing framework (Vitest, Jest, etc.)
+- ✅ Clean separation between test setup and implementation
+
+### Migration from nock
+
+If you're migrating from `nock`, the API is very similar:
+
+```typescript
+// Old (nock)
+nock('https://api.example.com')
+  .get('/users')
+  .reply(200, { users: [] });
+
+// New (rapido-http-client)
+const mock = setupRapidoHttpClientMock();
+mock.intercept('https://api.example.com')
+  .get('/users')
+  .reply(200, { users: [] }, { headers: { 'content-type': 'application/json' } });
+```
+
+The main differences:
+- You need to call `mock.cleanup()` in `afterAll`
+- Headers should be specified in the third parameter to `reply()`
+- The mock is set up once per test file/suite
+
+## Running Tests & Benchmarks
+
+### Run Tests
+
+```bash
+# Run all tests
+pnpm --filter @autofleet/rapido-http-client test
+```
+
+### Generate Coverage Report
+
+```bash
+pnpm --filter @autofleet/rapido-http-client coverage
+```
+
+### Run Benchmarks
+
+```bash
+# Run all benchmarks
+pnpm --filter @autofleet/rapido-http-client bench
+
+# Run benchmarks and save results
+pnpm --filter @autofleet/rapido-http-client bench --outputJson benchmark-results.json
+
+# Compare with previous results
+pnpm --filter @autofleet/rapido-http-client bench --compare benchmark-results.json
+```
+
+## Migration from @autofleet/network
+
+### Basic Request
+
+**Before (Network):**
+```typescript
+import Network from '@autofleet/network';
+
+const network = new Network({
+  serviceUrl: 'https://api.example.com',
+  logger,
+});
+
+const response = await network.get('/data');
+const data = response.data;
+```
+
+**After (Rapido HTTP Client):**
+```typescript
+import { RapidoHttpClient } from '@autofleet/rapido-http-client';
+
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+});
+
+const { data } = await client.get('/data');
+```
+
+### With Retries
+
+**Before (Network):**
+```typescript
+const network = new Network({
+  serviceUrl: 'https://api.example.com',
+  logger,
+  retries: 3,
+  retryDelay: (retryCount) => retryCount * 1000,
+});
+```
+
+**After (Rapido HTTP Client):**
+```typescript
+const client = new RapidoHttpClient({
+  serviceUrl: 'https://api.example.com',
+  logger,
+  retries: {
+    maxRetries: 3,
+    minTimeout: 1000,
+    timeoutFactor: 1,
+  },
+});
+```
+
+### Key Differences
+
+1. **Default Type**: Rapido HTTP Client uses `unknown` instead of `any` for better type safety
+2. **Error Handling**: Uses undici's error classes (`ResponseError`, `RequestAbortedError`, `UndiciError`)
+3. **Cache**: Built-in HTTP caching support (no external plugin needed)
+4. **Schema Validation**: Native Zod support with type inference
+5. **Disposal**: Supports async disposal pattern (`await using`)