Фильтры

• Фильтры
  • APIAggregator
    • Конфигурация | Имя | Тип |
    • Результаты
  • Proxy
    • Конфигурация
    • Результаты
  • Bridge
    • Конфигурация
    • Результаты
  • CORSAdaptor
    • Конфигурация
    • Результаты
  • Fallback
    • Конфигурация
    • Результаты
  • Mock
    • Конфигурация
    • Результаты
  • RemoteFilter
    • Конфигурация
    • Результаты
  • RequestAdaptor
    • Конфигурация
    • Результаты
  • CircuitBreaker
    • Конфигурация
    • Результаты
  • RateLimiter
    • Конфикация
    • Результаты
  • TimeLimiter
    • Конфигурация
    • Результаты
  • Retryer
    • Конфигурация
    • Результаты
  • ResponseAdaptor
    • Конфигурация
    • Результаты
  • Validator
    • Конфигурация
    • Результаты
  • WasmHost
    • Конфигурация
    • Результаты

Фильтр — это обработчик запросов и ответов. Несколько фильтров можно объединить в цепочку, при этом каждый фильтр после обработки входного запроса или ответа возвращает строку. Пустой результат означает, что текущий фильтр успешно обработал входные данные и они могут быть переданы следующему фильтру в цепочке. Непустой результат указывает на необходимость дополнительных действий со стороны цепочки фильтров или предыдущего фильтра.

APIAggregator

APIAggregator пересылает один запрос нескольким HTTP-конвейерам API в одном пространстве имён и объединяет ответы.

Ниже приведён пример конфигурации, которая пересылает запрос двум конвейерам: http-pipeline-1 и http-pipeline-2. При пересылке запроса http-pipeline-2 метод запроса изменяется на GET, а новый заголовок Original-Method добавляется с исходным методом запроса. Два ответа объединяются в один перед возвратом клиенту.

kind: APIAggregator
name: api-aggregator-example
mergeResponse: true
pipelines:
- name: http-pipeline-1
- name: http-pipeline-2
  method: GET
  header:
    add:
      Original-Method: "[[filter.api-aggregator-example.req.method]]"
  disableBody: false

Конфигурация

| Имя | Тип | | Описание | Требуется | | -------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | maxBodyBytes | int64 | Верхний предел размера тела запроса, по умолчанию равен 0, что означает отсутствие ограничения | Нет | | partialSucceed | bool | Определяет, будет ли результат исходного запроса считаться успешным при сбое запроса к некоторым из конвейеров API, по умолчанию имеет значение false | Нет | | timeout | string | Длительность тайм-аута для запросов к прокси API | Нет | | mergeResponse | bool | Определяет, будут ли несколько объектов ответа объединены в один, по умолчанию равно false, что означает, что окончательный ответ представляет собой массив ответов от прокси API | Нет | | pipelines | []apiaggregator.Pipeline | Конфигурация прокси API | Да |

Результаты

Прокси

Фильтр «Прокси» является прокси-сервером для внутреннего сервиса.

Ниже представлена одна из самых простых конфигураций прокси, которая перенаправляет запросы на http://127.0.0.1:9095.

kind: Proxy
name: proxy-example-1
mainPool:
  servers:
  - url: http://127.0.0.1:9095

Помимо mainPool, можно также настроить candidatePools, если это так, то прокси сначала проверяет, может ли один из пулов кандидатов обработать запрос. Например, пул кандидатов в следующей конфигурации случайным образом выбирает и обрабатывает 30‰ запросов, а основной пул обрабатывает остальные 970‰ запросов.

kind: Proxy
name: proxy-example-2
mainPool:
  servers:
  - url: http://127.0.0.1:9095
candidatePools:
  - servers:
    - url: http://127.0.0.2:9095
    probability:
      perMill: 30
      policy: random

Серверы пула также могут быть динамически настроены через обнаружение служб, следующая конфигурация получает список серверов через serviceRegistry и serviceName, и выбираются только серверы с тегом v2.

