http2-wrapper

What is http2-wrapper?

The http2-wrapper npm package is a module that provides an easy-to-use wrapper around the native HTTP/2 client and server capabilities in Node.js. It simplifies the process of making HTTP/2 requests and handling responses, as well as creating HTTP/2 servers.

What are http2-wrapper's main functionalities?

Making HTTP/2 requests

This feature allows you to make HTTP/2 requests to a server. The code sample demonstrates how to perform a simple GET request using the http2-wrapper.

const http2wrapper = require('http2-wrapper');

const options = {
  hostname: 'example.com',
  protocol: 'https:',
  path: '/',
  method: 'GET'
};

http2wrapper.request(options, (res) => {
  console.log(`Status Code: ${res.statusCode}`);

  res.on('data', (chunk) => {
    console.log(chunk);
  });
}).end();

Creating HTTP/2 servers

This feature allows you to create an HTTP/2 server. The code sample shows how to set up a simple HTTP/2 server that responds with 'Hello World' to all requests.

const http2wrapper = require('http2-wrapper');
const http2 = require('http2');

const server = http2.createSecureServer({
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem')
});

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html',
    ':status': 200
  });
  stream.end('<h1>Hello World</h1>');
});

http2wrapper.createServer(server).listen(8443);

Other packages similar to http2-wrapper

spdy

The 'spdy' package is an HTTP/2 and SPDY protocol client and server implementation for Node.js. It provides similar functionalities to http2-wrapper but also includes support for SPDY, which is a now-deprecated protocol that was a precursor to HTTP/2.

node-fetch

While 'node-fetch' is primarily a light-weight module that brings window.fetch to Node.js, it can be used to make HTTP/2 requests when combined with the built-in http2 module in Node.js. It does not provide server capabilities like http2-wrapper.

README

http2-wrapper

HTTP2 client, but with the HTTP1 API

This package was created for the purpose of supporting HTTP2 without the need to rewrite your code.
I recommend adapting to the http2 module if possible - it's much simpler to use and has many cool features!

Tip: http2-wrapper is very useful when you rely on other modules that use the HTTP1 API and you want to support HTTP2.

Usage

'use strict';
const http2 = require('http2-wrapper');

const options = {
	hostname: 'nghttp2.org',
	protocol: 'https:',
	path: '/httpbin/post',
	method: 'POST',
	headers: {
		'content-length': 6
	}
};

const req = http2.request(options, res => {
	console.log('statusCode:', res.statusCode);
	console.log('headers:', res.headers);

	const body = [];
	res.on('data', chunk => {
		body.push(chunk);
	});
	res.on('end', () => {
		console.log('body:', Buffer.concat(body).toString());
	});
});

req.on('error', e => console.error(e));

req.write('123');
req.end('456');

// statusCode: 200
// headers: { ':status': 200,
//   date: 'Sat, 11 Aug 2018 09:37:41 GMT',
//   'content-type': 'application/json',
//   'content-length': '264',
//   'access-control-allow-origin': '*',
//   'access-control-allow-credentials': 'true',
//   'x-backend-header-rtt': '0.002997',
//   'strict-transport-security': 'max-age=31536000',
//   server: 'nghttpx',
//   via: '1.1 nghttpx',
//   'x-frame-options': 'SAMEORIGIN',
//   'x-xss-protection': '1; mode=block',
//   'x-content-type-options': 'nosniff' }
// body: {
//   "args": {},
//   "data": "123456",
//   "files": {},
//   "form": {},
//   "headers": {
//     "Content-Length": "6",
//     "Host": "nghttp2.org:443",
//     "Via": "2 nghttpx"
//   },
//   "json": 123456,
//   "origin": "xxx.xxx.xxx.xxx",
//   "url": "https://nghttp2.org:443/httpbin/post"
// }

API

http2.auto(url, options)

Note: resolve-alpn package required.

Performs ALPN negotiation. Returns a Promise giving HTTP2ClientRequest instance or ClientRequest instance (depending on the ALPN).
Usage example:

'use strict';
const http2 = require('http2-wrapper');

const options = {
	hostname: 'httpbin.org',
	protocol: 'http:', // Note the `http:` protocol here
	path: '/post',
	method: 'POST',
	headers: {
		'content-length': 6
	}
};

(async () => {
	try {
		const req = await http2.auto(options);
		req.on('response', res => {
			console.log('statusCode:', res.statusCode);
			console.log('headers:', res.headers);

			const body = [];
			res.on('data', chunk => body.push(chunk));
			res.on('end', () => {
				console.log('body:', Buffer.concat(body).toString());
			});
		});

		req.on('error', console.error);

		req.write('123');
		req.end('456');
	} catch (error) {
		console.error(error);
	}
})();

// statusCode: 200
// headers: { connection: 'close',
//   server: 'gunicorn/19.9.0',
//   date: 'Sat, 15 Dec 2018 18:19:32 GMT',
//   'content-type': 'application/json',
//   'content-length': '259',
//   'access-control-allow-origin': '*',
//   'access-control-allow-credentials': 'true',
//   via: '1.1 vegur' }
// body: {
//   "args": {},
//   "data": "123456",
//   "files": {},
//   "form": {},
//   "headers": {
//     "Connection": "close",
//     "Content-Length": "6",
//     "Host": "httpbin.org"
//   },
//   "json": 123456,
//   "origin": "xxx.xxx.xxx.xxx",
//   "url": "http://httpbin.org/post"
// }

url

Type: string URL

options

Type: object

callback(error, clientRequestInstance)

Type: Function

http2.auto.resolveALPN(options)

Resolves ALPN using HTTP options.

http2.request(url, options, callback)

Same as https.request.

Note: session accepts HTTP2 sessions. To pass TLS session, you need to use socketSession instead.

http2.get(url, options, callback)

Same as https.get.

http2.HTTP2ClientRequest

Same as https.ClientRequest.

http2.HTTP2IncomingMessage

Same as https.IncomingMessage.

Tips

Reusing sessions

Due to the lack of HTTP2 session pools, you have to manage them by yourself. To reuse a session, you need to pass it through the session option:

const http2 = require('http2-wrapper');
const session = http2.connect('https://google.com');
session.unref(); // The session will destroy automatically when the process exits

const options = {
	hostname: 'google.com',
	session
};

// Reuses the same session
const makeRequest = () => {
	http2.request(options, res => {
		res.on('data', chunk => {
			console.log(`Received ${chunk.length} bytes of data`);
		});
	}).end();
};

makeRequest(); // Received 220 bytes of data
makeRequest(); // Received 220 bytes of data

Notes

• WebSockets over HTTP2 is not supported.
• HTTP2 sockets cannot be malformed.
• There's no pool (agent equivalent) option yet.

License

MIT