Low-level HTTP Parser for Whistle

0.5.0 · abandoned · verified Wed Apr 22

hparser is a low-level HTTP parser specifically designed to be used internally by the `whistle` network debugging and proxy tool. It provides capabilities to parse raw HTTP request and response data, handling the complexities of the HTTP protocol state machine. The package's current stable version is 0.5.0, with its last update approximately two years ago and it targets Node.js versions as old as `0.10.0` (released in 2013). This indicates a lack of active maintenance. Due to its specialized use-case within the `whistle` ecosystem and its abandoned status, it is not recommended for new projects or general-purpose HTTP parsing, especially given the availability of more modern and actively maintained alternatives.

Common errors

```
SyntaxError: Named export 'Parser' not found. The requested module 'hparser' does not provide an export named 'Parser'
```
cause Attempting to use ES module `import { Parser } from 'hparser';` syntax with a CommonJS-only package.

fix Change the import statement to CommonJS `const Parser = require('hparser');`.
```
TypeError: Cannot read properties of undefined (reading 'onHeadersComplete')
```
cause The parser's event handlers (`onHeadersComplete`, `onBody`, `onMessageComplete`, etc.) are properties of the parser instance (`this`) within the handler function's scope. This error typically occurs if a handler is defined as an arrow function or if the `this` context is lost when the callback is invoked.

fix Ensure event handler functions are bound correctly to the parser instance, typically by using regular function declarations (`function() { ... }`) or explicitly assigning them as methods (`parser.onHeadersComplete = function() { ... }`) where `this` refers to the parser instance. Avoid arrow functions for these handlers unless explicitly binding their `this` context.

Warnings

breaking The `hparser` package is effectively abandoned. Its last release (v0.5.0) was over two years ago and targets extremely old Node.js versions (>=0.10.0). It receives no security updates or bug fixes, making it unsuitable for production use.
Fix: Migrate to a modern, actively maintained HTTP parsing library like `http-parser-js` or utilize Node.js's built-in `http` module for higher-level parsing.
gotcha hparser is a CommonJS-only module. Attempting to use ES module `import` syntax will result in a runtime error like `SyntaxError: Named export 'Parser' not found.`. It does not provide an ES module entry point.
Fix: Always use `const Parser = require('hparser');` for importing the module.
gotcha The library is low-level and does not come with official TypeScript type definitions. Developers using TypeScript will need to create their own declaration files (`.d.ts`) or use a generic `any` type for imports and usage, which reduces type safety.
Fix: Consider writing a `hparser.d.ts` file (e.g., `declare module 'hparser' { class Parser { /* ... */ } export = Parser; }`) or migrating to a library with built-in or community-maintained types.
breaking As a low-level parser, `hparser` requires manual handling of raw `Buffer` instances and managing parser state through event-like callbacks. It does not abstract away streaming complexities or provide high-level request/response objects directly, requiring more boilerplate code.
Fix: Implement robust error handling, buffer management, and state tracking around the parser's `execute` and `finish` methods. Alternatively, use higher-level HTTP libraries if stream-level control is not strictly required.

Install

npm install hparser npm
yarn add hparser yarn
pnpm add hparser pnpm

Imports

Parser
wrong:
```
import { Parser } from 'hparser';
```
correct:
```
const Parser = require('hparser');
```
hparser is a CommonJS module, primarily exporting the `Parser` class. ES module `import` syntax is not supported.
Parser.prototype.execute
wrong:
```
import { execute } from 'hparser';
```
correct:
```
const Parser = require('hparser');
const parser = new Parser();
parser.execute(buffer);
```
The `execute` method is part of the `Parser` class prototype and is called on an instance to feed data chunks for parsing. The `Parser` itself is the default export.
onHeadersComplete
wrong:
```
import { onHeadersComplete } from 'hparser';
```
correct:
```
const Parser = require('hparser');
const parser = new Parser();
parser.onHeadersComplete = function() { /* ... */ };
```
Event handlers like `onHeadersComplete`, `onBody`, and `onMessageComplete` are properties of a `Parser` instance, not named exports. They are assigned functions for callback-based parsing.

Quickstart

Demonstrates initializing the `Parser`, feeding it a raw HTTP request buffer, and using its callback events to extract HTTP version, method, URL, headers, and body.

const Parser = require('hparser');
const { StringDecoder } = require('string_decoder');

const rawHttpRequest = Buffer.from(
  'GET /index.html HTTP/1.1\r\n'
  + 'Host: example.com\r\n'
  + 'User-Agent: test-client\r\n'
  + 'Accept: */*\r\n'
  + '\r\n'
);

const parser = new Parser();
const decoder = new StringDecoder('utf8');

let headers = {};
let bodyChunks = [];

parser.onHeadersComplete = function() {
  console.log('HTTP Version:', this.httpMajor + '.' + this.httpMinor);
  console.log('Method:', this.method);
  console.log('URL:', decoder.write(this.url));
  for (let i = 0; i < this.headers.length; i += 2) {
    const key = decoder.write(this.headers[i]);
    const value = decoder.write(this.headers[i + 1]);
    headers[key] = value;
  }
  console.log('Headers:', headers);
};

parser.onBody = function(buffer, start, len) {
  bodyChunks.push(buffer.slice(start, start + len));
};

parser.onMessageComplete = function() {
  console.log('Parsing complete!');
  console.log('Body:', Buffer.concat(bodyChunks).toString());
};

parser.execute(rawHttpRequest);
parser.finish();

view raw JSON →