HTTP/2 automatic server push


This is not an official Google product.

HTTP/2 is a major revision of the HTTP
protocol. One of its differences from HTTP/1 is *server
push*, which allows a
server to pre-emptively send responses to a client in association with a
previous client-initiated request. This can be useful when the server knows
the client will need to have those responses available in order to fully
process the response to the original request.

It sounds simple and easy but is quite tricky for service developers to
manually figure out and configure what resources to push in association with
another resource. There are also many pitfalls the implementors must know
about. See Rules of Thumb for HTTP/2
Push
for the details.

This project is for automating server push and getting rid of the need for
manual configurations from service developers. It is meant as a helper
library for building middlewares for various Node.js
web servers, such as Express,
fastify, etc.

This library assumes that the middlewares built on top of it act as a static
file server. That is because static file serving is one of the most common
use cases for HTTP/2 server push.

See https://github.com/google/node-fastify-auto-push for an example. It is a
fastify plugin for supporting auto-push.

This package currently works only with Node >=9.4.0.

Interface

$3

#### Constructor

``typescript
constructor(rootDir: string, cacheConfig?: AssetCacheConfig);
`

Constructs an AutoPush object.

* rootDir: Top-level directory that contains the static files to be served.
* cacheConfig: Configuration options for customizing the caching behavior.

#### preprocessRequest()

`typescript
preprocessRequest(
reqPath: string,
stream: http2.ServerHttp2Stream,
cacheCookie?: string): Promise;

interface PreprocessResult {
newCacheCookie: string;
pushFn: () => Promise;
}
`

This method must be called for every request from the client. It determines
which other resources must be pushed, if any, in association with the current
request path. It also checks whether any resources to be pushed are already
cached in the browser side. It is done by storing and reading the related
information in a cookie value.

* reqPath: The request path given from the client.
* stream: The current ServerHttp2Stream object.
* cacheCookie: The value of the cookie used for storing the information on
which resources are cached in the browser. It is up to the middleware
which cookie to use for this.

Returns a promise for the result (PreprocessResult). The middleware must
use the newCacheCookie value to store it in the browser cookie, and use
pushFn to push static resources that are associated with the current
request.

This method (and recordRequestPath() described below) must be called for
non-static file requests as well as static files that are being served by the
middleware. That's because there may be cases where a set of static files
must be pushed in association with a non-static resource. For example, when
index.html is a non-static file that is dynamically generated by the
application, it probably wants to push related resources such as stylesheets,
images, JavaScript files, etc. that are needed for the browser to render the
page.

When there is an error while pushing resources, a 'pushError' will be
emitted on the parent stream, whose argument is an error object that caused
it.

#### recordRequestPath()

`typescript
recordRequestPath(
session: http2.Http2Session,
reqPath: string,
isStatic: boolean): void;
`

This method must be called for every request from the client. It must be
called for non-static file requests as well as static files, as explained for
preprocessRequest() above.

* session: The current session object.
* reqPath: The request path given from the client.
* isStatic: true if the request is for a static file that is being served
by the middleware, false otherwise.

$3

This can be passed to the constructor of AutoPush to customize the caching
behavior.

`typescript
interface AssetCacheConfig {
warmupDuration: number;
promotionRatio: number;
demotionRatio: number;
minimumRequests: number;
}
`

#### warmupDuration

The time duration (in milliseconds) after a client request during which to
record additional requests. That record will be used for determining the
associated resources that may be pushed for a request path.

#### promotionRatio

If an additional request is frequently made for a certain original request
and its hit ratio is over the promotionRatio value, that request path is
considered one of the associated resources of the original request, and it'll
be pushed when a request is made for the same original request path later.

#### demotionRatio

Similar to promotionRatio, but if the hit ratio is lower than
demotionRatio, the request path will not be considered an associated
resource anymore.

#### minimumRequests`

The minimum number of requests for a certain path before being considered as
a candidate for an associated resource.