CatalystX::Fastly::Role::Response - Methods for Fastly intergration to Catalyst
package MyApp; ... use Catalyst qw/ +CatalystX::Fastly::Role::Response /; extends 'Catalyst'; ... package MyApp::Controller::Root sub a_page :Path('some_page') { my ( $self, $c ) = @_; $c->cdn_max_age('10d'); $c->browser_max_age('1d'); $c->add_surrogate_key('FOO','WIBBLE'); $c->response->body( 'Add cache and surrogate key headers' ); }
This role adds methods to set appropreate cache headers in Catalyst responses, relating to use of a Content Distribution Network (CDN) and/or Cacheing proxy as well as cache settings for HTTP clients (e.g. web browser). It is specifically targeted at Fastly but may also be useful to others.
Values are converted and headers set in finalize_headers. Headers affected are:
finalize_headers
Cache-Control: HTTP client (e.g. browser) and CDN (if Surrogate-Control not used) cache settings
Surrogate-Control: CDN only cache settings
Surrogate-Key: CDN only, can then later be used to purge content
Pragma: only set for for browser_never_cache
Expires: only for browser_never_cache
All time periods are expressed as: Xs, Xm, Xh, Xd, XM or Xy, e.g. seconds, minutes, hours, days, months or years, e.g. 3h is three hours.
Xs
Xm
Xh
Xd
XM
Xy
3h
$c->cdn_max_age( '1d' );
Used to set max-age in the Surrogate-Control header, which CDN's use to determine how long to cache for. If not supplied the CDN will use the Cache-Control headers value (as set by "browser_max_age").
$c->cdn_stale_while_revalidate('1y');
Applied to Surrogate-Control only when "cdn_max_age" is set, this informs the CDN how long to continue serving stale content from cache while it is revalidating in the background.
$c->cdn_stale_if_error('1y');
Applied to Surrogate-Control only when "cdn_max_age" is set, this informs the CDN how long to continue serving stale content from cache if there is an error at the origin.
$c->cdn_never_cache(1);
When true the a private will be added to the Cache-Control header this forces Fastly to never cache the results, no matter what other options have been set.
$c->browser_max_age( '1m' );
Used to set max-age in the Cache-Control header, browsers use this to determine how long to cache for. The CDN will also use this if there is no Surrogate-Control (as set by "cdn_max_age").
$c->browser_stale_while_revalidate('1y');
Applied to Cache-Control only when "browser_max_age" is set, this informs the browser how long to continue serving stale content from cache while it is revalidating from the CDN.
$c->browser_stale_if_error('1y');
Applied to Cache-Control only when "browser_max_age" is set, this informs the browser how long to continue serving stale content from cache if there is an error at the CDN.
$c->browser_never_cache(1);
When true the headers below are set, this forces the browser to never cache the results. private is NOT added as this would also affect the CDN even if cdn_max_age was set.
cdn_max_age
Cache-Control: no-cache, no-store, must-revalidate, max-age=0, max-stale=0, post-check=0, pre-check=0 Pragma: no-cache Expires: 0
N.b. Some versions of IE won't let you download files, such as a PDF if it is not allowed to cache it, it is recommended to set a "browser_max_age"('1m') in this situation.
IE8 have issues with the above and using the back button, and need an additional Vary: * header, as noted by Fastly, this is left for you to impliment.
$c->add_surrogate_key('FOO','WIBBLE');
This can be called multiple times, the values will be set as the Surrogate-Key header as `FOO WIBBLE`.
See "cdn_purge_now" in MooseX::Fastly::Role if you are interested in purging these keys!
The method that actually sets all the headers, should be called automatically by Catalyst.
MooseX::Fastly::Role - provides cdn_purge_now and access to Net::Fastly stale-while-validate
Leo Lapworth <LLAP@cpan.org>
To install CatalystX::Fastly::Role::Response, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CatalystX::Fastly::Role::Response
CPAN shell
perl -MCPAN -e shell install CatalystX::Fastly::Role::Response
For more information on module installation, please visit the detailed CPAN module installation guide.