Stale Response Plugin¶

This plugin adds stale-while-relavidate and stale-if-error Cache-Control directive functionality. The stale-while-revalidate directive specifies a number of seconds that an item can be stale and used as a cached response while Traffic Server revalidates the cached item. The stale-if-error directive specifies how stale a cached response can be and still be used as a response if the origin server replies with a 500, 502, 503, or 504 HTTP status. The plugin currently only supports the stale-if-error directive in responses. For more details, see RFC 5861 for the specification of these directives.

Building and Installation¶

The Stale Response plugin is an experimental plugin. To build it, pass -DBUILD_EXPERIMENTAL_PLUGINS=ON to the cmake command when building Traffic Server. By default, that will build the stale_response.so plugin and install it in the libexec/trafficserver directory.

Configuration¶

The Stale Response plugin supports being used as either a global plugin or as a remap plugin. To configure Traffic Server to use the Stale Response plugin, simply add it to either the plugin.config to configure it as a global plugin and restart traffic-server or add it to the desired remap lines in the remap.config and reload Traffic Server. The following configurations are available for the plugin:

Default values can be specified for responses that do not contain the directives:

--stale-while-revalidate-default <time> set a default stale-while-revalidate directive with a value of time for all responses where the directive is not present.

--stale-if-error-default <time> set a default stale-if-err directive with a value of time for all responses where the directive is not present.

Also, minimum values can be set for responses that do or do not contain the directives:

--force-stale-while-revalidate <time> set a minimum stale-while-revalidate time for all responses.

--force-stale-if-error <time> set a minimum stale-if-error time for all responses.

The plugin uses memory to temporarily store responses. By default, this is limited to 1 GB, but can be configured with: --max-memory-usage <size>

The plugin by default will only perform one asynchronous request at a time for a given URL. This can be changed with the --force-parallel-async option.

Logging¶

The plugin can log information about its behavior with respect to the stale-while-revalidate and stale-if-error directives.

--log-all enable logging of all stale responses for both stale-while-revalidate and stale-if-error directives.

--log-stale-while-revalidate``enable logging of all stale responses due to ``stale-while-revalidate directives.

--log-stale-if-error enable logging of all stale responses due to stale-if-error directives.

--log-filename <name> set the Stale Response log to <name>.log. The log will be in the proxy.config.log.logfile_dir directory.

Statistics¶

stale_response.swr.hit The number of times stale data was served for stale-while-relavidate.

stale_response.swr.locked_miss The number of times stale data could not be served with stale-while-relavidate because of a lock.

stale_response.sie.hit The number of times stale data was served for stale-if-error.

stale_response.memory.over The number of times stale data could not be served because of memory constraints.

Example¶

To configure the plugin as a global plugin with a default stale-while-revalidate and a default stale-if-error of 30 seconds, add the following to plugin.config:

stale_response.so --stale-while-revalidate-default 30 --stale-if-error-default 30

To configure the plugin the same way as a remap config plugin, add the following to an appropriate remap entry in remap.config:

map http://example.com http://backend.example.com @plugin=stale_response.so \
  @pparam=--stale-while-revalidate-default @pparam=30 \
  @pparam=--stale-if-error-default @pparam=30