Skip to content

Commit

Permalink
doc: specify encoding in text/html examples
Browse files Browse the repository at this point in the history 
Fixes: #29739

PR-URL: #34222
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
  • Loading branch information
@jasnell @MylesBorins
jasnell authored and MylesBorins committed Jul 16, 2020
1 parent 9339f9f commit 7416028
Showing 1 changed file with 31 additions and 19 deletions.
50 changes: 31 additions & 19 deletions doc/api/http2.md
View file
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 @@ -2138,7 +2150,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 @@ -2264,7 +2276,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 @@ -2725,7 +2737,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 @@ -3310,7 +3322,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 @@ -3329,9 +3341,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 @@ -3513,7 +3525,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 @@ -3536,9 +3548,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

0 comments on commit 7416028

Please sign in to comment.