Registry / http-networking / bare-http-parser

bare-http-parser

library1.1.3jsnpmunverified

bare-http-parser is a streaming HTTP request and response parser specifically designed for the Bare JavaScript runtime. Bare is a lightweight, modular runtime optimized for desktop and mobile environments, emphasizing embedded and cross-device support, particularly for peer-to-peer applications. This library, currently at version 1.1.3, provides the foundational capability to interpret raw HTTP stream data efficiently within the Bare ecosystem. Unlike traditional HTTP parsers that might operate on complete buffered messages, bare-http-parser processes data as it arrives, making it suitable for low-latency network operations characteristic of peer-to-peer systems. Its release cadence aligns with the development of the broader Holepunch/Bare project, with updates typically coinciding with advancements in the runtime itself. This parser is a critical component for building HTTP-based networking features directly within Bare applications, leveraging its stream-first architecture.

http-networking web-framework

npm install bare-http-parser

github ↗package ↗

INSTALL

IMPORT

SIG · BARE-HTTP-PARSER

bare-http-parser

http-networkingjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HTTPRequestParser

✓ import { HTTPRequestParser } from 'bare-http-parser'

✗ const { HTTPRequestParser } = require('bare-http-parser')

While Bare supports both ESM and CJS, ESM import syntax is preferred. CommonJS require() will work but is considered legacy for new development.

HTTPResponseParser

✓ import { HTTPResponseParser } from 'bare-http-parser'

✗ const { HTTPResponseParser } = require('bare-http-parser')

Used for parsing incoming HTTP response streams. Ensure proper stream handling to avoid data loss or parsing errors.

HTTPParserError

✓ import { HTTPParserError } from 'bare-http-parser/errors'

✗ import { HTTPParserError } from 'bare-http-parser'

Error classes are exported from a dedicated subpath for better modularity and tree-shaking.

This example demonstrates parsing a raw HTTP request and response using `HTTPRequestParser` and `HTTPResponseParser` classes, handling streaming data and event emission for headers, request/response lines, and body data.

import { HTTPRequestParser, HTTPResponseParser } from 'bare-http-parser'; import { Buffer } from 'buffer'; // Bare provides a Buffer implementation const rawRequest = Buffer.from( 'GET /hello HTTP/1.1\r\n' + 'Host: example.com\r\n' + 'User-Agent: bare-client/1.0\r\n' + 'Content-Length: 13\r\n' + '\r\n' + 'Hello, World!' ); const requestParser = new HTTPRequestParser(); let parsedRequest = { headers: {}, method: '', url: '', body: '' }; requestParser.on('headers', (headers) => { parsedRequest.headers = Object.fromEntries(headers); }); requestParser.on('request', (requestLine) => { parsedRequest.method = requestLine.method; parsedRequest.url = requestLine.url; }); requestParser.on('data', (chunk) => { parsedRequest.body += chunk.toString(); }); requestParser.on('end', () => { console.log('Parsed Request:', parsedRequest); if (parsedRequest.body !== 'Hello, World!') { console.error('Request body mismatch!'); } }); requestParser.on('error', (err) => { console.error('Request parsing error:', err.message); }); requestParser.write(rawRequest); requestParser.end(); const rawResponse = Buffer.from( 'HTTP/1.1 200 OK\r\n' + 'Content-Type: text/plain\r\n' + 'Content-Length: 12\r\n' + '\r\n' + 'Hello client' ); const responseParser = new HTTPResponseParser(); let parsedResponse = { headers: {}, statusCode: 0, statusMessage: '', body: '' }; responseParser.on('headers', (headers) => { parsedResponse.headers = Object.fromEntries(headers); }); responseParser.on('response', (statusLine) => { parsedResponse.statusCode = statusLine.statusCode; parsedResponse.statusMessage = statusLine.statusMessage; }); responseParser.on('data', (chunk) => { parsedResponse.body += chunk.toString(); }); responseParser.on('end', () => { console.log('Parsed Response:', parsedResponse); if (parsedResponse.body !== 'Hello client') { console.error('Response body mismatch!'); } }); responseParser.on('error', (err) => { console.error('Response parsing error:', err.message); }); responseParser.write(rawResponse); responseParser.end();

Debug

Known issues

gotchaAs a streaming parser, `bare-http-parser` requires careful handling of incomplete or malformed HTTP streams. If a stream ends prematurely (e.g., connection closes before Content-Length bytes are received), the parser may not emit an 'end' event for the body, potentially leading to incomplete data. Ensure stream integrity or implement robust error recovery for network failures.

fix

Implement explicit timeout mechanisms and 'error' event listeners. Validate parsed content lengths against actual received body data. For `Content-Length` mismatches, consider the stream closed prematurely.

affects: >=1.0.0

gotchaInteroperability between CommonJS (CJS) and ES Modules (ESM) in JavaScript runtimes, including Bare, can be complex, especially with default vs. named imports. While Bare aims for bidirectional interoperability, unexpected behavior can arise when mixing module types or consuming packages compiled with different transpiler assumptions.

fix

Prefer ESM `import` syntax. If encountering issues with `require()`, explicitly check the package's `exports` map in its `package.json` for correct paths and module types. Ensure your project's `tsconfig.json` (if using TypeScript) or build configuration is aligned with the target module system.

affects: >=1.0.0

gotchaHTTP headers can occasionally contain duplicate keys (e.g., 'Set-Cookie'). The parser provides raw header arrays where duplicates may exist. Directly converting these to a simple object (`Object.fromEntries`) will only retain the last value for a given header name, potentially losing information.

fix

When processing headers, iterate over the raw headers array (e.g., `[['Header-Name', 'value1'], ['Header-Name', 'value2']]`) and store values in an array for multi-value headers, rather than overwriting them in a simple object. For example, `headers[name].push(value)`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: HTTPRequestParser is not a constructor

Attempting to use `HTTPRequestParser` (or `HTTPResponseParser`) without correctly importing it from the module. This often happens with incorrect CommonJS `require()` syntax or trying to use a non-existent default export.

fix

Ensure you are using named imports: `import { HTTPRequestParser } from 'bare-http-parser';` for ESM, or `const { HTTPRequestParser } = require('bare-http-parser');` for CommonJS.

Error: premature close

The underlying stream or connection was closed before the HTTP message parsing was complete, typically indicating truncated data or a network issue.

fix

Implement comprehensive error handling on the parser's 'error' event and the underlying stream's 'close' or 'end' events. Consider adding timeouts to detect stalled connections. For client applications, retry logic might be necessary. For servers, send an appropriate HTTP error response.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/holepunchto/bare-http-parser ↗

packagehttps://www.npmjs.com/package/bare-http-parser ↗