@@ -16,14 +16,25 @@ support for HTTP/2 protocol features. It is specifically *not* designed for
1616compatibility with the existing [ HTTP/1] [ ] module API. However,
1717the [ Compatibility API] [ ] is.
1818
19+ The ` http2 ` Core API is much more symmetric between client and server than the
20+ ` http ` API. For instance, most events, like ` error ` and ` socketError ` , can be
21+ emitted either by client-side code or server-side code.
22+
23+ ### Server-side example
24+
1925The following illustrates a simple, plain-text HTTP/2 server using the
2026Core API:
2127
2228``` js
2329const http2 = require (' http2'
30+ const fs = require (' fs'
2431
25- // Create a plain-text HTTP/2 server
26- const server = http2 .createServer ();
32+ const server = http2 .createSecureServer ({
33+ key: fs .readFileSync (' localhost-privkey.pem'
34+ cert: fs .readFileSync (' localhost-cert.pem'
35+ });
36+ server .on (' error' err ) => console .error (err));
37+ server .on (' socketError' err ) => console .error (err));
2738
2839server .on (' stream' stream , headers ) => {
2940 // stream is a Duplex
@@ -34,34 +45,44 @@ server.on('stream', (stream, headers) => {
3445 stream .end (' <h1>Hello World</h1>'
3546});
3647
37- server .listen (80 );
48+ server .listen (8443 );
3849```
3950
40- Note that the above example is an HTTP/2 server that does not support SSL.
41- This is significant as most browsers support HTTP/2 only with SSL.
42- To make the above server be able to serve content to browsers,
43- replace ` http2.createServer() ` with
44- ` http2.createSecureServer({key: /* your SSL key */, cert: /* your SSL cert */}) ` .
51+ To generate the certificate and key for this example, run:
52+
53+ ``` bash
54+ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj ' /CN=localhost'
55+ -keyout localhost-privkey.pem -out localhost-cert.pem
56+ ```
57+
58+ ### Client-side example
4559
4660The following illustrates an HTTP/2 client:
4761
4862``` js
4963const http2 = require (' http2'
64+ const fs = require (' fs'
65+ const client = http2 .connect (' https://localhost:8443'
66+ ca: fs .readFileSync (' localhost-cert.pem'
67+ });
68+ client .on (' socketError' err ) => console .error (err));
69+ client .on (' error' err ) => console .error (err));
5070
51- const client = http2 .connect (' http://localhost:80'
52-
53- // req is a Duplex
5471const req = client .request ({ ' :path' : ' /'
5572
56- req .on (' response' headers ) => {
57- console .log (headers[' :status'
58- console .log (headers[' date'
73+ req .on (' response' headers , flags ) => {
74+ for (const name in headers) {
75+ console .log (` ${ name} ${ headers[name]} `
76+ }
5977});
6078
61- let data = ' '
6279req .setEncoding (' utf8'
63- req .on (' data' d ) => data += d);
64- req .on (' end' => client .destroy ());
80+ let data = ' '
81+ req .on (' data' chunk ) => { data += chunk; });
82+ req .on (' end' => {
83+ console .log (` \n ${ data} `
84+ client .destroy ();
85+ });
6586req .end ();
6687```
6788
@@ -463,12 +484,16 @@ added: v8.4.0
463484
464485* Value: {net.Socket|tls.TLSSocket}
465486
466- A reference to the [ ` net.Socket ` ] [ ] or [ ` tls.TLSSocket ` ] [ ] to which this
467- ` Http2Session ` instance is bound .
487+ Returns a Proxy object that acts as a ` net.Socket ` ( or ` tls.TLSSocket ` ) but
488+ limits available methods to ones safe to use with HTTP/2 .
468489
469- * Note* : It is not recommended for user code to interact directly with a
470- ` Socket ` bound to an ` Http2Session ` . See [ Http2Session and Sockets] [ ] for
471- details.
490+ ` destroy ` , ` emit ` , ` end ` , ` pause ` , ` read ` , ` resume ` , and ` write ` will throw
491+ an error with code ` ERR_HTTP2_NO_SOCKET_MANIPULATION ` . See
492+ [ Http2Session and Sockets] [ ] for more information.
493+
494+ ` setTimeout ` method will be called on this ` Http2Session ` .
495+
496+ All other interactions will be routed directly to the socket.
472497
473498#### http2session.state
474499<!-- YAML
@@ -2138,10 +2163,10 @@ Returns `request`.
21382163added: v8.4.0
21392164-->
21402165
2141- * {net.Socket}
2166+ * {net.Socket|tls.TLSSocket }
21422167
2143- Returns a Proxy object that acts as a ` net.Socket ` but applies getters,
2144- setters and methods based on HTTP/2 logic.
2168+ Returns a Proxy object that acts as a ` net.Socket ` (or ` tls.TLSSocket ` ) but
2169+ applies getters, setters and methods based on HTTP/2 logic.
21452170
21462171` destroyed ` , ` readable ` , and ` writable ` properties will be retrieved from and
21472172set on ` request.stream ` .
@@ -2293,7 +2318,7 @@ will result in a [`TypeError`][] being thrown.
22932318added: v8.4.0
22942319-->
22952320
2296- * {net.Socket}
2321+ * {net.Socket|tls.TLSSocket }
22972322
22982323See [ ` response.socket ` ] [ ] .
22992324
@@ -2510,10 +2535,10 @@ Returns `response`.
25102535added: v8.4.0
25112536-->
25122537
2513- * {net.Socket}
2538+ * {net.Socket|tls.TLSSocket }
25142539
2515- Returns a Proxy object that acts as a ` net.Socket ` but applies getters,
2516- setters and methods based on HTTP/2 logic.
2540+ Returns a Proxy object that acts as a ` net.Socket ` (or ` tls.TLSSocket ` ) but
2541+ applies getters, setters and methods based on HTTP/2 logic.
25172542
25182543` destroyed ` , ` readable ` , and ` writable ` properties will be retrieved from and
25192544set on ` response.stream ` .
0 commit comments