Expressions router

The expressions router provides a Domain Specific Language (DSL) that allows for complex routing rule definition. The expressions router ensures good runtime matching performance by providing specific routing comparisons such as non-regex equality checks that are not available in the traditional router.

You can do the following with the expressions router:

• Prefix-based path matching
• Regex-based path matching that is less of a performance burden than the traditional router
• Case insensitive path matching
• Match by header value
• Regex captures
• Match by source IP and destination port
• Match by SNI (for TLS Routes)

The plugin condition field also supports expressions, with some differences in options and considerations. See the Conditional expressions for plugins reference for more information.

In your kong.conf file, set router_flavor = expressions and restart your Kong Gateway. Once the router is enabled, you can use the expression parameter when you’re creating a Route to specify the Routes.

At runtime, Kong Gateway builds two separate routers for the HTTP and Stream (TCP, TLS, UDP) subsystem. When a request/connection comes in, Kong Gateway looks at which field your configured Routes require, and supplies the value of these fields to the router execution context.

Routes are inserted into each router with the appropriate priority field set. The priority is a positive integer that defines the order of evaluation of the router. The bigger the priority, the sooner a Route is evaluated. In the case of duplicate priority values between two Routes in the same router, their order of evaluation is undefined. The router is updated incrementally as configured Routes change.

As soon as a Route yields a match, the router stops matching and the matched Route is used to process the current request/connection.

For example, if you have the following three Routes:

• Route A

  expression: http.path ^= "/foo" && http.host == "example.com"
  priority: 100
  

  Copied!
• Route B

  expression: http.path ^= "/foo"
  priority: 50
  

  Copied!
• Route C

  expression: http.path ^= "/"
  priority: 10
  

  Copied!

And you have the following incoming request:

http.path:"/foo/bar"
http.post:"konghq.com"

The router does the following:

1. The router checks Route A first because it has the highest priority. It doesn’t match the incoming request, so the router checks the Route with the next highest priority.
2. Route B has the next highest priority, so the router checks this one second. It matches the request, so the router doesn’t check Route C.

This section explains how to optimize the expressions you write to get the most performance out of the routing engine.

Priority matching

Expressions routes are always evaluated in the descending priority order they were defined. Therefore, it is helpful to put more likely matched routes before (as in, higher priority) less frequently matched routes.

The following examples show how you would prioritize two routes based on if they were likely to be matched or not.

Example route 1:

expression: http.path == "/likely/matched/request/path"
priority: 100

Example route 2:

expression: http.path == "/unlikely/matched/request/path"
priority: 50

It’s also best to reduce the number of Route entities created by leveraging the logical combination capability of the expressions language.

If you find that a Route with lower priority is matched over Routes with higher priority and common routing criteria (for example, same hosts), try setting the route_match_calculation property in kong.conf to strict.

Combining routes

If multiple routes result in the same Service and Plugin config being used, they should be combined into a single expression Route with the || logical or operator. By combining routes into a single expression, this results in fewer Route objects created and better performance.

Example route 1:

service: example-service
expression: http.path == "/hello"

Example route 2:

service: example-service
expression: http.path == "/world"

These two routes can instead be combined as:

service: example-service
expression: http.path == "/hello" || http.path == "/world"

Regular expressions usage

Regular expressions (regexes) are powerful tool that can be used to match strings based on very complex criteria. Unfortunately, this has also made them more expensive to evaluate at runtime and hard to optimize. Therefore, there are some common scenarios where regex usage can be eliminated, resulting in significantly better matching performance.

When performing exact matches (non-prefix matching) of a request path, use the == operator instead of regex.

Faster performance example:

http.path == "/foo/bar"

Slower performance example:

http.path ~ r#"^/foo/bar$"#

When performing exact matches with the / optional slash at the end, it is tempting to write regexes. However, this is completely unnecessary with the expressions language.

Faster performance example:

http.path == "/foo/bar" || http.path == "/foo/bar/"

Slower performance example:

http.path ~ r#"^/foo/?$"#

This reference explains the different configurable entities for the expressions router.

Expressions formatting

Each Route contains one or more predicates combined with logical operators, which Kong Gateway uses to match requests with Routes.

A predicate is the basic unit of expressions code which takes the following form:

http.path ^= "/foo/bar"

This predicate example has the following structure:

• http.path: Field
• ^=: Operator
• "/foo/bar": Constant value

Predicates are made up of smaller units that you can configure:

Field and constant value types

Types define what you can use for a predicate’s field and constant value. Expressions language is strongly typed. Operations are only performed if such an operation makes sense in regard to the actual type of field and constant.

Type conversion at runtime is not supported, either explicitly or implicitly. Types are always known at the time a route is parsed. An error is returned if the operator cannot be performed on the provided field and constant.

The expressions language currently supports the following types:

http.path ~ "/\\d+\\-\\d+"

http.path ~ r#"/\d+\-\d+"#

In addition, the expressions router also supports one composite type, Array. Array types are written as Type[]. For example: String[], Int[]. Currently, arrays can only be present in field values. They are used in case one field could contain multiple values. For example, http.headers.x or http.queries.x.

Matching fields

The following table describes the available matching fields, as well as their associated type when using an expressions-based router.

Operators

An operator defines the desired comparison action to be performed on the field against the provided constant value. The operator always displays in the middle of the predicate, between the field and constant value.

The expressions language supports a rich set of operators that can be performed on various data types.

Allowed type and operator combinations

Depending on the field type, only certain content types and operators are supported.

Notes:

• The ~ operator is described as supporting both String ~ String and String ~ Regex. In reality, Regex constant values can only be written as String on the right hand side. The presence of ~ operators treats the string value as a regex. Even with the ~ operator, String escape rules described previously still apply and it is almost always easier to use raw string literals for the ~ operator.
• The ~ operator does not automatically anchor the regex to the beginning of the input. Meaning http.path ~ r#"/foo/\d"# could match a path like /foo/1 or /some/thing/foo/1. If you want to match from the beginning of the string (anchoring the regex), then you must manually specify it with the ^ meta-character. For example, http.path ~ r#"^/foo/\d"#.
• Operator behavior differs when performing IP address-related comparisons. Different families of address types for the field and constant value will cause the predicate to return the following values:
  • Using == or in: Returns false at runtime.
  • Using not in: Returns true at runtime.

The following tables contain examples of different types of expressions.

HTTP examples

The following expressions can be used to match HTTP requests.

TCP, TLS, and UDP examples

The following expressions can be used to match TCP, TLS, and UDP requests.