Filters

• Proxy
  • Configuration
  • Results
• SimpleHTTPProxy
  • Configuration
  • Results
• WebSocketProxy
  • Configuration
  • Results
• CORSAdaptor
  • Configuration
  • Results
• Fallback
  • Configuration
  • Results
• Mock
  • Configuration
  • Results
• RemoteFilter
  • Configuration
  • Results
• RequestAdaptor
  • Configuration
  • Results
• RequestBuilder
  • Configuration
  • Results
• RateLimiter
  • Configuration
  • Results
• ResponseAdaptor
  • Configuration
  • Results
• ResponseBuilder
  • Configuration
  • Results
• Validator
  • Configuration
  • Results
• WasmHost
  • Configuration
  • Results
• Kafka
  • Configuration
  • Results
• HeaderToJSON
  • Configuration
  • Results
• CertExtractor
  • Configuration
  • Results
• HeaderLookup
  • Configuration
  • Results
• ResultBuilder
  • Configuration
  • Results
• DataBuilder
  • Configuration
  • Results
• OIDCAdaptor
  • Configuration
  • Results
• OPAFilter
  • Configuration
  • Results
• Redirector
  • Configuration
  • Results
• GRPCProxy
  • Configuration
  • Results
• Common Types
  • pathadaptor.Spec
  • pathadaptor.RegexpReplace
  • httpheader.AdaptSpec
  • proxy.ServerPoolSpec
  • proxy.Server
  • proxy.LoadBalanceSpec
  • proxy.StickySessionSpec
  • proxy.HealthCheckSpec
  • proxy.MemoryCacheSpec
  • proxy.RequestMatcherSpec
  • grpcproxy.ServerPoolSpec
  • grpcproxy.RequestMatcherSpec
  • StringMatcher
  • proxy.MethodAndURLMatcher
  • urlrule.URLRule
  • proxy.Compression
  • proxy.MTLS
  • websocketproxy.WebSocketServerPoolSpec
  • mock.Rule
  • mock.MatchRule
  • ratelimiter.Policy
  • httpheader.ValueValidator
  • validator.JWTValidatorSpec
  • validator.BasicAuthValidatorSpec
  • basicAuth.LDAPSpec
  • signer.Spec
  • signer.HeaderHoisting
  • signer.Literal
  • validator.OAuth2ValidatorSpec
  • validator.OAuth2TokenIntrospect
  • validator.OAuth2JWT
  • kafka.Topic
  • headertojson.HeaderMap
  • headerlookup.HeaderSetterSpec
  • requestadaptor.SignerSpec
  • Template Of Builder Filters
    • HTTP Specific

A Filter is a request/response processor. Multiple filters can be orchestrated together to form a pipeline, each filter returns a string result after it finishes processing the input request/response. An empty result means the input was successfully processed by the current filter and can go forward to the next filter in the pipeline, while a non-empty result means the pipeline or preceding filter needs to take extra action.

Proxy

The Proxy filter is a proxy of the backend service.

Below is one of the simplest Proxy configurations, it forward requests to http://127.0.0.1:9095.

kind: Proxy
name: proxy-example-1
pools:
- servers:
  - url: http://127.0.0.1:9095
maxRedirection: 10

Pool without filter is considered the main pool, other pools with filter are considered candidate pools. Proxy first checks if one of the candidate pools can process a request. For example, the first candidate pool in the below configuration selects and processes requests with the header X-Candidate:candidate, the second candidate pool randomly selects and processes 400‰ of requests, and the main pool processes the other 600‰ of requests.

kind: Proxy
name: proxy-example-2
pools:
- servers:
  - url: http://127.0.0.1:9095
  filter:
    headers:
      X-Candidate:
        exact: candidate
- servers:
  - url: http://127.0.0.1:9096
  filter:
    permil: 400 # between 0 and 1000
    policy: random
- servers:
  - url: http://127.0.0.1:9097
maxRedirection: 10

Servers of a pool can also be dynamically configured via service discovery, the below configuration gets a list of servers by serviceRegistry & serviceName, and only servers that have tag v2 are selected.

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

