socks-proxy-agent 8.0.5: SocksProxyAgent

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 SocksProxyAgent in pkg:npm/socks-proxy-agent@8.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/socks-proxy-agent@8.0.5
Demonstrate these symbols/APIs:
  - SocksProxyAgent
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.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:0c07a0651cef8363c2b78a208c495297429f670969c1530c64f06b3053785ae5","constraints":{"executionContext":"node"},"contract":["SocksProxyAgent exports constructor function and supported protocols","SocksProxyAgent parses socks5 protocol URL with default port 1080 and enables client DNS lookup","SocksProxyAgent parses socks5h protocol URL and disables client DNS lookup","SocksProxyAgent parses socks4 and socks4a protocol URLs with custom port numbers","SocksProxyAgent configures custom timeout and socketOptions from options object","SocksProxyAgent throws TypeError when initialized with unsupported protocol","SocksProxyAgent implements connect method for Node HTTP agent tunneling","getSocksProxyDetails extracts normalized host, port, type, and lookup settings"],"goal":"verify SocksProxyAgent in pkg:npm/socks-proxy-agent@8.0.5","kind":"HOW","packages":["pkg:npm/socks-proxy-agent@8.0.5"],"schemaVersion":1,"symbols":["SocksProxyAgent"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/socks-proxy-agent@8.0.5"],"schemaVersion":1,"subject":"pkg:npm/socks-proxy-agent@8.0.5","symbols":["SocksProxyAgent"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-socks-proxy-agent",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-proxy-agent",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "socks-proxy-agent": "8.0.5"
      }
    },
    "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/ip-address": {
      "version": "10.5.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.5.0.tgz",
      "integrity": "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==",
      "license": "MIT",
      "engines": {
        "node": ">= 12"
      }
    },
    "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"
    },
    "node_modules/smart-buffer": {
      "version": "4.2.0",
      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
      "license": "MIT",
      "engines": {
        "node": ">= 6.0.0",
        "npm": ">= 3.0.0"
      }
    },
    "node_modules/socks": {
      "version": "2.8.9",
      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.9.tgz",
      "integrity": "sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==",
      "license": "MIT",
      "dependencies": {
        "ip-address": "^10.1.1",
        "smart-buffer": "^4.2.0"
      },
      "engines": {
        "node": ">= 10.0.0",
        "npm": ">= 3.0.0"
      }
    },
    "node_modules/socks-proxy-agent": {
      "version": "8.0.5",
      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-8.0.5.tgz",
      "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==",
      "license": "MIT",
      "dependencies": {
        "agent-base": "^7.1.2",
        "debug": "^4.3.4",
        "socks": "^2.8.3"
      },
      "engines": {
        "node": ">= 14"
      }
    }
  }
}

