Documentation

Policies Reference

Customization

Conditions

Express Gateway comes with a core set of conditions. These conditions can be used throughout all policies in Express Gateway. Additional conditions may also be added through Express Gateway plugins.

Action Conditions

Each Policy Action in a pipeline can be gated with a condition specification. Each condition specification is in the format:

Usage

  condition:
    name: condition-name # examples: always; never;
    some-param-1: p1 # if condition requires parameters they are listed here
    some-param-2: p1 #

Full Example

pipelines:
  default:
    apiEndpoints:
      - api
    policies:
      -
        simple-logger: # policy name
          -   # array of Actions optionally gated by a condition
            condition: # this action is executed only if path is exactly /v1
              name: pathExact
              path: /v1
            action:
              message: "V1: ${req.originalUrl}"
          -  # executed only after previous action is completed
            condition: # this action is executed only if path is exactly /v2
              name: pathExact
              path: /v2
            action:
              message: "V2: ${req.originalUrl}"
          -  # executed only after previous two actions are completed
            action: # no condition, always executed
              message: "GENERIC: ${req.method}"
      -
        proxy: # policy name
          -    # array of objects with condition\action properties
            action:
              serviceEndpoint: example

Conditions Reference

pathExact

Matches if the request’s path is equal to path parameter.

  condition:
    name: pathExact
    path: "/foo/bar"

pathMatch

Matches if the request’s path matches the given regular expression parameter.

  condition:
    name: pathMatch
    pattern: "/foo(/bar)?"

method

Matches if the request’s method matches the methods parameter. The parameter can be either a string (e.g. ‘GET’) or an array of such strings.

  condition:
    name: method
    methods: GET

  condition:
    name: method
    methods:
      - GET
      - POST

hostMatch

Matches if the Host header passed with the request matches the parameter. Parameter pattern should be a wildcard\string expression.

  condition:
    name: hostMatch
    pattern: '*.example.com'

expression

Matches execution result of JS code provided in expression property. Code is executed in limited space that has access only to egContext.

    condition:
      name: expression
      expression: "req.url.length>5"
      # will match for for path /long_path
      # will not match /a

See more info about egContext Also check Expression policy

In addition, several Conditions are provided that allow you to create logical combinations of conditions. The parameters to these conditions should be other condition statements:

allOf

Matches only if all of its parameters match.

{
  "condition":{
    "name": "allOf",
      "conditions": [
        {"name":"pathExact", "path": "/foo/bar"},
        { "name":"not",
          "condition":{ "name":"method", "methods": ["POST", "HEAD"]}
        }
      ]
  }
}

condition:
  name: allOf
  conditions:
      -
          name: pathExact
          path: /foo/bar
      -
          name: not
          condition:
              name: method
              methods:
                  - POST
                  - HEAD

The above will match only if the exact request path is “/foo/bar” and the request is not a POST or HEAD.

oneOf

Matches if at least one of its parameters matches.

{
  "condition":{
    "name": "oneOf",
      "conditions": [
        {"name":"pathExact", "path": "/foo/bar"},
        { "name":"not",
          "condition":{ "name":"method", "methods": ["POST", "HEAD"]}
        }
      ]
  }
}

condition:
  name: oneOf
  conditions:
      -
          name: pathExact
          path: /foo/bar
      -
          name: not
          condition:
              name: method
              methods:
                  - POST
                  - HEAD

The above will match if the exact request path is “/foo/bar” or the request is not a POST or HEAD.

not

Invert condition result

condition:
  name: not
    condition: # negates the condition
        name: method
        methods:
            - POST
            - HEAD

Will match only if method is other than POST and HEAD

authenticated

Matches if the current request is authenticated.

condition:
  name: authenticated

anonymous

Matches if the current request is not authenticated.

condition:
  name: anonymous

tlsClientAuthenticated

Matches if the current request came with a valid client certificate

condition:
  name: tlsClientAuthenticated

json-schema

Matches if the current request body came with a payload that passes the specified schema validation

condition:
  name: json-schema
  schema:
    type: object
    properties:
      name:
        type: string
      age:
        type: number
    required:
      - name
      - age

In the example shown above, the request’s body must have a name and age properties, respectively a string and a number and they’re both required.

You can put any valid JSON Schema in it, but it can’t currently resolve references.

Since any JSON is a valid YAML, you can also put a JSON Schema that’s coming from another source:

condition:
  name: json-schema
  schema: {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "age": {
        "type": "number"
      }
    },
    "required": [
      "name",
      "age"
    ]
  }

Best Practice Note

While it is possible to build quite complicated condition tree, huge trees could greatly affect readability of your EG configuration. In such cases it could be better to have multiple api endpoints and pipelines

The following two configs are equivalent, however we believe variant B is easier to read.

Conditions Based Config - Variant A

serviceEndpoints:
  admin: # will be referenced in proxy policy
    url: 'http://admin.com'
  staff: # will be referenced in proxy policy
    url: 'http://staff.com'

apiEndpoints:
  api:
    host: '*'
    paths:
      - /admin
      - /staff

pipelines:
  api:
    apiEndpoints:
      - api
    policies:
      -
        proxy:
          -
            condition:
              name: pathExact
              path: /admin
            action:
              serviceEndpoint: admin # see declaration above
          -
            condition:
              name: pathExact
              path: /staff
            action:
              serviceEndpoint: staff # see declaration above

Conditions Based Config - Variant B

serviceEndpoints:
  admin: # will be referenced in proxy policy
    url: 'http://admin.com'
  staff: # will be referenced in proxy policy
    url: 'http://staff.com'

apiEndpoints:
  admin:
    host: '*'
    paths: /admin
  staff:
    host: '*'
    paths: /staff

pipelines:
  admin:
    apiEndpoints:
      - admin
    policies:
      proxy:
        -   # note: no condition at all
          action:
            name: proxy
            serviceEndpoint: admin
  staff:
    apiEndpoints:
      - staff
    policies:
      -
        proxy:
          -   # note: no condition at all
            action:
              name: proxy
              serviceEndpoint: staff