Фильтр Transformations#

Фильтр Transformations предназначен для преобразования заголовков при выполнении заданных условий.

Механизм Transformations изначально использовался, в том числе, для обработки CORS запросов. В настоящий момент для этих целей рекомендуется использовать обновленный механизм, описанный в разделе «Работа модуля CORS».

Обязательные параметры:

  • transformations

    Фильтр transformations представляет собой последовательность параметров.

    Тип параметра: последовательность параметров и их значения.

    По умолчанию: не имеет значения по умолчанию.

    Обязательные параметры:

    • conditions

      В значении параметра определяются параметры для проверки, паттерн проверки, метод поиска соответствия и др.

      Обязательно в случае:

      • default is None.

      Т.е. будут использованы условия, описанные в conditions. Если какое-либо условие не описано, то используется значение default.

      Тип параметра: последовательность параметров и их значения.

      По умолчанию: не имеет значения по умолчанию.

      Обязательные параметры:

      • check

      В значении параметра определяется, что необходимо проверять.

      Тип параметра:

      • method;

      • request_header;

      • response_header;

      • remote_ip_address.

      По умолчанию: не имеет значения по умолчанию.

      • name

      В значении параметра определяется имя заголовка для проверки.

      Обязательно в случае:

      • check: request_header;

      • check: response_header.

      Тип параметра: строковое значение.

      По умолчанию: не имеет значения по умолчанию.

      • pattern

      В значении параметра задается regex, определяющий условие соответствия.

      Обязательно в случае:

      • string_match is None.

      Тип параметра: строковое значение.

      По умолчанию: не имеет значения по умолчанию.

      • string_match

      В значении параметра задается альтернативный метод поиска соответствий (алгоритм Ахо-Корасик), использующийся для поиска подстрок в строке, а также полного соответствия строке (white/blacklist’s).

      Важно: Поиск полного соответствия будет производиться только в том случае, если в начале и в конце строки поиска задан символ привязки - „' (см. параметр anchor).

      Обязательно в случае:

      • pattern is None.

      Тип параметра: группа параметров и их значения.

      По умолчанию: не имеет значения по умолчанию.

      Опциональные параметры:

      • anchor

        В значении параметра задается привязку для ограничения строки.

        Корректная работа параметра возможна только в случае использования значения по умолчанию.

        Тип параметра: текстовое значение.

        По умолчанию:

        anchor: '\'

        • file

        В значении параметра указывается путь к файлу со списком строк для осуществления проверки.

        Обязательное в случае:

        • strings is None.

        string_match:
  file: path/to/file.data

        Пример содержимого файла file.data:

        subdomen.com
\exactdomen.com\

        Тип параметра: строковое значение.

        По умолчанию: не имеет значения по умолчанию.

        • strings

        В значении параметра указывается последовательность строк для осуществления проверки.

        Обязательно в случае:

        • file is None.

        strings:
  - \exactdomen.com\
  - subdomen.com

        Тип параметра: последовательность строковых значений.

        По умолчанию: не имеет значения по умолчанию.

      • case_sensitive

      В значении параметра указывается, соответствует ли шаблон строке регистра или нет.

      Тип параметра:

      • true;

      • false.

      По умолчанию: не имеет значения по умолчанию.

      Опциональные параметры:

      • contains

      В значении параметра указывается, содержит ли файл со строками проверочное значение.

      Тип параметра:

      • true;

      • false.

      По умолчанию:

      contains: true

      Пример:

      - conditions:
  - check: method
    pattern: ^POST|GET$
    case_sensitive: false

      • skip_unicode_decoding

      В значении параметра указывается, необходимо ли пропускать шаг декодирования Utf8ToUnicode и Unicode для нормализации кириллических символов.

      Тип параметра:

      • true;

      • false.

      По умолчанию:

      skip_unicode_decoding: false

      Пример:

       - case_sensitive: false
   check: request_header
   name: RqTm
   pattern: ^[0-9T:.\-\x2B]{0,32}$
   skip_unicode_decoding: true

    • default

      В значении параметра указывается набор действий, используемых по умолчанию.

      Значение параметра default должно быть уникальным для фильтра transformations в рамках одного сервиса.

      Обязательно в случае:

      • conditions is None.

      Т.е. будет использовано условие по умолчанию в случае, если действие не описано в conditions.

      # Default action if no conditions matched
