Header transformation plugin for traefik

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

Forked from https://github.com/tomMoulard/htransformation.

How to dev

$ docker compose up

See DEVELOPMENT.md for detailed testing instructions, including streaming verification and how to reproduce the upstream buffering bug.

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.

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 needs one argument:

• Header, the exact header you want to delete — or with a trailing * to delete all headers matching the prefix (e.g. X-Internal-*)

Prefix matching is case-insensitive and uses strings.HasPrefix — no regex.

# Example: delete a single header
- Rule:
      Name: 'Delete Cache-Control'
      Header: 'Cache-Control'
      Type: 'Del'

# Example: delete all headers with a prefix (trailing wildcard)
- Rule:
      Name: 'Strip internal headers'
      Header: 'X-Internal-*'
      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