Merge pull request #11 from proxymesh/feature/tier-a-proxy-extensions

Release v0.2.0: Tier A proxy extensions

Author: proxymesh

README.md

@@ -14,23 +14,30 @@ This library solves both problems for popular JavaScript HTTP libraries.
 
 ## Supported Libraries
 
-| Library | Module | Use Case |
-|---------|--------|----------|
-| [axios](https://axios-http.com/) | `axios-proxy` | Most popular HTTP client |
-| [node-fetch](https://github.com/node-fetch/node-fetch) | `node-fetch-proxy` | Fetch API for Node.js |
-| [got](https://github.com/sindresorhus/got) | `got-proxy` | Human-friendly HTTP client |
-| [undici](https://undici.nodejs.org/) | `undici-proxy` | Fast HTTP client (Node.js core) |
-| [superagent](https://github.com/ladjs/superagent) | `superagent-proxy` | Flexible HTTP client |
+| Library | Subpath export | Notes |
+|---------|----------------|--------|
+| [axios](https://axios-http.com/) | `javascript-proxy-headers/axios` | Widely used client |
+| [node-fetch](https://github.com/node-fetch/node-fetch) | `javascript-proxy-headers/node-fetch` | Fetch API on Node |
+| [got](https://github.com/sindresorhus/got) | `javascript-proxy-headers/got` | Ergonomic API |
+| [undici](https://undici.nodejs.org/) | `javascript-proxy-headers/undici` | Node’s fast HTTP stack |
+| [superagent](https://github.com/ladjs/superagent) | `javascript-proxy-headers/superagent` | Chaining API |
+| [ky](https://github.com/sindresorhus/ky) | `javascript-proxy-headers/ky` | Tiny fetch wrapper |
+| [wretch](https://github.com/elbywan/wretch) | `javascript-proxy-headers/wretch` | Fetch wrapper (sets wretch’s global fetch polyfill) |
+| [make-fetch-happen](https://github.com/npm/make-fetch-happen) | `javascript-proxy-headers/make-fetch-happen` | npm-style fetch (cache, retries, proxy) |
+| [needle](https://github.com/tomas/needle) | `javascript-proxy-headers/needle` | Lean HTTP client |
+| [typed-rest-client](https://github.com/microsoft/typed-rest-client) | `javascript-proxy-headers/typed-rest-client` | Azure / DevOps–style REST client |
+
+**urllib** is not integrated yet: it expects an [undici](https://undici.nodejs.org/) `Dispatcher`, not a Node `Agent`. See `notes/urllib-integration-deferred.md` in this repo for a possible approach.
 
 ## Installation
 
 ```bash
 npm install javascript-proxy-headers
 ```
 
-Then install the HTTP library you want to use (e.g., `npm install axios`).
+Then install the HTTP client(s) you use (for example `axios`, `got`, `ky`, `wretch`, `make-fetch-happen`, `needle`, or `typed-rest-client`). Each is an optional peer dependency.
 
-> **Note:** This package has no dependencies by default - install only what you need.
+> **Note:** This package has no runtime dependencies by default—install only the adapters you need.
 
 ## Quick Start
 
@@ -94,6 +101,85 @@ const { statusCode, headers, body, proxyHeaders } = await request(
 console.log(proxyHeaders.get('x-proxymesh-ip'));
 ```
 
+### ky
+
+Uses a custom `fetch` built from node-fetch + `ProxyHeadersAgent` (`ky.create({ fetch })`).
+
+```javascript
+import { createProxyKy } from 'javascript-proxy-headers/ky';
+
+const api = await createProxyKy({
+    proxy: 'http://user:pass@proxy.example.com:8080',
+    proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
+});
+
+const response = await api('https://httpbin.org/ip');
+console.log(response.proxyHeaders.get('x-proxymesh-ip'));
+```
+
+### wretch
+
+Registers the same custom `fetch` as wretch’s fetch polyfill. Use the normal wretch chain (for example `.get().res()`).
+
+```javascript
+import { createProxyWretch } from 'javascript-proxy-headers/wretch';
+
+const wretch = await createProxyWretch({
+    proxy: 'http://user:pass@proxy.example.com:8080',
+    proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
+});
+
+const response = await wretch('https://httpbin.org/ip').get().res();
+console.log(response.proxyHeaders.get('x-proxymesh-ip'));
+```
+
+### make-fetch-happen
+
+Passes a `ProxyHeadersAgent` as `agent`; `@npmcli/agent` uses it as-is when set.
+
+```javascript
+import { createProxyMakeFetchHappen } from 'javascript-proxy-headers/make-fetch-happen';
+
+const fetch = createProxyMakeFetchHappen({
+    proxy: 'http://user:pass@proxy.example.com:8080',
+    proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
+});
+
+const response = await fetch('https://httpbin.org/ip');
+console.log(response.proxyHeaders.get('x-proxymesh-ip'));
+```
+
+### needle
+
+```javascript
+import { proxyNeedleGet } from 'javascript-proxy-headers/needle';
+
+const res = await proxyNeedleGet('https://httpbin.org/ip', {
+    proxy: 'http://user:pass@proxy.example.com:8080',
+    proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
+});
+
+// CONNECT response headers merged onto res.headers where missing
+console.log(res.headers['x-proxymesh-ip']);
+```
+
+### typed-rest-client
+
+Uses a subclass of `HttpClient` that routes HTTPS through `ProxyHeadersAgent` (no `tunnel` agent).
+
+```javascript
+import { createProxyRestClient } from 'javascript-proxy-headers/typed-rest-client';
+
+const client = createProxyRestClient({
+    userAgent: 'my-app',
+    proxy: 'http://user:pass@proxy.example.com:8080',
+    proxyHeaders: { 'X-ProxyMesh-Country': 'US' }
+});
+
+await client.get('https://httpbin.org/ip');
+console.log(client.proxyAgent.lastProxyHeaders?.get('x-proxymesh-ip'));
+```
+
 ### Core Agent (Advanced)
 
 For direct control, use the core `ProxyHeadersAgent`:
@@ -116,19 +202,22 @@ https.get('https://httpbin.org/ip', { agent }, (res) => {
 
 ## Testing
 
-A test harness is included to verify proxy header functionality:
+Integration tests need a real proxy (set `PROXY_URL` or `HTTPS_PROXY`):
 
 ```bash
-# Set your proxy
 export PROXY_URL='http://user:pass@proxy.example.com:8080'
 
-# Test all modules
-npm test
+npm test                              # all adapters (see package.json "test")
+node run_tests.js -v                  # same harness from repo root
+npm run test:ts                       # same checks via tsx + TypeScript harness
+npm run test:types                    # `tsc --noEmit` only (no network)
 
-# Test specific module
-npm test axios
+# Limit modules
+node test/test_proxy_headers.js -v axios ky
 ```
 
+Verbose (`-v`) prints captured header values. See `test/test_proxy_headers.js --help`.
+
 ## Requirements
 
 - Node.js >= 18.0.0

lib/core/proxy-response.js

@@ -0,0 +1,48 @@
+/**
+ * Wraps a fetch Response and exposes CONNECT proxy response headers.
+ */
+
+export class ProxyResponse {
+    /**
+     * @param {import('node-fetch').Response} response
+     * @param {Map<string, string>|null|undefined} proxyHeaders
+     */
+    constructor(response, proxyHeaders) {
+        this._response = response;
+        this.proxyHeaders = proxyHeaders || new Map();
+
+        this.ok = response.ok;
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.headers = response.headers;
+        this.url = response.url;
+        this.redirected = response.redirected;
+        this.type = response.type;
+        this.body = response.body;
+        this.bodyUsed = response.bodyUsed;
+    }
+
+    async text() {
+        return this._response.text();
+    }
+
+    async json() {
+        return this._response.json();
+    }
+
+    async blob() {
+        return this._response.blob();
+    }
+
+    async arrayBuffer() {
+        return this._response.arrayBuffer();
+    }
+
+    async formData() {
+        return this._response.formData();
+    }
+
+    clone() {
+        return new ProxyResponse(this._response.clone(), this.proxyHeaders);
+    }
+}

lib/ky-proxy.js

@@ -0,0 +1,39 @@
+/**
+ * ky extension for proxy header support.
+ *
+ * Uses a custom `fetch` backed by node-fetch + ProxyHeadersAgent.
+ */
+
+import { createProxyFetch } from './node-fetch-proxy.js';
+
+/**
+ * Create a ky instance with proxy header support.
+ *
+ * @param {Object} options - Configuration
+ * @param {string} options.proxy - Proxy URL
+ * @param {Object} [options.proxyHeaders] - Headers to send on CONNECT
+ * @param {Function} [options.onProxyConnect] - CONNECT callback
+ * @param {Object} [options.kyOptions] - Options passed to ky.create()
+ * @returns {Promise<import('ky').KyInstance>}
+ */
+export async function createProxyKy(options) {
+    const { proxy, proxyHeaders = {}, onProxyConnect, kyOptions = {} } = options;
+
+    if (!proxy) {
+        throw new Error('proxy option is required');
+    }
+
+    let ky;
+    try {
+        ky = (await import('ky')).default;
+    } catch {
+        throw new Error('ky is required. Install it with: npm install ky');
+    }
+
+    const fetch = createProxyFetch({ proxy, proxyHeaders, onProxyConnect });
+
+    return ky.create({
+        ...kyOptions,
+        fetch,
+    });
+}

lib/make-fetch-happen-proxy.js

@@ -0,0 +1,52 @@
+/**
+ * make-fetch-happen extension for proxy header support.
+ *
+ * Passes a ProxyHeadersAgent via opts.agent; @npmcli/agent returns it as-is when set.
+ */
+
+import makeFetchHappen from 'make-fetch-happen';
+import { ProxyHeadersAgent } from './core/proxy-headers-agent.js';
+import { ProxyResponse } from './core/proxy-response.js';
+
+function wrapFetchWithProxyResponse(fetchImpl, agent) {
+    const wrapped = (url, opts = {}) =>
+        fetchImpl(url, opts).then((res) => new ProxyResponse(res, agent.lastProxyHeaders));
+
+    wrapped.defaults = (defaultUrl, defaultOptions = {}) => {
+        const inner = fetchImpl.defaults(defaultUrl, defaultOptions);
+        return wrapFetchWithProxyResponse(inner, agent);
+    };
+
+    wrapped.proxyAgent = agent;
+    return wrapped;
+}
+
+/**
+ * Create a make-fetch-happen fetch function with proxy header support.
+ *
+ * @param {Object} options - Configuration
+ * @param {string} options.proxy - Proxy URL
+ * @param {Object} [options.proxyHeaders] - Headers to send on CONNECT
+ * @param {Function} [options.onProxyConnect] - CONNECT callback
+ * @param {Object} [options.defaults] - Extra options for make-fetch-happen.defaults()
+ * @returns {Function} Fetch function with .defaults() and .proxyAgent
+ */
+export function createProxyMakeFetchHappen(options) {
+    const { proxy, proxyHeaders = {}, onProxyConnect, ...makeFetchHappenOptions } = options;
+
+    if (!proxy) {
+        throw new Error('proxy option is required');
+    }
+
+    const agent = new ProxyHeadersAgent(proxy, {
+        proxyHeaders,
+        onProxyConnect,
+    });
+
+    const inner = makeFetchHappen.defaults({
+        ...makeFetchHappenOptions,
+        agent,
+    });
+
+    return wrapFetchWithProxyResponse(inner, agent);
+}