kind: Proxy
name: proxy-example-3
mainPool:
  serverTags: ["v2"]
  serviceName: service-001
  serviceRegistry: eureka-service-registry-example

Когда в пуле несколько серверов, прокси может выполнять балансировку нагрузки между ними:

kind: Proxy
name: proxy-example-4
mainPool:
  serverTags: ["v2"]
  serviceName: service-001
  serviceRegistry: eureka-service-registry-example
  loadBalance:
    policy: roundRobin
    headerHashKey: X-User-Id

Конфигурация

| Имя | Тип | Описание | Требуется | | -------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | Отправлять запрос или получать ответ об ошибке | Нет | | Основной пул | proxy.PoolSpec | Основной пул бэкенд-серверов | Да | | Пулы кандидатов | []proxy.PoolSpec | Одна или несколько конфигураций пулов, похожих на mainPool, но с настроенными параметрами filter. Когда Proxy получает запрос, он сначала проходит через пулы в candidatePools, и если один из пулов фильтрует запрос, серверы этого пула обрабатывают запрос, в противном случае запрос передаётся в mainPool | Нет | | Зеркальный пул | proxy.PoolSpec | Определение зеркального пула, запросы отправляются в этот пул одновременно, когда они отправляются в пулы кандидатов или основной пул | Нет | | Коды ошибок | []int | Необходимо обрабатывать HTTP-коды состояния как ошибки | Нет | | Сжатие | proxy.CompressionSpec | Опции сжатия ответов | Нет |

Результаты

Bridge

Фильтр Bridge перенаправляет запросы из одного конвейера в другие конвейеры или HTTP-прокси под HTTP-сервером.

Входящий фильтр устанавливает целевой конвейер/прокси в заголовке запроса X-Easegress-Bridge-Dest. Bridge извлекает значение заголовка и пытается сопоставить его с конфигурацией. Он отправляет запрос, если совпадение найдено, и прерывает процесс, если совпадения нет. Если в конфигурации фильтра нет заголовка с именем X-Easegress-Bridge-Dest, он выбирает первый пункт назначения.

Ниже приведён пример конфигурации с двумя пунктами назначения.

kind: Bridge
name: bridge-example
destinations: ["pipeline1", "pipeline2"]

Конфигурация

Результаты

CORSAdaptor

CORSAdaptor обрабатывает предварительный запрос CORS для бэкенд-сервиса.

Приведённая ниже конфигурация обрабатывает предварительный GET-запрос от *.megaease.com. Конфигурация

Результаты

Fallback

Фильтр Fallback имитирует ответ в качестве резервного действия других фильтров. Приведённая ниже конфигурация имитирует ответ с указанным кодом состояния, заголовками и телом.

kind: Fallback
name: fallback-example
mockCode: 200
mockHeaders:
  Content-Type: application/json
mockBody: '{"message": "The feature turned off, please try it later."}'

Конфигурация

Results

RateLimiter

RateLimiter защищает бэкенд-сервис для обеспечения высокой доступности и надёжности, ограничивая количество запросов, отправляемых сервису в течение настроенного периода времени.

В приведённой ниже конфигурации запросы GET, POST, PUT, DELETE к пути, который соответствует регулярному выражению ^/pets/\d+$, ограничены 50 запросами за 10 мс, и запрос завершается ошибкой, если он не может быть разрешён в течение 100 мс из-за большого количества одновременных запросов.

kind: RateLimiter
name: rate-limiter-example
policies:
- name: policy-example
  timeoutDuration: 100ms
  limitRefreshPeriod: 10ms
  limitForPeriod: 50
defaultPolicyRef: policy-example
urls:
- methods: [GET, POST, PUT, DELETE]
  url:
    regex: ^/pets/\d+$
  policyRef: policy-example

Configuration

Результаты

TimeLimiter

