Implement Strict Routing Semantics for Routing Rules by Peiyingy · Pull Request #804 · trinodb/trino-gateway

Peiyingy · 2025-12-04T03:35:37Z

Description

This PR adds strictRouting flag for routing as proposed in #797.
Routing rules can now support strictRouting: True to force pinning the query to the routing group

When strictRouting = false (default), the routing behavior remains unchanged.
When strictRouting = true, the gateway would not fall back to default clusters if the pinned backend becomes unavailable. Instead, the query should fail immediately with a 404 error.

Testing

mvn clean install
Added new test cases in TestStochasticRoutingManager
Local test to verify the strictRouting flag works

trino> select 1;
Error starting query at http://localhost:8080/v1/statement returned an invalid response: JsonResponse{statusCode=404, headers={content-length=[96], content-type=[text/plain], date=[Thu, 04 Dec 2025 03:45:04 GMT], vary=[Accept-Encoding]}, hasValue=false} [Error: No healthy backends available for routing group 'adhoc1' under strict routing for user 'pye']

clean up code wip add tests

RoeyoOgen · 2025-12-04T12:37:23Z

Just a few remarks:

why "enforceIsolation" and not strictRouting? or noFallback?
does this differ if the routing group is a single cluster rather than a group? - does this clash with your other PR #796?

xkrogen · 2025-12-04T16:21:56Z

why "enforceIsolation" and not strictRouting? or noFallback?

+1 strictRouting is a good name

Peiyingy · 2025-12-04T16:57:46Z

Just a few remarks:

why "enforceIsolation" and not strictRouting? or noFallback?

does this differ if the routing group is a single cluster rather than a group? - does this clash with your other PR #796?

Thanks for the suggesting. I'll change the name to strictRouting
This would also support routing cluster rules. After either of the PR is merged, we just need to rebase the other PR to make sure both strictRouting and cluster routing are supported.

RoeyoOgen · 2025-12-07T07:28:36Z

                .filter(backEnd -> isBackendHealthy(backEnd.getName()))
                .toList();
