feat: add HTTP client and rate limiting utilities

Author: Mearman

src/utils/http.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HttpError, fetchWithTimeout, parseJsonResponse } from './http.js';
+
+// Mock global fetch
+global.fetch = vi.fn();
+
+describe('fetchWithTimeout', () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+		vi.restoreAllMocks();
+	});
+
+	it('should make a successful request', async () => {
+		const mockResponse = new Response('Success', { status: 200 });
+		vi.mocked(fetch).mockResolvedValueOnce(mockResponse);
+
+		const response = await fetchWithTimeout('https://example.com');
+		expect(response).toBe(mockResponse);
+		expect(fetch).toHaveBeenCalledWith('https://example.com', {
+			signal: expect.any(AbortSignal),
+		});
+	});
+
+	it('should handle HTTP errors', async () => {
+		const mockResponse = new Response('Not Found', {
+			status: 404,
+			statusText: 'Not Found',
+		});
+		vi.mocked(fetch).mockResolvedValueOnce(mockResponse);
+
+		await expect(fetchWithTimeout('https://example.com')).rejects.toThrow(HttpError);
+	});
+
+	it('should handle timeout', async () => {
+		// Create an abort controller to simulate timeout
+		const abortError = new Error('The operation was aborted');
+		abortError.name = 'AbortError';
+
+		vi.mocked(fetch).mockRejectedValueOnce(abortError);
+
+		await expect(fetchWithTimeout('https://example.com', { timeout: 100 })).rejects.toThrow(
+			'Request timeout after 100ms',
+		);
+	});
+
+	it('should handle network errors', async () => {
+		vi.mocked(fetch).mockRejectedValueOnce(new Error('Network error'));
+
+		await expect(fetchWithTimeout('https://example.com')).rejects.toThrow('Network error');
+	});
+});
+
+describe('parseJsonResponse', () => {
+	it('should parse valid JSON response', async () => {
+		const data = { test: 'value' };
+		const response = new Response(JSON.stringify(data));
+
+		const result = await parseJsonResponse(response);
+		expect(result).toEqual(data);
+	});
+
+	it('should handle invalid JSON', async () => {
+		const response = new Response('invalid json');
+
+		await expect(parseJsonResponse(response)).rejects.toThrow('Failed to parse JSON response');
+	});
+});

src/utils/http.ts

@@ -0,0 +1,73 @@
+/**
+ * HTTP utilities for making API calls to the Wayback Machine
+ */
+
+interface FetchOptions {
+	method?: string;
+	headers?: Record<string, string>;
+	body?: string;
+	timeout?: number;
+}
+
+export class HttpError extends Error {
+	constructor(
+		message: string,
+		public readonly status?: number,
+		public readonly response?: string,
+	) {
+		super(message);
+		this.name = 'HttpError';
+	}
+}
+
+/**
+ * Wrapper around fetch with timeout support and error handling
+ */
+export async function fetchWithTimeout(url: string, options: FetchOptions = {}): Promise<Response> {
+	const { timeout = 30000, ...fetchOptions } = options;
+
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+	try {
+		const response = await fetch(url, {
+			...fetchOptions,
+			signal: controller.signal,
+		});
+
+		clearTimeout(timeoutId);
+
+		if (!response.ok) {
+			const text = await response.text().catch(() => '');
+			throw new HttpError(
+				`HTTP ${response.status}: ${response.statusText}`,
+				response.status,
+				text,
+			);
+		}
+
+		return response;
+	} catch (error) {
+		clearTimeout(timeoutId);
+
+		if (error instanceof Error) {
+			if (error.name === 'AbortError') {
+				throw new HttpError(`Request timeout after ${timeout}ms`);
+			}
+			throw error;
+		}
+
+		throw new HttpError('Network error occurred');
+	}
+}
+
+/**
+ * Parse JSON response with error handling
+ */
+export async function parseJsonResponse<T>(response: Response): Promise<T> {
+	try {
+		return (await response.json()) as T;
+	} catch (error) {
+		throw new HttpError('Failed to parse JSON response');
+	}
+}

src/utils/rate-limit.test.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { RateLimiter } from './rate-limit.js';
+
+describe('RateLimiter', () => {
+	let rateLimiter: RateLimiter;
+
+	beforeEach(() => {
+		rateLimiter = new RateLimiter({
+			maxRequests: 3,
+			windowMs: 1000, // 1 second
+		});
+		vi.useFakeTimers();
+	});
+
+	it('should allow requests within limit', () => {
+		expect(rateLimiter.canMakeRequest()).toBe(true);
+		rateLimiter.recordRequest();
+		expect(rateLimiter.canMakeRequest()).toBe(true);
+		rateLimiter.recordRequest();
+		expect(rateLimiter.canMakeRequest()).toBe(true);
+		rateLimiter.recordRequest();
+		expect(rateLimiter.canMakeRequest()).toBe(false);
+	});
+
+	it('should reset after window expires', () => {
+		rateLimiter.recordRequest();
+		rateLimiter.recordRequest();
+		rateLimiter.recordRequest();
+		expect(rateLimiter.canMakeRequest()).toBe(false);
+
+		vi.advanceTimersByTime(1100);
+		expect(rateLimiter.canMakeRequest()).toBe(true);
+	});
+
+	it('should wait for slot when rate limited', async () => {
+		rateLimiter.recordRequest();
+		rateLimiter.recordRequest();
+		rateLimiter.recordRequest();
+
+		const waitPromise = rateLimiter.waitForSlot();
+		vi.advanceTimersByTime(1100);
+		await vi.runAllTimersAsync();
+		await expect(waitPromise).resolves.toBeUndefined();
+	});
+});

src/utils/rate-limit.ts

@@ -0,0 +1,63 @@
+/**
+ * Rate limiting utilities for Wayback Machine API
+ */
+
+interface RateLimitOptions {
+	maxRequests: number;
+	windowMs: number;
+}
+
+export class RateLimiter {
+	private requests: number[] = [];
+	private readonly maxRequests: number;
+	private readonly windowMs: number;
+
+	constructor(options: RateLimitOptions) {
+		this.maxRequests = options.maxRequests;
+		this.windowMs = options.windowMs;
+	}
+
+	/**
+	 * Check if a request can be made without violating rate limits
+	 */
+	canMakeRequest(): boolean {
+		this.cleanup();
+		return this.requests.length < this.maxRequests;
+	}
+
+	/**
+	 * Wait until a request can be made
+	 */
+	async waitForSlot(): Promise<void> {
+		while (!this.canMakeRequest()) {
+			const oldestRequest = this.requests[0];
+			const waitTime = oldestRequest + this.windowMs - Date.now();
+			if (waitTime > 0) {
+				await new Promise((resolve) => setTimeout(resolve, waitTime + 100));
+			}
+			this.cleanup();
+		}
+	}
+
+	/**
+	 * Record a request
+	 */
+	recordRequest(): void {
+		this.requests.push(Date.now());
+	}
+
+	/**
+	 * Remove expired requests from the tracking array
+	 */
+	private cleanup(): void {
+		const cutoff = Date.now() - this.windowMs;
+		this.requests = this.requests.filter((time) => time > cutoff);
+	}
+}
+
+// Default rate limiter for Wayback Machine
+// Conservative limits to be respectful of the service
+export const waybackRateLimiter = new RateLimiter({
+	maxRequests: 15, // 15 requests
+	windowMs: 60000, // per minute
+});