feat(config) add 'headers' property to replace '*_tokens'

As new headers are introduced by Kong's core, instead of introducing a
config option for each and every header or set of headers, an array of
these values can be now specified using the `headers` config option.

This offers a fine grained controlled and does not blow up the number of
configuration options.

The goal here is to move towards a  simpler and easier to understand
configuration, similar to 1b9976f (Kong#3147).

From Kong#3300

Signed-off-by: Thibault Charbonnier <[email protected]>

kong.conf.default

@@ -190,15 +190,25 @@
                                  # process. When this number is exceeded, the
                                  # least recently used connections are closed.
 
-#server_tokens = on              # Enables or disables emitting Kong version on
-                                 # error pages and in the "Server" or "Via"
-                                 # (in case the request was proxied) response
-                                 # header field.
-
-#latency_tokens = on             # Enables or disables emitting Kong latency
-                                 # information in the "X-Kong-Proxy-Latency"
-                                 # and "X-Kong-Upstream-Latency" response
-                                 # header fields.
+#headers = server_tokens, latency_tokens
+                                 # Specify Kong-specific headers that should
+                                 # be injected in responses to the client.
+                                 # Acceptable values are:
+                                 # - `server_tokens`: inject 'Via' and 'Server'
+                                 #   headers.
+                                 # - `latency_tokens`: inject
+                                 #   'X-Kong-Proxy-Latency' and
+                                 #   'X-Kong-Upstream-Latency' headers.
+                                 # - `X-Kong-<header-name>`: only inject this
+                                 #   specific the header when applicable.
+                                 #
+                                 # Example:
+                                 #   headers = via, latency_tokens
+                                 #
+                                 # This value can be set to `off`, which
+                                 # prevents Kong from injecting any of these
+                                 # headers. Note that plugins can still inject
+                                 # headers.
 
 #trusted_ips =                   # Defines trusted IP addresses blocks that are
                                  # known to send correct X-Forwarded-* headers.

kong/conf_loader.lua

@@ -17,6 +17,16 @@ local DEFAULT_PATHS = {
   "/etc/kong.conf"
 }
 
+local headers = constants.HEADERS
+local header_key_to_name = {
+  ["server_tokens"] = "server_tokens",
+  ["latency_tokens"] = "latency_tokens",
+  [string.lower(headers.VIA)] = headers.VIA,
+  [string.lower(headers.SERVER)] = headers.SERVER,
+  [string.lower(headers.PROXY_LATENCY)] = headers.PROXY_LATENCY,
+  [string.lower(headers.UPSTREAM_LATENCY)] = headers.UPSTREAM_LATENCY,
+}
+
 local PREFIX_PATHS = {
   nginx_pid = {"pids", "nginx.pid"},
   nginx_err_logs = {"logs", "error.log"},
@@ -61,8 +71,7 @@ local CONF_INFERENCES = {
   nginx_user = {typ = "string"},
   nginx_worker_processes = {typ = "string"},
   upstream_keepalive = {typ = "number"},
-  server_tokens = {typ = "boolean"},
-  latency_tokens = {typ = "boolean"},
+  headers = {typ = "array"},
   trusted_ips = {typ = "array"},
   real_ip_header = {typ = "string"},
   real_ip_recursive = {typ = "ngx_boolean"},
@@ -278,6 +287,14 @@ local function check_and_infer(conf)
     end
   end
 
+  if conf.headers then
+    for _, token in ipairs(conf.headers) do
+      if token ~= "off" and not header_key_to_name[string.lower(token)] then
+        errors[#errors+1] = "headers: invalid entry '" .. tostring(token) .. "'"
+      end
+    end
+  end
+
   if conf.dns_resolver then
     for _, server in ipairs(conf.dns_resolver) do
       local dns = utils.normalize_ip(server)
@@ -587,6 +604,35 @@ local function load(path, custom_conf)
     end
   end
 
+  -- load headers configuration
+  do
+    local headers_enabled = {}
+
+    for _, v in pairs(header_key_to_name) do
+      headers_enabled[v] = false
+    end
+
+    if #conf.headers > 0 and conf.headers[1] ~= "off" then
+      for _, token in ipairs(conf.headers) do
+        if token ~= "off" then
+          headers_enabled[header_key_to_name[string.lower(token)]] = true
+        end
+      end
+    end
+
+    if headers_enabled.server_tokens then
+      headers_enabled[headers.VIA] = true
+      headers_enabled[headers.SERVER] = true
+    end
+
+    if headers_enabled.latency_tokens then
+      headers_enabled[headers.PROXY_LATENCY] = true
+      headers_enabled[headers.UPSTREAM_LATENCY] = true
+    end
+
+    conf.headers = headers_enabled
+  end
+
   -- load absolute paths
   conf.prefix = pl_path.abspath(conf.prefix)
 

kong/constants.lua

@@ -59,7 +59,9 @@ return {
     CONSUMER_GROUPS = "X-Consumer-Groups",
     FORWARDED_HOST = "X-Forwarded-Host",
     FORWARDED_PREFIX = "X-Forwarded-Prefix",
-    ANONYMOUS = "X-Anonymous-Consumer"
+    ANONYMOUS = "X-Anonymous-Consumer",
+    VIA = "Via",
+    SERVER = "Server"
   },
   RATELIMIT = {
     PERIODS = {

kong/core/error_handlers.lua

@@ -1,4 +1,5 @@
 local singletons = require "kong.singletons"
+local constants = require "kong.constants"
 
 local find = string.find
 local format = string.format
@@ -57,8 +58,8 @@ return function(ngx)
   local status = ngx.status
   message = BODIES["s" .. status] and BODIES["s" .. status] or format(BODIES.default, status)
 
-  if singletons.configuration.server_tokens then
-    ngx.header["Server"] = SERVER_HEADER
+  if singletons.configuration.headers[constants.HEADERS.SERVER] then
+    ngx.header[constants.HEADERS.SERVER] = SERVER_HEADER
   end
 
   ngx.header["Content-Type"] = content_type

kong/core/handler.lua

@@ -698,21 +698,24 @@ return {
       local header = ngx.header
 
       if ctx.KONG_PROXIED then
-        if singletons.configuration.latency_tokens then
+        if singletons.configuration.headers[constants.HEADERS.UPSTREAM_LATENCY] then
           header[constants.HEADERS.UPSTREAM_LATENCY] = ctx.KONG_WAITING_TIME
-          header[constants.HEADERS.PROXY_LATENCY]    = ctx.KONG_PROXY_LATENCY
         end
 
-        if singletons.configuration.server_tokens then
-          header["Via"] = server_header
+        if singletons.configuration.headers[constants.HEADERS.PROXY_LATENCY] then
+          header[constants.HEADERS.PROXY_LATENCY] = ctx.KONG_PROXY_LATENCY
+        end
+
+        if singletons.configuration.headers[constants.HEADERS.VIA] then
+          header[constants.HEADERS.VIA] = server_header
         end
 
       else
-        if singletons.configuration.server_tokens then
-          header["Server"] = server_header
+        if singletons.configuration.headers[constants.HEADERS.SERVER] then
+          header[constants.HEADERS.SERVER] = server_header
 
         else
-          header["Server"] = nil
+          header[constants.HEADERS.SERVER] = nil
         end
       end
     end

kong/templates/kong_defaults.lua

@@ -25,8 +25,7 @@ ssl_ciphers = ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-EC
 admin_ssl_cert = NONE
 admin_ssl_cert_key = NONE
 upstream_keepalive = 60
-server_tokens = on
-latency_tokens = on
+headers = server_tokens, latency_tokens
 trusted_ips = NONE
 real_ip_header = X-Real-IP
 real_ip_recursive = off

spec-old-api/02-integration/05-proxy/12-server_tokens_spec.lua

@@ -80,7 +80,7 @@ describe("Server Tokens", function()
 
     setup(start {
       nginx_conf    = "spec/fixtures/custom_nginx.template",
-      server_tokens = "on",
+      headers = "server_tokens",
     })
 
     teardown(helpers.stop_kong)
@@ -119,7 +119,7 @@ describe("Server Tokens", function()
 
     setup(start {
       nginx_conf    = "spec/fixtures/custom_nginx.template",
-      server_tokens = "off",
+      headers = "off",
     })
 
     teardown(helpers.stop_kong)
@@ -212,7 +212,7 @@ describe("Latency Tokens", function()
 
     setup(start {
       nginx_conf = "spec/fixtures/custom_nginx.template",
-      latency_tokens = "on",
+      headers = "latency_tokens",
     })
 
     teardown(helpers.stop_kong)
@@ -251,7 +251,7 @@ describe("Latency Tokens", function()
 
     setup(start {
       nginx_conf     = "spec/fixtures/custom_nginx.template",
-      latency_tokens = "off",
+      headers = "off",
     })
 
     teardown(function()

spec/01-unit/002-conf_loader_spec.lua

@@ -342,6 +342,13 @@ describe("Configuration loader", function()
       assert.is_nil(conf)
       assert.equal([[dns_order: invalid entry 'CXAME']], err)
     end)
+    it("errors on bad entries in headers", function()
+      local conf, err = conf_loader(nil, {
+        headers = "server_tokens,Foo-Bar",
+      })
+      assert.is_nil(conf)
+      assert.equal([[headers: invalid entry 'Foo-Bar']], err)
+    end)
     it("errors when hosts have a bad format in cassandra_contact_points", function()
       local conf, err = conf_loader(nil, {
           database                 = "cassandra",