http-proxy-agent 7.0.2

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/http-proxy-agent@7.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/http-proxy-agent@7.0.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:77a4dacaf09ea9bd70097629ffdf78847dc00a4682b8921aa1d9cafa4b62431a","contract":["HttpProxyAgent is exported as a class by http-proxy-agent and wrapper module","HttpProxyAgent.protocols supports http and https protocols","createHttpProxyAgent initializes an agent instance with URL object and parses host and port","HttpProxyAgent strips square brackets from IPv6 hostnames in connectOpts","HttpProxyAgent parses basic auth credentials from proxy URL and sets Base64 Proxy-Authorization header","HttpProxyAgent sets Proxy-Connection to Keep-Alive when keepAlive is true and close when omitted","HttpProxyAgent supports dynamic proxyHeaders function and custom headers","HttpProxyAgent rewrites req.path to absolute URL format","requestViaProxy performs an end-to-end HTTP GET request through an HTTP proxy and returns response status, headers, and body"],"goal":"verify pkg:npm/http-proxy-agent@7.0.2","kind":"HOW","packages":["pkg:npm/http-proxy-agent@7.0.2"],"schemaVersion":1,"symbols":["HttpProxyAgent"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/http-proxy-agent@7.0.2"],"schemaVersion":1,"subject":"pkg:npm/http-proxy-agent@7.0.2","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-http-proxy-agent",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-http-proxy-agent",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "http-proxy-agent": "7.0.2"
      }
    },
    "node_modules/agent-base": {
      "version": "7.1.4",
      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
      "license": "MIT",
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/http-proxy-agent": {
      "version": "7.0.2",
      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
      "license": "MIT",
      "dependencies": {
        "agent-base": "^7.1.0",
        "debug": "^4.3.4"
      },
      "engines": {
        "node": ">= 14"
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-http-proxy-agent",
  "version": "1.0.0",
  "license": "MIT-0",
  "main": "src/index.js",
  "dependencies": {
    "http-proxy-agent": "7.0.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/http-proxy-agent@7.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/http-proxy-agent@7.0.2"
  ]
}

const { HttpProxyAgent } = require('http-proxy-agent');
const http = require('http');

/**
 * Creates an HttpProxyAgent instance for routing HTTP requests through an HTTP or HTTPS proxy.
 *
 * @param {string | URL} proxy - The proxy server URL (e.g. 'http://127.0.0.1:8080')
 * @param {object} [options={}] - Additional agent options such as headers, timeout, or keepAlive
 * @returns {HttpProxyAgent} Configured HttpProxyAgent instance
 */
function createHttpProxyAgent(proxy, options = {}) {
  return new HttpProxyAgent(proxy, options);
}

/**
 * Performs an HTTP GET request through an HttpProxyAgent.
 *
 * @param {string | URL} targetUrl - Target URL to request
 * @param {HttpProxyAgent} agent - HttpProxyAgent instance
 * @param {object} [options={}] - Additional http.request options
 * @returns {Promise<{ statusCode: number, headers: import('http').IncomingHttpHeaders, body: string }>}
 */
function requestViaProxy(targetUrl, agent, options = {}) {
  return new Promise((resolve, reject) => {
    const req = http.get(targetUrl, { ...options, agent }, (res) => {
      let data = '';
      res.setEncoding('utf8');
      res.on('data', (chunk) => {
        data += chunk;
      });
      res.on('end', () => {
        resolve({
          statusCode: res.statusCode || 200,
          headers: res.headers,
          body: data
        });
      });
    });
    req.on('error', reject);
  });
}

module.exports = {
  HttpProxyAgent,
  createHttpProxyAgent,
  requestViaProxy
};

import assert from 'node:assert/strict';
import http from 'node:http';
import { createRequire } from 'node:module';
import { URL } from 'node:url';

const require = createRequire(import.meta.url);
const { HttpProxyAgent, createHttpProxyAgent, requestViaProxy } = require('../src/index.js');
const upstream = require('http-proxy-agent');

function createMockRequest(path = '/test', headers = {}) {
  const storedHeaders = { ...headers };
  return {
    path,
    getHeader(name) {
      return storedHeaders[name.toLowerCase()];
    },
    setHeader(name, value) {
      storedHeaders[name.toLowerCase()] = value;
    }
  };
}

// 1. HttpProxyAgent is exported as a class by http-proxy-agent and wrapper module
assert.equal(typeof HttpProxyAgent, 'function', 'HttpProxyAgent must be a class/function');
assert.strictEqual(HttpProxyAgent, upstream.HttpProxyAgent, 'HttpProxyAgent must match upstream export');
assert.deepEqual(HttpProxyAgent.protocols, ['http', 'https'], 'HttpProxyAgent.protocols must support http and https');

// 2. createHttpProxyAgent initializes agent instance with URL object and parses host, port, protocol
const agent1 = createHttpProxyAgent('http://127.0.0.1:8888');
assert.ok(agent1 instanceof HttpProxyAgent, 'agent1 must be instance of HttpProxyAgent');
assert.equal(agent1.proxy.hostname, '127.0.0.1', 'proxy hostname must match');
assert.equal(agent1.proxy.port, '8888', 'proxy port must match');
assert.equal(agent1.connectOpts.host, '127.0.0.1', 'connectOpts host must match');
assert.equal(agent1.connectOpts.port, 8888, 'connectOpts port must match');

// 3. HttpProxyAgent strips square brackets from IPv6 hostnames in connectOpts
const agentIpv6 = new HttpProxyAgent('http://[::1]:9999');
assert.equal(agentIpv6.proxy.hostname, '[::1]', 'proxy hostname contains bracketed IPv6');
assert.equal(agentIpv6.connectOpts.host, '::1', 'connectOpts host strips square brackets');
assert.equal(agentIpv6.connectOpts.port, 9999, 'connectOpts port must match');

// 4. HttpProxyAgent parses basic auth credentials from proxy URL and generates Proxy-Authorization header
const authUrl = new URL('http://127.0.0.1:8080');
authUrl.username = 'proxyuser';
authUrl.password = 'proxypass';
const agentAuth = new HttpProxyAgent(authUrl);
const reqAuth = createMockRequest('/resource');
agentAuth.setRequestProps(reqAuth, { host: '127.0.0.1', port: 80 });
const expectedAuthHeader = `Basic ${Buffer.from('proxyuser:proxypass').toString('base64')}`;
assert.equal(reqAuth.getHeader('proxy-authorization'), expectedAuthHeader, 'Proxy-Authorization header must match Basic auth');

// 5. HttpProxyAgent sets Proxy-Connection to Keep-Alive when keepAlive is true, and close when omitted
const agentKeepAlive = new HttpProxyAgent('http://127.0.0.1:8080', { keepAlive: true });
const reqKA = createMockRequest('/test-ka');
agentKeepAlive.setRequestProps(reqKA, { host: '127.0.0.1', port: 80 });
assert.equal(reqKA.getHeader('proxy-connection'), 'Keep-Alive', 'Proxy-Connection must be Keep-Alive');

const agentNoKA = new HttpProxyAgent('http://127.0.0.1:8080');
const reqNoKA = createMockRequest('/test-noka');
agentNoKA.setRequestProps(reqNoKA, { host: '127.0.0.1', port: 80 });
assert.equal(reqNoKA.getHeader('proxy-connection'), 'close', 'Proxy-Connection must default to close');

// 6. HttpProxyAgent supports dynamic proxyHeaders function and custom headers
const agentDynamic = new HttpProxyAgent('http://127.0.0.1:8080', {
  headers: () => ({
    'X-Custom-Proxy-Header': 'custom-dynamic-value'
  })
});
const reqDyn = createMockRequest('/test-dyn');
agentDynamic.setRequestProps(reqDyn, { host: '127.0.0.1', port: 80 });
assert.equal(reqDyn.getHeader('x-custom-proxy-header'), 'custom-dynamic-value', 'Dynamic header must be set');

// 7. HttpProxyAgent rewrites req.path to absolute URL format
const reqRewrite = createMockRequest('/api/items?limit=10', { host: '127.0.0.1:3000' });
agent1.setRequestProps(reqRewrite, { host: '127.0.0.1', port: 3000 });
assert.equal(reqRewrite.path, 'http://127.0.0.1:3000/api/items?limit=10', 'req.path must be rewritten to absolute URL');

// 8. End-to-end offline HTTP GET request through a mock proxy server
let proxyReceivedPath = '';
let proxyReceivedHeaders = null;

const proxyServer = http.createServer((req, res) => {
  proxyReceivedPath = req.url;
  proxyReceivedHeaders = req.headers;
  res.writeHead(200, {
    'Content-Type': 'application/json',
    'X-Proxy-Response': 'proxied-ok'
  });
  res.end(JSON.stringify({ status: 'ok', requestedUrl: req.url }));
});

await new Promise((resolve) => proxyServer.listen(0, '127.0.0.1', resolve));
const proxyPort = proxyServer.address().port;

try {
  const liveAgent = createHttpProxyAgent(`http://127.0.0.1:${proxyPort}`, {
    headers: {
      'X-Client-Proxy-Tag': 'contract-test'
    }
  });

  const response = await requestViaProxy('http://127.0.0.1:4000/target-endpoint?foo=bar', liveAgent, {
    headers: {
      'X-Target-Custom': 'target-value'
    }
  });

  assert.equal(response.statusCode, 200, 'response status code must be 200');
  assert.equal(response.headers['x-proxy-response'], 'proxied-ok', 'proxy header must be present in response');

  const parsedBody = JSON.parse(response.body);
  assert.equal(parsedBody.status, 'ok', 'response body status must match');
  assert.equal(parsedBody.requestedUrl, 'http://127.0.0.1:4000/target-endpoint?foo=bar', 'requested url in proxy must match absolute url');

  assert.equal(proxyReceivedPath, 'http://127.0.0.1:4000/target-endpoint?foo=bar', 'proxy must receive absolute URL in request line');
  assert.equal(proxyReceivedHeaders['x-client-proxy-tag'], 'contract-test', 'proxy must receive configured proxy headers');
  assert.equal(proxyReceivedHeaders['x-target-custom'], 'target-value', 'proxy must forward request headers');
  assert.equal(proxyReceivedHeaders['proxy-connection'], 'close', 'proxy-connection header must be close by default');
} finally {
  await new Promise((resolve) => proxyServer.close(resolve));
}

console.log('All http-proxy-agent contract assertions passed successfully.');