bare-http1

library4.5.6jsnpmunverified

bare-http1 is a low-level, native HTTP/1 library for JavaScript, designed for efficient and direct interaction with the HTTP/1 protocol without higher-level abstractions. It provides fundamental primitives for creating HTTP/1 servers and clients, making it suitable for environments where fine-grained control or minimal overhead is paramount. The current stable version is 4.5.6, indicating ongoing maintenance and incremental improvements, as shown by recent patch releases addressing stability. Key differentiators include its 'bare' philosophy, focusing solely on HTTP/1, and its light footprint, often used in conjunction with other 'bare-' ecosystem modules like bare-buffer and bare-url for buffer and URL handling. It ships with TypeScript types, facilitating robust development in TypeScript projects and ensuring type safety.

http-networking web-framework

npm install bare-http1

github ↗package ↗

INSTALL

IMPORT

SIG · BARE-HTTP1

bare-http1

http-networkingjavascriptv4.5.6

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.

createServer

✓ import { createServer } from 'bare-http1'

✗ const { createServer } = require('bare-http1')

Use named import for ESM. For CommonJS, destructure from the `require` result.

request

✓ import { request } from 'bare-http1'

✗ const { request } = require('bare-http1')

Similar to `createServer`, use named import for ESM or destructure for CommonJS.

http

✓ const http = require('bare-http1')

✗ import http from 'bare-http1'

The library primarily exposes named exports. When using CommonJS, the `require` call returns an object containing `createServer` and `request`.

This example demonstrates how to create a basic HTTP/1 server that listens on a random port, then makes a client request to that server, logging the response body. It showcases the core `createServer` and `request` functions for fundamental HTTP/1 communication and includes basic error handling.

import { createServer, request } from 'bare-http1'; import { Buffer } from 'bare-buffer'; const server = createServer((req, res) => { console.log(`Server received request: ${req.method} ${req.url}`); res.statusCode = 200; res.setHeader('Content-Type', 'text/plain'); res.setHeader('Content-Length', 12); res.write('hello world!'); res.end(); }); server.listen(0, () => { const { port } = server.address() as { port: number }; console.log('Server is bound on port', port); const client = request({ port, method: 'GET', path: '/' }, (res) => { console.log(`Client received response: ${res.statusCode}`); const chunks: Buffer[] = []; res.on('data', (data) => chunks.push(Buffer.from(data))); res.on('end', () => { console.log('Client received data:', Buffer.concat(chunks).toString()); server.close(() => console.log('Server closed.')); }); }); client.end(); }); server.on('error', (err) => { console.error('Server error:', err); });

Debug

Known issues

gotchaPrior to version 4.5.6, the library had a higher chance of crashing if error handlers were not explicitly set on servers and clients. It's crucial to always attach 'error' event listeners to prevent unhandled exceptions and process exits, especially in production environments.

fix

Ensure `server.on('error', ...)` and `client.on('error', ...)` listeners are always present in your code to gracefully handle network and protocol errors.

affects: <4.5.6

gotchabare-http1 provides a minimal, low-level API. Users accustomed to higher-level HTTP frameworks (e.g., Node.js `http` module or Express) should be aware that manual handling of request/response streams, headers, and body parsing (e.g., JSON, forms) is often required. There are no built-in middleware or routing capabilities.

fix

Be prepared to implement stream processing, header validation, and body parsing logic manually or integrate with other 'bare-' ecosystem modules designed for these tasks.

affects: >=1.0.0

gotchaThis library exclusively supports HTTP/1.x. It does not provide built-in support for HTTP/2 or HTTP/3. Attempting to use it with clients or servers expecting newer HTTP versions will likely result in protocol errors or unexpected behavior.

fix

For HTTP/2 or HTTP/3 communication, use dedicated libraries or proxies that support those protocols. `bare-http1` is not a drop-in replacement for multi-protocol HTTP stacks.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::<port>

The specified port is already in use by another application or a previous instance of your server that wasn't properly shut down.

fix

Choose a different port, ensure previous server instances are closed, or configure the server to listen on port 0 to let the OS assign an available port.

Error: connect ECONNREFUSED <ip>:<port>

The client attempted to connect to a server that was not listening on the specified IP address and port, or a firewall blocked the connection.

fix

Verify that the server is running and listening on the correct IP/port, check network connectivity, and ensure no firewalls are blocking the connection.

ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client

An attempt was made to modify HTTP headers or call `setHeader()` after the response body has already started being sent (e.g., after `res.write()` or `res.end()` has been called).

fix

Ensure all header-related operations (setting status code, `setHeader()`) are performed *before* any calls to `res.write()` or `res.end()`.

Upgrade

Version history

4.5.6latest on npm

Audit

Dependencies

bare-bufferrequiredEssential for buffer allocation and manipulation in low-level HTTP message processing.

bare-urlrequiredUsed for parsing and constructing URLs within HTTP requests and responses.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/holepunchto/bare-http1 ↗

packagehttps://www.npmjs.com/package/bare-http1 ↗