← Cloudflare Workers / workers / runtime-apis / nodejs

http

Chcete-li používat metody HTTP na straně klienta (http.get, http.request, atd.), musíte povolit enable_nodejs_http_modules příznak kompatibility navíc k nodejs_compat příznak.

Tento příznak se automaticky povolí pro Workery používající compatibility date z 2025-08-15 nebo novější, když nodejs_compat je povoleno. U Workerů s dřívějším datem kompatibility jej můžete povolit ručně přidáním příznaku do konfiguračního souboru Wrangler:

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

compatibility_flags = [ "nodejs_compat", "enable_nodejs_http_modules" ]

Chcete-li používat metody HTTP na straně serveru (http.createServer, http.Server, http.ServerResponse), musíte povolit enable_nodejs_http_server_modules příznak kompatibility navíc k nodejs_compat příznak.

Tento příznak se automaticky povolí pro Workery používající compatibility date z 2025-09-01 nebo novější, když nodejs_compat je povoleno. U Workerů s dřívějším datem kompatibility jej můžete povolit ručně přidáním příznaku do konfiguračního souboru Wrangler:

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

compatibility_flags = [ "nodejs_compat", "enable_nodejs_http_server_modules" ]

Chcete-li použít metody na straně klienta i na straně serveru, povolte oba příznaky:

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

Implementace Node.js http.get ↗ metoda.

get metoda provede GET požadavek na zadanou URL adresu a zavolá callback s odpovědí. Jde o pomocnou metodu, která zjednodušuje vytváření HTTP GET požadavků bez nutnosti ručně konfigurovat možnosti požadavku.

Protože get je obal kolem fetch(...), lze jej použít pouze uvnitř exportovaného handleru fetch nebo podobného. Mimo takový handler se pokusy o použití get vyvolá chybu.

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

Implementace get ve Workers je wrapperem kolem globálního fetch API ↗ a proto podléhá stejným limity ↗.

Jak ukazuje příklad výše, je nutné zajistit, aby na požadavky bylo správně čekáno (await) v fetch handler pomocí promise, jinak může být fetch předčasně zrušen, když se handler vrátí.

Implementace Node.js `http.request' ↗ metoda.

request metoda vytváří HTTP požadavek s přizpůsobitelnými možnostmi, jako je metoda, hlavičky a tělo. Poskytuje plnou kontrolu nad konfigurací požadavku a vrací Node.js stream.Writable ↗ pro odesílání dat požadavku.

Protože request je obal kolem fetch(...), lze jej použít pouze uvnitř exportovaného handleru fetch nebo podobného. Mimo takový handler se pokusy o použití request vyvolá chybu.

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

Následující možnosti předané do request (a get) metody nejsou podporovány kvůli rozdílům, které vyžaduje implementace Cloudflare Workers pro node:http jako obal kolem globálního fetch API:

• maxHeaderSize
• insecureHTTPParser
• createConnection
• lookup
• socketPath

OutgoingMessage ↗ třída reprezentuje HTTP odpověď odesílanou klientovi. Poskytuje metody pro zápis hlaviček a těla odpovědi i pro její ukončení. OutgoingMessage dědí od Node.js stream.Writable třída streamu ↗.

OutgoingMessage třída je základní třídou pro odchozí HTTP zprávy (jak požadavky, tak odpovědi). Poskytuje metody pro zápis hlaviček a těla zprávy i pro její ukončení. OutgoingMessage dědí od Writable třída streamu ↗.

Obojí ClientRequest a ServerResponse oba dědí z OutgoingMessage.

IncomingMessage třída reprezentuje HTTP požadavek přijatý od klienta. Poskytuje metody pro čtení hlaviček a těla požadavku i pro jeho ukončení. IncomingMessage dědí od Readable třída streamu.

IncomingMessage třída reprezentuje HTTP zprávu (požadavek nebo odpověď). Poskytuje metody pro čtení hlaviček a dat těla. IncomingMessage dědí od Readable třída streamu.

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

Implementace Workers zahrnuje cloudflare vlastnost na IncomingMessage objekty:

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 vlastnost obsahuje Vlastnosti požadavku specifické pro Cloudflare.

Mezi implementací ve Workers a Node.js existují následující rozdíly:

• Hlavičky Trailer nejsou podporovány
• socket atribut nedědí od net.Socket a obsahuje pouze následující vlastnosti: encrypted, remoteFamily, remoteAddress, remotePort, localAddress, localPort, a destroy() metoda.
• Následující socket atributy se chovají jinak než jejich protějšky v Node.js:
  • remoteAddress vrátí 127.0.0.1 při lokálním spuštění
  • remotePort vrátí náhodné číslo portu mezi 2^15 a 2^16
  • localAddress vrátí hodnotu vlastnosti request host hlavičku, pokud existuje. V opačném případě vrátí 127.0.0.1
  • localPort vrátí číslo portu přiřazené dané instanci serveru
  • req.socket.destroy() propadne do req.destroy()

Částečná implementace Node.js `http.Agent' ↗ třídu.

