@isdk/proxy-server

HTTP Caching Proxy Server (Node.js)

HttpCachingProxy is a high-performance caching proxy server adapter built into @isdk/proxy, specifically designed for the Node.js environment. It operates as a standalone HTTP forward proxy, making it ideal for integration testing, traffic recording, or adding caching capabilities to existing services without modifying their code.

Features

• Non-intrusive: Works via standard HTTP proxy protocol; no changes to your application code required.
• Core Power: Fully leverages @isdk/proxy core features including L1/L2 hybrid caching, request coalescing, and SWR support.
• Modern Architecture: Built with @whatwg-node/server for Web Standard bridging and uses ky for efficient backend fetching.
• Developer Friendly: Injects x-proxy-cache response headers for easy monitoring of cache status.

Installation

Ensure you have the core library and necessary dependencies installed:

pnpm add @isdk/proxy-server @isdk/proxy ky @whatwg-node/server undici@6

Quick Start

Example: Using with ky for Integration Testing

In integration tests, you can spin up a temporary proxy to speed up requests and enable offline testing.

import { HttpCachingProxy } from '@isdk/proxy-server';
import { ProxyAgent } from 'undici';
import ky from 'ky';

// 1. Start the proxy server
const proxy = new HttpCachingProxy({
  cachePath: './.cache',
  port: 0 // Auto-assign port
});
await proxy.start();

// 2. Configure client to use the proxy
const agent = new ProxyAgent(proxy.url);
const client = ky.extend({ dispatcher: agent });

// 3. Make requests
const response = await client.get('https://api.example.com/data');
console.log(response.headers.get('x-proxy-cache')); // HIT, MISS, STALE...

// 4. Stop when finished
await proxy.stop();

Configuration Options ProxyServerOptions

Option	Type	Description
config	ProxyConfig	Full caching strategy configuration (site rules, filters, etc.).
cachePath	string	Directory for persistent cache storage.
port	number	Port to listen on, default is 0.
logError	boolean	Whether to log errors to console, default is true.
timeout	number	Timeout for backend requests (ms).
rejectUnauthorized	boolean	Whether to verify SSL certificates, default is true.
backgroundUpdate	boolean	Whether to enable SWR background updates, default is true.

FAQ

Does it support HTTPS?

It supports proxying to https:// target URLs. However, the proxy server itself currently only listens on HTTP. CONNECT tunneling is not supported for simplicity and security reasons.

License

MIT