Skip to content

Commit

Permalink
Fix broken links, finish copyedits
Browse files Browse the repository at this point in the history 
Signed-off-by: Diana <[email protected]>
  • Loading branch information
@cloudjumpercat
cloudjumpercat committed Nov 17, 2023
1 parent 364cef1 commit 233e529
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 57 deletions.
49 changes: 24 additions & 25 deletions app/_src/gateway/key-concepts/routes/expressions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,29 @@ title: How to Configure Routes using Expressions
content-type: how-to
---

Configuring routes using Expressions allows for more flexibility and performance
when dealing with complex or large sized configurations.
This how-to guide will walk through switching to the Expressions router, and configuring routes with the new expressive domain specific language.
Please be sure to familiar yourself with the [Expressions Language Reference](/gateway/latest/reference/expressions-language/overview/)
before processing through the rest of this guide.
Configuring routes using expressions allows for more flexibility and better performance
when dealing with complex or large configurations.
This how-to guide explains how to switch to the expressions router and how to configure routes with the new expressive domain specific language.
Familiar yourself with the [Expressions Language Reference](/gateway/latest/reference/expressions-language/)
before proceeding through the rest of this guide.

## Prerequisite
## Prerequisites

Edit [kong.conf](/gateway/latest/production/kong-conf/) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}.
> **Note:** Once you enable expressions, the match fields that traditionally exist on the Route object (such as `paths`, `methods`) will no longer
be configurable and you must specify Expressions in the `expression` field. A new field `priority` will be made available
that allows specifying the order of evaluation of configured Expression routes.
Edit the [kong.conf](/gateway/latest/production/kong-conf/) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}.
{:.note}
> **Note:** Once you enable expressions, the match fields that traditionally exist on the route object (such as `paths` and `methods`) will no longer be configurable and you must specify Expressions in the `expression` field. A new field `priority` will be made available that allows specifying the order of evaluation of configured Expression routes.
## Create routes with Expressions
## Create routes with expressions

To create a new Route object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route) like this:
To create a new route object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route):
```sh
curl --request POST \
--url http://localhost:8001/services/example-service/routes \
--form-string expression='http.path == "/mock"'
```

In this example, you associated a new route object with the path `/mock` to the existing service `example-service`.
The Expressions DSL also allows you to create complex router match conditions.
The Expressions DSL also allows you to create complex router match conditions:

```sh
curl --request POST \
Expand All @@ -35,9 +34,9 @@ curl --request POST \
--form-string 'expression=(http.path == "/mock" || net.protocol == "https")'
```

### Create complex routes with Expressions
### Create complex routes with expressions

You can describe complex route objects using operators within a `POST` request.
You can describe complex route objects using operators within a `POST` request:

```sh

Expand All @@ -52,30 +51,30 @@ curl --request POST \
http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")'
```

