https-proxy-agent 7.0.6: HttpsProxyAgent

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 https-proxy-agent.HttpsProxyAgent in pkg:npm/https-proxy-agent@7.0.6
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/https-proxy-agent@7.0.6
Demonstrate these symbols/APIs:
  - https-proxy-agent.HttpsProxyAgent

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:fd838c8496840996e61f8a52f34d54c2baa8921b6cee860d30ca777546253aff","contract":["HttpsProxyAgent instantiates from a proxy URL string and parses proxy host and port","HttpsProxyAgent instantiates from a WHATWG URL instance","HttpsProxyAgent supports custom headers configuration via object and function","HttpsProxyAgent configures agent connection options such as keepAlive and maxSockets","getProxyDetails extracts normalized proxy URL components from an HttpsProxyAgent instance","HttpsProxyAgent establishes an HTTP CONNECT tunnel socket to proxy destination"],"goal":"verify https-proxy-agent.HttpsProxyAgent in pkg:npm/https-proxy-agent@7.0.6","kind":"HOW","packages":["pkg:npm/https-proxy-agent@7.0.6"],"schemaVersion":1,"symbols":["https-proxy-agent.HttpsProxyAgent"]},"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/https-proxy-agent@7.0.6"],"schemaVersion":1,"subject":"pkg:npm/https-proxy-agent@7.0.6","symbols":["https-proxy-agent.HttpsProxyAgent"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-https-proxy-agent-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-https-proxy-agent-verify",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "https-proxy-agent": "7.0.6"
      }
    },
    "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/https-proxy-agent": {
      "version": "7.0.6",
      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
      "license": "MIT",
      "dependencies": {
        "agent-base": "^7.1.2",
        "debug": "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-https-proxy-agent-verify",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of https-proxy-agent HttpsProxyAgent",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "https-proxy-agent": "7.0.6"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify https-proxy-agent.HttpsProxyAgent in pkg:npm/https-proxy-agent@7.0.6",
  "kind": "HOW",
  "packages": [
    "pkg:npm/https-proxy-agent@7.0.6"
  ],
  "symbols": [
    "https-proxy-agent.HttpsProxyAgent"
  ]
}

const { HttpsProxyAgent } = require('https-proxy-agent');

/**
 * Creates an HttpsProxyAgent instance from a URL string or WHATWG URL instance.
 *
 * @param {string | URL} proxy - The proxy URL string or URL instance
 * @param {object} [options] - Additional agent options
 * @returns {HttpsProxyAgent} The configured HttpsProxyAgent instance
 */
function createProxyAgent(proxy, options) {
  return new HttpsProxyAgent(proxy, options);
}

/**
 * Extracts and normalizes proxy configuration details from an HttpsProxyAgent instance.
 *
 * @param {HttpsProxyAgent} agent - The HttpsProxyAgent instance
 * @returns {object} Normalized proxy configuration details
 */
function getProxyDetails(agent) {
  if (!agent || !agent.proxy) {
    throw new TypeError('Expected an HttpsProxyAgent instance with a valid proxy property');
  }

  const { protocol, hostname, port, host, pathname } = agent.proxy;

  return {
    protocol,
    hostname,
    port: port ? parseInt(port, 10) : (protocol === 'https:' ? 443 : 80),
    host,
    pathname
  };
}

module.exports = {
  createProxyAgent,
  getProxyDetails,
  HttpsProxyAgent
};

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

const require = createRequire(import.meta.url);
const { createProxyAgent, getProxyDetails, HttpsProxyAgent } = require('../src/index.js');

async function runContracts() {
  // 1. HttpsProxyAgent instantiates from a proxy URL string and parses proxy host and port
  {
    const agent = createProxyAgent('http://localhost:8080');
    assert(agent instanceof HttpsProxyAgent, 'agent should be an instance of HttpsProxyAgent');
    assert(agent.proxy instanceof URL, 'agent.proxy should be an instance of WHATWG URL');
    assert.strictEqual(agent.proxy.protocol, 'http:');
    assert.strictEqual(agent.proxy.hostname, 'localhost');
    assert.strictEqual(agent.proxy.port, '8080');
  }

  // 2. HttpsProxyAgent instantiates from a WHATWG URL instance
  {
    const proxyUrl = new URL('https://localhost:8443/tunnel');
    const agent = createProxyAgent(proxyUrl);
    assert.strictEqual(agent.proxy.protocol, 'https:');
    assert.strictEqual(agent.proxy.hostname, 'localhost');
    assert.strictEqual(agent.proxy.port, '8443');
    assert.strictEqual(agent.proxy.pathname, '/tunnel');
  }

  // 3. HttpsProxyAgent supports custom headers configuration via object and function
  {
    const agentWithHeaders = createProxyAgent('http://localhost:8080', {
      headers: {
        'X-Proxy-Header': 'custom-value'
      }
    });
    assert.deepStrictEqual(agentWithHeaders.proxyHeaders, {
      'X-Proxy-Header': 'custom-value'
    });

    const headerFn = () => ({ 'X-Dynamic-Header': 'dynamic-value' });
    const agentWithHeaderFn = createProxyAgent('http://localhost:8080', {
      headers: headerFn
    });
    assert.strictEqual(typeof agentWithHeaderFn.proxyHeaders, 'function');
    assert.deepStrictEqual(agentWithHeaderFn.proxyHeaders(), {
      'X-Dynamic-Header': 'dynamic-value'
    });
  }

  // 4. HttpsProxyAgent configures agent connection options such as keepAlive and maxSockets
  {
    const agent = createProxyAgent('http://localhost:8080', {
      keepAlive: true,
      maxSockets: 20
    });
    assert.strictEqual(agent.keepAlive, true);
    assert.strictEqual(agent.maxSockets, 20);
  }

  // 5. getProxyDetails extracts normalized proxy URL components from an HttpsProxyAgent instance
  {
    const agent = createProxyAgent('http://localhost:8080/custom');
    const details = getProxyDetails(agent);
    assert.deepStrictEqual(details, {
      protocol: 'http:',
      hostname: 'localhost',
      port: 8080,
      host: 'localhost:8080',
      pathname: '/custom'
    });

    const defaultPortAgent = createProxyAgent('http://localhost');
    const defaultDetails = getProxyDetails(defaultPortAgent);
    assert.strictEqual(defaultDetails.port, 80);
    assert.strictEqual(defaultDetails.protocol, 'http:');
  }

  // 6. HttpsProxyAgent establishes an HTTP CONNECT tunnel socket to proxy destination
  {
    const proxyServer = http.createServer();
    let connectReceived = false;

    proxyServer.on('connect', (req, clientSocket, head) => {
      connectReceived = true;
      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
      clientSocket.on('data', (chunk) => {
        clientSocket.write(`ACK:${chunk.toString()}`);
      });
    });

    await new Promise((resolve, reject) => {
      proxyServer.listen(0, '127.0.0.1', () => resolve());
      proxyServer.on('error', reject);
    });

    const address = proxyServer.address();
    const port = address.port;
    const agent = createProxyAgent(`http://127.0.0.1:${port}`);

    const fakeReq = http.request({
      host: 'example.com',
      port: 443,
      method: 'GET',
      agent: agent
    });
    fakeReq.on('error', () => {});

    const tunnelSocket = await agent.connect(fakeReq, { host: 'example.com', port: 443 });
    assert.ok(tunnelSocket, 'tunnelSocket should be returned by agent.connect');

    const receivedData = await new Promise((resolve, reject) => {
      tunnelSocket.on('data', (data) => {
        resolve(data.toString());
      });
      tunnelSocket.on('error', reject);
      tunnelSocket.write('TEST_PAYLOAD');
    });

    assert.strictEqual(receivedData, 'ACK:TEST_PAYLOAD');
    assert.strictEqual(connectReceived, true);

    fakeReq.destroy();
    tunnelSocket.destroy();
    await new Promise((resolve) => proxyServer.close(resolve));
  }

  console.log('Contract tests passed successfully.');
}

runContracts().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});