8.9.0.0 | Services | Response Messaging service

The Response Messaging service enables Repose to conditionally overwrite the response body with a pre-configured message.

This service may be used to provide consistent error messages to users. For example, if a user asks for JSON, but the origin service normally returns a plain text message, this service can be configured to pack the plain text message into a JSON envelope.

Configuration

Default Configuration: response-messaging.cfg.xml
Released: v1.0
Schema

Exhaustive

This configuration uses all available options.

response-messaging.cfg.xml

<?xml version="1.0" encoding="UTF-8"?>

<response-messaging xmlns="http://docs.openrepose.org/repose/response-messaging/v1.0">
    <status-code id="four-one-eight" (1)
        code-regex="418" (2)
        overwrite="ALWAYS"> (3)
        <message (4)
            media-type="*/*" (5)
            content-type="application/xml"> (6)
            <![CDATA[<I> am a teapot</I>]]> (7)
        </message>
    </status-code>

    <status-code id="518">
        <message media-type="application/json"
            href="file:///etc/repose/jsonresponsefor518"> (8)
        </message>

        <message media-type="application/xml"
            href="file:///etc/repose/xmlresponsefor518">
        </message>
    </status-code>
</response-messaging>

1	Specifies the response status code(s) for which the response message might be modified. This declaration is given a unique ID for service-internal identification purposes.
2	Declares a regular expression that must match the response status code for any response message modification to occur.
3	Declares that this service should always overwrite the original response message when a declared message is applied. `ALWAYS` will always overwrite the original response message. `IF_EMPTY` will only overwrite the original response message if the current response message is missing. Default: `IF_EMPTY`
4	Defines the message that will be written to the response, if applicable.
5	Declares a media type that must match the `Accept` of the request for any response message modification to occur. This attribute allows different message formats for different requested media types. Wildcard media types other than `/` are not supported in this attribute. A media type of `/` will match all requested media types. Default: `/`
6	Defines the `Content-Type` of the configured response message. This value will be written to the `Content-Type` header of the response. Default: `text/plain`
7	Define the response message itself. Template Parameters may be used in the message, and will be replaced when the message is written to the response. XML messages should always be placed within `CDATA` tags.
8	Specifies the external location of a response message. If both the `message` element and the `href` attribute have a value, then this service will use the message in the `href` location.

Template Parameters

Configured messages may contain template parameters that will be replaced when the message is written to the response.

Table 1. Template Parameters
Format	Description
\t	Tab character.
\n	Newline character.
%%	Percent sign character.
%a	Remote IP address.
%A	Local IP address.
%b	Size of the response body in bytes in CLF format (i.e., substitutes `-` rather than `0` when no bytes are sent).
%B	Size of the response body in bytes. `0` is substituted when no bytes are sent.
%D	Time taken to serve the request, in microseconds.
%g	Internal GUID assigned to the request.
%H	Request Protocol.
%h	Remote Host.
%{header}i	Value of the request header identified by `{header}`. Note that header names are case-insensitive. For example, `%{X-Auth-Token}i` is equivalent to `%{x-auth-token}i`.
%{header type out-format}i	See above. Supported `type` are: `DATE`. Supported `out-format` are: `RFC_1123` and `ISO_8601`. The input format will be taken to be `RFC_1123`.
%{header type out-format in-format}i	See above. Supported `in-format` are: `RFC_1123` and `ISO_8601`.
%M	HTTP response status message, if set.
%m	HTTP request method.
%{header}o	Value of the response header identified by `{header}`. Note that header names are case-insensitive. For example, `%{LOCATION}o` is equivalent to `%{location}o`.
%{header type out-format}o	See above. Supported `type` are: `DATE`. Supported `out-format` are: `RFC_1123` and `ISO_8601`. The input format will be taken to be `RFC_1123`.
%{header type out-format in-format}o	See above. Supported `in-format` are: `RFC_1123` and `ISO_8601`.
%p	Canonical port of the origin service that handled the request.
%q	Query string of the HTTP request. If no query string exists, then the empty string will be used.
%r	First line of HTTP request (e.g., `GET /index.html HTTP/1.1`).
%s	HTTP response status code.
%t	Time the HTTP request was received in the format `yyyy-MM-dd HH:mm:ss`.
%{format}t	Time the HTTP request was received using the specified date format. The format must be a `SimpleDateFormat`. The format string is limited to letters, numbers, dashes, spaces, periods, and colons. For example, `%{yyyy-MM-dd HH:mm:ss}t` is a valid format and template.
%T	Time taken to serve the request, in seconds.
%u	Remote user. This value is taken from the `X-PP-User` header.
%U	URL path of the HTTP request, not including the query string.

Templates may be conditionally written for specified status codes.

Table 2. Conditional Templates
Format	Description
%403,401U	Logs the URL path requested on responses with status codes `403` and `401` only.
%\!200,304,302U	Logs the URL path requested for all responses except those with status codes: `200`, `304`, and `302`.

These parameters are a subset of Apache HTTP Logging functionality. This service only supports this subset of Apache logging paremeters plus the listed non-standard extras.

Additional Information

If this service encounters a response status code and media type combination it is not configured to handle, this service will not alter the response in any way.

This service will always use the first (i.e., the closest to the top of the configuration file), and only the first, matching status-code. That means that only messages defined in the first matching status-code are candidates for being written as the response body.

Windows Operating System

When running Repose in the Windows Operating System, if the response message is external to the configuration for this service, then any file location specified in the href attribute must be in the following format:

href="file:///C:/Users/Administrator/repose/regression-node-1/repose/node3/responsefor5xx"

Despite running in Windows, the path separator should be /.