Edge Technologies, Inc. | Documentation | HeaderHandlers Content Rule

The HeaderHandlers content rule is used by BaseWeb to deal with headers when processing both client requests to be forwarded to the target application, and application responses to be forwarded to the client.

Requests

By default, all headers from the client request are copied into the application request during onRequest. The exceptions are:

connection
content-length
cookie
upgrade-insecure-requests

In addition, the following headers are either transformed or replaced with a more suitable value before being copied into the application request:

host – set to reflect the backend host
referer – expected to be a mapped URL – is transformed to its unmapped form
origin – set to reflect the backend host
accept-encoding: if present, the AppRequest’s header is set to gzip, which is currently the only encoding supported by edgeWeb. Prior behavior was to exclude this header for all AppRequests.

All of these headers are named in the requestHeaderHandlers property of the HeaderHandlers object. Each header has a corresponding handler function. In the case of the headers that aren’t copied, null is specified for the function (and empty function definition will have the same effect). For the headers that are transformed, a function is defined – these can be seen in the HeaderHandlers rule, which can be found in tomcat/webapps/ROOT/WEB-INF/classes/webrules/system/lib/HeaderHandlers.js.

Any of the default behaviors can be overridden as described in the Customization section below.

Responses

By default all headers from the application response are copied into the client response during onResponse. The exceptions are:

content-encoding
content-length
connection
keep-alive
location
set-cookie
transfer-encoding
www-authenticate
x-content-type-options
x-xss-protection
x-frame-options
content-security-policy

Customization

The header handling behavior can be customized through a number of methods of the HeaderHandlers object. For each of the methods, the HeaderHandler type is a function with the following signature: function(headerName, headerValues, outputMessage, ctx). The arguments are described below:

Argument	Type	Description
headerName	String	Name of the header being handled. The name will be as it appears in the original message.
headerValues	String[]	Potentially multiple values of the named header, in the order they appear in the original message.
outputMessage	AppRequest \| ClientResponse	The message being prepared for sending. For request header handling, this is the application request. For response header handling, this is the client response.
ctx	Request Context Object	The usual request context object.

The handler has access to all the usual context via the usual ctx object passed as the last argument. Normally, the effect of the handler is to set the same named header(s) in the forwarded message (outputMessage) to a value based on the incoming value(s).

The table below lists the methods for adding request and response header handlers. In each case, the headerName argument should be lowercase, otherwise, processing may not work as expected.

Method	Return Type	Arguments	Description
addRequestHeaderHandler	void	String headerName, HeaderHandler handler	Sets the handler for the named request header. If the header is present in the client request, then the supplied handler will be called.
excludeRequestHeader	void	String headerName	Excludes the named header from being forwarded from the client to the app request. The equivalent of calling addRequestHeaderHandler with a null handler specified.
addResponseHeaderHandler	void	String headerName, HeaderHandler handler	Sets the handler for the named response header. If the header is present in the app response, then the supplied handler will be called.
excludeResponseHeader	void	String headerName	Excludes the named header from being forwarded from the app to the client response. The equivalent of calling addResponseHeaderHandler with a null handler specified.

Finally, the methods in the table below are normally called by (or via) the BaseWeb rule, but this does not preclude us from calling them directly in the unusual case that we’re not using the base rule.

Method	Return Type	Arguments	Description
handleHeaders	void	headerHandlers, HttpMessage input, MutableHttpMessage output, ctx	A generic header handling function to deal with both request and response headers based on a list of handlers, and input message, and an output message.
onRequest	void	ctx	Request handler – handles request headers according to registered request header handlers.
onResponse	void	ctx	Response handler – handles response headers according to registered response header handlers.