Skip to content

doc: specify encoding in text/html examples #34222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

doc: specify encoding in text/html examples #34222

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
doc: specify encoding in text/html examples 
Fixes: #29739
  • Loading branch information
@jasnell
jasnell committed Jul 9, 2020
commit dee3caf74bae44022d5042f594f52decb2f00b14
50 changes: 31 additions & 19 deletions doc/api/http2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ server.on('error', (err) => console.error(err));
server.on('stream', (stream, headers) => {
// stream is a Duplex
stream.respond({
'content-type': 'text/html',
'content-type': 'text/html; charset=utf-8',
':status': 200
});
stream.end('<h1>Hello World</h1>');
Expand Down Expand Up @@ -271,7 +271,7 @@ session.on('stream', (stream, headers, flags) => {
// ...
stream.respond({
':status': 200,
'content-type': 'text/plain'
'content-type': 'text/plain; charset=utf-8'
});
stream.write('hello ');
stream.end('world');
Expand All @@ -291,7 +291,7 @@ const server = http2.createServer();

server.on('stream', (stream, headers) => {
stream.respond({
'content-type': 'text/html',
'content-type': 'text/html; charset=utf-8',
':status': 200
});
stream.on('error', (error) => console.error(error));
Expand Down Expand Up @@ -889,6 +889,18 @@ All `Http2Stream` instances are [`Duplex`][] streams. The `Writable` side of the
`Duplex` is used to send data to the connected peer, while the `Readable` side
is used to receive data sent by the connected peer.

The default text character encoding for all `Http2Stream`s is UTF-8. As a best
practice, it is recommended that when using an `Http2Stream` to send text,
the `'content-type'` header should be set and should identify the character
encoding used.

```js
stream.respond({
'content-type': 'text/html; charset=utf-8',
':status': 200
});
```

#### `Http2Stream` Lifecycle

##### Creation
Expand Down Expand Up @@ -1509,7 +1521,7 @@ server.on('stream', (stream) => {
const headers = {
'content-length': stat.size,
'last-modified': stat.mtime.toUTCString(),
'content-type': 'text/plain'
'content-type': 'text/plain; charset=utf-8'
};
stream.respondWithFD(fd, headers);
stream.on('close', () => fs.closeSync(fd));
Expand Down Expand Up @@ -1554,7 +1566,7 @@ server.on('stream', (stream) => {
const headers = {
'content-length': stat.size,
'last-modified': stat.mtime.toUTCString(),
'content-type': 'text/plain'
'content-type': 'text/plain; charset=utf-8'
};
stream.respondWithFD(fd, headers, { waitForTrailers: true });
stream.on('wantTrailers', () => {
Expand Down Expand Up @@ -1624,7 +1636,7 @@ server.on('stream', (stream) => {
}

stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain' },
{ 'content-type': 'text/plain; charset=utf-8' },
{ statCheck, onError });
});
```
Expand All @@ -1644,7 +1656,7 @@ server.on('stream', (stream) => {
return false; // Cancel the send operation
}
stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain' },
{ 'content-type': 'text/plain; charset=utf-8' },
{ statCheck });
});
```
Expand Down Expand Up @@ -1674,7 +1686,7 @@ const http2 = require('http2');
const server = http2.createServer();
server.on('stream', (stream) => {
stream.respondWithFile('/some/file',
{ 'content-type': 'text/plain' },
{ 'content-type': 'text/plain; charset=utf-8' },
{ waitForTrailers: true });
stream.on('wantTrailers', () => {
stream.sendTrailers({ ABC: 'some value to send' });
Expand Down Expand Up @@ -1766,7 +1778,7 @@ server.on('stream', (stream, headers, flags) => {
// ...
stream.respond({
[HTTP2_HEADER_STATUS]: 200,
[HTTP2_HEADER_CONTENT_TYPE]: 'text/plain'
[HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8'
});
stream.write('hello ');
stream.end('world');
Expand Down Expand Up @@ -1929,7 +1941,7 @@ server.on('stream', (stream, headers, flags) => {
// ...
stream.respond({
[HTTP2_HEADER_STATUS]: 200,
[HTTP2_HEADER_CONTENT_TYPE]: 'text/plain'
[HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8'
});
stream.write('hello ');
stream.end('world');
Expand Down Expand Up @@ -2140,7 +2152,7 @@ const server = http2.createServer();

server.on('stream', (stream, headers) => {
stream.respond({
'content-type': 'text/html',
'content-type': 'text/html; charset=utf-8',
':status': 200
});
stream.end('<h1>Hello World</h1>');
Expand Down Expand Up @@ -2268,7 +2280,7 @@ const server = http2.createSecureServer(options);

server.on('stream', (stream, headers) => {
stream.respond({
'content-type': 'text/html',
'content-type': 'text/html; charset=utf-8',
':status': 200
});
stream.end('<h1>Hello World</h1>');
Expand Down Expand Up @@ -2731,7 +2743,7 @@ const http2 = require('http2');
const server = http2.createServer((req, res) => {
res.setHeader('Content-Type', 'text/html');
res.setHeader('X-Foo', 'bar');
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('ok');
});
```
Expand Down Expand Up @@ -3316,7 +3328,7 @@ in the to-be-sent headers, its value will be replaced. Use an array of strings
here to send multiple headers with the same name.

```js
response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Type', 'text/html; charset=utf-8');
```

or
Expand All @@ -3335,9 +3347,9 @@ to [`response.writeHead()`][] given precedence.
```js
// Returns content-type = text/plain
const server = http2.createServer((req, res) => {
res.setHeader('Content-Type', 'text/html');
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.setHeader('X-Foo', 'bar');
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('ok');
});
```
Expand Down Expand Up @@ -3519,7 +3531,7 @@ will be emitted.
const body = 'hello world';
response.writeHead(200, {
'Content-Length': Buffer.byteLength(body),
'Content-Type': 'text/plain' });
'Content-Type': 'text/plain; charset=utf-8' });
```

`Content-Length` is given in bytes not characters. The
Expand All @@ -3542,9 +3554,9 @@ to [`response.writeHead()`][] given precedence.
```js
// Returns content-type = text/plain
const server = http2.createServer((req, res) => {
res.setHeader('Content-Type', 'text/html');
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.setHeader('X-Foo', 'bar');
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
res.end('ok');
});
```
Expand Down