TimeLimiter ограничивает время запросов, запрос отменяется, если ответ не получен в настроенное время.

Приведённая ниже конфигурация помечает запрос POST к пути /users/1 как тайм-аут, если ответ не будет получен в течение 500 мс.

kind: TimeLimiter
name: time-limiter-example
urls:
- methods: [POST]
  url:
    exact: /users/1
  timeoutDuration: 500ms

Configuration

Примечание: в ответе были сохранены оригинальное форматирование текста и спецсимволы. Политика, применяемая к соответствующим запросам | Да |

Результаты

Retryer

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

Ниже приведён пример конфигурации, которая повторяет запросы GET, POST, PUT и DELETE к путям, начинающимся с /books/, когда код состояния ответа равен 500, 503 или 504, максимальное количество попыток равно 3, а базовая продолжительность ожидания между попытками составляет 500 мс.

kind: Retryer
name: retryer-example
policies:
- name: policy-example
  maxAttempts: 3
  waitDuration: 500ms
  failureStatusCodes: [500, 503, 504]
defaultPolicyRef: policy-example
urls:
- methods: [GET, POST, PUT, DELETE]
  url:
    prefix: /books/
  policyRef: policy-example

Конфигурация

Результаты

Фильтр всегда возвращает результат своего последующего фильтра, и результат последней попытки возвращается, когда есть две или более попытки.

ResponseAdaptor

ResponseAdaptor изменяет исходный ответ в соответствии с конфигурацией перед его возвратом.

Ниже приведена конфигурация, которая добавляет заголовок с именем X-Response-Adaptor со значением response-adaptor-example в ответы.

kind: ResponseAdaptor
name: response-adaptor-example
header:
  add:
    X-Response-Adaptor: response-adaptor-example

Конфигурация

Результаты

Фильтр всегда возвращает пустой результат.

Validator

Validator фильтрует запросы, пересылает действительные и отклоняет недействительные. На данный момент поддерживаются четыре метода проверки (headers, jwt, signature и oauth2), которые можно использовать вместе или по отдельности. Когда используются два или более методов вместе, запрос должен пройти все из них, чтобы быть пересланным.

Ниже представлена конфигурация для метода проверки headers. Запросы, имеющие заголовок с именем Is-Valid со значением abc или goodplan или соответствующие регулярному выражению ^ok-.+$, считаются действительными. Конфигурация

Результаты

WasmHost

Фильтр WasmHost реализует среду хоста для пользовательского кода WebAssembly. Ниже приведён пример конфигурации, которая загружает код wasm из файла, более подробную информацию можно найти в этом документе.

name: wasm-host-example
kind: WasmHost
maxConcurrency: 2
code: /home/megaease/wasm/hello.wasm
timeout: 200ms

Примечание: этот фильтр отключён в стандартной сборке Easegress, его можно включить с помощью команд:

$ make GOTAGS=wasmhost

или

$ go build -tags=wasmhost

Конфигурация

proxy.PoolSpec

proxy.Server

proxy.LoadBalance

| Наименование | Тип | Описание | Требуется | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------- | -------- | | Имя | Тип | Описание | Требуется | | --- | --- | --- | --- | | Load balance policy, допустимые значения: roundRobin, random, weightedRandom, ipHash и headerHash | Да | Политика балансировки нагрузки. Допустимые значения: roundRobin, random, weightedRandom, ipHash и headerHash | Нет | | headerHashKey | строка | Когда политика — headerHash, эта опция является именем заголовка, значение которого используется для расчёта хеша | Нет |

memorycache.Spec

httpfilter.Spec

Если настроены критерии заголовков, запрос фильтруется, если он соответствует как заголовкам, так и URL-адресам. Если критерии заголовков НЕ настроены, используются параметры вероятности.

urlrule.StringMatch

Отношение между exact, prefix и regex — ИЛИ.

urlrule.URLRule

Отношение между методами и URL — И.

resilience.URLRule

