Header transformation plugin for traefik

This plugin allows changing on the fly, the header value of a request.

How to dev

$ docker compose up

How to use

To choose a Rule you have to fill the Type field with one of the following:

• 'Del' : to Delete a header
• 'Join' : to Join values on a header
• 'Rename' : to rename a header
• 'RewriteValueRule': to rewrite header values
• 'Set' : to Set a header

Each Rule can be named with the Name field.

Each Rule can also be configured to change headers on the request or the response by using the SetOnResponse configuration. If SetOnResponse is set to true, the header will be changed on the response. Otherwise, it will be changed on the request. Its default value is false.

Rename

A Rule Rename needs two arguments.

• Header, the regex of the header you want to replace
• Value, the new header

# Example Rename
- Rule:
      Name: 'Header rename'
      Header: 'Cache-Control'
      Value: 'NewHeader'
      Type: 'Rename'

# Old header:
Cache-Control: gzip, deflate

# New header:
NewHeader: gzip, deflate

- Rule:
      Name: 'Header Renaming'
      Header: 'X-Traefik-*'
      Value: 'X-Traefik-merged'
      Type: 'Rename'

# Old header:
X-Traefik-uuid: 0
X-Traefik-date: mer. 21 oct. 2020 11:57:39 CEST
# New header:
X-Traefik-merged: 0 # A value from old headers

Set

A Set rule will either create or replace the header and value (if it already exists)

A rule Set need 2 arguments

• Header, the header you want to create
• Value, the value of the new header

# Example 
- Rule:
      Name: 'Set Cache-Control'
      Header: 'Cache-Control'
      Value: 'Foo'
      Type: 'Set'

# New header:
Cache-Control: Foo

Delete

A rule Delete need one arguments

• Header, the header you want to delete

# Example Del
- Rule:
      Name: 'Delete Cache-Control'
      Header: 'Cache-Control'
      Type: 'Del'

Join

A Join rule will concatenate the values of the existing header with the new one. If the header doesn't exist, it'll do nothing

It needs 3 arguments

• Header, the header you want to join
• Values, a list of values to add to the existing header
• Sep, the separator you want to use

# Example Join
- Rule:
      Name: 'Header join'
      Header: 'Cache-Control'
      Sep: ','
      Values:
        - 'Foo'
        - 'Bar'
      Type: 'Join'

# Old header:
Cache-Control: gzip, deflate

# Joined header:
Cache-Control: gzip, deflate,Foo,Bar

You can reuse other header values in Value or one of the Values by setting an additional argument HeaderPrefix. Example:

# Example Usage
- Rule:
  Name: 'Header set'
  Header: 'X-Forwarded-For'
  HeaderPrefix: "^"
  Sep: ','
  Values:
      - 'Foo'
      - '^CF-Connecting-IP'
  Type: 'Join'

# Old header:
X-Forwarded-For: 1.1.1.1
CF-Connecting-IP: 2.2.2.2
# New headers:
X-Forwarded-For: 1.1.1.1,Foo,2.2.2.2
CF-Connecting-IP: 2.2.2.2

RewriteValue Rule

A RewriteValue Rule will replace all instances of the matching pattern in the values of the headers identified by a matching regex with the provided value. This works for multiple matches within a single header value (e.g., values separated by semicolons).

It needs 2 arguments

• Header, the header or regex identifying the headers you want to change
• Value, the regex pattern to match in the header value
• ValueReplace, the replacement value (can use capture groups like $1)

# Example RewriteValueRule
- Rule:
      Name: 'Header rewriteValue'
      Header: 'Foo'
      Value: 'X-(.*)'
      ValueReplace: 'Y-$1'
      Type: 'RewriteValueRule'

# Old header:
Foo: X-Test

# Modified header:
Foo: Y-Test

Multiple matches in a single header value

# Example RewriteValueRule with multiple matches
- Rule:
      Name: 'Header rewriteValue multiple'
      Header: 'Foo'
      Value: 'X-(\\d+)-(\\w+)'
      ValueReplace: 'Y-$2-$1'
      Type: 'RewriteValueRule'

# Old header:
Foo: X-12-Test;X-34-Prod

# Modified header:
Foo: Y-Test-12;Y-Prod-34

Careful

The rules will be evaluated in the order of definition

#Example
- Rule:
  Name: 'Header addition'
  Header: 'X-Custom-2'
  Value: 'True'
  Type: 'Set'
- Rule:
  Name: 'Header deletion'
  Header: 'X-Custom-2'
  Type: 'Del'
- Rule:
  Name: 'Header join'
  Header: 'X-Custom-2'
  Value: 'False'
  Type: 'Set'

Will set the header X-Custom-2 to 'True', then delete it and set it again but with False

Authors

Tom Moulard	Clément David	Martin Huvelle	Alexandre Bossut-Lasry