From df506862f1c8870701f5b8a129ba5f3385fdf421 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Fri, 29 Dec 2017 09:44:08 -0800 Subject: [PATCH 1/2] http2: add altsvc support Add support for sending and receiving ALTSVC frames. --- doc/api/errors.md | 10 +++ doc/api/http2.md | 88 ++++++++++++++++++++++ lib/internal/errors.js | 4 + lib/internal/http2/core.js | 50 +++++++++++++ src/env.h | 1 + src/node_http2.cc | 76 +++++++++++++++++++ src/node_http2.h | 7 ++ test/parallel/test-http2-altsvc.js | 114 +++++++++++++++++++++++++++++ 8 files changed, 350 insertions(+) create mode 100644 test/parallel/test-http2-altsvc.js diff --git a/doc/api/errors.md b/doc/api/errors.md index e0ec3957764914..1a45bbe6e0d2ec 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -821,6 +821,16 @@ that. Occurs with multiple attempts to shutdown an HTTP/2 session. + +### ERR_HTTP2_ALTSVC_INVALID_ORIGIN + +HTTP/2 ALTSVC frames require a valid origin. + + +### ERR_HTTP2_ALTSVC_LENGTH + +HTTP/2 ALTSVC frames are limited to a maximum of 16,382 payload bytes. + ### ERR_HTTP2_CONNECT_AUTHORITY diff --git a/doc/api/http2.md b/doc/api/http2.md index d19f395e856e87..8b604c07d64f43 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -558,11 +558,97 @@ added: REPLACEME Calls [`unref()`][`net.Socket.prototype.unref`] on this `Http2Session` instance's underlying [`net.Socket`]. +### Class: ServerHttp2Session + + +#### serverhttp2session.altsvc(alt, originOrStream) + + +* `alt` {string} A description of the alternative service configuration as + defined by [RFC 7838][]. +* `originOrStream` {string|number} Either a URL string specifying the origin or + the numeric identifier of an active `Http2Stream`. + +Submits an `ALTSVC` frame (as defined by [RFC 7838][]) to the connected client. + +```js +const http2 = require('http2'); + +const server = http2.createServer(); +server.on('session', (session) => { + // Set altsvc for origin https://example.org:80 + session.altsvc('h2=":8000"', 'https://example.org:80'); +}); + +server.on('stream', (stream) => { + // Set altsvc for a specific stream + stream.session.altsvc('h2=":8000"', stream.id); +}); +``` + +Sending an `ALTSVC` frame with a specific stream ID indicates that the alternate +service is associated with the origin of the given `Http2Stream`. + +The `alt` and origin string *must* contain only ASCII bytes and are +strictly interpreted as a sequence of ASCII bytes. The special value `'clear'` +may be passed to clear any previously set alternative service for a given +domain. + +When a string is passed for the `originOrStream` argument, it will be parsed as +a URL and the origin will be derived. For insetance, the origin for the +HTTP URL `'https://example.org/foo/bar'` is the ASCII string +`'https://example.org'`. An error will be thrown if either the given string +cannot be parsed as a URL or if a valid origin cannot be derived. + +#### Specifying alternative services + +The format of the `alt` parameter is strictly defined by [RFC 7838][] as an +ASCII string containing a comma-delimited list of "alternative" protocols +associated with a specific host and port. + +For example, the value `'h2="example.org:81"'` indicates that the HTTP/2 +protocol is available on the host `'example.org'` on TCP/IP port 81. The +host and port *must* be contained within the quote (`"`) characters. + +Multiple alternatives may be specified, for instance: `'h2="example.org:81", +h2=":82"'` + +The protocol identifier (`'h2'` in the examples) may be any valid +[ALPN Protocol ID][]. + +The syntax of these values is not validated by the Node.js implementation and +are passed through as provided by the user or received from the peer. + ### Class: ClientHttp2Session +#### Event: 'altsvc' + + +The `'altsvc'` event is emitted whenever an `ALTSVC` frame is received by +the client. The event is emitted with the `ALTSVC` value, origin, and stream +ID, if any. If no `origin` is provided in the `ALTSVC` frame, `origin` will +be an empty string. + +```js +const http2 = require('http2'); +const client = http2.connect('https://example.org'); + +client.on('altsvc', (alt, origin, stream) => { + console.log(alt); + console.log(origin); + console.log(stream); +}); +``` + #### clienthttp2session.request(headers[, options])