Please refer to the [Expressions Language Quickstart](/gateway/latest/reference/expressions-language/quickstart/#examples-http) page for common use cases
and how to write Expressions route for them.
See the [expressions language overview](/gateway/latest/reference/expressions-language/) page for common use cases
and how to write expressions routes for them.

For a list of all available language features, see the [Expressions Language References](/gateway/latest/reference/expressions-language/language-references/).
For a list of all available language features, see the [expressions language reference](/gateway/latest/reference/expressions-language/language-references/).

## Matching fields

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

| Field | Type | Available in HTTP Subsystem | Available in Stream Subsystem | Description |
|---------------------------------------|------------|-----------------------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `net.protocol` | `String` | ✅ | ✅ | Protocol of the route. Roughly equivalent to the `protocols` field on the `Route` entity. **Note:** Configured `protocols` on the `Route` entity are always added to the top level of the generated route but additional constraints can be provided by using the `net.prococol` field directly inside the expression. |
| `tls.sni` | `String` | ✅ | ✅ | If the connection is over TLS, the `server_name` extention from the ClientHello packet. |
| `http.method` | `String` | ✅ | ❌ | The method of the incoming HTTP request. (e.g. `"GET"`, `"POST"`) |
| `http.method` | `String` | ✅ | ❌ | The method of the incoming HTTP request. (for example, `"GET"` or `"POST"`) |
| `http.host` | `String` | ✅ | ❌ | The `Host` header of the incoming HTTP request. |
| `http.path` | `String` | ✅ | ❌ | The normalized request path. This field value does **not** contain any query parameters that might exist. |
| `http.headers.<header_name>` | `String[]` | ✅ | ❌ | The value(s) of request header `<header_name>`. **Note:** The header name is always normalized to the underscore and lowercase form, so `Foo-Bar`, `Foo_Bar` and `fOo-BAr` all becomes value of the `http.headers.foo_bar` field. |
| `http.headers.<header_name>` | `String[]` | ✅ | ❌ | The value(s) of request header `<header_name>`. **Note:** The header name is always normalized to the underscore and lowercase form, so `Foo-Bar`, `Foo_Bar`, and `fOo-BAr` all become values of the `http.headers.foo_bar` field. |
| `http.queries.<query_parameter_name>` | `String[]` | ✅ | ❌ | The value(s) of query parameter `<query_parameter_name>`. |
| `net.src.ip` | `IpAddr` | ❌ | ✅ | IP address of the client. |
| `net.src.port` | `Int` | ❌ | ✅ | The port number using by the client to connect. |
| `net.dst.ip` | `IpAddr` | ❌ | ✅ | Listening IP address where Kong accepted the incoming connection. |
| `net.dst.port` | `Int` | ❌ | ✅ | Listening port number where Kong accepted the incoming connection. |
| `net.src.port` | `Int` | ❌ | ✅ | The port number used by the client to connect. |
| `net.dst.ip` | `IpAddr` | ❌ | ✅ | Listening IP address where {{site.base_gateway}} accepted the incoming connection. |
| `net.dst.port` | `Int` | ❌ | ✅ | Listening port number where {{site.base_gateway}} accepted the incoming connection. |

## More information

* [Expressions Language Reference](/gateway/latest/reference/expressions-language/overview/)
* [Expressions Language Reference](/gateway/latest/reference/expressions-language/)
* [Repository for the Expressions router engine](https://github.com/Kong/atc-router)
4 changes: 2 additions & 2 deletions app/_src/gateway/key-concepts/routes/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ to route a request, the latency introduced by {{site.base_gateway}}
can suffer and its CPU usage can increase. In installations with
thousands of routes, replacing regular expression routes by simple
prefix routes can improve throughput and latency of
{{site.base_gateway}}. If regex must be used due to exact
{{site.base_gateway}}. If regex must be used because an exact
path match must be performed, using the [expressions router](expressions)
will significantly improve {{site.base_gateway}}'s performance in this case.

Expand All @@ -119,7 +119,7 @@ Routes can be configured dynamically to rewrite the requested URL to a different

{{site.base_gateway}} can also handle more complex URL rewriting cases by using regular expression capture groups in the route path and the [Request Transformer Advanced](/hub/kong-inc/request-transformer-advanced/) plugin. For example, this can be used when you must replace `/api/<function>/old` with `/new/api/<function>`.

{{site.base_gateway}} 3.0.x or later ships with a new router. The new router can use regex expression capture groups to describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. For more information about how to configure the router using Expressions, see [How to configure Routes using expressions](/gateway/{{page.kong_version}}/key-concepts/routes/expressions/).
{{site.base_gateway}} 3.0.x or later ships with a new router. The new router can use regex expression capture groups to describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. For more information about how to configure the router using Expressions, see [How to configure routes using expressions](/gateway/{{page.kong_version}}/key-concepts/routes/expressions/).

## Plugins for routes

Expand Down
2 changes: 1 addition & 1 deletion app/_src/gateway/reference/expressions-language/language-references.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ This operator is used to check the existence of a string inside another string.
For example, `http.path contains "foo"` will return `true` if `foo` can be found anywhere inside `http.path`.
This will match a `http.path` that looks like `/foo`, `/abc/foo`, or `/xfooy`, for example.

### Type/operator semantics
### Type and operator semantics

Here are the allowed combination of field types and constant types with each operator:

Expand Down
56 changes: 27 additions & 29 deletions app/_src/gateway/reference/expressions-language/performance.md
View file
Original file line number Diff line number Diff line change
@@ -1,60 +1,60 @@
---
title: Performance Optimizations
title: Expressions Performance Optimizations
content-type: reference
---

Performance is critical when it comes to proxying API traffic. Learn how to optimize the
Expressions you write to get the most performance out of the routing engine.
Performance is critical when it comes to proxying API traffic. This guide explains how to optimize the
expressions you write to get the most performance out of the routing engine.

## Number of routes

### Route matching priority order

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

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

Route 1:
Example route 1:
```
expression: http.path == "/very/hot/request/path"
expression: http.path == "/likely/matched/request/path"
priority: 100
```

Route 2:
Example route 2:
```
expression: http.path == "/not/so/hot/request/path"
expression: http.path == "/unlikely/matched/request/path"
priority: 50
```

It is also desirable to reduce the number of `Route` entity created by leveraging the
logical combination capability of the Expressions language.
It's also best to reduce the number of `Route` entities created by leveraging the
logical combination capability of the expressions language.

### Examples
### Combining routes

If multiple routes results in the same `Service` and `Plugin` config being used,
they should be combined into a single Expression `Route` with logical or operator `||`:
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.

Route 1:
Example route 1:
```
service: example-service
expression: http.path == "/hello"
```

Route 2:
Example route 2:
```
service: example-service
expression: http.path == "/world"
```

Could instead be combined as:
These two routes can instead be combined as:

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

which results in less `Route` object created, and better performance.

## Regular expressions usage

Regular expressions (regexes) are powerful tool that can be used to match strings based on
Expand All @@ -63,30 +63,28 @@ evaluate at runtime and hard to optimize. Therefore, there are some common
scenarios where regex usages can be eliminated, resulting in significantly
better matching performance.

### Examples

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

<span style="color:green">**Fast:**</span>
**Faster performance example:**
```
http.path == "/foo/bar"
```

<span style="color:red">**Slow:**</span>
**Slower performance example:**
```
http.path ~ r#"^/foo/bar$"#
```

When performing exact matches with optional slash `/` at the end, it is tempting to write
regexes. However, this is completely unnecessary with the Expressions language:
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.

<span style="color:green">**Fast:**</span>
**Faster performance example:**
```
http.path == "/foo/bar" || http.path == "/foo/bar/"
```

<span style="color:red">**Slow:**</span>
**Slower performance example:**
```
http.path ~ r#"^/foo/?$"#
```

0 comments on commit 233e529

Please sign in to comment.