http

Note

To enable built-in Node.js APIs and polyfills, add the nodejs_compat compatibility flag to your Wrangler configuration file. This also enables nodejs_compat_v2 as long as your compatibility date is 2024-09-23 or later. Learn more about the Node.js compatibility flag and v2.

Compatibility flags

Client-side methods

To use the HTTP client-side methods (http.get, http.request, etc.), you must enable the enable_nodejs_http_modules compatibility flag in addition to the nodejs_compat flag.

This flag is automatically enabled for Workers using a compatibility date of 2025-08-15 or later when nodejs_compat is enabled. For Workers using an earlier compatibility date, you can manually enable it by adding the flag to your wrangler.toml:

compatibility_flags = ["nodejs_compat", "enable_nodejs_http_modules"]

Server-side methods

To use the HTTP server-side methods (http.createServer, http.Server, http.ServerResponse), you must enable the enable_nodejs_http_server_modules compatibility flag in addition to the nodejs_compat flag.

This flag is automatically enabled for Workers using a compatibility date of 2025-09-01 or later when nodejs_compat is enabled. For Workers using an earlier compatibility date, you can manually enable it by adding the flag to your wrangler.toml:

compatibility_flags = ["nodejs_compat", "enable_nodejs_http_server_modules"]

To use both client-side and server-side methods, enable both flags:

compatibility_flags = ["nodejs_compat", "enable_nodejs_http_modules", "enable_nodejs_http_server_modules"]

Agent

An implementation of the Node.js http.Agent ↗ class.

An Agent ↗ manages HTTP connection reuse by maintaining request queues per host/port. In the Workers environment, however, such low-level management of the network connection, ports, etc, is not relevant because it is handled by the Cloudflare infrastructure instead. Accordingly, the implementation of Agent in Workers is a stub implementation that does not support connection pooling or keep-alive.

import { Agent } from 'node:http';
import { strictEqual } from 'node:assert';

const agent = new Agent();
strictEqual(agent.protocol, 'http:');

get

An implementation of the Node.js http.get ↗ method.

The get method performs a GET request to the specified URL and invokes the callback with the response. It's a convenience method that simplifies making HTTP GET requests without manually configuring request options.

import { get } from 'node:http';
import { strictEqual, ok } from 'node:assert';

get('http://docs.cloudflare.com/robots.txt', (res) => {
  // requests to http://docs.cloudflare.com get redirected to their https counterpart.
  strictEqual(res.statusCode, 301);
  let data = '';
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    ok(data.includes('301 Moved Permanently'));
  });
});

request

An implementation of the Node.js http.request ↗ method.

The request method creates an HTTP request with customizable options like method, headers, and body. It provides full control over the request configuration and returns a writable stream ↗ for sending request data.

import { request } from 'node:http';
import { strictEqual, ok } from 'node:assert';

const req = request({
  method: 'GET',
  protocol: 'http:',
  hostname: 'docs.cloudflare.com',
  path: '/'
}, (res) => {
  // requests to http://docs.cloudflare.com get redirected to their https counterpart.
  strictEqual(res.statusCode, 301);

  let data = '';
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    ok(data.includes('301 Moved Permanently'));
  });
});
req.end();

import { request } from 'node:http';
import { strictEqual } from 'node:assert';

const req = request(new URL('http://docs.cloudflare.com'), {
  method: 'GET',
}, (res) => {
  // requests to http://docs.cloudflare.com get redirected to their https counterpart.
  strictEqual(res.statusCode, 301);
});

req.end();

The following options passed to the request method are not supported due to differences in the Cloudflare Workers implementation of the node:http module:

• maxHeaderSize
• insecureHTTPParser
• createConnection
• lookup
• socketPath

OutgoingMessage

An implementation of the Node.js http.OutgoingMessage ↗ class.

The OutgoingMessage class is a base class for outgoing HTTP messages (both requests and responses). It provides methods for writing headers and body data, as well as for ending the message. OutgoingMessage extends from the Writable stream class ↗.

import { OutgoingMessage } from 'node:http';

const res = new OutgoingMessage();
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('Hello, World!');
res.end();

IncomingMessage

An implementation of the Node.js http.IncomingMessage ↗ class.

