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.
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(
reqPath: string,
stream: http2.ServerHttp2Stream,
cacheCookie?: string): Promise<PreprocessResult>;
interface PreprocessResult {
newCacheCookie: string;
pushFn: () => Promise<void>;
}
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 currentServerHttp2Stream
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(
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.
This can be passed to the constructor of AutoPush
to customize the caching
behavior.
interface AssetCacheConfig {
warmupDuration: number;
promotionRatio: number;
demotionRatio: number;
minimumRequests: number;
}
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.
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.
Similar to promotionRatio
, but if the hit ratio is lower than
demotionRatio
, the request path will not be considered an associated
resource anymore.
The minimum number of requests for a certain path before being considered as a candidate for an associated resource.