Summary
Some ATS destination 'properties' would like to return custom/meaningful error pages to users in the event of a failure in dependent services (i.e. ATS cannot connect to origin server). For example, if ATS cannot connect to Flickr’s services or if Flickr services fail internally, we may want to return the “Bad Panda” page to the user http://www.flickr.com/badpanda.html. Alternatively, if a particular origin is failing, a property might want to forward the request to a different origin.
Requirements
Since ATS is used to front many different 'properties' via reverse proxy operation, the specification for what to return to users in the event of an error must be done on a per remap basis.
The requirements are for the plugin to be able to detect and act upon on specified errors (from specific remap rules) which would be returned to the user. Instead of returning the error to the user, the plugin will remap the request to another URL or a static file. If to another URL, the URL must have a matching remap rule in remap.config (thus allowing chaining).
What is an error?
For the purposes of this document, an error is any error (4xx-5xx) that would be returned to the client. This includes both internally generated errors (e.g. like a 404 if a remap rule is not matched) and externally generated errors (e.g. the origin returned a 500 error).
Configuration
Configuration of the global plugin is done via a single configuration file (specified in plugin.config as the only parameter to the plugin) which contains named sections. Remap rules must reference a named section to apply that configuration to the remap rule. Remap line will identify the plugin and pass a single parameter which is the name of the section. Example:
regex_map http://(.*\.)?flickr\.com/ http://real.flickr.com/ @plugin=custom_error.so @pparam=flickr
Config File
The configuration file for the plugin is a simple text file containing named sections which map from (would be) response code(s) to the escalation content references with a single mapping per line. Optionally, each section may include language and character set information for static content. Example:
#error code content
name default
500 /usr/local/error_conf/global_500.txt
name flickr
500 /usr/local/error_conf/500.txt
501 http://xyz.com/501.txt
503-546 ./546.txt
Content-Language kr
Content-Charset iso-2022-kr
The default section, if present, will apply to errors which are not “overridden” by a remap rule.
Response Code
The response code(s) may be a single HTTP error code or a range of codes.
Escalation Content
The escalation content is either a static (local) HTML file OR is an external HTML object which the plugin can retrieve via HTTP. Escalation content references may also include the following substitution strings (subset of regex_remap plugin):
$h - The original host header from the request
$p - The original port number
$s - The scheme (e.g. http) of the request
$P - The entire path of the request
$q - The query part of the request
Language
In order to indicate to the client what language and character set the error content is made up of, the plugin supports setting the value of the returned Content-Language and Content-Charset headers for static content. If not specified, the default is assumed (English text in standard utf-8 character set.). For external HTML objects, the plugin will forward all request headers to the external server so that it can determine the proper language for the returned content.
Mis-configuration
If the specified escalation static file is not found, the client will be returned the default 404 error body as provided in the configuration. In the event, the plugin’s attempt to return a 404 fails, then the internal ATS 404 error body (as defined by the ATS body factory) will be returned. As appropriate for the error, an error will be logged with enough detail to help diagnose the issue (e.g. “Couldn't find file 'xx.txt' on line y of config file z.”).
Function
Upon detection of an error (as described above) the plugin will return the specified ‘error content’. If the error code is NOT configured, then the default/global behavior of ATS will prevail.
When returning a static file, the plugin will include Content-Language and Content-Charset headers in the response to the client as they are specified in the config file. If they are not specified, then the response will not include them.
Requests for external content will be made via the ATS stack (meaning all plugins, remap rules, etc will take effect for the request), therefore a remap rule is required for external content references.