doc: add note about browsers and HTTP/2

styfle · vsemozhetbyt · commit cb69a7d22e33 · 2018-03-20T23:50:12.000+02:00
PR-URL: #19476 Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/http2.md b/doc/api/http2.md
@@ -24,8 +24,11 @@ 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 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.
 
 ```js
 const http2 = require('http2');
@@ -252,7 +255,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) => {
@@ -1727,10 +1730,18 @@ changes:
 Returns a `net.Server` instance that creates and manages `Http2Session`
 instances.
 
+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.
+
 ```js
 const http2 = require('http2');
 
-// Create a plain-text HTTP/2 server
+// Create an unencrypted HTTP/2 server.
+// Since there are no browsers known that support
+// unencrypted HTTP/2, the use of `http2.createSecureServer()`
+// is necessary when communicating with browser clients.
 const server = http2.createServer();
 
 server.on('stream', (stream, headers) => {
@@ -3085,6 +3096,7 @@ following additional properties:
 [Compatibility API]: #http2_compatibility_api
 [HTTP/1]: http.html
 [HTTP/2]: https://tools.ietf.org/html/rfc7540
+[HTTP/2 Unencrypted]: https://http2.github.io/faq/#does-http2-require-encryption
 [HTTP2 Headers Object]: #http2_headers_object
 [HTTP2 Settings Object]: #http2_settings_object
 [HTTPS]: https.html
