This page documents Bun's node:http and node:https compatibility modules: the classes they expose, how the module is assembled from internal submodules, and how the Node.js-style callback API maps to Bun's native HTTP stack.
For Bun's native HTTP server (Bun.serve), see page 5.1 For the native fetch() client, see page 5.2 For WebSocket support, see page 5.3 For node:stream compatibility, see page 8.6
node:http and node:https are compatibility modules that expose Node.js's HTTP callback-style API. They are implemented as a JavaScript layer in src/js/node/http.ts that assembles classes from several internal submodules. At runtime, these classes delegate to Bun's native HTTP engine (uWS/libusockets) and fetch() stack under the hood.
The node:http module in src/js/node/http.ts is a thin re-export layer. It imports from internal private submodules and the internal/http utility module, then combines them into a single export object.
Module Assembly Diagram
Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L1-L10" min=1 max=10 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L46-L82" min=46 max=82 file-path="src/js/node/http.ts">Hii</FileRef>
The following symbols are exported from node:http:
| Export | Source submodule | Description |
|---|---|---|
Agent | node:_http_agent | Connection pool / keep-alive manager |
globalAgent | node:_http_agent | Default global Agent instance |
ClientRequest | node:_http_client | Outgoing client HTTP request |
IncomingMessage | node:_http_incoming | Incoming message (server requests, client responses) |
OutgoingMessage | node:_http_outgoing | Base class for outgoing messages |
Server | node:_http_server | HTTP server |
ServerResponse | node:_http_server | Server-side response object |
createServer | src/js/node/http.ts | Factory: new Server(options, callback) |
request | src/js/node/http.ts | Factory: new ClientRequest(url, options, cb) |
get | src/js/node/http.ts | request() + immediate .end() |
METHODS | internal/http | Array of HTTP method strings |
STATUS_CODES | internal/http | Object mapping status codes to reason phrases |
maxHeaderSize | internal/http | Get/set max HTTP header size |
validateHeaderName | node:_http_common | Validates a header field name |
validateHeaderValue | node:_http_common | Validates a header field value |
setMaxIdleHTTPParsers | src/js/node/http.ts | Sets parsers.max via validateInteger |
WebSocket | globalThis | Re-exported from global |
Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L46-L82" min=46 max=82 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L18-L44" min=18 max=44 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L64-L67" min=64 max=67 file-path="src/js/node/http.ts">Hii</FileRef>
OutgoingMessage serves as the base class for both ServerResponse and ClientRequest, providing common header and stream handling logic.
Class Hierarchy Diagram
Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_outgoing.ts#L18-L20" min=18 max=20 file-path="src/js/node/_http_outgoing.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_server.ts#L74-L84" min=74 max=84 file-path="src/js/node/_http_server.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L164-L168" min=164 max=168 file-path="src/js/node/_http_client.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_incoming.ts#L1-L10" min=1 max=10 file-path="src/js/node/_http_incoming.ts">Hii</FileRef>
node:http.Server)Server is created via createServer(options?, callback?) or new Server(options, callback). The request callback receives (IncomingMessage, ServerResponse).
Key Behaviors:
req.connection.encrypted = false <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L69-L84" min=69 max=84 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.server.listen() returns the server instance itself, allowing for method chaining <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L140-L146" min=140 max=146 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.this === server) <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L148-L161" min=148 max=161 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.0, undefined, or no port <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L163-L195" min=163 max=195 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L18-L20" min=18 max=20 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L52-L68" min=52 max=68 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>
ServerResponse handles the server's response to an incoming request. It inherits from OutgoingMessage and implements the Writable stream interface.
Implementation Details:
res.setHeader() supports array values for headers like Set-Cookie <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L216-L220" min=216 max=220 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.kOutHeaders and headerStateSymbol <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_server.ts#L39-L68" min=39 max=68 file-path="src/js/node/_http_server.ts">Hii</FileRef>.strictContentLength(response) <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_server.ts#L174-L195" min=174 max=195 file-path="src/js/node/_http_server.ts">Hii</FileRef>.write and end methods <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/test/js/node/http/node-http.test.ts#L85-L109" min=85 max=109 file-path="test/js/node/http/node-http.test.ts">Hii</FileRef>.Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_server.ts#L1-L68" min=1 max=68 file-path="src/js/node/_http_server.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_outgoing.ts#L74-L83" min=74 max=83 file-path="src/js/node/_http_outgoing.ts">Hii</FileRef>
ClientRequest represents an in-flight outgoing request. It can be initiated using http.request() or http.get().
Initialization:
URL objects, or options objects <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L170-L187" min=170 max=187 file-path="src/js/node/_http_client.ts">Hii</FileRef>.Agent.globalAgent if no agent is specified <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L189-L193" min=189 max=193 file-path="src/js/node/_http_client.ts">Hii</FileRef>.urlToHttpOptions <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L172-L175" min=172 max=175 file-path="src/js/node/_http_client.ts">Hii</FileRef>.Proxy Support:
rewriteForProxiedHttp to handle absolute-form request paths and proxy headers (proxy-authorization, proxy-connection) when an agent with proxy configuration is used <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L111-L149" min=111 max=149 file-path="src/js/node/_http_client.ts">Hii</FileRef>.Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L29-L31" min=29 max=31 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_client.ts#L164-L203" min=164 max=203 file-path="src/js/node/_http_client.ts">Hii</FileRef>
Agent manages a pool of connections for HTTP clients, enabling keep-alive and connection reuse.
globalAgent: The default agent used by http.request if none is provided <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L71-L76" min=71 max=76 file-path="src/js/node/http.ts">Hii</FileRef>.setGlobalProxyFromEnv(): Configures the global agents based on environment variables (HTTP_PROXY, HTTPS_PROXY), returning a restore function <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L92-L138" min=92 max=138 file-path="src/js/node/http.ts">Hii</FileRef>.keepAlive: true and specific scheduling (e.g., "lifo") <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L112-L117" min=112 max=117 file-path="src/js/node/http.ts">Hii</FileRef>.Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L2-L3" min=2 max=3 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L110-L128" min=110 max=128 file-path="src/js/node/http.ts">Hii</FileRef>
Bun's node:http implementation bridges Node.js's JavaScript-heavy API with Bun's high-performance C++ and Rust core. The RequestContext in Rust manages the lifecycle of the request/response pair, while JSJSSink classes handle the streaming of data from JavaScript to the native transport.
Native Entity Mapping
Data Flow Sequence
Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/codegen/generate-jssink.ts#L6-L8" min=6 max=8 file-path="src/codegen/generate-jssink.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/runtime/server/RequestContext.rs#L128-L155" min=128 max=155 file-path="src/runtime/server/RequestContext.rs">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_server.ts#L105-L108" min=105 max=108 file-path="src/js/node/_http_server.ts">Hii</FileRef>
Bun enforces strict validation for HTTP headers to prevent injection attacks and ensure spec compliance.
validateHeaderName: Checks for invalid characters in header keys <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_common.ts#L8-L10" min=8 max=10 file-path="src/js/node/_http_common.ts">Hii</FileRef>.validateHeaderValue: Checks for invalid characters (like CRLF) in header values <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/_http_common.ts#L9-L11" min=9 max=11 file-path="src/js/node/_http_common.ts">Hii</FileRef>.maxHeaderSize: Limits the total size of HTTP headers to prevent DoS, managed via internal/http <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L56-L61" min=56 max=61 file-path="src/js/node/http.ts">Hii</FileRef>.setMaxIdleHTTPParsers: Allows tuning the parser pool size <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L64-L67" min=64 max=67 file-path="src/js/node/http.ts">Hii</FileRef>.Sources: <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L62-L63" min=62 max=63 file-path="src/js/node/http.ts">Hii</FileRef>, <FileRef file-url="https://github.com/oven-sh/bun/blob/6618e7f7/src/js/node/http.ts#L10-L11" min=10 max=11 file-path="src/js/node/http.ts">Hii</FileRef>