Skip to content
Merged
121 changes: 121 additions & 0 deletions src/content/docs/workers/runtime-apis/nodejs/http.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
pcx_content_type: configuration
title: http
---

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

## Agent

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.

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

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

## get

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.

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

get('http://docs.cloudflare.com/robots.txt', (res) => {
// http://docs.cloudflare.com redirects to https url.
strictEqual(res.statusCode, 301);
let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
// Returns the response body as a string.
console.log(data);
ok(data.includes('301 Moved Permanently'));
});
});
```

## request
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a comment somewhere that appears to have been marked resolved about how these should include links to the relevant node.js docs for these methods. I still think we should include those links.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean the header should be a link to node.js docs? Can you be specific?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jasnell is the current state sufficient?


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.

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

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

let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
// Returns the response body as a string.
console.log(data);
ok(data.includes('301 Moved Permanently'));
});
});
req.end();

const req2 = request(new URL('http://docs.cloudflare.com'),{
method: 'GET',
}, (res) => {
// http://docs.cloudflare.com redirects to https url.
strictEqual(res.statusCode, 301);
});

req2.end();
```

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:
- `maxHeaderSize`
- `insecureHTTPParser`
- `createConnection`
- `lookup`
- `socketPath`

## OutgoingMessage

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

```js
import { OutgoingMessage } from 'node:http';

const res = new OutgoingMessage();
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.write('Hello, World!');
res.end();
```
## 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.

```js
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);
});
```
82 changes: 82 additions & 0 deletions src/content/docs/workers/runtime-apis/nodejs/https.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
pcx_content_type: configuration
title: https
---

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

## Agent

An Agent 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.

```js
import { Agent } from 'node:https';
import { strictEqual } from 'node:assert';

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

## get

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.

`get` methods behaves the same as `node:http` get method.

```js
import { get } from 'node:https';
import { strictEqual, ok } from 'node:assert';

get('https://developers.cloudflare.com/robots.txt', (res) => {
strictEqual(res.statusCode, 200);
let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
// Returns the response body as a string.
console.log(data);
ok(data.includes('User-agent'));
});
});
```

## request

The [`request`](https://nodejs.org/docs/latest/api/https.html#httpsrequesturl-options-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://nodejs.org/docs/latest/api/stream.html#class-streamwritable) for sending request data.

Request method accepts all options from `http.request` with some differences in default values:
- `protocol`: default `https:`
- `port`: default `443`
- `agent`: default `https.globalAgent`

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.

```js
import { request } from 'node:https';
import { strictEqual, ok } from 'node:assert';

const req = request('https://developers.cloudflare.com/robots.txt', {
method: 'GET',
}, (res) => {
strictEqual(res.statusCode, 200);
let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
// Returns the response body as a string.
console.log(data);
ok(data.includes('User-agent'));
});
});
req.end();
```
Loading