← Cloudflare Workers / workers / runtime-apis / nodejs

http

Чтобы использовать клиентские методы HTTP (http.get, http.request, и т. д.), необходимо включить enable_nodejs_http_modules флаг совместимости в дополнение к nodejs_compat флаг.

Этот флаг автоматически включается для Workers, использующих дата совместимости 2025-08-15 или более поздней версии, когда nodejs_compat включен. Для Workers с более ранней датой совместимости его можно включить вручную, добавив флаг в файл конфигурации Wrangler:

{
	"compatibility_flags": [
		"nodejs_compat",
		"enable_nodejs_http_modules"
	]
}

compatibility_flags = [ "nodejs_compat", "enable_nodejs_http_modules" ]

Чтобы использовать серверные методы HTTP (http.createServer, http.Server, http.ServerResponse), необходимо включить enable_nodejs_http_server_modules флаг совместимости в дополнение к nodejs_compat флаг.

Этот флаг автоматически включается для Workers, использующих дата совместимости 2025-09-01 или более поздней версии, когда nodejs_compat включен. Для Workers с более ранней датой совместимости его можно включить вручную, добавив флаг в файл конфигурации Wrangler:

{
	"compatibility_flags": [
		"nodejs_compat",
		"enable_nodejs_http_server_modules"
	]
}

compatibility_flags = [ "nodejs_compat", "enable_nodejs_http_server_modules" ]

Чтобы использовать методы и на стороне клиента, и на стороне сервера, включите оба флага:

{
	"compatibility_flags": [
		"nodejs_compat",
		"enable_nodejs_http_modules",
		"enable_nodejs_http_server_modules"
	]
}

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

Реализация Node.js http.get ↗ метод.

get метод выполняет GET-запрос по указанному URL и вызывает callback-функцию с ответом. Это вспомогательный метод, упрощающий выполнение HTTP GET-запросов без ручной настройки параметров запроса.

Поскольку get представляет собой обёртку над fetch(...), его можно использовать только внутри экспортированного обработчика fetch или аналогичного. Вне такого обработчика попытки использовать get выбросит ошибку.

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

Реализация get в Workers представляет собой обёртку вокруг глобального fetch API ↗ и поэтому подпадает под те же ограничения ↗.

Как показано в примере выше, необходимо обеспечить корректное ожидание запросов в fetch обработчика с помощью promise, иначе fetch может быть преждевременно отменен после того, как обработчик завершит выполнение.

Реализация Node.js `http.request' ↗ метод.

request метод создаёт HTTP-запрос с настраиваемыми параметрами, такими как метод, заголовки и тело. Он даёт полный контроль над конфигурацией запроса и возвращает Node.js stream.Writable ↗ для отправки данных запроса.

Поскольку request представляет собой обёртку над fetch(...), его можно использовать только внутри экспортированного обработчика fetch или аналогичного. Вне такого обработчика попытки использовать request выбросит ошибку.

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

Следующие параметры, передаваемые в request (и get) метода не поддерживаются из-за отличий, обусловленных тем, как Cloudflare Workers реализует node:http как обёртку вокруг глобального fetch API:

• maxHeaderSize
• insecureHTTPParser
• createConnection
• lookup
• socketPath

OutgoingMessage ↗ класс представляет HTTP ответ, отправляемый клиенту. Он предоставляет методы для записи заголовков и тела ответа, а также для завершения ответа. OutgoingMessage наследуется от Node.js stream.Writable класс потока ↗.

OutgoingMessage класс является базовым классом для исходящих HTTP сообщений (как запросов, так и ответов). Он предоставляет методы для записи заголовков и данных тела, а также для завершения сообщения. OutgoingMessage наследуется от Writable класс потока ↗.

Оба ClientRequest и ServerResponse оба расширяют и наследуют от OutgoingMessage.

IncomingMessage класс представляет HTTP запрос, полученный от клиента. Он предоставляет методы для чтения заголовков и тела запроса, а также для завершения запроса. IncomingMessage наследуется от Readable класс потока.

IncomingMessage класс представляет HTTP сообщение (запрос или ответ). Он предоставляет методы для чтения заголовков и данных тела. IncomingMessage наследуется от Readable класс потока.

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);
		});
		// ...
	},
};

Реализация Workers включает cloudflare свойство у IncomingMessage объекты:

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

cloudflare.cf свойство содержит Специфичные для Cloudflare свойства запроса.

Между реализацией в Workers и Node.js существуют следующие различия:

• Заголовки trailer не поддерживаются
• socket атрибут не наследует от net.Socket и содержит только следующие свойства: encrypted, remoteFamily, remoteAddress, remotePort, localAddress, localPort, а также destroy() метод.
• Следующие socket атрибуты ведут себя иначе, чем их аналоги в Node.js:
  • remoteAddress вернёт 127.0.0.1 при локальном запуске
  • remotePort вернёт случайный номер порта в диапазоне от 2^15 до 2^16
  • localAddress вернёт значение свойства request host заголовок, если он существует. В противном случае будет возвращён 127.0.0.1
  • localPort вернёт номер порта, присвоенный экземпляру сервера
  • req.socket.destroy() переходит к req.destroy()

Частичная реализация Node.js `http.Agent' ↗ в качестве класса.

