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"]

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.

Because get is a wrapper around fetch(...), it may be used only within an exported fetch or similar handler. Outside of such a handler, attempts to use get will throw an error.

import { get } from "node:http";

export default {
  async fetch() {
    const { promise, resolve, reject } = Promise.withResolvers();
    get("http://example.org", (res) => {
      let data = "";
      res.setEncoding("utf8");
      res.on("data", (chunk) => {
        data += chunk;
      });
      res.on("end", () => {
        resolve(new Response(data));
      });
      res.on("error", reject);
    }).on("error", reject);
    return promise;
  },
};

The implementation of get in Workers is a wrapper around the global fetch API ↗ and is therefore subject to the same limits ↗.

As shown in the example above, it is necessary to arrange for requests to be correctly awaited in the fetch handler using a promise or the fetch may be canceled prematurely when the handler returns.

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 Node.js stream.Writable ↗ for sending request data.

Because request is a wrapper around fetch(...), it may be used only within an exported fetch or similar handler. Outside of such a handler, attempts to use request will throw an error.

import { get } from "node:http";

export default {
  async fetch() {
    const { promise, resolve, reject } = Promise.withResolvers();
    get(
      {
        method: "GET",
        protocol: "http:",
        hostname: "example.org",
        path: "/",
      },
      (res) => {
        let data = "";
        res.setEncoding("utf8");
        res.on("data", (chunk) => {
          data += chunk;
        });
        res.on("end", () => {
          resolve(new Response(data));
        });
        res.on("error", reject);
      },
    )
      .on("error", reject)
      .end();
    return promise;
  },
};

The following options passed to the request (and get) method are not supported due to the differences required by Coudflare Workers implementation of node:http as a wrapper around the global fetch API:

• maxHeaderSize
• insecureHTTPParser
• createConnection
• lookup
• socketPath

OutgoingMessage

The OutgoingMessage ↗ class represents an HTTP response that is sent to the client. It provides methods for writing response headers and body, as well as for ending the response. OutgoingMessage extends from the Node.js stream.Writable stream 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 ↗.

Both ClientRequest and ServerResponse both extend from and inherit from OutgoingMessage.

IncomingMessage

The IncomingMessage class represents an HTTP request that is received from the client. It provides methods for reading request headers and body, as well as for ending the request. IncomingMessage extends from the Readable stream 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";

export default {
  async fetch() {
    // ...
    get("http://example.org", (res) => {
      ok(res instanceof IncomingMessage);
    });
    // ...
  },
};

The Workers implementation includes a cloudflare property on IncomingMessage objects:

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

const server = createServer((req, res) => {
  console.log(req.cloudflare.cf.country);
  console.log(req.cloudflare.cf.ray);
  res.write("Hello, World!");
  res.end();
});

server.listen(8080);

export default httpServerHandler({ port: 8080 });

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.
• The following socket attributes behave differently than their Node.js counterparts:
  • remoteAddress will return 127.0.0.1 when ran locally
  • remotePort will return a random port number between 2^15 and 2^16
  • localAddress will return the value of request's host header if exists. Otherwise, it will return 127.0.0.1
  • localPort will return the port number assigned to the server instance
  • req.socket.destroy() falls through to req.destroy()

Agent

A partial 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:");

createServer

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

The createServer method creates an HTTP server instance that can handle incoming requests.

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

Node.js integration

httpServerHandler

The httpServerHandler function integrates Node.js HTTP servers with the Cloudflare Workers request model. It supports two API patterns:

import http from "node:http";
import { httpServerHandler } from "cloudflare:node";

const server = http.createServer((req, res) => {
  res.end("hello world");
});

// Pass server directly (simplified) - automatically calls listen() if needed
export default httpServerHandler(server);

// Or use port-based routing for multiple servers
server.listen(8080);
export default httpServerHandler({ port: 8080 });

The handler automatically routes incoming Worker requests to your Node.js server. When using port-based routing, the port number acts as a routing key to determine which server handles requests, allowing multiple servers to coexist in the same Worker.

handleAsNodeRequest

For more direct control over request routing, you can use the handleAsNodeRequest function from cloudflare:node. This function directly routes a Worker request to a Node.js server running on a specific port:

import { createServer } from "node:http";
import { handleAsNodeRequest } 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 {
  fetch(request) {
    return handleAsNodeRequest(8080, request);
  },
};

This approach gives you full control over the fetch handler while still leveraging Node.js HTTP servers for request processing.

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 ↗.

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. Using a port value of 0 (or null or undefined) will result in a random port number being assigned.

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. For reference, see the Node.js documentation ↗.
• 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, ServerResponse } from "node:http";
import { httpServerHandler } from "cloudflare:node";
import { ok } from "node:assert";

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

export default httpServerHandler(server);

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

Other differences between Node.js and Workers implementation of node:http

Because the Workers implementation of node:http is a wrapper around the global fetch API, there are some differences in behavior and limitations compared to a standard Node.js environment:

• Connection headers are not used. Workers will manage connections automatically.
• Content-Length headers will be handled the same way as in the fetch API. If a body is provided, the header will be set automatically and manually set values will be ignored.
• Expect: 100-continue headers are not supported.
• Trailing headers are not supported.
• The 'continue' event is not supported.
• The 'information' event is not supported.
• The 'socket' event is not supported.
• The 'upgrade' event is not supported.
• Gaining direct access to the underlying socket is not supported.