HTTPCloak Node.js Client

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/httpcloak/dist/index.js

  cause Attempting to use `require()` to import `httpcloak` in an ECMAScript Module (ESM) project, or when Node.js is running in ESM mode.
  fix Change your import statement to `import { Session } from 'httpcloak';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• TypeError: session.get is not a function

  cause The `Session` class was not correctly imported or instantiated, leading to an attempt to call a method on an undefined or incorrect object.
  fix Verify that `import { Session } from 'httpcloak';` (ESM) or `const { Session } = require('httpcloak');` (CJS) is used, and that you are creating an instance: `const session = new Session({...});`.

• UnhandledPromiseRejectionWarning: Error: Session already closed or invalid state

  cause Attempting to make a request or perform an action on an `httpcloak` session after `session.close()` has already been called.
  fix Ensure that `session.close()` is called only once, after all operations for that session are complete. If concurrent operations are intended, manage them with `Promise.all` before closing the session, or use separate sessions for distinct sets of operations.

Warnings

• gotcha Failing to call `session.close()` can lead to resource leaks, including open sockets and memory, especially in long-running applications or when creating many sessions. Each `Session` instance manages its own network connections and state.
  Fix: Always ensure `session.close()` is called in a `finally` block or equivalent cleanup mechanism after all requests associated with the session are completed. For streaming, `stream.close()` is also necessary.
• gotcha HTTP/3 support might require specific Node.js versions (Node.js 14+ is listed, but specific HTTP/3 features might be more robust in newer versions) and could be sensitive to underlying operating system QUIC implementations. Connection failures or unexpected behavior might occur if the environment is not fully compatible.
  Fix: Ensure you are running a recent Node.js version (e.g., Node.js 18+ for best HTTP/3 stability). If encountering issues, test with HTTP/2 or HTTP/1.1 by explicitly setting `protocol: 'http2'` or `protocol: 'http1'` in session options, or by disabling HTTP/3 in presets if possible.
• breaking The library primarily uses named exports. Directly `require('httpcloak')` without destructuring in CommonJS, or `import Session from 'httpcloak'` in ESM (expecting a default export), will result in `undefined` or an error when trying to access `Session`.
  Fix: Use `const { Session } = require('httpcloak');` for CommonJS and `import { Session } from 'httpcloak';` for ES Modules to correctly import the Session class.

Install

• npm install httpcloak npm
• yarn add httpcloak yarn
• pnpm add httpcloak pnpm

Imports

• Session
  wrong:

  const Session = require('httpcloak').Session; // Incorrect CommonJS access if in ESM context
  import Session from 'httpcloak'; // Incorrect default import

  correct:

  import { Session } from 'httpcloak';

  For ES Modules, use named import. This is the primary class for creating HTTP sessions.
• Session (CommonJS)
  wrong:

  import { Session } from 'httpcloak'; // Will throw 'ERR_REQUIRE_ESM' in CommonJS environment

  correct:

  const { Session } = require('httpcloak');

  Use object destructuring for CommonJS environments. The library primarily exports named members.
• SessionOptions (TypeScript Type)
  wrong:

  import { SessionOptions } from 'httpcloak'; // Incorrect if only importing the type, may cause runtime issues if SessionOptions is not a runtime value

  correct:

  import type { SessionOptions } from 'httpcloak';

  For TypeScript projects, explicitly import types using `import type` to ensure they are removed during compilation.

Quickstart

This quickstart demonstrates promise-based asynchronous usage of HTTPCloak, covering GET and POST requests, handling responses, and executing concurrent requests, while emphasizing proper session management with `session.close()`.

import { Session } from 'httpcloak';

async function runHttpcloakExample() {
  const session = new Session({
    preset: 'chrome-latest', // Emulate the latest Chrome browser fingerprint
    // You can also specify proxy, timeouts, etc. here
    // proxy: 'http://username:password@proxy.example.com:8080',
    // timeout: 15000
  });

  try {
    console.log('Performing GET request to Cloudflare trace...');
    const getResponse = await session.get('https://www.cloudflare.com/cdn-cgi/trace');
    console.log('GET Status Code:', getResponse.statusCode);
    console.log('GET Response Text:\n', getResponse.text.slice(0, 200), '...'); // Log first 200 chars

    console.log('\nPerforming POST request to a mock API...');
    const postResponse = await session.post('https://jsonplaceholder.typicode.com/posts', {
      title: 'foo',
      body: 'bar',
      userId: 1,
    }, {
      'Content-Type': 'application/json' // Custom headers for the request
    });
    console.log('POST Status Code:', postResponse.statusCode);
    console.log('POST Response JSON:', JSON.parse(postResponse.text));

    console.log('\nAttempting concurrent requests...');
    const [res1, res2] = await Promise.all([
      session.get('https://example.com/'),
      session.get('https://httpbin.org/get')
    ]);
    console.log('Concurrent Request 1 Status:', res1.statusCode);
    console.log('Concurrent Request 2 Status:', res2.statusCode);

  } catch (error) {
    console.error('An error occurred:', error.message);
  } finally {
    console.log('\nClosing HTTPCloak session...');
    session.close(); // Essential for resource cleanup
  }
}

runHttpcloakExample();