Bare HTTP/1 Library

Common errors

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

  cause 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>

  cause 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

  cause 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()`.

Warnings

• gotcha Prior 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.
• gotcha bare-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.
• gotcha This 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.

Install

• npm install bare-http1 npm
• yarn add bare-http1 yarn
• pnpm add bare-http1 pnpm

Imports

• createServer
  wrong:

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

  correct:

  import { createServer } from 'bare-http1'

  Use named import for ESM. For CommonJS, destructure from the `require` result.
• request
  wrong:

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

  correct:

  import { request } from 'bare-http1'

  Similar to `createServer`, use named import for ESM or destructure for CommonJS.
• http
  wrong:

  import http from 'bare-http1'

  correct:

  const http = require('bare-http1')

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

Quickstart

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);
});