cURL Trace Parser

0.0.10 · abandoned · verified Wed Apr 22

curl-trace-parser is a Node.js package designed to parse the output generated by the `curl` command-line tool when using its `--trace` or `--trace-ascii` options. It extracts raw HTTP request and response messages from curl's custom trace format, which otherwise presents data in fragmented chunks. This utility is particularly useful for debugging or introspecting HTTP communication of RESTful APIs without resorting to lower-level tools like tcpdump or Wireshark. It offers output in a raw HTTP message format or an API Blueprint format. The package is at version 0.0.10 and appears to be abandoned, with no recent updates or a clear release cadence. Its key differentiator is simplifying the often complex task of interpreting curl's trace output into structured HTTP messages.

Common errors

```
TypeError: parser.on is not a function
```
cause Attempting to `new` the exported `Parser` or trying to access it as a class, instead of using the pre-instantiated EventEmitter.

fix The package exports a pre-instantiated `EventEmitter` instance directly. Use `const parser = require('curl-trace-parser');` and then `parser.on(...)`.
```
Error: stream.push() after EOF
```
cause This error typically occurs when feeding data into a stream after it has been explicitly ended, for example, by calling `parser.end()` too early.

fix Ensure `parser.end()` is called only after all trace lines have been processed by `parser.execute(line)` to correctly signal the end of input.
```
Error: Cannot find module 'curl-trace-parser'
```
cause The package is not installed or not available in the current project's `node_modules`.

fix Run `npm install curl-trace-parser` in your project directory, or `npm install -g curl-trace-parser` if you intend to use its CLI globally.

Warnings

breaking The package version 0.0.10 indicates it is pre-1.0 and highly unstable. Expect frequent, undocumented breaking changes if development were to resume. Functionality or API signatures could change without adhering to semantic versioning.
Fix: Due to its pre-1.0 status and apparent abandonment, consider this package for experimental use only. Avoid in production systems where stability is critical, or be prepared to fork and maintain it yourself.
gotcha The project appears to be abandoned. Its repository badges (Travis CI, David-DM, Greenkeeper) are outdated, and the last commit activity and version suggest no active maintenance. This implies no support for newer Node.js versions, cURL trace format changes, or security fixes.
Fix: Thoroughly test compatibility with your Node.js version and cURL output. If you encounter issues, you will likely need to debug and fix them yourself or seek alternative solutions.
gotcha The package exports an instance of `Parser` directly, which is an `EventEmitter`. Attempting `new Parser()` or expecting named exports will fail.
Fix: Always import using `const parser = require('curl-trace-parser');` to get the pre-instantiated parser instance. Listen to events like `parser.on('request', ...)` and `parser.on('response', ...)`.
gotcha The parser relies on cURL's `--trace` output format. If future cURL versions significantly alter this format, `curl-trace-parser` may break without warning or updates.
Fix: Regularly verify parser output with your specific cURL version if relying on this tool in a critical workflow. Be prepared for manual adjustments or to find alternatives if cURL's trace format evolves.

Install

npm install curl-trace-parser npm
yarn add curl-trace-parser yarn
pnpm add curl-trace-parser pnpm

Imports

parserInstance
wrong:
```
import { parser } from 'curl-trace-parser';
```
correct:
```
const parser = require('curl-trace-parser');
```
The package exports an already instantiated parser (an EventEmitter) as its default CommonJS export. It is not a class to be `new`d or a named export.
CLI usage (raw format)
wrong:
```
require('curl-trace-parser').raw(data)
```
correct:
```
cat tracefile | curl-trace-parser --raw
```
The `--raw` and `--blueprint` formatting options are primarily exposed via the command-line interface, not directly through the programmatic API (which focuses on parsing events).

Quickstart

Demonstrates programmatic usage of `curl-trace-parser` by reading a mock trace file, feeding its lines to the parser's `execute` method, listening for 'request' and 'response' events, and piping the parser's transformed output to a custom stream to collect the raw HTTP messages.

const fs = require('fs');
const { Writable } = require('stream');
const parser = require('curl-trace-parser');

// Simulate curl --trace output from a file
const traceData = fs.readFileSync('trace.log', 'utf8');

// Create a custom writable stream to capture parsed output
let rawOutput = '';
const customWriter = new Writable({
  write(chunk, encoding, callback) {
    rawOutput += chunk.toString();
    callback();
  }
});

// Pipe the parser's raw output to our custom writer
parser.pipe(customWriter);

parser.on('request', (req) => {
  console.log('--- Parsed Request ---');
  // For programmatic access, you would process the 'req' object
  // The 'req' object itself might contain structured data or just the raw lines depending on internal implementation
});

parser.on('response', (res) => {
  console.log('--- Parsed Response ---');
  // For programmatic access, you would process the 'res' object
});

// Feed the trace data line by line to the parser
traceData.split('\n').forEach(line => {
  parser.execute(line);
});

parser.end(); // Signal end of input

// After processing all lines, the rawOutput will contain the parsed HTTP messages
console.log('\n--- Raw HTTP Output from Parser Stream ---');
console.log(rawOutput);

view raw JSON →