You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,15 +7,39 @@ import { Render } from "~/components"
7
7
8
8
<Renderfile="nodejs-compat-howto" />
9
9
10
+
## Compatibility flags
11
+
12
+
### Client-side methods
13
+
14
+
To use the HTTP client-side methods (`http.get`, `http.request`, etc.), you must enable the [`enable_nodejs_http_modules`](/workers/runtime-apis/compatibility-dates/#enable-nodejs-http-client-modules) compatibility flag in addition to the [`nodejs_compat`](/workers/runtime-apis/nodejs/) flag.
15
+
16
+
This flag is automatically enabled for Workers using a [compatibility date](/workers/runtime-apis/compatibility-dates/) 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`:
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`](/workers/runtime-apis/nodejs/) flag.
25
+
26
+
This flag is automatically enabled for Workers using a [compatibility date](/workers/runtime-apis/compatibility-dates/) 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`:
An implementation of the Node.js [`http.Agent'](https://nodejs.org/docs/latest/api/http.html#class-httpagent) class.
40
+
An implementation of the Node.js [`http.Agent`](https://nodejs.org/docs/latest/api/http.html#class-httpagent) class.
13
41
14
-
An [Agent](https://nodejs.org/docs/latest/api/http.html#class-httpagent) manages HTTP connection reuse by maintaining request queues per host/port. In the
15
-
workers environment, however, such low-level management of the network connection, ports,
16
-
etc, is not relevant because it is handled by the Cloudflare infrastructure instead. Accordingly, the
17
-
implementation of `Agent` in Workers is a stub implementation that does not support connection
18
-
pooling or keep-alive.
42
+
An [Agent](https://nodejs.org/docs/latest/api/http.html#class-httpagent) 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.
An implementation of the Node.js [`http.request'](https://nodejs.org/docs/latest/api/http.html#httprequesturl-options-callback) method.
78
+
An implementation of the Node.js [`http.request`](https://nodejs.org/docs/latest/api/http.html#httprequesturl-options-callback) method.
55
79
56
80
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](https://nodejs.org/docs/latest/api/stream.html#class-streamwritable) for sending request data.
The following options passed to the `request` method are not supported due to the differences in the Cloudflare Workers and the implementation of the `node:http` module:
121
+
The following options passed to the `request` method are not supported due to differences in the Cloudflare Workers implementation of the `node:http` module:
95
122
-`maxHeaderSize`
96
123
-`insecureHTTPParser`
97
124
-`createConnection`
@@ -100,7 +127,9 @@ The following options passed to the `request` method are not supported due to th
100
127
101
128
## OutgoingMessage
102
129
103
-
The [`OutgoingMessage`](https://nodejs.org/docs/latest/api/http.html#class-httpoutgoingmessage) 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 [`Writable` stream class](https://nodejs.org/docs/latest/api/stream.html#class-streamwritable).
130
+
An implementation of the Node.js [`http.OutgoingMessage`](https://nodejs.org/docs/latest/api/http.html#class-httpoutgoingmessage) class.
131
+
132
+
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](https://nodejs.org/docs/latest/api/stream.html#class-streamwritable).
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.
145
+
An implementation of the Node.js [`http.IncomingMessage`](https://nodejs.org/docs/latest/api/http.html#class-httpincomingmessage) class.
146
+
147
+
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.
The Workers implementation includes a `cloudflare` property on `IncomingMessage` objects:
160
+
161
+
```js
162
+
import { get } from'node:http';
163
+
164
+
get('http://example.com', (res) => {
165
+
// Access Cloudflare-specific request properties
166
+
console.log(res.cloudflare.cf.country);
167
+
console.log(res.cloudflare.cf.ray);
168
+
});
169
+
```
170
+
171
+
The `cloudflare.cf` property contains [Cloudflare-specific request properties](/workers/runtime-apis/request/#incomingrequestcfproperties).
172
+
173
+
The following differences exist between the Workers implementation and Node.js:
174
+
175
+
- Trailer headers are not supported
176
+
- The `socket` attribute only contains the following properties: `encrypted`, `remoteFamily`, `remoteAddress`, `remotePort`, `localAddress`, `localPort`, and `destroy()` method
177
+
- The `socket` attribute does not extend from `net.Socket`
178
+
179
+
## createServer
180
+
181
+
An implementation of the Node.js [`http.createServer`](https://nodejs.org/docs/latest/api/http.html#httpcreateserveroptions-requestlistener) method.
182
+
183
+
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.
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.
199
+
200
+
:::note
201
+
Failing to call `close()` on an HTTP server may result in the server being leaked. To prevent this, call `close()` when you're done with the server, or use explicit resource management:
202
+
203
+
```js
204
+
import { createServer } from'node:http';
205
+
206
+
await using server =createServer((req, res) => {
207
+
res.end('Hello World');
208
+
});
209
+
// Server will be automatically closed when it goes out of scope
210
+
```
211
+
:::
212
+
213
+
## Server
214
+
215
+
An implementation of the Node.js [`http.Server`](https://nodejs.org/docs/latest/api/http.html#class-httpserver) class.
216
+
217
+
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.
res.end(JSON.stringify({ message:'Hello from HTTP Server!' }));
225
+
});
226
+
```
227
+
228
+
The following differences exist between the Workers implementation and Node.js:
229
+
230
+
- Connection management methods such as `closeAllConnections()` and `closeIdleConnections()` are not implemented
231
+
- Only `listen()` variants with a port number or no parameters are supported: `listen()`, `listen(0, callback)`, `listen(callback)`, etc.
232
+
- The following server options are not supported: `maxHeaderSize`, `insecureHTTPParser`, `keepAliveTimeout`, `connectionsCheckingInterval`
233
+
234
+
## ServerResponse
235
+
236
+
An implementation of the Node.js [`http.ServerResponse`](https://nodejs.org/docs/latest/api/http.html#class-httpserverresponse) class.
237
+
238
+
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.
Copy file name to clipboardExpand all lines: src/content/docs/workers/runtime-apis/nodejs/https.mdx
+92-12Lines changed: 92 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,15 +7,39 @@ import { Render } from "~/components";
7
7
8
8
<Renderfile="nodejs-compat-howto" />
9
9
10
+
## Compatibility flags
11
+
12
+
### Client-side methods
13
+
14
+
To use the HTTPS client-side methods (`https.get`, `https.request`, etc.), you must enable the [`enable_nodejs_http_modules`](/workers/runtime-apis/compatibility-dates/#enable-nodejs-http-client-modules) compatibility flag in addition to the [`nodejs_compat`](/workers/runtime-apis/nodejs/) flag.
15
+
16
+
This flag is automatically enabled for Workers using a [compatibility date](/workers/runtime-apis/compatibility-dates/) 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`:
To use the HTTPS server-side methods (`https.createServer`, `https.Server`, `https.ServerResponse`), you must enable the `enable_nodejs_http_server_modules` compatibility flag in addition to the [`nodejs_compat`](/workers/runtime-apis/nodejs/) flag.
25
+
26
+
This flag is automatically enabled for Workers using a [compatibility date](/workers/runtime-apis/compatibility-dates/) 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`:
An implementation of the Node.js [`https.Agent'](https://nodejs.org/docs/latest/api/https.html#class-httpsagent) class.
40
+
An implementation of the Node.js [`https.Agent`](https://nodejs.org/docs/latest/api/https.html#class-httpsagent) class.
13
41
14
-
An [Agent](https://nodejs.org/docs/latest/api/https.html#class-httpsagent) manages HTTPS connection reuse by maintaining request queues per host/port. In the
15
-
workers environment, however, such low-level management of the network connection, ports,
16
-
etc, is not relevant because it is handled by the Cloudflare infrastructure instead. Accordingly, the
17
-
implementation of `Agent` in Workers is a stub implementation that does not support connection
18
-
pooling or keep-alive.
42
+
An [Agent](https://nodejs.org/docs/latest/api/https.html#class-httpsagent) manages HTTPS 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.
An implementation of the Node.js [`https.get'](https://nodejs.org/docs/latest/api/https.html#httpsgetoptions-callback) method.
54
+
An implementation of the Node.js [`https.get`](https://nodejs.org/docs/latest/api/https.html#httpsgetoptions-callback) method.
31
55
32
-
The [`get`](https://nodejs.org/docs/latest/api/https.html#httpsgetoptions-callback) method performs a GET request to the specified URL and invokes the callback with the response. This is a convenience method that simplifies making HTTPS GET requests without manually configuring request options.
56
+
The `get` method performs a GET request to the specified URL and invokes the callback with the response. This is a convenience method that simplifies making HTTPS GET requests without manually configuring request options.
An implementation of the Node.js [`https.request'](https://nodejs.org/docs/latest/api/https.html#httpsrequestoptions-callback) method.
82
+
An implementation of the Node.js [`https.request`](https://nodejs.org/docs/latest/api/https.html#httpsrequestoptions-callback) method.
59
83
60
-
The [`request`](https://nodejs.org/docs/latest/api/https.html#httpsrequestoptions-callback) method creates an HTTPS request with customizable options like method, headers, and body. It provides full control over the request configuration and returns a [writable stream](https://developers.cloudflare.com/workers/runtime-apis/streams/writablestream/) for sending request data.
84
+
The `request` method creates an HTTPS request with customizable options like method, headers, and body. It provides full control over the request configuration and returns a [writable stream](https://nodejs.org/docs/latest/api/stream.html#class-streamwritable) for sending request data.
61
85
62
-
Request method accepts all options from `http.request` with some differences in default values:
86
+
The request method accepts all options from `http.request` with some differences in default values:
63
87
64
88
-`protocol`: default `https:`
65
89
-`port`: default `443`
@@ -90,3 +114,59 @@ req.end();
90
114
```
91
115
92
116
The following additional options are not supported: `ca`, `cert`, `ciphers`, `clientCertEngine` (deprecated), `crl`, `dhparam`, `ecdhCurve`, `honorCipherOrder`, `key`, `passphrase`, `pfx`, `rejectUnauthorized`, `secureOptions`, `secureProtocol`, `servername`, `sessionIdContext`, `highWaterMark`.
117
+
118
+
## createServer
119
+
120
+
An implementation of the Node.js [`https.createServer`](https://nodejs.org/docs/latest/api/https.html#httpscreateserveroptions-requestlistener) method.
121
+
122
+
The `createServer` method creates an HTTPS server instance that can handle incoming secure requests. It's a convenience function that creates a new `Server` instance and optionally sets up a request listener callback.
The `httpServerHandler` function integrates Node.js HTTPS 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.
138
+
139
+
:::note
140
+
Failing to call `close()` on an HTTPS server may result in the server being leaked. To prevent this, call `close()` when you're done with the server, or use explicit resource management:
141
+
142
+
```js
143
+
import { createServer } from'node:https';
144
+
145
+
await using server =createServer((req, res) => {
146
+
res.end('Hello World');
147
+
});
148
+
// Server will be automatically closed when it goes out of scope
149
+
```
150
+
:::
151
+
152
+
## Server
153
+
154
+
An implementation of the Node.js [`https.Server`](https://nodejs.org/docs/latest/api/https.html#class-httpsserver) class.
155
+
156
+
The `Server` class represents an HTTPS server and provides methods for handling incoming secure requests. It extends the Node.js `EventEmitter` class and can be used to create custom secure server implementations.
0 commit comments