From 564fa857a26a2bcb0e68fe5699d775acab244384 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Sat, 21 Oct 2017 12:04:35 -0700 Subject: [PATCH 1/4] Improve HTTP2 documentation. Provide section headings for server-side and client side examples. Add error handling and TLS to server-side example, following example of `https`. Add error handling, TLS, more efficient Buffer usage, and header printing to client example. --- doc/api/http2.md | 49 +++++++++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index c85de0092a72a2..c2177ebadaac85 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -16,14 +16,25 @@ support for HTTP/2 protocol features. It is specifically *not* designed for compatibility with the existing [HTTP/1][] module API. However, the [Compatibility API][] is. +The `http2` Core API is much more symmetric between client and server than the +`http` API. For instance, most events, like `error` and `socketError`, can 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: ```js const http2 = require('http2'); +const fs = require('fs'); -// Create a plain-text HTTP/2 server -const server = http2.createServer(); +const server = http2.createSecureServer({ + key: fs.readFileSync("test/fixtures/keys/agent2-key.pem"), + cert: fs.readFileSync("test/fixtures/keys/agent2-cert.pem"), +}); +server.on('error', (err) => console.error(err)); +server.on('socketError', (err) => console.error(err)); server.on('stream', (stream, headers) => { // stream is a Duplex @@ -34,34 +45,34 @@ server.on('stream', (stream, headers) => { stream.end('

Hello World

'); }); -server.listen(80); +server.listen(8443); ``` -Note that the above example is an HTTP/2 server that does not support SSL. -This is significant as most browsers support HTTP/2 only with SSL. -To make the above server be able to serve content to browsers, -replace `http2.createServer()` with -`http2.createSecureServer({key: /* your SSL key */, cert: /* your SSL cert */})`. +### Client-side example The following illustrates an HTTP/2 client: ```js -const http2 = require('http2'); - -const client = http2.connect('http://localhost:80'); +var http2 = require('http2'); +const client = http2.connect('https://localhost'); +client.on('socketError', (err) => console.error(err)) +client.on('error', (err) => console.error(err)) -// req is a Duplex const req = client.request({ ':path': '/' }); -req.on('response', (headers) => { - console.log(headers[':status']); - console.log(headers['date']); +req.on('response', (headers, flags) => { + for (var name in headers) { + console.log(name + ": " + headers[name]); + } }); -let data = ''; -req.setEncoding('utf8'); -req.on('data', (d) => data += d); -req.on('end', () => client.destroy()); +let data = [] +req.on('data', (d) => data.push(d)); +req.on('end', () => { + console.log(); + console.log(Buffer.concat(data).toString('utf8')); + client.destroy() +}); req.end(); ``` From e0e5aeafe27bbb94916810e8997f2e20c6b96e99 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Sat, 21 Oct 2017 15:06:19 -0700 Subject: [PATCH 2/4] Add localhost cert instructions. Also connect to port 8443 in client, and add require('fs') --- doc/api/http2.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index c2177ebadaac85..b18e1c3845ade9 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -30,8 +30,8 @@ const http2 = require('http2'); const fs = require('fs'); const server = http2.createSecureServer({ - key: fs.readFileSync("test/fixtures/keys/agent2-key.pem"), - cert: fs.readFileSync("test/fixtures/keys/agent2-cert.pem"), + key: fs.readFileSync("localhost-privkey.pem"), + cert: fs.readFileSync("localhost-cert.pem") }); server.on('error', (err) => console.error(err)); server.on('socketError', (err) => console.error(err)); @@ -48,13 +48,22 @@ server.on('stream', (stream, headers) => { server.listen(8443); ``` +To generate the certificate and key for this example, run: + +```bash +openssl req -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' -x509 -keyout localhost-privkey.pem -out localhost-cert.pem +``` + ### Client-side example The following illustrates an HTTP/2 client: ```js var http2 = require('http2'); -const client = http2.connect('https://localhost'); +var fs = require('fs'); +const client = http2.connect('https://localhost:8443', { + ca: fs.readFileSync("localhost-cert.pem") +}); client.on('socketError', (err) => console.error(err)) client.on('error', (err) => console.error(err)) From cb0acb6ee7d97761b2db04004f3eece0f0ac7be0 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Sun, 22 Oct 2017 15:09:16 -0700 Subject: [PATCH 3/4] Consts and line wrap. --- doc/api/http2.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index b18e1c3845ade9..6528c20246d630 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -51,7 +51,8 @@ server.listen(8443); To generate the certificate and key for this example, run: ```bash -openssl req -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' -x509 -keyout localhost-privkey.pem -out localhost-cert.pem +openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \ + -keyout localhost-privkey.pem -out localhost-cert.pem ``` ### Client-side example @@ -59,8 +60,8 @@ openssl req -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' -x509 -keyout The following illustrates an HTTP/2 client: ```js -var http2 = require('http2'); -var fs = require('fs'); +const http2 = require('http2'); +const fs = require('fs'); const client = http2.connect('https://localhost:8443', { ca: fs.readFileSync("localhost-cert.pem") }); @@ -70,7 +71,7 @@ client.on('error', (err) => console.error(err)) const req = client.request({ ':path': '/' }); req.on('response', (headers, flags) => { - for (var name in headers) { + for (const name in headers) { console.log(name + ": " + headers[name]); } }); From 7a44c9da3e8557a0bf00f536da3002f75163fe59 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Sun, 22 Oct 2017 15:34:37 -0700 Subject: [PATCH 4/4] Go back to string concatenation. --- doc/api/http2.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 6528c20246d630..5a0859648f0bc5 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -76,11 +76,12 @@ req.on('response', (headers, flags) => { } }); -let data = [] -req.on('data', (d) => data.push(d)); +req.setEncoding('utf8'); +let rawData = ''; +req.on('data', (chunk) => { rawData += chunk; }); req.on('end', () => { console.log(); - console.log(Buffer.concat(data).toString('utf8')); + console.log(rawData); client.destroy() }); req.end();