HTTP/2 server-push for hapi

Lead Maintainer - Devin Ivy

npm install underdog

See also the API Reference

Underdog is intended for use with hapi v19+ and nodejs v12+ (see v4 for lower support).

This module is currently under ad hoc maintenance, which means it relies fully on community support.

Underdog brings HTTP/2 server-push to hapi. The way it works is that you specify paths to resources that you'd like to push alongside a particular response. This is achieved with a call to the response toolkit decoration h.push(). Before hapi responds to the original request, those push-requests will be made internally and their results will be streamed to the client as push-responses. Even pushed resources can specify additional resources to push. You can't make this stuff up!

const Fs = require('fs');
const Http2 = require('http2');
const Hapi = require('@hapi/hapi');
const Underdog = require('underdog');

(async () => {

    const listener = Http2.createSecureServer({
        // See tests for a key/cert that you can use to try this out
        key: Fs.readFileSync(`${__dirname}/localhost.key`),
        cert: Fs.readFileSync(`${__dirname}/localhost.cert`)
    });

    const server = Hapi.server({
        listener,
        tls: true,
        port: 3000
    });

    await server.register(Underdog);

    server.route([
        {
            method: 'get',
            path: '/',
            handler: (request, h) => {

                const response = h.response('<script src="/push-me.js"></script>');

                h.push(response, 'push-me.js');

                return response;
            }
        },
        {
            method: 'get',
            path: '/push-me.js',
            handler: (request) => {

                return 'document.write(\'I was definitely pushed!\');';
            },
            // To demonstrate that it must have been pushed, not requested directly
            config: { isInternal: true }
        }
    ]);

    await server.start();

    console.log(`Check-out ${server.info.uri} in your favorite HTTP/2-supporting client`);
})();

Underdog is compatible with nodejs's Http2Server and Http2SecureServer under the Compatibility API. Using any other HTTP server will simply disable server-push; h.push() will no-op and return { response, allowed: false } and h.pushAllowed() will return false.

• The HTTP/2 spec (here)
• For debugging HTTP/2 in Chrome, see chrome://net-internals/#http2
• Nodejs's HTTP/2 docs (here)
• Shout-out to the original userland spdy and http2 modules.

HTTP/2 server-push for hapi

Note

Underdog is intended for use with hapi v19+ and nodejs v12+ (see v4 for lower support).

This module is currently under ad hoc maintenance, which means it relies fully on community support.

You should register Underdog in any plugin that would like to take advantage of its features; it does not take any options. Underdog specifies the once plugin attribute, which means hapi will ensure it is not registered multiple times.

Note, Underdog utilizes an onPreResponse extension to finalize server-push, so if you modify the response in an onPreResponse extension and would like that response to push additional resources, you must specify { before: 'underdog' } as an option when calling server.ext().

• response - the hapi response for which you'd like to push additional resources. Should not be an error response. When this argument is omitted Underdog will attempt to use the request's currently set response, which will fail with an error if there is no such response.
• path - the path to another resource on the same hapi server that you'd like to server-push, or an array of such paths. If a path is relative (does not begin with /) then it is adjusted based upon the relevant realm's route prefix.
• headers - any headers that you would like to add to the push-request for this resource. By default a user-agent header is automatically added to match the user-agent of the originating request.

Returns an object { response, allowed } where response is the response for which resources are intended to be pushed, and allowed indicates whether the server-push was allowed by the client and protocol (when false, no resources were pushed).

Note that when push requests are resolved credentials from the originating request will be used, and that routes marked as isInternal are accessible.

Returns true or false, indicating whether server-push is allowed by the client and protocol. Sometimes resources cannot be pushed, for example when the server handles an http/1.1 request or when an http/2 client disables pushes. See ALPN Negotiation and HTTP/2 Session Settings in the nodejs docs for more info.