Skip to content
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.

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

doc: add note about browsers and HTTP/2 #19476

Closed
wants to merge 5 commits into from
Closed
Changes from 2 commits
Commits
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
17 changes: 12 additions & 5 deletions doc/api/http2.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ be emitted either by client-side code or server-side code.

### Server-side example

The following illustrates a simple, plain-text HTTP/2 server using the
Core API:
The following illustrates a simple HTTP/2 server using the Core API.
Since no browsers support [unencrypted HTTP/2][HTTP2 Unencrypted],
the use of [`http2.createSecureServer()`][] is preferred.

Copy link
Member

Choose a reason for hiding this comment

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

I would say something like...

Since there are no browsers known that support [unencrypted HTTP/2](HTTP/2 Unencrypted),
the use of [`http2.createSecureServer()`][] is necessary when communicating with browser
clients.

Using Unencrypted HTTP/2 would actually be the preference when running purely within internal environments with non-browser clients.

Copy link
Member Author

Choose a reason for hiding this comment

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

Okie dokie 👍

```js
const http2 = require('http2');
Expand Down Expand Up @@ -252,7 +253,7 @@ and would instead register a handler for the `'stream'` event emitted by the
```js
const http2 = require('http2');

// Create a plain-text HTTP/2 server
// Create an unencrypted HTTP/2 server
const server = http2.createServer();

server.on('stream', (stream, headers) => {
Expand Down Expand Up @@ -1727,10 +1728,15 @@ changes:
Returns a `net.Server` instance that creates and manages `Http2Session`
instances.

Since no browsers support [unencrypted HTTP/2][HTTP2 Unencrypted],
the use of [`http2.createSecureServer()`][] is preferred.
Copy link
Member

Choose a reason for hiding this comment

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

Again,

Since there are no browsers known that support [unencrypted HTTP/2](HTTP/2 Unencrypted),
the use of [`http2.createSecureServer()`][] is necessary when communicating with browser
clients.

Copy link
Member Author

Choose a reason for hiding this comment

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

Okie dokie 👍


```js
const http2 = require('http2');

// Create a plain-text HTTP/2 server
// Create an unencrypted HTTP/2 server.
// Since no browsers support unencrypted HTTP/2,
// the use of `http2.createSecureServer()` is preferred.
const server = http2.createServer();

server.on('stream', (stream, headers) => {
Expand Down Expand Up @@ -3085,6 +3091,7 @@ following additional properties:
[Compatibility API]: #http2_compatibility_api
[HTTP/1]: http.html
[HTTP/2]: https://tools.ietf.org/html/rfc7540
[HTTP2 Unencrypted]: https://http2.github.io/faq/#does-http2-require-encryption
Copy link
Contributor

Choose a reason for hiding this comment

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

A nit: we usually sort references in ASCII order, so this should go after [HTTP2 Settings Object] ref.

Copy link
Member Author

Choose a reason for hiding this comment

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

I fixed this by renaming to [HTTP/2 Unencrypted] since its not linking to a section anchor but its more like the external link above.

[HTTP2 Headers Object]: #http2_headers_object
[HTTP2 Settings Object]: #http2_settings_object
[HTTPS]: https.html
Expand Down Expand Up @@ -3124,4 +3131,4 @@ following additional properties:
[`tls.TLSSocket`]: tls.html#tls_class_tls_tlssocket
[`tls.connect()`]: tls.html#tls_tls_connect_options_callback
[`tls.createServer()`]: tls.html#tls_tls_createserver_options_secureconnectionlistener
[error code]: #error_codes
[error code]: #error_codes
Copy link
Contributor

Choose a reason for hiding this comment

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

A nit: missing line break at the end of the file.

Copy link
Member Author

Choose a reason for hiding this comment

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

Oops! Fixed! 🔧