http-debug: Simple HTTP(S) Debugger

0.1.2 · abandoned · verified Wed Apr 22

http-debug is a lightweight utility designed to provide verbose debugging output for Node.js `http` and `https` requests. It operates by patching Node's built-in `http` and `https` modules to intercept and log request, write, end, and socket events to `stderr`. The current stable version is `0.1.2`. Given its low version number and the age of the provided changelog, the project appears to have a very slow or effectively ceased release cadence, last updated around 2013-2014. Its primary differentiator is its simplicity and direct global patching approach, allowing for debugging without modifying application code for each request, though this can lead to conflicts. It supports enabling debugging via `process.env.HTTP_DEBUG` or by setting `http.debug` at runtime, offering different verbosity levels.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'debug')
```
cause Attempting to set `http.debug` before `http-debug` has correctly patched the `http` module, or if `http-debug` was not properly imported.

fix Ensure `const http = require('http-debug').http;` is called before accessing `http.debug`. Verify `http-debug` is installed and accessible.
```
ReferenceError: http is not defined
```
cause The `http` object from `http-debug` was not correctly imported or assigned to a variable, or an `import` statement was used instead of `require`.

fix Use `const http = require('http-debug').http;` to correctly import the patched `http` module.
```
Error: Cannot find module 'http-debug'
```
cause The `http-debug` package is not installed in the project's `node_modules`.

fix Run `npm install http-debug` to install the package.

Warnings

breaking This library globally patches Node.js's native `http` and `https` modules. This behavior can lead to conflicts if other libraries or your application also attempt to patch or wrap these modules, causing unpredictable behavior or crashes.
Fix: Avoid using `http-debug` in environments where other global `http`/`https` interceptors are present. Consider alternative debugging methods like network proxies or `console.log` on `request.on('request')` events for complex scenarios. Given its age, it might also conflict with modern Node.js versions or features.
gotcha The `http.debug` property takes precedence over `process.env.HTTP_DEBUG`. If both are set, the runtime assignment to `http.debug` will override the environment variable.
Fix: Be mindful of the precedence. If you want to control debugging solely via environment variables, ensure `http.debug` (or `https.debug`) is not explicitly set in your code after the module is loaded.
deprecated This package is very old (last updated around 2013-2014) and likely unmaintained. It relies on a global patching strategy that is generally discouraged in modern Node.js development due to potential side effects and conflicts.
Fix: For new projects or existing projects needing active support, consider using modern debugging tools like Node.js's built-in debugger, `process.env.NODE_DEBUG`, dedicated network proxies (e.g., Fiddler, Charles, mitmproxy), or more actively maintained HTTP client debugging utilities.
gotcha The library primarily uses CommonJS `require()` syntax and may not be compatible with ES Modules (`import`) without additional transpilation or specific Node.js loader configurations, which are not explicitly supported.
Fix: Ensure your project uses CommonJS (`.js` files with `require`) or a build setup that correctly transpiles `require` calls if you're using ES Modules.

Install

npm install http-debug npm
yarn add http-debug yarn
pnpm add http-debug pnpm

Imports

http
wrong:
```
import { http } from 'http-debug';
```
correct:
```
const http = require('http-debug').http;
```
This library predates widespread ESM adoption and primarily supports CommonJS `require()` syntax. It modifies Node's global http module.
https
wrong:
```
import { https } from 'http-debug';
```
correct:
```
const https = require('http-debug').https;
```
Similar to `http`, this imports the patched `https` module. Ensure you use `require()`.
debug state
wrong:
```
const debug = require('http-debug').debug; debug = 2;
```
correct:
```
http.debug = 2;
```
The debugging level is set directly on the imported `http` or `https` object (which are effectively Node's global modules). It's not an export itself.

Quickstart

This quickstart demonstrates how to import and enable verbose HTTP request debugging using http-debug, then makes a sample HTTP GET request to observe the detailed output on stderr.

const httpDebug = require('http-debug');
const http = httpDebug.http;

// Set debugging level to verbose (2).
// 0: off, 1: on (request, write, end), 2: verbose (on + error, socket events)
http.debug = 2;

// Alternatively, set via environment variable before running:
// process.env.HTTP_DEBUG = '2';

console.log('Making an HTTP GET request to mervine.net...');
console.log('Debug output will appear on stderr.');

http.get('http://mervine.net/', (res) => {
   let data = '';
   res.on('data', (chunk) => { data += chunk; });
   res.on('end', () => {
      console.log(`\nHTTP Response Status Code: ${res.statusCode}`);
      console.log(`Content length: ${data.length} bytes`);
   });
}).on('error', (err) => {
   console.error('Error during HTTP request:', err.message);
});

// Example for HTTPS (uncomment to use)
// const https = httpDebug.https;
// https.debug = 2;
// https.get('https://example.com/', (res) => {
//    // ... handle response ...
// }).on('error', (err) => {
//    console.error('Error during HTTPS request:', err.message);
// });

view raw JSON →