HTTP Module

Relevant source files

• src/bun.js/bindings/c-bindings.cpp
• src/bun.js/node/node_fs.zig
• src/bun.js/node/node_fs_binding.zig
• src/bun.js/node/types.zig
• src/js/node/fs.promises.ts
• src/js/node/http.ts
• src/js/node/stream.ts
• src/main.zig
• src/output.zig
• src/sys.zig
• src/windows.zig
• test/js/node/fs/fs.test.ts
• test/js/node/http/node-http.test.ts
• test/js/node/stream/node-stream.test.js

This document covers Bun's Node.js-compatible HTTP module implementation (node:http), which provides server and client APIs for HTTP/1.1 communication. This implementation wraps Bun's native networking layer to provide a Node.js-compatible interface.

For information about the underlying networking stack (uWebSockets, event loop integration), see Socket and Network Layer. For HTTPS support, the same architecture applies with TLS wrapping. For higher-level server APIs specific to Bun, see HTTP Server (Bun.serve).

Sources: src/js/node/http.ts1-72

Module Architecture

The HTTP module is organized into several internal sub-modules that handle different aspects of HTTP communication:

The module exports a unified interface that combines functionality from these internal modules. The primary exports include:

• Server-side: createServer, Server, ServerResponse, IncomingMessage
• Client-side: request, get, ClientRequest, Agent, globalAgent
• Utilities: METHODS, STATUS_CODES, validateHeaderName, validateHeaderValue

Sources: src/js/node/http.ts1-72

Server-Side Components

Server Creation and Lifecycle

The createServer function is the primary entry point for creating HTTP servers:

The Server class (from _http_server) manages the lifecycle of incoming connections and dispatches request events. When a request arrives, the server creates an IncomingMessage instance for the request and a ServerResponse instance for the response, then invokes the user callback.

Sources: src/js/node/http.ts13-15 test/js/node/http/node-http.test.ts49-65

IncomingMessage

The IncomingMessage class represents incoming HTTP requests (on the server) or responses (on the client). It extends Node.js streams and provides access to:

• Request metadata: method, url, httpVersion, headers, rawHeaders
• Connection information: connection, socket
• Body streaming: Implements Readable stream interface for request/response body

Key properties:

• req.url - Request URL path and query string
• req.method - HTTP method (GET, POST, etc.)
• req.headers - Parsed headers object (lowercase keys)
• req.connection.encrypted - Boolean indicating TLS/HTTPS

Sources: src/js/node/http.ts5 test/js/node/http/node-http.test.ts52-61 test/js/node/http/node-http.test.ts67-79

ServerResponse

The ServerResponse class represents outgoing HTTP responses. It extends OutgoingMessage and provides methods for:

• Status and headers: writeHead(statusCode, headers), setHeader(name, value), getHeader(name)
• Body writing: write(chunk), end(data)
• State management: headersSent, finished

Key methods:

• res.writeHead(statusCode, headers) - Set status code and headers atomically
• res.setHeader(name, value) - Set individual headers before writeHead
• res.getHeader(name) / res.getHeaders() - Retrieve set headers
• res.write(chunk) - Write body data (can be called multiple times)
• res.end(data) - Finish response (optional final data chunk)

Special handling for Set-Cookie headers: stored as an array to support multiple values.

Sources: src/js/node/http.ts7 test/js/node/http/node-http.test.ts213-227

Request Processing Flow

Sources: test/js/node/http/node-http.test.ts82-106 test/js/node/http/node-http.test.ts230-369

Client-Side Components

ClientRequest

The ClientRequest class represents outgoing HTTP requests. It extends OutgoingMessage and manages:

• Request configuration: Method, URL, headers, timeout
• Body streaming: Writable stream for request body
• Response handling: Emits 'response' event with IncomingMessage
• Error handling: Connection errors, timeouts

Key methods and properties:

• req.setHeader(name, value) - Set request headers
• req.write(chunk) - Write request body data
• req.end() - Finish request (triggers sending)
• req.abort() - Cancel request
• req.path, req.method, req.host, req.protocol - Request metadata

Sources: src/js/node/http.ts3 src/js/node/http.ts64 test/js/node/http/node-http.test.ts434-451

Agent and Connection Pooling

The Agent class manages connection pooling for HTTP clients:

Agent options:

• keepAlive - Enable connection reuse
• keepAliveMsecs - TCP keep-alive delay
• maxSockets - Maximum concurrent sockets per host
• maxFreeSockets - Maximum idle sockets to keep
• timeout - Socket timeout

The module exports a globalAgent singleton used by default for all http.request() and http.get() calls unless explicitly overridden.

Sources: src/js/node/http.ts2 src/js/node/http.ts63

Request and Get Functions

The module provides two convenience functions for making HTTP requests:

The get function is a shorthand that automatically calls end() on the request, making it suitable for simple GET requests without a body.

Sources: src/js/node/http.ts24-39 test/js/node/http/node-http.test.ts434-451

Common Infrastructure

HTTP Methods and Status Codes

The module exports constants for HTTP methods and status codes:

These are imported from internal/http module.

Sources: src/js/node/http.ts9

Header Validation

The module provides header validation functions:

• validateHeaderName(name) - Validates header name syntax
• validateHeaderValue(name, value) - Validates header value syntax

These functions throw TypeError for invalid headers according to HTTP specification.

Sources: src/js/node/http.ts4 src/js/node/http.ts57-58

HTTP Parser Configuration

The module exposes parser configuration:

These control the HTTP parser behavior for memory management and security limits.

Sources: src/js/node/http.ts51-62

Request/Response Body Streaming

Both IncomingMessage and OutgoingMessage integrate with Node.js streams:

Request and response bodies can be streamed incrementally:

• Server request body: Read via 'data' events or by piping the IncomingMessage
• Server response body: Written via write() calls, finished with end()
• Client request body: Written via write() calls, finished with end()
• Client response body: Read via 'data' events or by piping the IncomingMessage

Large request/response bodies are handled efficiently through streaming without buffering the entire body in memory.

Sources: test/js/node/http/node-http.test.ts82-106 test/js/node/http/node-http.test.ts108-135

Integration with Bun's Networking Stack

The HTTP module bridges Node.js-compatible APIs with Bun's native networking:

The HTTP module's server implementation leverages Bun's high-performance Bun.serve infrastructure under the hood, while the client implementation uses Bun's native fetch for HTTP requests. This provides Node.js compatibility while maintaining Bun's performance characteristics.

Key integration points:

• Server requests/responses wrap Bun's native request/response objects
• Client requests use the fetch implementation with streaming adapters
• Headers are normalized between Node.js and Bun conventions
• Connection management uses Bun's event loop for async I/O

Sources: src/js/node/http.ts1-72

WebSocket Support

The HTTP module also exports WebSocket-related classes for upgrade scenarios:

These are re-exported from the global namespace to support WebSocket upgrades from HTTP connections, though the primary WebSocket implementation is documented elsewhere.

Sources: src/js/node/http.ts11 src/js/node/http.ts66-68

Type Definitions and Validation

The module uses several type validation utilities:

These types and validators ensure proper handling of various input formats (strings, buffers, typed arrays) across the HTTP module's surface area.

Sources: src/js/node/http.ts1 src/bun.js/node/types.zig1-133