add_missing_headers

README

Add Missing Headers

A Traefik plugin that adds missing HTTP headers to requests and responses without overriding existing headers. Supports both strict and loose header checking modes, explicit flushing control, and conditional bypass functionality.

GitHub: https://github.com/giacomoferretti/add-missing-headers

Features

• ✅ Add missing request headers
• ✅ Add missing response headers
• ✅ Configurable header checking modes (strict/loose)
• ✅ Optional explicit flushing control
• ✅ Preserves existing headers (won't override)

Configuration

Static Configuration

YAML (traefik.yml)

experimental:
  plugins:
    add-missing-headers:
      moduleName: github.com/giacomoferretti/add-missing-headers
      version: v0.1.2

TOML (traefik.toml)

[experimental.plugins]
  [experimental.plugins.add-missing-headers]
    moduleName = "github.com/giacomoferretti/add-missing-headers"
    version = "v0.1.2"

CLI

--experimental.plugins.add-missing-headers.modulename=github.com/giacomoferretti/add-missing-headers \
--experimental.plugins.add-missing-headers.version=v0.1.2

Dynamic Configuration Examples

Basic Example

YAML

http:
  middlewares:
    custom-headers:
      plugin:
        add-missing-headers:
          requestHeaders:
            X-Custom-RequestHeader: "CustomRequestValue"
          responseHeaders:
            X-Custom-ResponseHeader: "CustomResponseValue"
          # Bypass example
          bypassHeaders:
            X-Skip-Headers: ""

TOML

[http.middlewares]
  [http.middlewares.custom-headers]
    [http.middlewares.custom-headers.plugin]
      [http.middlewares.custom-headers.plugin.add-missing-headers]
        [http.middlewares.custom-headers.plugin.add-missing-headers.requestHeaders]
          X-Custom-RequestHeader = "CustomRequestValue"
        [http.middlewares.custom-headers.plugin.add-missing-headers.responseHeaders]
          X-Custom-ResponseHeader = "CustomResponseValue"
        # Bypass example
        [http.middlewares.custom-headers.plugin.add-missing-headers.bypassHeaders]
          X-Skip-Headers = ""

Docker Labels

  labels:
    - "traefik.http.middlewares.custom-headers.plugin.add-missing-headers.requestHeaders.X-Custom-RequestHeader=CustomRequestValue"
    - "traefik.http.middlewares.custom-headers.plugin.add-missing-headers.responseHeaders.X-Custom-ResponseHeader=CustomResponseValue"
    - "traefik.http.middlewares.custom-headers.plugin.add-missing-headers.bypassHeaders.X-Skip-Headers="

Configuration Options

Option	Type	Default	Description
requestHeaders	map[string]string	{}	Headers to add to incoming requests if missing
responseHeaders	map[string]string	{}	Headers to add to outgoing responses if missing
strictHeaderCheck	bool	true	Header checking mode (see below)
disableExplicitFlush	bool	false	Disable explicit flushing after response writes
bypassHeaders	map[string]string	{}	Headers that bypass the middleware when present/matched

Bypass Headers

The bypassHeaders option allows you to completely skip the middleware when certain request headers are present or match specific values.

Bypass Modes

Header Presence Check - Set value to empty string "":

bypassHeaders:
  X-Accel-Buffering: ""  # Bypass if header exists with any value

Header Value Match - Set specific value:

bypassHeaders:
  X-Skip-Processing: "true"  # Bypass only if header equals "true"

Example Configuration

http:
  middlewares:
    conditional-headers:
      plugin:
        add-missing-headers:
          # Normal header additions
          requestHeaders:
            X-Forwarded-Proto: "https"
          responseHeaders:
            Cache-Control: "max-age=3600"
          # Bypass conditions
          bypassHeaders:
            X-Accel-Buffering: ""        # Skip if present (any value)
            X-Skip-Headers: "true"       # Skip if exactly "true"
            X-Debug-Mode: "enabled"      # Skip if exactly "enabled"

TOML Format

[http.middlewares]
  [http.middlewares.conditional-headers]
    [http.middlewares.conditional-headers.plugin]
      [http.middlewares.conditional-headers.plugin.add-missing-headers]
        # Normal header additions
        [http.middlewares.conditional-headers.plugin.add-missing-headers.requestHeaders]
          X-Forwarded-Proto = "https"
        [http.middlewares.conditional-headers.plugin.add-missing-headers.responseHeaders]
          Cache-Control = "max-age=3600"
        # Bypass conditions
        [http.middlewares.conditional-headers.plugin.add-missing-headers.bypassHeaders]
          X-Accel-Buffering = ""        # Skip if present (any value)
          X-Skip-Headers = "true"       # Skip if exactly "true"
          X-Debug-Mode = "enabled"      # Skip if exactly "enabled"

Docker Labels Format

labels:
  # Normal header additions
  - "traefik.http.middlewares.conditional-headers.plugin.add-missing-headers.requestHeaders.X-Forwarded-Proto=https"
  - "traefik.http.middlewares.conditional-headers.plugin.add-missing-headers.responseHeaders.Cache-Control=max-age=3600"
  # Bypass conditions
  - "traefik.http.middlewares.conditional-headers.plugin.add-missing-headers.bypassHeaders.X-Accel-Buffering="
  - "traefik.http.middlewares.conditional-headers.plugin.add-missing-headers.bypassHeaders.X-Skip-Headers=true"
  - "traefik.http.middlewares.conditional-headers.plugin.add-missing-headers.bypassHeaders.X-Debug-Mode=enabled"

Header Checking Modes

Strict Mode (strictHeaderCheck: true) - Default

• Only adds headers if they don't exist at all
• Respects explicitly set empty headers
• More precise and safer behavior
• Example: Won't override Content-Type: ""

Loose Mode (strictHeaderCheck: false)

• Adds headers if they don't exist OR are empty
• Will overwrite explicitly empty headers
• More aggressive header replacement
• Example: Will override Content-Type: "" with configured value

Documentation

Overview

Package add_missing_headers provides a Traefik plugin for adding missing HTTP headers.

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Config
  • func CreateConfig() *Config
• type Plugin
  • func (p *Plugin) ServeHTTP(rw http.ResponseWriter, req *http.Request)

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New instantiates and returns the required components used to handle an HTTP request.

Types

type Config

type Config struct {
	RequestHeaders       map[string]string `yaml:"requestHeaders,omitempty"`
	ResponseHeaders      map[string]string `yaml:"responseHeaders,omitempty"`
	DisableExplicitFlush bool              `yaml:"disableExplicitFlush,omitempty"`
	StrictHeaderCheck    bool              `yaml:"strictHeaderCheck,omitempty"`
	BypassHeaders        map[string]string `yaml:"bypassHeaders,omitempty"`
}

Config holds the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin holds the necessary components of a Traefik plugin.

func (*Plugin) ServeHTTP

func (p *Plugin) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.