- default: true
  actions:
    - action: return
      status_code: 500

      Тип параметра:

      • true;

      • false.

      По умолчанию: не имеет значения по умолчанию.

    • actions

      Тип параметра: последовательность параметров и их значения.

      По умолчанию: не имеет значения по умолчанию.

      Обязательные параметры:

      • action

        В значении параметра определяется, какое действие, из списка доступных, воспроизвести.

        Тип параметра:

        • add_response_header;

        • add_proxy_header;

        • remove_response_header;

        • remove_proxy_header;

        • return.

        По умолчанию: не имеет значения по умолчанию.

        Данные действия не рекомендованы к использованию в SOWA. В качестве альтернативы действий add_response_header, add_proxy_header, remove_response_header, remove_proxy_header рекомендуется использовать параметры set_input_headers/set_output_headers с указанием нужных условий (см. раздел Пaраметр modifiers). Для замены действия return рекомендуется использовать совместно действие ConditionChecker с указанием условий и механизм постобработчика.

      • status_code

        В значении параметра указывается код состояния ответа.

        Обязательно в случае:

        • action: return.

        Тип параметра: целочисленное значение.

        По умолчанию: не имеет значения по умолчанию.

      • name

        В значении параметра указывается заголовок, который необходимо преобразовать.

        Обязательно в случае:

        • action: add_response_header;

        • action: add_proxy_header;

        • action: remove_response_header;

        • action: remove_proxy_header.

        Тип параметра: строковое значение.

        По умолчанию: не имеет значения по умолчанию.

      • value

        В значении параметра указывается имя, которое будет установлено в заголовок, указанный в поле name.

        Обязательно в случае:

        • action: add_response_header;

        • action: add_proxy_header;

        • value_from_header is None;

        • value_from_variable is None.

        Тип параметра: строковое значение.

        По умолчанию: не имеет значения по умолчанию.

      • value_from_header

        В значении параметра задается имя заголовка запроса, значение которого будет установлено в заголовок, указанные в поле name.

        Обязательно в случае:

        • action: add_response_header;

        • action: add_proxy_header;

        • value is None;

        • value_from_variable is None.

        Тип параметра: строковое значение.

        По умолчанию: не имеет значения по умолчанию.

      • value_from_variable

        В значении параметра задается имя переменной, значение которой будет установлено в заголовок, указанный в поле name.

        Обязательно в случае:

        • action: add_response_header;

        • action: add_proxy_header;

        • value is None;

        • value_from_header is None.

        Тип параметра:

        • remote-address — адрес клиента;

        • ngx-x-forwarded-for — поле заголовка запроса клиента “X-Forwarded-For” и добавленная к нему через запятую переменная remote-address. Если же поле “X-Forwarded-For” в заголовке запроса клиента отсутствует, то значением будет являться переменная remote-address.

        По умолчанию: не имеет значения по умолчанию.

      Опциональные параметры:

      • override

        В значении параметра определяется, необходимо ли перезаписать текущее значение заголовка.

        Используется в случае:

        • action: add_response_header;

        • action: add_proxy_header.

        Тип параметра:

        • true;

        • false.

        По умолчанию:

        override: true

        Пример:

        actions:
  - action: add_response_header
    name: Access-Control-Allow-Origin
    value_from_header: Origin

Пример импорта filter_transformations (в примере трансформация полей заголовков осуществляется для первого и третьего сервиса):

service_http_proxy:
  - id: 1
    transformations:
      !include: *profile*_transforms.yml
    
  - id: 2
    
  #  transformations:
  #    !include: *profile*_transforms.yml
    
  - id: 3
    
    transformations:
      !include: *profile*_transforms.yml

Пример конфигурационного файла profile_transforms.yml:

# MAIN request transformations BEGINNING
- conditions: # 1.1 valid Origin header & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 1.2 invalid Origin header due to whitelist & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 1.3 NO Origin header & invalid X-Forwarded-For header due to mask
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.1 valid Origin header & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.2 invalid Origin header due to whitelist & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 2.3 NO Origin header due to whitelist & valid X-Forwarded-For header & client IP not in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_variable: remote-address
- conditions: # 3.1 valid Origin header & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
- conditions: # 3.2 invalid Origin header due to whitelist & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
- conditions: # 3.3 NO Origin header & valid X-Forwarded-For header & client IP in the white list
    - check: method
      pattern: ^POST|GET$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: X-Forwarded-For
      pattern: ^(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])(\.(25[0-5]|2[0-4][0-9]|[0-1][0-9]{2}|[0-9]{2}|[0-9])){3}$
      contains: true
    - check: remote_ip_address
      string_match:
        file: valid-ip.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_proxy_header
      name: X-Forwarded-For
      value_from_header: X-Forwarded-For
# MAIN request transformations END
#
# PREFLIGHT request transformations BEGINNING
- conditions: # valid Origin header
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: true
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 200
- conditions: # invalid Origin header due to whitelist
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
    - check: request_header
      name: Origin # Assumes that Origin header exists
      string_match:
        file: valid-origins.data
      contains: false
  actions:
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 500
- conditions: #  NO Origin header
    - check: method
      pattern: ^OPTIONS$
    - check: request_header
      name: Origin
      pattern: ^$
    - check: request_header
      name: Access-Control-Request-Method
      pattern: ^.+$
  actions:
    - action: add_proxy_header
      name: Origin
      value: ""
    - action: add_response_header
      name: Access-Control-Allow-Headers
      value_from_header: Access-Control-Request-Headers
    - action: add_response_header
      name: Access-Control-Allow-Methods
      value: "POST,GET"
    - action: add_proxy_header
      name: Access-Control-Request-Method
      value: "POST,GET"
    - action: add_response_header
      name: Access-Control-Allow-Origin
      value_from_header: Origin
    - action: add_response_header
      name: Access-Control-Allow-Credentials
      value: "true"
    - action: add_response_header
      name: Access-Control-Max-Age
      value: "600"
    - action: add_response_header
      name: Content-Type
      value: "application/json;charset=UTF8"
    - action: return
      status_code: 500
# PREFLIGHT request transformations END
#
# Default action if no conditions matched
- default: true
  actions:
    - action: return
      status_code: 500