+        if (strictRouting && backends.isEmpty()) {
+            throw new WebApplicationException(


why WebApplicationException and not IllegalStateException like in IllegalStateException("Number of active backends found zero"))

or maybe a custom Explicit Exception inherited from RouterException?

felicity3786

Let's also update the official doc?

felicity3786 · 2025-12-08T23:13:08Z

                .filter(backEnd -> isBackendHealthy(backEnd.getName()))
                .toList();
+        if (strictRouting && backends.isEmpty()) {
+            throw new WebApplicationException(


We can add a WARN or ERROR with context when the 404 is triggered? Also +1 on maybe making it a NoBackendAvailableException?

oneonestar

It's ambiguous what you mean strictRouting.

There are two fallback logics in routing.

If RoutingGroupSelector failed to select a routing group for a query, fallback to defaultRoutingGroup.

trino-gateway/gateway-ha/src/main/java/io/trino/gateway/ha/handler/RoutingTargetHandler.java

Lines 97 to 99 in eb736ee

    
           String routingGroup = !isNullOrEmpty(routingDestination.routingGroup()) 
        
                   ? routingDestination.routingGroup() 
        
                   : defaultRoutingGroup;

If there are no available active healthy cluster for the selected routing group, fallback to ActiveDefaultBackends (ie. active healthy cluster in defaultRoutingGroup).

trino-gateway/gateway-ha/src/main/java/io/trino/gateway/ha/router/BaseRoutingManager.java

Line 121 in a4159fc

return selectBackend(backends, user).orElseGet(() -> provideDefaultBackendConfiguration(user));

It's not clear which fallback logic (or both) are disabled. If you decided to disable both (currently you only handled 2), please make sure the error messages are clearly distinguishable for these cases. Docs are also required to explain the exact affect of this config.

oneonestar · 2025-12-10T12:57:07Z

                .toList();
+        if (strictRouting && backends.isEmpty()) {
+            throw new WebApplicationException(
+                             Response.status(NOT_FOUND)


Client did nothing wrong and shouldn't receive a 4xx error. We should return a 5XX indicate a server side error, maybe 503 Service Unavailable.

github-actions · 2026-01-27T17:07:32Z

This pull request has gone a while without any activity. Ask for help on #trino-gateway-dev on Trino slack.

github-actions · 2026-02-17T17:21:44Z

Closing this pull request, as it has been stale for six weeks. Feel free to re-open at any time.

oneonestar

I don’t like setting the default value to false when it’s null in multiple places, but it might require heavy refactoring to remove that pattern. I’m okay with it for now, and we can improve it later in another PR.

oneonestar · 2026-02-19T09:36:15Z

                ? routingDestination.routingGroup()
                : defaultRoutingGroup;
-        ProxyBackendConfiguration backendConfiguration = routingManager.provideBackendConfiguration(routingGroup, user);
+        boolean strictRouting = Optional.ofNullable(routingDestination.strictRouting()).orElse(false);


Suggested change

boolean strictRouting = Optional.ofNullable(routingDestination.strictRouting()).orElse(false);

boolean strictRouting = requireNonNullElse(routingDestination.strictRouting(), false);

oneonestar · 2026-02-19T09:37:12Z

 * Response from the external routing service that includes:
 * - routingGroup: The target routing group for the request (optional)
 * - errors: Any errors that occurred during routing
 * - externalHeaders: Headers that can be set in the request


Update comment.

oneonestar · 2026-02-19T09:37:49Z

 * @param priority priority of the routing rule. Higher number represents higher priority. If two rules have same priority then order of execution is not guaranteed.
 * @param actions actions of the routing rule
 * @param condition condition of the routing rule
 */


Update comment.

oneonestar · 2026-02-19T09:40:47Z

+        // When no cluster is found:
+        //   - If strictRouting is false, fall back to the default routing group backend.
+        //   - If strictRouting is true, return a 404 response.


Move the comment to provideBackendConfiguration().
Also, we return 503 now, not 404.

oneonestar · 2026-02-19T09:57:26Z

+        boolean strictRouting = false;
+        for (RoutingRule rule : requireNonNull(rules.get())) {
            if (rule.evaluateCondition(data, state)) {
                log.debug("%s evaluated to true on request: %s", rule, request);
                rule.evaluateAction(result, data, state);
+                strictRouting = rule.isStrictRouting();
            }
-        });
-        return new RoutingSelectorResponse(result.get(RESULTS_ROUTING_GROUP_KEY));
+        }
+        return new RoutingSelectorResponse(result.get(RESULTS_ROUTING_GROUP_KEY), ImmutableMap.of(), strictRouting);


This logic is flawed.
The value of strictRouting is always equal to the last evaluated rule, but the last evaluated rule may not be the one that sets the final routingGroup (e.g., it may only update the state without setting routingGroup).

flag wip

d7fe5fc

clean up code wip add tests

cla-bot Bot added the cla-signed label Dec 4, 2025

Peiyingy marked this pull request as ready for review December 4, 2025 03:57

rename to strictRouting

2810a25

Peiyingy changed the title ~~Implement Stronger Isolation Semantics for Routing Rules~~ Implement Strict Routing Semantics for Routing Rules Dec 4, 2025

update error msg

ac28ac5

kbhatianr reviewed Dec 4, 2025

View reviewed changes

Comment thread gateway-ha/src/main/java/io/trino/gateway/ha/router/BaseRoutingManager.java Outdated

Peiyingy added 3 commits December 4, 2025 17:17

address comment

54d3c37

small fixes

a4159fc

small fixes

eb736ee

RoeyoOgen reviewed Dec 7, 2025

View reviewed changes

felicity3786 reviewed Dec 8, 2025

View reviewed changes

oneonestar reviewed Dec 10, 2025

View reviewed changes

xkrogen mentioned this pull request Dec 15, 2025

[Darft WIP]Add Best-Effort Routing Fallback When All Backends in Default Group Are Unhealthy #810

Closed

github-actions Bot added the stale label Jan 27, 2026

github-actions Bot closed this Feb 17, 2026

Peiyingy reopened this Feb 18, 2026

address comments

88479d8

Peiyingy removed the stale label Feb 19, 2026

mosabua added the stale-ignore Use this label on PRs that should be ignored by the stale bot so they are not flagged or closed. label Feb 19, 2026

oneonestar reviewed Feb 19, 2026

View reviewed changes

address comments

aafb20e

ebyhr removed the stale-ignore Use this label on PRs that should be ignored by the stale bot so they are not flagged or closed. label Mar 13, 2026

	String routingGroup = !isNullOrEmpty(routingDestination.routingGroup())
	? routingDestination.routingGroup()
	: defaultRoutingGroup;

	boolean strictRouting = Optional.ofNullable(routingDestination.strictRouting()).orElse(false);
	boolean strictRouting = requireNonNullElse(routingDestination.strictRouting(), false);

Conversation

Peiyingy commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Uh oh!

RoeyoOgen commented Dec 4, 2025

Uh oh!

xkrogen commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Peiyingy commented Dec 4, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felicity3786 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oneonestar left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jan 27, 2026

Uh oh!

github-actions Bot commented Feb 17, 2026

Uh oh!

oneonestar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

8 participants

Peiyingy commented Dec 4, 2025 •

edited

Loading

xkrogen commented Dec 4, 2025 •

edited

Loading

oneonestar left a comment •

edited

Loading