HTTP Deceiver

Common errors

• TypeError: Deceiver is not a constructor

  cause Attempting to instantiate `http-deceiver` without the `new` keyword, or calling it as a regular function.
  fix Ensure that `Deceiver` is instantiated as a class: `const deceiver = new Deceiver();`.

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

  cause Attempting to use `require()` to import an ES module, or more likely, using `import` syntax for this CommonJS-only package in an ESM context.
  fix This package is strictly CommonJS. If you are in an ESM project, you might need a wrapper or dynamic import if your environment supports it, but the primary fix is to ensure the consuming code is CommonJS or use `const Deceiver = require('http-deceiver');` if your setup allows CJS imports in ESM.

• Deceiver error: Parse Error: ... (or similar error message related to parsing)

  cause The raw buffer data fed into the `deceiver.write()` method contained syntactical errors or unexpected structures that the parser could not reconcile, even with its 'deceiving' capabilities.
  fix Carefully examine the raw HTTP buffer being provided. While `http-deceiver` is designed for flexibility, it still expects a certain underlying structure. Debug the raw bytes to ensure they align with the intended (even if malformed) HTTP protocol. Implement comprehensive error handling for the 'error' event emitted by the deceiver.

Warnings

• breaking The `http-deceiver` package has not been updated in approximately eight years and is considered abandoned. This means it is highly unlikely to receive bug fixes, security patches, or compatibility updates for newer Node.js versions or evolving HTTP standards. Using it in production environments is strongly discouraged due to potential security vulnerabilities and instability.
  Fix: Consider using actively maintained alternatives for HTTP parsing and manipulation, especially for security-sensitive applications. If direct buffer manipulation is required, assess modern stream parsing libraries or implement custom parsers with robust error handling.
• gotcha Due to its age and CommonJS-only design, `http-deceiver` does not support ES module (ESM) import syntax. Attempting to use `import Deceiver from 'http-deceiver';` will result in a runtime error.
  Fix: Always use the CommonJS `require` syntax: `const Deceiver = require('http-deceiver');`.
• gotcha The library's low-level nature means it expects raw buffer inputs and emits events based on its parsing. Mismanagement of input buffers (e.g., incorrect chunking or malformed HTTP beyond its intended 'deceiving' scope) can lead to 'error' events or unexpected parsing behavior.
  Fix: Thoroughly test inputs and outputs. Implement robust error handling for the `deceiver.on('error', ...)` event to catch and manage parsing issues gracefully. Refer to its original (limited) documentation or source code for expected buffer formats.

Install

• npm install http-deceiver npm
• yarn add http-deceiver yarn
• pnpm add http-deceiver pnpm

Imports

• Deceiver
  wrong:

  import Deceiver from 'http-deceiver';

  correct:

  const Deceiver = require('http-deceiver');

  This package is CommonJS-only and exports its primary class as the module.exports value. ESM import syntax will not work.

Quickstart

This quickstart demonstrates how to use `http-deceiver` to parse a raw HTTP request fed through a `net.Socket`. It sets up a simple `net` server to receive client data, passes that data to `Deceiver`, and listens for `header`, `data`, and `error` events, simulating deep packet inspection or custom HTTP handling.

const Deceiver = require('http-deceiver');
const net = require('net');

const rawHttpRequest = Buffer.from(
  'GET /malformed-path HTTP/1.1\r\n' +
  'Host: example.com\r\n' +
  'X-Custom-Header: potential-injection-attempt\r\n' +
  'Content-Length: 0\r\n' +
  '\r\n' // Note: A standard HTTP/1.1 request requires two CRLFs at the end of headers.
);

const server = net.createServer((socket) => {
  console.log('Client connected to server.');
  const deceiver = new Deceiver();

  deceiver.on('error', (err) => {
    console.error('Deceiver parsing error:', err.message);
    socket.end('HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\n\r\nDeceiver encountered a parsing error.\n');
  });

  deceiver.on('header', (header) => {
    console.log('Parsed Header:', header);
    // Example: Manipulate headers for a proxy or security scan
    if (header['x-custom-header'] && header['x-custom-header'].includes('injection')) {
      console.warn('Potential injection attempt detected in X-Custom-Header!');
    }
  });

  deceiver.on('data', (data) => {
    console.log('Parsed Data (body chunk):', data.toString());
  });

  deceiver.on('end', () => {
    console.log('Deceiver parsing ended successfully.');
    socket.write('HTTP/1.1 200 OK\r\nContent-Length: 18\r\nContent-Type: text/plain\r\n\r\nDeceiver processed it!\n');
    socket.end();
  });

  socket.on('data', (chunk) => {
    console.log('Received raw chunk from client:', chunk.toString().trim());
    deceiver.write(chunk); // Feed client data to the deceiver
  });

  socket.on('end', () => {
    console.log('Client disconnected from server.');
    deceiver.end(); // Signal end of input to the deceiver
  });
});

server.listen(3000, () => {
  console.log('Server listening on port 3000. Simulating client request...');

  const client = net.connect({ port: 3000 }, () => {
    console.log('Simulated client connected.');
    client.write(rawHttpRequest);
    client.end(); // End client connection after sending the request
  });

  client.on('data', (data) => {
    console.log('Simulated client received response:', data.toString().trim());
    server.close(); // Close server after receiving response
  });

  client.on('end', () => {
    console.log('Simulated client disconnected after response.');
  });
});