Request Filtering Agent

Common errors

• DNS lookup [IP_ADDRESS](family:[NUMBER], host:[HOSTNAME]) is not allowed. Because, It is private IP address.

  cause Attempting to connect to a private or reserved IP address which is blocked by `request-filtering-agent` by default.
  fix Verify the target IP address. If it's legitimately intended to be accessed and is a private IP, configure the `allowIPAddressList` option in `FilteringAgentOptions` to explicitly permit that IP or range.

• ERR_REQUIRE_ESM: require() of ES Module .../request-filtering-agent/index.js from ... not supported.

  cause Attempting to use `require()` with `request-filtering-agent` v3.x, which is an ESM-only package.
  fix Refactor your codebase to use ES module `import` syntax. Ensure your environment supports ESM (e.g., Node.js 20+ and `"type": "module"` in `package.json` for top-level files). If you need CommonJS, downgrade to `request-filtering-agent@^2.0.0`.

Warnings

• breaking Package switched from CommonJS to ESM and requires Node.js 20+.
  Fix: Update your Node.js version to 20 or higher and refactor `require()` statements to `import` statements. For older Node.js versions or continued CommonJS support, use `request-filtering-agent@^2.0.0`.
• breaking Dropped support for older Node.js versions (12, 14, 16), requiring Node.js 18+.
  Fix: Upgrade your Node.js runtime to 18 or higher. For Node.js 20+ and ESM, refer to the v3 breaking changes.
• gotcha Node.js's built-in `fetch` API does not support custom `http.Agent` implementations, making it incompatible with `request-filtering-agent`.
  Fix: Use alternative HTTP client libraries like `node-fetch`, `axios`, or `got` which provide `http.Agent` support. Avoid using `request-filtering-agent` with the native `fetch`.
• gotcha CIDR notation support for `allowIPAddressList` and `denyIPAddressList` was introduced in minor updates.
  Fix: Ensure you are using `request-filtering-agent@^3.2.0` (or `^3.1.0` for `allowIPAddressList` CIDR) to utilize CIDR notation in your filtering rules.

Install

• npm install request-filtering-agent npm
• yarn add request-filtering-agent yarn
• pnpm add request-filtering-agent pnpm

Imports

• useAgent
  wrong:

  const { useAgent } = require('request-filtering-agent');

  correct:

  import { useAgent } from 'request-filtering-agent';

  Since v3.0.0, the package is ESM-only. Attempting to `require()` it will result in `ERR_REQUIRE_ESM`. For CommonJS support, use v2.x.x or earlier.
• HttpFilteringAgent
  wrong:

  const { HttpFilteringAgent } = require('request-filtering-agent');

  correct:

  import { HttpFilteringAgent } from 'request-filtering-agent';

  The class implementation for filtering HTTP requests. The `useAgent` factory function internally returns an instance of this class for HTTP URLs.
• HttpsFilteringAgent
  wrong:

  const { HttpsFilteringAgent } = require('request-filtering-agent');

  correct:

  import { HttpsFilteringAgent } from 'request-filtering-agent';

  The class implementation for filtering HTTPS requests. The `useAgent` factory function internally returns an instance of this class for HTTPS URLs.
• FilteringAgentOptions

  import type { FilteringAgentOptions } from 'request-filtering-agent';

  Type definition for configuring the `useAgent` function or agent constructors, allowing specification of IP address filtering lists (e.g., `allowIPAddressList`, `denyIPAddressList`).

Quickstart

Demonstrates how to initialize and use `request-filtering-agent` with Node.js's built-in `http.request` to prevent requests to private IP addresses, showing expected error handling.

import { request } from 'node:http';
import { useAgent, FilteringAgentOptions } from 'request-filtering-agent';

// This URL resolves to a private loopback IP (127.0.0.1) and will be blocked by default.
const url = new URL('http://127.0.0.1:8080/');

const agentOptions: FilteringAgentOptions = {
    // Optionally, specify allowed or denied IP lists using CIDR notation.
    // allowIPAddressList: ['192.168.1.0/24'],
    // denyIPAddressList: ['10.0.0.0/8']
};

// Create a filtering agent instance for the target URL
const agent = useAgent(url, agentOptions);

// Use the agent with Node.js's built-in http.request
const req = request(url, { agent }, (res) => {
    console.log(`STATUS: ${res.statusCode}`);
    res.setEncoding('utf8');
    res.on('data', (chunk) => {
        console.log(`BODY: ${chunk}`);
    });
    res.on('end', () => {
        console.log('No more data in response.');
    });
});

req.on('error', (e) => {
    // Expected error for 127.0.0.1: "DNS lookup 127.0.0.1(...) is not allowed. Because, It is private IP address."
    console.error(`Problem with request: ${e.message}`);
});

req.end();