When there are multiple servers in a pool, the Proxy can do a load balance between them:

kind: Proxy
name: proxy-example-4
pools:
- serverTags: ["v2"]
  serviceName: service-001
  serviceRegistry: eureka-service-registry-example
  loadBalance:
    policy: roundRobin
maxRedirection: 10

Configuration

Results

SimpleHTTPProxy

The SimpleHTTPProxy filter is a simplified version of the Proxy filter, unlike Proxy, which are mainly used as reverse proxy, this filter is mainly for forward proxies.

The following example demonstrates a basic configuration for SimpleHTTPProxy. Unlike the Proxy filter, the backend service’s address is not specified in the SimpleHTTPProxy configuration. Instead, the request URL is used directly, allowing for the use of a single SimpleHTTPProxy instance for any backend services.

name: simple-http-proxy
kind: Pipeline
flow:
  - filter: requestBuilder
  - filter: proxy

filters:
  - kind: RequestBuilder
    name: requestBuilder
    template: |
      url: http://127.0.0.1:9095
      method: GET      

  - kind: SimpleHTTPProxy
    name: proxy

Configuration

Results

WebSocketProxy

The WebSocketProxy filter is a proxy of the websocket backend service.

Below is one of the simplest WebSocketProxy configurations, it forwards the websocket connection to ws://127.0.0.1:9095.

kind: WebSocketProxy
name: proxy-example-1
pools:
- servers:
  - url: ws://127.0.0.1:9095

Same as the Proxy filter:

• a filter can be configured on a pool.
• the servers of a pool can be dynamically configured via service discovery.
• When there are multiple servers in a pool, the pool can do a load balance between them.

Note, when routing traffic to a pipeline with a WebSocketProxy, the HTTPServer must set the corresponding clientMaxBodySize to -1, as below:

name: demo-server
kind: HTTPServer
port: 8080
rules:
- paths:
  path: /ws
  clientMaxBodySize: -1          # REQUIRED!
  backend: websocket-pipeline

Configuration

Results

CORSAdaptor

The CORSAdaptor handles the CORS preflight, simple and not so simple request for the backend service.

The below example configuration handles the CORS GET request from *.megaease.com.

kind: CORSAdaptor
name: cors-adaptor-example
allowedOrigins: ["http://*.megaease.com"]
allowedMethods: [GET]

Configuration

Results

Fallback

The Fallback filter mocks a response as the fallback action of other filters. The below example configuration mocks the response with a specified status code, headers, and body.

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

Configuration

Results

Mock

The Mock filter mocks responses according to configured rules, mainly for testing purposes.

Below is an example configuration to mock response for requests to path /users/1 with specified status code, headers, and body, also with a 100ms delay to mock the time for request processing.

kind: Mock
name: mock-example
rules:
- match:
    path: /users/1
  code: 200
  headers:
    Content-Type: application/json
  body: '{"name": "alice", "age": 30}'
  delay: 100ms

Configuration

Results

RemoteFilter

The RemoteFilter is a filter making remote service act as an internal filter. It forwards original request & response information to the remote service and returns a result according to the response of the remote service.

The below example configuration forwards request & response information to http://127.0.0.1:9096/verify.

kind: RemoteFilter
name: remote-filter-example
url: http://127.0.0.1:9096/verify
timeout: 500ms

Configuration

Results

RequestAdaptor

The RequestAdaptor modifies the original request according to configuration.

The example configuration below adds prefix /v3 to the request path.

kind: RequestAdaptor
name: request-adaptor-example
path:
  addPrefix: /v3

The example configuration below removes header X-Version from all GET requests.

kind: RequestAdaptor
name: request-adaptor-example
method: GET
header:
  del: ["X-Version"]

The example configuration below modifies the request path using regular expressions.

kind: RequestAdaptor
name: request-adaptor-example
path:
  regexpReplace:
    regexp: "^/([a-z]+)/([a-z]+)" # groups /$1/$2 for lowercase alphabet
    replace: "/$2/$1" # changes the order of groups