Одна Agent управляет повторным использованием HTTP-соединений, поддерживая очереди запросов для каждого хоста и порта. Однако в среде workers такое низкоуровневое управление сетевым соединением, портами и прочим не имеет значения, поскольку этим занимается инфраструктура Cloudflare. Поэтому реализация Agent в Workers представляет собой заглушку, которая не поддерживает пул соединений или keep-alive.

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

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

Реализация Node.js http.createServer ↗ метод.

createServer метод создаёт экземпляр HTTP-сервера, способный обрабатывать входящие запросы.

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

httpServerHandler функция интегрирует HTTP-серверы Node.js с моделью запросов Cloudflare Workers. Она поддерживает два шаблона API:

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

Обработчик автоматически направляет входящие запросы Worker на ваш сервер Node.js. При маршрутизации на основе портов номер порта служит ключом, определяющим, какой сервер обрабатывает запрос, что позволяет нескольким серверам работать в рамках одного Worker.

Для более прямого контроля над маршрутизацией запросов можно использовать handleAsNodeRequest функцию из cloudflare:node. Эта функция напрямую направляет запрос Worker на сервер Node.js, работающий на определённом порту:

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

Такой подход даёт вам полный контроль над обработчиком fetch, при этом позволяя использовать HTTP-серверы Node.js для обработки запросов.

Реализация Node.js http.Server ↗ в качестве класса.

Server класс представляет HTTP сервер и предоставляет методы для обработки входящих запросов. Он расширяет Node.js EventEmitter класс, и его можно использовать для создания собственных реализаций сервера.

При использовании httpServerHandler, номер порта, указанный в server.listen() выступает в роли ключа маршрутизации, а не настоящего сетевого порта. По этому порту обработчик определяет, какой экземпляр HTTP сервера должен обслуживать входящий запрос, что позволяет нескольким серверам сосуществовать в рамках одного Worker благодаря разным номерам портов для идентификации. При значении порта 0 (или null или undefined) приведёт к назначению случайного номера порта.

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

Между реализацией в Workers и Node.js существуют следующие различия:

• Методы управления соединением, такие как closeAllConnections() и closeIdleConnections() не реализованы
• Только listen() поддерживаются варианты с номером порта или без параметров: listen(), listen(0, callback), listen(callback), и т. д. Подробнее см. в документация Node.js ↗.
• Следующие серверные параметры не поддерживаются: maxHeaderSize, insecureHTTPParser, keepAliveTimeout, connectionsCheckingInterval

Реализация Node.js http.ServerResponse ↗ в качестве класса.

ServerResponse класс представляет серверный объект ответа, который передаётся обработчикам запросов. Он предоставляет методы для записи заголовков и данных тела ответа и расширяет Node.js Writable класс потока.

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

В реализации Workers не поддерживаются следующие методы и возможности:

• assignSocket() и detachSocket() методы недоступны
• Заголовки trailer не поддерживаются
• writeContinue() и writeEarlyHints() методы недоступны
• Ответы 1xx в целом не поддерживаются

Поскольку в Workers реализация node:http представляет собой обёртку над глобальным fetch API есть отличия в поведении и ограничениях по сравнению со стандартным окружением Node.js:

• Connection заголовки не используются. Workers будет управлять соединениями автоматически.
• Content-Length заголовки будут обрабатываться так же, как в fetch API. Если указано тело запроса, заголовок устанавливается автоматически, а значения, заданные вручную, игнорируются.
• Expect: 100-continue заголовки не поддерживаются.
• Завершающие заголовки не поддерживаются.
• 'continue' событие не поддерживается.
• 'information' событие не поддерживается.
• 'socket' событие не поддерживается.
• 'upgrade' событие не поддерживается.
• Получение прямого доступа к базовой socket не поддерживается.