From 19dbab7971e0db38b124dad3c3a16a7fc6a53d96 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Tue, 19 Dec 2017 07:03:30 -0800 Subject: [PATCH] Fixes #2069 - Update the PushCacheFilter documentation. (#2070) Signed-off-by: Simone Bordet --- .../http2/configuring-push.adoc | 51 +++++++++++++++---- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc index 3e59d9b8115..4951a575832 100644 --- a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc @@ -17,10 +17,14 @@ [[http2-configuring-push]] === Configuring HTTP/2 Push -HTTP/2 Push is a mechanism that allows the server to send multiple resources to the client for a single client request. -This will reduce the amount of round-trips necessary to retrieve all the resources that make up a web page and can significantly improve the page load time. +HTTP/2 Push is a mechanism that allows the server to send multiple resources +to the client for a single client request. +This will reduce the amount of round-trips necessary to retrieve all the +resources that make up a web page and can significantly improve the page load time. -HTTP/2 Push can be automated in your application by configuring a link:{JDURL}/org/eclipse/jetty/servlets/PushCacheFilter.html[`PushCacheFilter`] in the `web.xml`, in this way: +HTTP/2 Push can be automated in your application by configuring a +link:{JDURL}/org/eclipse/jetty/servlets/PushCacheFilter.html[`PushCacheFilter`] +in the `web.xml`, in this way: [source, xml, subs="{sub-order}"] ---- @@ -47,13 +51,38 @@ HTTP/2 Push can be automated in your application by configuring a link:{JDURL}/o ---- -`PushCacheFilter` analyzes the HTTP requests for resources that arrive to your web application. -Some of these requests contain the HTTP `Referrer` header that points to a resource that has been requested previously. -This allows the `PushCacheFilter` to organize resources in to two categories: _primary_ resources (those referenced by the `Referrer` header) and _secondary_ resources (those that have the `Referer` header). +`PushCacheFilter` analyzes the HTTP requests for resources that arrive to your web +application. +Some of these requests contain the HTTP `Referer` header that points to a resource +that has been requested previously. -`PushCacheFilter` associates secondary resources to primary resources. -Only secondary resources that have been requested within a time window from the request of the primary resource are associated with the primary resource. +This allows the `PushCacheFilter` to organize resources in a tree, for example +a root `index.html` resource having two children resources, `styles.css` and +`application.js`, and `styles.css` having a child resource, `background.png`. +The root resource is called the _primary_ resource, while descendant resources +are called _secondary_ resources. -`PushCacheFilter` can be configured with the following `init-params`:: -* `associatePeriod`: the time window, in milliseconds, within which a request for a secondary resource will be associated to a primary resource. -* `maxAssociations`: the max number of secondary resources that may be associated to a primary resource. +The resource tree is built using a time window so that when a root resource is +requested, only subsequent requests that are made within the time window will +be added to the resource tree. +The resource tree can also be limited in size so that the number of secondary +resources associated to a primary resource is limited. + +By default, only the resource _path_ (without the _query_ string) is used to +associate secondary resources to the primary resource, but you can configure +`PushCacheFilter` to take the query string into account. + +`PushCacheFilter` can be configured with the following `init-params`: + +* `associatePeriod`: the time window, in milliseconds, within which a request +for a secondary resource will be associated to a primary resource; defaults to +4000 ms +* `maxAssociations`: the max number of secondary resources that may be +associated to a primary resource; defaults to 16 +* `hosts`: a comma separated list of hosts that are allowed in the `Referer` +header; defaults to the host in the `Host` header +* `ports`: a comma separated list of ports that are allowed in the `Referer` +header; defaults to the port in the `Host` header +* `useQueryInKey`: a boolean indicating whether the query string of the +request should be considered when associating secondary resources to +primary resources; defaults to false