https-proxy-agent 7.0.6

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/https-proxy-agent@7.0.6
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/https-proxy-agent@7.0.6

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:cee16f3963d1462f30c32407a0344e3a0f206f42bf40a91236ad6dbfd43c51f5","contract":["createProxyAgent instantiates an HttpsProxyAgent from a string URL with parsed WHATWG URL properties","supports URL instance input and parses credentials including username and password","supports custom headers object and function via proxy configuration options","supports agent options such as keepAlive and maxSockets","getProxyDetails extracts normalized proxy URL and configuration from the agent instance","implements connect method required for Node HTTP CONNECT tunneling"],"goal":"verify pkg:npm/https-proxy-agent@7.0.6","kind":"HOW","packages":["pkg:npm/https-proxy-agent@7.0.6"],"schemaVersion":1},"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","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-https-proxy-agent",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-https-proxy-agent",
      "version": "1.0.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",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of https-proxy-agent",
  "main": "src/index.js",
  "dependencies": {
    "https-proxy-agent": "7.0.6"
  }
}

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

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

/**
 * Creates an HttpsProxyAgent instance from a URL string or URL object and optional settings.
 *
 * @param {string | URL} proxy - Proxy URL string or WHATWG URL instance
 * @param {object} [options] - Additional agent and proxy options
 * @returns {HttpsProxyAgent} 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, username, password, href } = agent.proxy;

  return {
    protocol,
    hostname,
    port: port ? parseInt(port, 10) : (protocol === 'https:' ? 443 : 80),
    username: username || null,
    password: password || null,
    href
  };
}

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

import assert from 'node:assert';
import { createRequire } from 'node:module';

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

// 1. Export verification
assert.strictEqual(typeof HttpsProxyAgent, 'function', 'HttpsProxyAgent should be exported as a constructor function');
assert.strictEqual(typeof createProxyAgent, 'function', 'createProxyAgent should be exported as a function');
assert.strictEqual(typeof getProxyDetails, 'function', 'getProxyDetails should be exported as a function');

// 2. createProxyAgent instantiates an HttpsProxyAgent from a string URL with parsed WHATWG URL properties
const agent1 = createProxyAgent('http://127.0.0.1:8080');
assert(agent1 instanceof HttpsProxyAgent, 'agent1 should be an instance of HttpsProxyAgent');
assert(agent1.proxy instanceof URL, 'agent.proxy should be an instance of WHATWG URL');
assert.strictEqual(agent1.proxy.protocol, 'http:');
assert.strictEqual(agent1.proxy.hostname, '127.0.0.1');
assert.strictEqual(agent1.proxy.port, '8080');

// 3. supports URL instance input and parses credentials including username and password
const proxyUrl = new URL('http://127.0.0.1:8443/proxy-path');
proxyUrl.username = 'proxyuser';
proxyUrl.password = 'proxypass';
const agentAuth = createProxyAgent(proxyUrl);
assert.strictEqual(agentAuth.proxy.protocol, 'http:');
assert.strictEqual(agentAuth.proxy.username, 'proxyuser');
assert.strictEqual(agentAuth.proxy.password, 'proxypass');
assert.strictEqual(agentAuth.proxy.port, '8443');

// 4. supports custom headers object and function via proxy configuration options
const agentHeadersObj = createProxyAgent('http://127.0.0.1:8080', {
  headers: {
    'X-Proxy-Header': 'custom-value'
  }
});
assert.deepStrictEqual(agentHeadersObj.proxyHeaders, {
  'X-Proxy-Header': 'custom-value'
});

const headerFn = () => ({ 'X-Dynamic-Proxy': 'dynamic-token' });
const agentHeadersFn = createProxyAgent('http://127.0.0.1:8080', {
  headers: headerFn
});
assert.strictEqual(typeof agentHeadersFn.proxyHeaders, 'function');
assert.deepStrictEqual(agentHeadersFn.proxyHeaders(), {
  'X-Dynamic-Proxy': 'dynamic-token'
});

// 5. supports agent options such as keepAlive and maxSockets
const agentOpts = createProxyAgent('http://127.0.0.1:8080', {
  keepAlive: true,
  maxSockets: 15
});
assert.strictEqual(agentOpts.keepAlive, true);
assert.strictEqual(agentOpts.maxSockets, 15);

// 6. getProxyDetails extracts normalized proxy URL and configuration from the agent instance
const detailsAuth = getProxyDetails(agentAuth);
assert.deepStrictEqual(detailsAuth, {
  protocol: 'http:',
  hostname: '127.0.0.1',
  port: 8443,
  username: 'proxyuser',
  password: 'proxypass',
  href: proxyUrl.href
});

const agentDefaultPort = createProxyAgent('http://127.0.0.1');
const detailsDefault = getProxyDetails(agentDefaultPort);
assert.deepStrictEqual(detailsDefault, {
  protocol: 'http:',
  hostname: '127.0.0.1',
  port: 80,
  username: null,
  password: null,
  href: 'http://127.0.0.1/'
});

// 7. implements connect method required for Node HTTP CONNECT tunneling
assert.strictEqual(typeof agent1.connect, 'function', 'agent.connect should be a function');

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