Set Response Headers§

As mentioned above, you use Unit’s router to add, remove, or override response headers. In most cases, the router will already be in use. If your listener points to a router object like this, you are good to go.

{
    "listeners": {
        "*:80": {
            "pass": "routes"
        }
    }
}

If not, and you are new to the world of Unit Routes, be sure to read the documentation before diving into this new feature.

Let’s start with a simple use case. We are using Unit to host a frontend along with a web API. The languages or the Unit application object do not really matter in this case. The current configuration looks like this:

{
    "listeners": {
        "*:8080": {
            "pass": "routes/app"
        }
    },

    "routes": {
        "app": [
            {
                "match": {
                    "uri": [
                        "/api/*"
                    ]
                },

                "action": {
                    "pass": "applications/api"
                }
            },
            {
                "action": {
                    "share": [
                        "/var/www/frontend$uri",
                        "/var/www/frontend/index.html"
                    ]
                }
            }
        ]
    }
}

A newly introduced response_headers object can be added to any action object. The response_headers object contains a list of key/value pairs, each of which defines a single header. If a header name matches a response header already present in the response, its value is replaced. Otherwise, a new response header is created. A value of null omits the header from the response. An empty string does not. Let’s change the configuration to demonstrate what all this means. First, we want to hide an X-Version header sent by the API application:

{
    "action": {
        "pass": "applications/api",
        "response_headers": {
            "X-Version": null
        }
    }
}

For our front-end, we want to add a version hash to identify the deployed version without digging into the sources:

{
    "action": {
        "share": [
            "/var/www/frontend$uri",
            "/var/www/frontend/index.html"
        ],
        "response_headers": {
            "X-FE-Version": "abc1234def"
        }
    }
}

In addition to fixed values, you can call an NJS function to create a value using some more complex rules. To do this, use a template literal:

"Upper-Case": "`${host.toUpperCase()}`"

If this sounds all new to you, read more about the NGINX JavaScript Engine in Unit in our documentation.

Use Response Header Variables§

With 1.31 and the ability to control response headers, we have added a new set of variables. When Unit receives a response from an application hosted on Unit, and you want to modify an existing response header based on the value that was shared by the application, it becomes imperative for Unit to retain that specific value. This is where the newly introduced response header variables come into play.

The format of the new variables is based on other variables that Unit already supports in the router. To retrieve the value of a particular HTTP header, use response_header as the key identifier, followed by name_of_the_header enclosed in ${}. If you are new to using variables with Unit during request processing, use this documentation to learn more. Let’s look at this through an example use case.

In the following configuration, we want to add a charset to the Content-Type response header that was already set by the application:

[
    {
        "action": {
            "pass": "applications/calc",
            "response_headers": {
                "Content-Type": "${response_header_content_type};charset=iso-8859-1"
            }
        }
    }
]

Since the Content-Type header already exists in the response, Unit will change its value.