Отношение между методами и URL — И.

httpfilter.Probability

proxy.Compression

mock.Rule

circuitbreaker.Policy

ratelimiter.Policy

timelimiter.URLRule

| Имя | Тип | Описание | Требуется | | --- | --- --- | --- --- | --- | | methods | []string | критерии метода HTTP. По умолчанию пустой список означает все методы | Нет | | url | urlrule.StringMatch | критерии соответствия URL | Да | | timeoutDuration | string | длительность тайм-аута для соответствующих запросов. По умолчанию 500 мс | Нет |

retryer.Policy

| Имя | Тип | Описание | Требуется | | --- | --- --- | --- --- | ------ | | name | string | имя политики. Должен быть уникальным в конфигурации Retryer | Да | | countingNetworkError | bool | учёт сетевой ошибки как сбоя или нет. По умолчанию false | Нет | | failureStatusCodes | []int | коды состояния HTTP, которые должны считаться сбоями | Нет | | maxAttempts | int | максимальное количество попыток | Количество попыток (включая начальную). По умолчанию — 3 | Нет | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | Длительность ожидания | строка | Базовая длительность ожидания между попытками. По умолчанию — 500 мс | Нет | | Политика отката | строка | Политика отката для длительности ожидания, может быть EXPONENTIAL или RANDOM, по умолчанию — RANDOM. Если настроено как EXPONENTIAL, базовая длительность ожидания после каждой неудачной попытки становится в 1,5 раза больше | Нет | | Коэффициент рандомизации | float64 | Коэффициент рандомизации для фактической длительности ожидания, число в интервале [0, 1], по умолчанию равен 0. Фактическая длительность ожидания — случайное число в интервале [(базовая длительность ожидания) * (1 - коэффициент рандомизации), (базовая длительность ожидания) * (1 + коэффициент рандомизации)] | Нет |

httpheader.ValueValidator

validator.JWTValidatorSpec

signer.Spec

signer.Literal

| Имя | Тип | Описание | Требуется | |

Примечание: в ответе сохранены оригинальное форматирование текста и спецсимволы. | Область суффикса | Алгоритм имени | Алгоритм значения | Подписанные заголовки | подпись | дата | истекает срок действия | учётные данные | contentSha256 | Префикс ключа подписи | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Строка | Строка | строка | строка | строка | строка | строка | строка | строка | строка | | Последняя часть для построения области учётных данных, по умолчанию — «megaease_request», в Amazon Signature V4 — «aws4_request» | Имя алгоритма запроса в запросе, по умолчанию — X-Me-Algorithm, в Amazon Signature V4 — X-Amz-Algorithm | Заголовок/значение запроса алгоритма для запроса, по умолчанию — ME-HMAC-SHA256, в Amazon Signature V4 — AWS4-HMAC-SHA256 | Заголовок/запрос заголовков подписанных заголовков, по умолчанию — X-Me-SignedHeaders, в Amazon Signature V4 — X-Amz-SignedHeaders | Имя запроса подписи, по умолчанию — X-Me-Signature, в Amazon Signature V4 — X-Amz-Signature | Заголовок/имя запроса времени, по умолчанию — X-Me-Date, в Amazon Signature V4 — X-Amz-Date | Имя запроса срока действия, по умолчанию — X-Me-Expires, в Amazon Signature V4 — X-Amz-Expires | Имя запроса учётных данных, по умолчанию — X-Me-Credential, в Amazon Signature V4 — X-Amz-Credential | Заголовок имени хэша тела/полезной нагрузки, по умолчанию — X-Me-Content-Sha256, в Amazon Signature V4 — X-Amz-Content-Sha256 | Префикс добавляется к секрету ключа доступа при получении ключа подписи, по умолчанию — ME, в Amazon Signature V4 — AWS4 |

validator.OAuth2ValidatorSpec

validator.OAuth2TokenIntrospect

validator.OAuth2JWT