Implement Strict Routing Semantics for Routing Rules

[Peiyingy]

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']

[RoeyoOgen]

Just a few remarks:

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

[xkrogen]

why "enforceIsolation" and not strictRouting? or noFallback?

+1 strictRouting is a good name

[Peiyingy]

Just a few remarks:

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

1. Thanks for the suggesting. I'll change the name to strictRouting
2. 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.

[kbhatianr]

This may be a nitpick, but evaluating strictRouting first can short circuit the backends.isEmpty() one, in case it's false. A teeny performance optimization would be to re-order these so it's if (strictRouting && backends.isEmpty())

[RoeyoOgen]

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]

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.

1. 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;

2. 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]

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.