{
  "name": "sample-socks-proxy-agent",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for socks-proxy-agent@8.0.5",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "socks-proxy-agent": "8.0.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify SocksProxyAgent in pkg:npm/socks-proxy-agent@8.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/socks-proxy-agent@8.0.5"
  ],
  "symbols": [
    "SocksProxyAgent"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const { SocksProxyAgent } = require('socks-proxy-agent');

/**
 * Creates a SocksProxyAgent instance configured with a proxy URL and options.
 *
 * @param {string | URL} uri - SOCKS proxy URL string or WHATWG URL instance
 * @param {object} [options] - Additional agent options
 * @returns {SocksProxyAgent} Configured SocksProxyAgent instance
 */
function createSocksProxyAgent(uri, options) {
  return new SocksProxyAgent(uri, options);
}

/**
 * Retrieves normalized SOCKS proxy connection details from a SocksProxyAgent instance.
 *
 * @param {SocksProxyAgent} agent - SocksProxyAgent instance
 * @returns {object} Normalized proxy metadata
 */
function getSocksProxyDetails(agent) {
  if (!agent || !agent.proxy) {
    throw new TypeError('Expected a SocksProxyAgent instance with proxy configuration');
  }

  return {
    host: agent.proxy.host,
    port: agent.proxy.port,
    type: agent.proxy.type,
    shouldLookup: agent.shouldLookup,
    timeout: agent.timeout,
    socketOptions: agent.socketOptions
  };
}

module.exports = {
  SocksProxyAgent,
  createSocksProxyAgent,
  getSocksProxyDetails
};

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

const require = createRequire(import.meta.url);
const {
  SocksProxyAgent,
  createSocksProxyAgent,
  getSocksProxyDetails
} = require('../src/index.js');

async function testContract() {
  // 1. SocksProxyAgent exports constructor function and supported protocols
  assert.equal(typeof SocksProxyAgent, 'function', 'SocksProxyAgent should be a constructor function');
  assert.equal(typeof createSocksProxyAgent, 'function', 'createSocksProxyAgent should be a function');
  assert.equal(typeof getSocksProxyDetails, 'function', 'getSocksProxyDetails should be a function');
  assert.ok(Array.isArray(SocksProxyAgent.protocols), 'SocksProxyAgent.protocols should be an array');
  assert.deepEqual(
    [...SocksProxyAgent.protocols],
    ['socks', 'socks4', 'socks4a', 'socks5', 'socks5h'],
    'protocols should match supported socks schemes'
  );

  // 2. SocksProxyAgent parses socks5 protocol URL with default port 1080 and enables client DNS lookup
  const agentSocks5 = new SocksProxyAgent('socks5://127.0.0.1:1080');
  assert.ok(agentSocks5 instanceof SocksProxyAgent, 'should be instance of SocksProxyAgent');
  assert.equal(agentSocks5.proxy.host, '127.0.0.1', 'proxy host should match URL');
  assert.equal(agentSocks5.proxy.port, 1080, 'proxy port should match URL');
  assert.equal(agentSocks5.proxy.type, 5, 'proxy type should be 5 for socks5');
  assert.equal(agentSocks5.shouldLookup, true, 'shouldLookup should be true for socks5');

  const agentDefaultPort = new SocksProxyAgent('socks5://127.0.0.1');
  assert.equal(agentDefaultPort.proxy.port, 1080, 'default port should be 1080 when omitted');

  // 3. SocksProxyAgent parses socks5h protocol URL and disables client DNS lookup
  const agentSocks5h = new SocksProxyAgent('socks5h://127.0.0.1:1080');
  assert.equal(agentSocks5h.proxy.type, 5, 'proxy type should be 5 for socks5h');
  assert.equal(agentSocks5h.shouldLookup, false, 'shouldLookup should be false for socks5h');

  // 4. SocksProxyAgent parses socks4 and socks4a protocol URLs with custom port numbers
  const agentSocks4 = new SocksProxyAgent('socks4://127.0.0.1:9050');
  assert.equal(agentSocks4.proxy.host, '127.0.0.1');
  assert.equal(agentSocks4.proxy.port, 9050);
  assert.equal(agentSocks4.proxy.type, 4, 'proxy type should be 4 for socks4');
  assert.equal(agentSocks4.shouldLookup, true, 'shouldLookup should be true for socks4');

  const agentSocks4a = new SocksProxyAgent('socks4a://127.0.0.1:9050');
  assert.equal(agentSocks4a.proxy.type, 4, 'proxy type should be 4 for socks4a');
  assert.equal(agentSocks4a.shouldLookup, false, 'shouldLookup should be false for socks4a');

  const agentGenericSocks = new SocksProxyAgent('socks://127.0.0.1:1080');
  assert.equal(agentGenericSocks.proxy.type, 5, 'generic socks protocol should default to type 5');
  assert.equal(agentGenericSocks.shouldLookup, false, 'generic socks protocol should default to socks5h lookup behavior');

  // 5. Supports WHATWG URL object input
  const urlObj = new URL('socks5://127.0.0.1:1080');
  const agentFromUrl = createSocksProxyAgent(urlObj);
  assert.equal(agentFromUrl.proxy.host, '127.0.0.1');
  assert.equal(agentFromUrl.proxy.port, 1080);
  assert.equal(agentFromUrl.proxy.type, 5);

  // 6. SocksProxyAgent configures custom timeout and socketOptions from options object
  const agentWithOptions = createSocksProxyAgent('socks5://127.0.0.1:1080', {
    timeout: 3000,
    socketOptions: {
      keepAlive: true
    }
  });
  assert.equal(agentWithOptions.timeout, 3000, 'timeout should match options');
  assert.deepEqual(agentWithOptions.socketOptions, { keepAlive: true }, 'socketOptions should match options');

  // 7. SocksProxyAgent throws TypeError when initialized with unsupported protocol
  assert.throws(
    () => new SocksProxyAgent('http://127.0.0.1:8080'),
    {
      name: 'TypeError'
    },
    'should throw TypeError for non-socks protocol'
  );

  // 8. SocksProxyAgent implements connect method for Node HTTP agent tunneling
  assert.equal(typeof agentSocks5.connect, 'function', 'agent.connect should be a function');

  // 9. getSocksProxyDetails extracts normalized host, port, type, and lookup settings
  const details = getSocksProxyDetails(agentWithOptions);
  assert.deepEqual(details, {
    host: '127.0.0.1',
    port: 1080,
    type: 5,
    shouldLookup: true,
    timeout: 3000,
    socketOptions: {
      keepAlive: true
    }
  });

  assert.throws(
    () => getSocksProxyDetails(null),
    {
      name: 'TypeError'
    },
    'getSocksProxyDetails should throw TypeError for invalid agent'
  );

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

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