hagent: HTTP Agent for Whistle

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

  cause Attempting to use `require()` on a package that is ESM-only, or more likely in this context, attempting to use `import` with a CommonJS-only package like `hagent`.
  fix Ensure you are using `require()` for this CommonJS-only package: `const { HttpClientAgent } = require('hagent');`

• TypeError: Cannot read property 'request' of undefined (or similar for http/https methods)

  cause This error typically indicates that the `agent` object passed to `http.request` or `https.request` is not a valid agent instance, or that the `http` module itself is not correctly imported.
  fix Verify that `hagent` is correctly installed (`npm install hagent`) and that `HttpClientAgent` or `HttpsClientAgent` are correctly imported and instantiated before being passed to Node.js's native `http.request` or `https.request` methods.

Warnings

• breaking The `hagent` package has been abandoned since April 2020. It is unlikely to be compatible with modern Node.js versions (e.g., Node.js 16+), potentially leading to runtime errors, unexpected behavior, or security vulnerabilities.
  Fix: Consider migrating to actively maintained HTTP agent solutions or newer versions of Whistle that might embed similar functionality or provide alternative integration points. If Whistle itself is still in use, check its documentation for recommended agent configurations.
• gotcha This package is strictly CommonJS (`require`) and does not provide ES Module (`import`) support. Attempting to use `import { HttpClientAgent } from 'hagent'` will result in a module resolution error.
  Fix: Always use `const { HttpClientAgent } = require('hagent');` or `const hagent = require('hagent');` for module imports.
• gotcha Due to its abandoned status, `hagent` likely contains unpatched security vulnerabilities or bugs. Using it in production environments is highly discouraged as it poses a significant security risk.
  Fix: Perform a thorough security audit before considering use, or ideally, replace with a maintained alternative. Rely on Whistle's own mechanisms if they provide a maintained HTTP agent solution.

Install

• npm install hagent npm
• yarn add hagent yarn
• pnpm add hagent pnpm

Imports

• HttpClientAgent
  wrong:

  import { HttpClientAgent } from 'hagent'; // hagent@0.9.3 is CommonJS-only
  const HttpClientAgent = require('hagent').HttpClientAgent; // Not strictly wrong, but destructuring is cleaner

  correct:

  const { HttpClientAgent } = require('hagent');

  This package is CommonJS-only. There is no ESM support in v0.9.3.
• HttpsClientAgent
  wrong:

  import { HttpsClientAgent } from 'hagent'; // hagent@0.9.3 is CommonJS-only

  correct:

  const { HttpsClientAgent } = require('hagent');

  Used for HTTPS connections; similar CommonJS-only import as HttpClientAgent.
• hagent (default export)

  const hagent = require('hagent');
  // Then access hagent.HttpClientAgent or hagent.HttpsClientAgent

  The package exports an object containing both HttpClientAgent and HttpsClientAgent as named properties, not a default export in the traditional sense. Direct destructuring is often preferred.

Quickstart

This quickstart demonstrates how to instantiate and use `HttpClientAgent` to make an HTTP request. The agent is configured to connect through a hypothetical Whistle proxy, showing how it would be integrated into a Node.js HTTP client call.

const http = require('http');
const { HttpClientAgent } = require('hagent');

// Configure a basic HTTP agent for use with Whistle
const agent = new HttpClientAgent({
  // These options are standard for Node.js http.Agent
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  // The 'whistle' option is specific to how hagent integrates
  // It typically holds configurations like the Whistle server address
  // For demonstration, we'll use a placeholder whistle server address
  whistle: {
    host: '127.0.0.1',
    port: 8899, // Default Whistle proxy port
  },
});

const options = {
  hostname: 'example.com',
  port: 80,
  path: '/',
  method: 'GET',
  agent: agent, // Use the hagent instance
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      console.log('Response Body Snippet:', rawData.substring(0, 200) + '...');
    } catch (e) {
      console.error(e.message);
    }
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.end();