The IncomingMessage class represents an HTTP message (request or response). It provides methods for reading headers and body data. IncomingMessage extends from the Readable stream class.

import { get, IncomingMessage } from 'node:http';
import { ok, strictEqual } from 'node:assert';

get('http://docs.cloudflare.com', (res) => {
  strictEqual(res.statusCode, 301);
  ok(res instanceof IncomingMessage);
});

The Workers implementation includes a cloudflare property on IncomingMessage objects:

import { get } from 'node:http';

get('http://example.com', (res) => {
  // Access Cloudflare-specific request properties
  console.log(res.cloudflare.cf.country);
  console.log(res.cloudflare.cf.ray);
});

The cloudflare.cf property contains Cloudflare-specific request properties.

The following differences exist between the Workers implementation and Node.js:

• Trailer headers are not supported
• The socket attribute does not extend from net.Socket and only contains the following properties: encrypted, remoteFamily, remoteAddress, remotePort, localAddress, localPort, and destroy() method

createServer

An implementation of the Node.js http.createServer ↗ method.

The createServer method creates an HTTP server instance that can handle incoming requests. It's a convenience function that creates a new Server instance and optionally sets up a request listener callback.

import { createServer } from 'node:http';
import { httpServerHandler } from 'cloudflare:node';

const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Node.js HTTP server!');
});

server.listen(8080);
export default httpServerHandler({ port: 8080 });

The httpServerHandler function integrates Node.js HTTP servers with the Cloudflare Workers request model. When a request arrives at your Worker, the handler automatically routes it to your Node.js server running on the specified port. This bridge allows you to use familiar Node.js server patterns while benefiting from the Workers runtime environment, including automatic scaling, edge deployment, and integration with other Cloudflare services.

Note

Failing to call close() on an HTTP server may result in the server persisting until the worker is destroyed. In most cases, this is not an issue since servers typically live for the lifetime of the worker. However, if you need to create multiple servers during a worker's lifetime or want explicit lifecycle control (such as in test scenarios), call close() when you're done with the server, or use explicit resource management:

import { createServer } from 'node:http';

await using server = createServer((req, res) => {
  res.end('Hello World');
});
// Server will be automatically closed when it goes out of scope

Server

An implementation of the Node.js http.Server ↗ class.

The Server class represents an HTTP server and provides methods for handling incoming requests. It extends the Node.js EventEmitter class and can be used to create custom server implementations.

When using httpServerHandler, the port number specified in server.listen() acts as a routing key rather than an actual network port. The handler uses this port to determine which HTTP server instance should handle incoming requests, allowing multiple servers to coexist within the same Worker by using different port numbers for identification.

import { Server } from 'node:http';
import { httpServerHandler } from 'cloudflare:node';

const server = new Server((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: 'Hello from HTTP Server!' }));
});

server.listen(8080);
export default httpServerHandler({ port: 8080 });

The following differences exist between the Workers implementation and Node.js:

• Connection management methods such as closeAllConnections() and closeIdleConnections() are not implemented
• Only listen() variants with a port number or no parameters are supported: listen(), listen(0, callback), listen(callback), etc.
• The following server options are not supported: maxHeaderSize, insecureHTTPParser, keepAliveTimeout, connectionsCheckingInterval

ServerResponse

An implementation of the Node.js http.ServerResponse ↗ class.

The ServerResponse class represents the server-side response object that is passed to request handlers. It provides methods for writing response headers and body data, and extends the Node.js Writable stream class.

import { createServer } from 'node:http';
import { httpServerHandler } from 'cloudflare:node';

const server = createServer((req, res) => {
  ok(res instanceof ServerResponse);

  // Set multiple headers at once
  res.writeHead(200, {
    'Content-Type': 'application/json',
    'X-Custom-Header': 'Workers-HTTP'
  });

  // Stream response data
  res.write('{"data": [');
  res.write('{"id": 1, "name": "Item 1"},');
  res.write('{"id": 2, "name": "Item 2"}');
  res.write(']}');

  // End the response
  res.end();
});

server.listen(8080);
export default httpServerHandler({ port: 8080 });

The following methods and features are not supported in the Workers implementation:

• assignSocket() and detachSocket() methods are not available
• Trailer headers are not supported
• writeContinue() and writeEarlyHints() methods are not available
• 1xx responses in general are not supported