The example configuration below signs the request using the Amazon Signature V4 signing process, with the default configuration of this signing process.

kind: RequestAdaptor
name: request-adaptor-example
path:
  signer:
    for: "aws4"

Configuration

NOTE: template field takes higher priority than the static field with the same name.

Results

RequestBuilder

The RequestBuilder creates a new request from existing requests/responses according to the configuration, and saves the new request into the namespace it is bound.

The example configuration below creates a reference to the request of namespace DEFAULT.

name: requestbuilder-example-1
kind: RequestBuilder
protocol: http
sourceNamespace: DEFAULT

The example configuration below creates an HTTP request with method GET, url http://127.0.0.1:8080, header X-Mock-Header:mock-value, and body this is the body.

name: requestbuilder-example-1
kind: RequestBuilder
protocol: http
template: |
  method: get
  url: http://127.0.0.1:8080
  headers:
    X-Mock-Header:
    - mock-value
  body: "this is the body"  

Configuration

NOTE: sourceNamespace and template are mutually exclusive, you must set one and only one of them.

Results

RateLimiter

RateLimiter protects backend service for high availability and reliability by limiting the number of requests sent to the service in a configured duration.

Below example configuration limits GET, POST, PUT, DELETE requests to path which matches regular expression ^/pets/\d+$ to 50 per 10ms, and a request fails if it cannot be permitted in 100ms due to high concurrency requests count.

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

Results

ResponseAdaptor

The ResponseAdaptor modifies the input response according to the configuration.

Below is an example configuration that adds a header named X-Response-Adaptor with the value response-adaptor-example to the input response.

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

Configuration

NOTE: template field takes higher priority than the static field with the same name.

Results

ResponseBuilder

The ResponseBuilder creates a new response from existing requests/responses according to the configuration, and saves the new response into the namespace it is bound.

The example configuration below creates a reference to the response of namespace DEFAULT.

name: responsebuilder-example-1
kind: ResponseBuilder
protocol: http
sourceNamespace: DEFAULT

The example configuration below creates an HTTP response with status code 200, header X-Mock-Header:mock-value, and body this is the body.

name: responsebuilder-example-1
kind: ResponseBuilder
protocol: http
template: |
  statusCode: 200
  headers:
    X-Mock-Header:
    - mock-value
  body: "this is the body"  

Configuration

NOTE: sourceNamespace and template are mutually exclusive, you must set one and only one of them.

Results

Validator

The Validator filter validates requests, forwards valid ones, and rejects invalid ones. Four validation methods (headers, jwt, signature, oauth2 and basicAuth) are supported up to now, and these methods can either be used together or alone. When two or more methods are used together, a request needs to pass all of them to be forwarded.

Below is an example configuration for the headers validation method. Requests which has a header named Is-Valid with value abc or goodplan or matches regular expression ^ok-.+$ are considered to be valid.

kind: Validator
name: header-validator-example
headers:
  Is-Valid:
    values: ["abc", "goodplan"]
    regexp: "^ok-.+$"

Below is an example configuration for the jwt validation method.

kind: Validator
name: jwt-validator-example
jwt:
  cookieName: auth
  algorithm: HS256
  secret: 6d79736563726574

Below is an example configuration for the signature validation method, note multiple access keys id/secret pairs can be listed in accessKeys, but there’s only one pair here as an example.

kind: Validator
name: signature-validator-example
signature:
  accessKeys:
    AKID: SECRET

Below is an example configuration for the oauth2 validation method which uses a token introspection server for validation.

kind: Validator
name: oauth2-validator-example
oauth2:
  tokenIntrospect:
    endPoint: https://127.0.0.1:8443/auth/realms/test/protocol/openid-connect/token/introspect
    clientId: easegress
    clientSecret: 42620d18-871d-465f-912a-ebcef17ecb82
    insecureTls: false

Here’s an example of basicAuth validation method which uses Apache2 htpasswd formatted encrypted password file for validation.