Agent spravuje opětovné využití HTTP připojení tím, že udržuje fronty požadavků podle hostitele a portu. V prostředí workerů však toto nízkoúrovňové řízení síťového připojení, portů a podobně není relevantní, protože jej za vás zajišťuje infrastruktura Cloudflare. Implementace Agent ve Workers je stub implementace, která nepodporuje pooling připojení ani keep-alive.

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

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

Implementace Node.js http.createServer ↗ metoda.

createServer metoda vytváří instanci HTTP serveru, která umí zpracovávat příchozí požadavky.

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 funkce propojuje servery Node.js HTTP s modelem požadavků Cloudflare Workers. Podporuje dva vzory 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 });

Handler automaticky směruje příchozí požadavky Workeru na váš server Node.js. Při směrování založeném na portech funguje číslo portu jako směrovací klíč, který určuje, který server požadavky zpracuje, což umožňuje, aby v rámci jednoho Workeru fungovalo více serverů současně.

Pro přímější kontrolu nad směrováním požadavků můžete použít handleAsNodeRequest funkce z cloudflare:node. Tato funkce směruje požadavek Workeru přímo na server Node.js běžící na konkrétním portu:

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

Tento přístup vám dává plnou kontrolu nad fetch handlerem a zároveň umožňuje využít HTTP servery Node.js pro zpracování požadavků.

Implementace Node.js http.Server ↗ třídu.

Server třída reprezentuje HTTP server a poskytuje metody pro zpracování příchozích požadavků. Rozšiřuje Node.js EventEmitter třída a lze ji použít k vytvoření vlastních implementací serveru.

Při použití httpServerHandler, číslo portu uvedené v server.listen() funguje jako směrovací klíč, nikoli jako skutečný síťový port. Handler podle tohoto portu určuje, která instance HTTP serveru má příchozí požadavek zpracovat, díky čemuž může v rámci jednoho Workeru fungovat vedle sebe více serverů odlišených čísly portů. Při použití hodnoty portu 0 (nebo null nebo undefined) povede k přidělení náhodného čísla portu.

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

Mezi implementací ve Workers a Node.js existují následující rozdíly:

• Metody správy připojení, jako například closeAllConnections() a closeIdleConnections() nejsou implementovány
• Pouze listen() varianty s číslem portu nebo bez parametrů jsou podporovány: listen(), listen(0, callback), listen(callback), atd. Jako referenci si prohlédněte Dokumentace Node.js ↗.
• Následující možnosti serveru nejsou podporovány: maxHeaderSize, insecureHTTPParser, keepAliveTimeout, connectionsCheckingInterval

Implementace Node.js http.ServerResponse ↗ třídu.

ServerResponse třída reprezentuje objekt odpovědi na straně serveru, který se předává handlerům požadavků. Poskytuje metody pro zápis hlaviček a dat odpovědi a rozšiřuje Node.js Writable třída streamu.

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

Následující metody a funkce nejsou v implementaci Workers podporovány:

• assignSocket() a detachSocket() metody nejsou dostupné
• Hlavičky Trailer nejsou podporovány
• writeContinue() a writeEarlyHints() metody nejsou dostupné
• Odpovědi řady 1xx obecně nejsou podporovány

Protože implementace Workers node:http je obal kolem globálního fetch API existují určité rozdíly v chování a omezeních oproti standardnímu prostředí Node.js:

• Connection hlavičky se nepoužívají. Workers spravují připojení automaticky.
• Content-Length hlavičky se budou zpracovávat stejně jako v fetch API. Pokud je zadáno tělo požadavku, hlavička se nastaví automaticky a ručně nastavené hodnoty budou ignorovány.
• Expect: 100-continue hlavičky nejsou podporované.
• Koncové hlavičky nejsou podporovány.
• 'continue' událost není podporována.
• 'information' událost není podporována.
• 'socket' událost není podporována.
• 'upgrade' událost není podporována.
• Získání přímého přístupu k podkladové socket není podporováno.