Construct HTTP/HTTPS Tunneling Agents

2.0.1 · abandoned · verified Wed Apr 22

caw is a JavaScript utility designed to simplify the creation of HTTP/HTTPS agents for tunneling through proxies. It abstracts the configuration of proxy agents by internally utilizing `tunnel-agent` for the tunneling logic and `get-proxy` for automatic discovery of proxy settings from environment variables if a proxy URL is not explicitly provided. The current stable version is 2.0.1. Due to the age of its underlying dependencies (`tunnel-agent` and `get-proxy`), which are themselves largely unmaintained or deprecated, `caw` has seen no recent development and can be considered abandoned. It serves a niche for older Node.js environments (targeting `node >=4`) that require simple proxy agent construction, but modern applications should seek more actively maintained alternatives.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to import `caw` using ES module `import` syntax in an ES module environment.

fix Change the import statement to `const caw = require('caw');` or convert your project to CommonJS. For pure ESM projects, migrate to an ESM-compatible proxy agent library.
```
Error: tunneling socket could not be established, cause=...
```
cause The configured proxy server either rejected the connection, is misconfigured, or network issues prevented the application from reaching the proxy.

fix Verify the proxy URL, port, and authentication credentials. Ensure network connectivity from your application to the proxy server. Check the proxy server's logs for more detailed error information. Also, check for `NO_PROXY` environment variables that might unintentionally prevent proxying for certain domains.
```
TypeError: Cannot read properties of undefined (reading 'protocol')
```
cause This or similar `TypeError` issues often arise when the `caw` agent, built on older `tunnel-agent` mechanisms, becomes incompatible with newer Node.js `http`/`https` module internals or other HTTP client libraries due to its age.

fix Upgrade to a modern, actively maintained HTTP/HTTPS proxy agent library (e.g., `@http-proxy-agent/https`, `@https-proxy-agent/https`) that is explicitly compatible with your Node.js version and chosen HTTP client.

Warnings

breaking caw relies on deprecated and unmaintained underlying dependencies (`tunnel-agent` and `get-proxy`). This can lead to security vulnerabilities, lack of compatibility with modern Node.js versions, and unaddressed bugs.
Fix: Consider migrating to actively maintained libraries such as `http-proxy-agent`, `https-proxy-agent`, or `socks-proxy-agent` for proxy tunneling, ideally used with modern HTTP clients like `undici` or `axios` with appropriate proxy agent integration.
gotcha caw is a CommonJS module and does not provide native ES Module (ESM) support. Using `import` syntax will typically result in errors in pure ESM environments without a transpilation step.
Fix: Always use `const caw = require('caw');` for importing. For ESM-only projects, a direct migration to an ESM-first proxy agent library is the most robust solution.
gotcha While `caw` states compatibility with Node.js versions `>=4`, its internal mechanisms and dependencies may not function correctly or securely on modern Node.js versions (e.g., Node.js 14+).
Fix: Thoroughly test `caw` on your target Node.js version. For production environments, it is highly recommended to migrate to a current, actively maintained solution that explicitly supports your Node.js runtime.
gotcha When no proxy URL is explicitly provided to `caw()`, it attempts to automatically discover proxy settings from environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). This can lead to unintended proxying if these variables are set in your environment without your explicit knowledge or intent for a specific application.
Fix: Always provide an explicit `proxy` URL to `caw(proxyUrl)` for predictable behavior. If relying on environment variables, ensure they are correctly configured and understood for the application's context. Always be mindful of `NO_PROXY` to prevent local requests from being proxied.

Install

npm install caw npm
yarn add caw yarn
pnpm add caw pnpm

Imports

caw
wrong:
```
import caw from 'caw';
```
correct:
```
const caw = require('caw');
```
caw is a CommonJS module and does not natively support ES module `import` syntax. For ESM projects, direct migration to an ESM-compatible alternative is recommended.
caw (for `agent` option)
wrong:
```
agent: new caw()
```
correct:
```
agent: caw('http://proxy.example.com:8080')
```
The `caw` function is called directly to create an agent instance, it's not a class constructor.

Quickstart

Demonstrates how to create and use `caw` agents with the `got` HTTP client, both with explicit proxy URLs and automatic proxy discovery from environment variables.

const caw = require('caw');
const got = require('got');

// Example using an explicit proxy URL
const proxyAgent = caw('http://your-proxy-server:8080', { protocol: 'http' });

// If no proxy URL is provided, caw will try to get it from environment variables (HTTP_PROXY, HTTPS_PROXY)
const autoProxyAgent = caw();

(async () => {
  try {
    // Make a request using the proxy agent
    const { body: explicitProxyBody } = await got('https://api.github.com/zen', {
      agent: { https: proxyAgent } // Specify https agent for https requests
    });
    console.log('Response with explicit proxy:', explicitProxyBody);

    // Make another request, letting caw discover proxy from env vars
    // For this to work, ensure HTTP_PROXY or HTTPS_PROXY are set in your environment
    // For demonstration, we'll just show the call.
    // process.env.HTTPS_PROXY = 'http://another-proxy.example.com:8081'; // Uncomment to test env var discovery
    const { body: autoProxyBody } = await got('https://ipinfo.io/json', {
      agent: { https: autoProxyAgent }
    });
    console.log('Response with auto-discovered proxy:', autoProxyBody);

  } catch (error) {
    console.error('Request failed:', error.message);
  }
})();

view raw JSON →