kind: Validator
name: basicAuth-validator-example
basicAuth:
  mode: "FILE"
  userFile: /etc/apache2/.htpasswd

Configuration

Results

WasmHost

The WasmHost filter implements a host environment for user-developed WebAssembly code. Below is an example configuration that loads wasm code from a file, and more details could be found in this document.

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

Note: this filter is disabled in the default build of Easegress, it can be enabled by:

$ make GOTAGS=wasmhost

or

$ make wasm

Configuration

Results

Kafka

The Kafka filter converts HTTP Requests to Kafka messages and sends them to the Kafka backend. The topic of the Kafka message comes from the HTTP header, if not found, then the default topic will be used. The payload of the Kafka message comes from the body of the HTTP Request.

Below is an example configuration.

kind: Kafka
name: kafka-example
backend: [":9093"]
topic:
  default: kafka-topic
  dynamic:
    header: X-Kafka-Topic

Configuration

Results

HeaderToJSON

The HeaderToJSON converts HTTP headers to JSON and combines it with the HTTP request body. To use this filter, make sure your HTTP Request body is empty or JSON schema.

Below is an example configuration.

kind: HeaderToJSON
name: headertojson-example
headerMap:
  - header: X-User-Name
    json: username
  - header: X-Type
    json: type

Configuration

Results

CertExtractor

