Skip to content

Update routing-logic.md #691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 28, 2025
Merged

Update routing-logic.md #691

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions docs/routing-logic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,39 @@
## Overview

Trino Gateway checks incoming requests to see if they're related to previous
ones it handled. If they are, then Trino Gateway sends them to the same backend
that dealt with the earlier requests.
ones it handled. If they are, then Trino Gateway sends them to the same
Trino cluster that dealt with the earlier requests.

If it is a new request, the Trino Gateway refers to [Routing rules](routing-rules.md)
to decide which group of backends, called a 'Routing Group,' should handle it.
It then picks a backend from that Routing Group to handle the request using
to decide which group of clusters, called a 'Routing Group,' should handle it.
It then picks a cluster from that Routing Group to handle the request using
either an adaptive or round-robin strategy.

![Request Routing Flow](assets/gateway-routing-flow.svg)

## Sticky routing

A request related to an ongoing process, or to state maintained on a single
backend cluster, must be routed to that backend for proper handling. Two
Trino cluster, must be routed to that cluster for proper handling. Two
mechanisms for identifying related requests are currently implemented. By default,
only routing based on query identifier is enabled.

### Routing based on query identifier (default)

When a query is initiated through the Trino Gateway, the query id will be
extracted from the response and mapped to the backend that provided the
extracted from the response and mapped to the cluster that provided the
response. Any subsequent request containing that query id will be forwarded
to that backend. For example, to retrieve query results, the trino client
to that cluster. For example, to retrieve query results, the Trino client
polls a URI of the form
`v1/statement/executing/queryid/nonce/counter`. The Trino Gateway will extract
the queryid from this URI.

### Routing based on cookies

OAuth2 authentication requires that the same backend is used for each step of
OAuth2 authentication requires that the same cluster is used for each step of
the handshake. When `gatewayCookieConfiguration.enabled` is set to true, a cookie
will be added to requests made to paths beginning with `/oauth2` unless they already have
a cookie present, which is used to route further `/oauth2/*` requests to the correct backend.
a cookie present, which is used to route further `/oauth2/*` requests to the correct cluster.
Cookies are not added to requests to `v1/*` and other Trino endpoints.

Trino Gateway signs its cookies to ensure that they are not tampered with. You
Expand All @@ -54,7 +54,7 @@ the paths used to define the OAuth handshake may be modified.

`routingPaths`: If the request URI starts with a path in this list, then
* If no cookie is present, add a routing cookie
* If a cookie is present, route the request to the backend defined by that cookie
* If a cookie is present, route the request to the cluster defined by that cookie

`deletePaths`: If the request URI starts with a path in this list,
return a response that instructs the client to delete the cookie.
Expand Down