Custom HTTP Headers for the HTTP Management Interface

In  management

Overview

The HTTP management endpoint of the application server already returns a pre-defined set of HTTP headers in all of the responses that are sent to the clients, however it is sometimes desirable that additional headers can be returned to satisfy the requirements of an environment the application server is installed within. This enhancement is to add support for an end user to specify a custom set of HTTP headers that should be returned within each response.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Testing By

[ ] Engineering

[X] QE

Affected Projects or Components

Other Interested Projects

Requirements

Hard Requirements

This enhancement is to allow an administrator to define a constant set of headers that can be returned from requests handled via the management HTTP interface of the application server.

The HTTP management interface provides access to a number of contexts, our primary contexts are accessed at the following paths: -

  • /management - The endpoint for servicing management requests over HTTP.

  • /console - The endpoint to provide the admin console initial page and complete JavaScript.

Subsystems can also dynamically register additional contexts to dynamically provide additional functionality or content over the HTTP management interface.

As we have different endpoints it may be desirable for them to return different headers, as an example some headers are only applicable to the handling of pages or interpretation of the JavaScript so should only be applied to the /console endpoint whilst other headers may be applicable to both.

Configuration will be added to the HTTP management endpoint to allow headers to be specified, the following constraints will apply when applying the headers: -

  • The configuration will allow an end user to specify headers to be added based on a specified path prefix.

  • There will be a new constant-headers attribute on the /core-service=management/management-interface=http-interface resource.

  • Within the constant-headers attribute it will be possible to specify a set of headers using key / value pairs against a specific path prefix.

  • All paths will be assumed to be prefixes starting with / - any paths missing a leading / will be handled as though the leading / has been specified.

  • If a specific header is defined multiple times it will be added to the response multiple times.

For a specific request multiple configured path prefixes may match, as an example a request to /management would match both / and /management - in this case the defined headers for both mappings will be applied to the resulting response.

Any headers specified within the configuration will be applied just before the response is sent to the client, this means any headers specified will override any of the headers set by the endpoint which handled the request.

Some headers are integral to the correct operation of the server and so can not be overridden, these headers are: -

  • Connection

  • Content-Length

  • Content-Type

  • Date

  • Transfer-Encoding

If an administrator attempts to set these headers an error will be reported.

An error will also be reported if the name of a header specified includes invalid characters as defined by the HTTP specification RFCs.

The new attribute to be added to the /core-service=management/management-interface=http-interface resource will be called constant-headers and will be defined as: -

            "constant-headers" => {
                "type" => LIST,
                "description" => "The set of constant HTTP headers to apply to response messages.",
                "expressions-allowed" => false,
                "required" => false,
                "value-type" => {
                    "path" => {
                        "type" => STRING,
                        "description" => "The path the headers should be applied to.",
                        "expressions-allowed" => true,
                        "required" => true,
                    },
                    "headers" => {
                        "type" => LIST,
                        "description" => "The headers to set for the matched path.",
                        "expressions-allowed" => false,
                        "required" => false,
                        "value-type" => {
                            "name" => {
                                "type" => STRING,
                                "description" => "The name of the HTTP header to set.",
                                "expressions-allowed" => true,
                                "required" => true,
                            },
                            "value" => {
                                "type" => STRING,
                                "description" => "The value to set for the HTTP header.",
                                "expressions-allowed" => true,
                                "required" => true,
                            }
                        }
                    }
                }

The following example shows how the interface can be configured to add a constant header for the /management endpoint: -

/] /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers, value=[{path=/management, headers=[{name=X-Header, value=HeaderValue}]}])

The write-attribute operation will trigger a reload-required state as the management interface will need to be re-initialised.

Nice-to-Have Requirements

Non-Requirements

As the contexts supported by the HTTP management interface can be added dynamically by subsystems no validation will be performed to verify that the specified paths are genuinely reachable paths as this information is not available to us at the time we perform model validation.

It is not intended that configured headers alter how an endpoint processes a response, however as endpoint process a response after the custom headers have been set an endpoint could still choose to check if a header has already been set by a previous handler and alter it’s behaviour but this is outside the scope of this enhancement.

Test Plan

Within the WildFly Core project we will add add a test case against the /management and /error endpoints, this will allow us to verify headers can be applied both via a common root context and to specific contexts. This testing will also make use of the management interface to perform the actual configuration which will trigger persistence and require reload of the configuration.

Tests will also be added verifying invalid header names are correctly rejected.

Community Documentation

Community documentation will need to be added describing how to configure custom HTTP headers that should be returned on every request. The documentation will be added within section 3.1 of the "WildFly Admin Guide" adding a description of the new configuration attribute as well as describing how it affects the resulting response.

Release Note Content

A new attribute constant-headers has been added to the HTTP management interface resource definition. Administrators can make use of this attribute to specify additional HTTP headers to be returned in the responses to requests made against the HTTP management interface. See the WildFly Admin Guide for information on how to configure this feature.