CertExtractor extracts a value from requests TLS certificates Subject or Issuer metadata (https://pkg.go.dev/crypto/x509/pkix#Name) and adds the value to headers. Request can contain zero or multiple certificates so the position (first, second, last, etc) of the certificate in the chain is required.

Here’s an example configuration, that adds a new header tls-cert-postalcode, based on the PostalCode of the last TLS certificate’s Subject:

kind: "CertExtractor"
name: "postalcode-extractor"
certIndex: -1 # take last certificate in chain
target: "subject"
field: "PostalCode"
headerKey: "tls-cert-postalcode"

Configuration

Results

The CertExtractor is always success and returns no results.

HeaderLookup

HeaderLookup checks custom data stored in etcd and put them into HTTP header.

Suppose you create a custom data kind of client-info and post a data key client1 with the value:

name: client1
id: 123
kind: vip

Then HeaderLookup with the following configuration adds X-Id:123 and X-Kind:vip to HTTP request header.

name: headerlookup-example-1
kind: HeaderLookup
etcdPrefix: client-info # get custom data kind
headerKey: client1      # get custom data name
headerSetters:
- etcdKey: id           # custom data value of id
  headerKey: X-Id
- etcdKey: kind         # custom data value of kind
  headerKey: X-Kind

You can also use pathRegExp to check different keys for different requests. When pathRegExp is defined, pathRegExp is used with regexp.FindStringSubmatch to identify a group from the path. The first captured group is appended to the etcd key in the following format: {headerKey's value}-{regex group}.

Suppose you create a custom data kind of client-info and post several data:

name: client-abc
id: 123
kind: vip

name: client-def
id: 124
kind: vvip

Then HeaderLookup with the following configuration adds X-Id:123 and X-Kind:vip for requests with path /api/abc, adds X-Id:124 and X-Kind:vvip for requests with path /api/def.

name: headerlookup-example-1
kind: HeaderLookup
etcdPrefix: client-info # get custom data kind
headerKey: client      # get custom data name
pathRegExp: "^/api/([a-z]+)"
headerSetters:
- etcdKey: id           # custom data value of id
  headerKey: X-Id
- etcdKey: kind         # custom data value of kind
  headerKey: X-Kind

Configuration

Results

HeaderLookup has no results.

ResultBuilder

ResultBuilder generates a string, which will be the result of the filter. This filter exists to work with the jumpIf mechanism for conditional jumping.

Currently, the result string can only be result0 - result9, this will be changed in the future to allow arbitrary result string.

For example, we can use the following configuration to check if the request body contains an image field, and forward it to proxy1 or proxy2 conditionally.

name: demo-pipeline
kind: Pipeline
flow:
- filter: resultBuilder
  jumpIf:
    result1: proxy1
    result2: proxy2
- filter: proxy1
- filter: END
- filter: proxy2

filters:
- name: resultBuilder
  kind: ResultBuilder
  template: |
    {{- if .requests.DEFAULT.JSONBody.image}}result1{{else}}result2{{end -}}    

Configuration

Results

DataBuilder

DataBuilder is used to manipulate and store data. The data from the previous filter can be transformed and stored in the context so that the data can be used in subsequent filters.

The example below shows how to use DataBuilder to store the request body in the context.

- name: requestBodyDataBuilder
  kind: DataBuilder
  dataKey: requestBody
  template: |
    {{.requests.DEFAULT.JSONBody | jsonEscape}}    

Configuration

Results

OIDCAdaptor

OpenID Connect(OIDC) is an identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User.

For identity platforms that implement standard OIDC specification like Google Accounts、OKTA、 Auth0、Authing. configure discovery endpoint as below example:

name: demo-pipeline
kind: Pipeline
flow:
  - filter: oidc
    jumpIf: { oidcFiltered: END }
filters:
  - name: oidc
    kind: OIDCAdaptor
    cookieName: oidc-auth-cookie
    clientId: <Your ClientId>
    clientSecret: <Your clientSecret>
    discovery: https://accounts.google.com/.well-known/openid-configuration  #Replace your own discovery
    redirectURI: /oidc/callback

For third platforms that only implement OAuth2.0 like GitHub, users should configure authorizationEndpoint、 tokenEndpoint、userinfoEndpoint at the same time as below example:

name: demo-pipeline
kind: Pipeline
flow:
  - filter: oidc
    jumpIf: { oidcFiltered: END }
filters:
  - name: oidc
    kind: OIDCAdaptor
    cookieName: oidc-auth-cookie
    clientId: <Your ClientId>
    clientSecret: <Your clientSecret>
    authorizationEndpoint: https://github.com/login/oauth/authorize
    tokenEndpoint: https://github.com/login/oauth/access_token
    userinfoEndpoint: https://api.github.com/user
    redirectURI: /oidc/callback

Configuration

Results

After OIDCAdaptor handled, following OIDC related information can be obtained from Easegress HTTP request headers:

• X-User-Info: Base64 encoded OIDC End-User basic profile.
• X-Origin-Request-URL: End-User origin request URL before OpenID Connect or OAuth2.0 flow.
• X-Id-Token: The ID Token returned by OpenID Connect flow.
• X-Access-Token: The AccessToken returned by OpenId Connect or OAuth2.0 flow.

OPAFilter

The Open Policy Agent (OPA) is an open source, general-purpose policy engine that unifies policy enforcement across the stack. It provides a high-level declarative language, which can be used to define and enforce policies in Easegress API Gateway. Currently, there are 160+ built-in operators and functions we can use, for examples net.cidr_contains and contains.

name: demo-pipeline
kind: Pipeline
flow:
  - filter: opa-filter
    jumpIf: { opaDenied: END }
filters:
  - name: opa-filter
    kind: OPAFilter
    defaultStatus: 403
    readBody: true
    includedHeaders: a,b,c
    policy: |
      package http
      default allow = false
      allow {
         input.request.method == "POST"
         input.request.scheme == "https"
         contains(input.request.path, "/")               
         net.cidr_contains("127.0.0.0/24",input.request.realIP)          
      }      

The following table lists input request fields that can be used in an OPA policy to help enforce it.

Configuration

Results

Redirector

The Redirector filter is used to do HTTP redirect. Redirector matches request url, do replacement, and return response with status code of 3xx and put new path in response header with key of Location.

Here a simple example:

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "^/users/([0-9]+)"
  replacement: "http://example.com/display?user=$1"

In this example, request with path /users/123 will redirect to http://example.com/display?user=123.

HTTP/1.1 301 Moved Permanently
Location: http://example.com/display?user=123

More details about spec:

We use ReplaceAllString to do match and replace and put output into response header with key Location. By default, we use URI as input, but you can change input by control parameter of matchPart.

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "^/users/([0-9]+)"
  # by default, value of matchPart is uri, supported values: uri, path, full.
  matchPart: "full" 
  replacement: "http://example.com/display?user=$1"

For request with URL of https://example.com:8080/apis/v1/user?id=1, URI part is /apis/v1/user?id=1, path part is /apis/v1/user and full part is https://example.com:8080/apis/v1/user?id=1.

By default, we return status code of 301 “Moved Permanently”. To return status code of 302 “Found” or other 3xx, change statusCode in yaml.

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "^/users/([0-9]+)"
  # default value of 301, supported values: 301, 302, 303, 304, 307, 308.
  statusCode: 302
  replacement: "http://example.com/display?user=$1"

Following are some common used examples:

1. URI prefix redirect

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "^(.*)$"
  matchPart: "uri"
  replacement: "/prefix$1"

input: https://example.com/path/to/api/?key1=123&key2=456
output: /prefix/path/to/api/?key1=123&key2=456

URI prefix redirect with schema and host:

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "(^.*\/\/)([^\/]*)(.*)$"
  matchPart: "full"
  replacement: "${1}${2}/prefix$3"

input: https://example.com/path/to/api/?key1=123&key2=456
output: https://example.com/prefix/path/to/api/?key1=123&key2=456

2. Domain Redirect

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "(^.*\/\/)([^\/]*)(.*$)"
  matchPart: "full"
  # use ${1} instead of $1 here.
  replacement: "${1}my.com${3}"

input: https://example.com/path/to/api/?key1=123&key2=456
output: https://my.com/path/to/api/?key1=123&key2=456

3. Path Redirect

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "/path/to/(user)\.php\?id=(\d*)"
  matchPart: "uri"
  replacement: "/api/$1/$2"

input: https://example.com/path/to/user.php?id=123
output: /api/user/123

Path redirect with schema and host:

name: demo-pipeline
kind: Pipeline
flow:
- filter: redirector
filters:
- name: redirector
  kind: Redirector
  match: "(^.*\/\/)([^\/]*)/path/to/(user)\.php\?id=(\d*)"
  matchPart: "full"
  replacement: "${1}${2}/api/$3/$4"

input: https://example.com/path/to/user.php?id=123
output: https://example.com/api/user/123

Configuration

Results

GRPCProxy

The GRPCProxy filter is a proxy for gRPC backend service. It supports both unary RPCs and streaming RPCs.

Below is one of the simplest GRPCProxy configurations, it forwards incoming gRPC connections to 127.0.0.1:9095.

name: demo-pipeline
kind: Pipeline

flow:
- filter: proxy

filters:
- name: proxy
  kind: GRPCProxy
  pools:
  - servers:
    - url: http://127.0.0.1:9095

Same as the Proxy filter:

• a filter can be configured on a pool.
• the servers of a pool can be configured dynamically via service discovery.
• when there are multiple servers in a pool, the pool can do a load balance between them.

Because gRPC does not support the http Connect method, it does not support tunneling mode, we provide a new load balancer policy.forward to achieve a similar effect.

Note that each gRPC client establishes a connection with Easegress. However, Easegress may utilize a single connection when forwarding requests from various clients to a gRPC server, due to its use of HTTP2. This action could potentially disrupt some client or server applications. For instance, if the client applications are structured to directly connect to the server, and both the client and server have the ability to request a connection closure, then problems may arise once Easegress is installed between them. If the server wants to close the connection of one client, it closes the shared connection with Easegress, thus affecting other clients.

Configuration

Results

Common Types

pathadaptor.Spec

pathadaptor.RegexpReplace

httpheader.AdaptSpec

Rules to revise request header.

proxy.ServerPoolSpec

proxy.Server

proxy.LoadBalanceSpec

proxy.StickySessionSpec

proxy.HealthCheckSpec

proxy.MemoryCacheSpec

proxy.RequestMatcherSpec

Polices:

• If the policy is empty or general, matcher match requests with headers and urls.
• If the policy is ipHash, the matcher match requests if their IP hash value is less than `permil``.
• If the policy is headerHash, the matcher match requests if their header hash value is less than permil, use the key of headerHashKey.
• If the policy is random, the matcher matches requests with probability permil/1000.

grpcproxy.ServerPoolSpec

grpcproxy.RequestMatcherSpec

Polices:

• If the policy is empty or general, matcher match requests with headers, urls and methods.
• If the policy is ipHash, the matcher match requests if their IP hash value is less than `permil``.
• If the policy is headerHash, the matcher match requests if their header hash value is less than permil, use the key of headerHashKey.
• If the policy is random, the matcher matches requests with probability permil/1000.

StringMatcher

The relationship between exact, prefix, and regex is OR.

proxy.MethodAndURLMatcher

The relationship between methods and url is AND.

urlrule.URLRule

The relationship between methods and url is AND.

proxy.Compression

proxy.MTLS

websocketproxy.WebSocketServerPoolSpec

mock.Rule

mock.MatchRule

ratelimiter.Policy

httpheader.ValueValidator

validator.JWTValidatorSpec

validator.BasicAuthValidatorSpec

basicAuth.LDAPSpec

signer.Spec

signer.HeaderHoisting

signer.Literal

validator.OAuth2ValidatorSpec

validator.OAuth2TokenIntrospect

validator.OAuth2JWT

kafka.Topic

headertojson.HeaderMap

headerlookup.HeaderSetterSpec

requestadaptor.SignerSpec

This type is derived from signer.Spec, with the following two more fields.

Template Of Builder Filters

The content of the template field in the builder filters’ spec is a a template defined in Golang text/template, with extra functions from the sprig package, and extra functions defined by Easegress:

• addf: calculate the sum of the input two numbers.
• subf: calculate the difference of the two input numbers.
• mulf: calculate the product of the two input numbers.
• divf: calculate the quotient of the two input numbers.
• log: write a log message to Easegress log, the first argument must be debug, info, warn or error, and the second argument is the message.
• mergeObject: merge two or more objects into one, the type of the input objects must be map[string]interface{}, and if one of their field is also an object, its type must also be map[string]interface{}.
• jsonEscape: escape a string so that it can be used as the key or value in JSON text.

Easegress injects existing requests/responses of the current context into the template engine at runtime, so we can use .requests.<namespace>.<field> or .responses.<namespace>.<field> to read the information out (the available fields vary from the protocol of the request or response, and please refer Pipeline for what is namespace). For example, if the request of the DEFAULT namespace is an HTTP one, we can access its method via .requests.DEFAULT.Method.

Easegress also injects other data into the template engine, which can be accessed with .data.<name>, for example, we can use .data.PIPELINE to read the data defined in the pipeline spec.

The template should generate a string in YAML format, the schema of the result YAML varies from filters and protocols.

HTTP Specific

• Available fields of existing requests

  All exported fields of the http.Request. And RawBody is the body as bytes; Body is the body as string; JSONBody is the body as a JSON object; YAMLBody is the body as a YAML object.

• Available fields of existing responses

  All exported fields of the http.Response. And RawBody is the body as bytes; Body is the body as string; JSONBody is the body as a JSON object; YAMLBody is the body as a YAML object.

• Schema of result request

  Name	Type	Description	Required
  method	string	HTTP Method of the result request, default is GET.	No
  url	string	URL of the result request, default is /.	No
  headers	map[string][]string	Headers of the result request.	No
  body	string	Body of the result request.	No
  formData	map[string]field	Body of the result request, in form data pattern.	No

  Please note body takes higher priority than formData, and the schema of field in formData is:

  Name	Type	Description	Required
  value	string	value of the field.	No
  fileName	string	the file name, if value is the content of a file.	No

• Schema of result response

  Name	Type	Description	Required
  statusCode	int	HTTP status code, default is 200.	No
  headers	map[string][]string	Headers of the result request.	No
  body	string	Body of the result request.	No

• Schema of RequestAdaptor

• Schema of ResponseAdaptor