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, they may want to return the “Bad Panda” page to the user http://www.flickr.com/badpanda.html.
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. ATS already supports custom error pages globally on a per-language basis but not on a per remap basis.
For the purposes of this document, an error is any error (4xx-5xx) that is detected/generated by ATS. This includes errors detected during remapping (404) and connection errors related to connecting to the origin (5xx) errors. Not covered as errors are 4xx-5xx responses which are returned from the origin.
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
The configuration file for the custom error plugin is a simple text file containing named sections which map from error code(s) to the error content(s) with a single mapping per line and optional language and character set information for the 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.
The error code may be a single HTTP error code or a range of codes.
The error content is either a static (local) HTML file OR is an external HTML object which the plugin can retrieve via HTTP. Error content references may also include the following replacement variables:
%{host} - Value of the host header (post remap value)
%{path} - Path from the URL (post remap value)
%{scheme} - Scheme of client connection (http or https)
%{port} - Port number of client connection.
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. 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.
If the specified HTML error object is not found, either due to the file not existing or a request on the external HTML object fails with a 404 error, the client will be returned the ATS 404 error body (as defined by the ATS body factory). Additionally, 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.”).
If a request for an external HTML object fails, an ATS default error body will be returned to the client. Additionally, an error will be logged with enough detail to help diagnose the issue (e.g. “Error 502 while requesting http://flickr.com/badpanda.jpg as configured on line y of config file z.”).
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.
