Add external routing group selector

Author: Chaho12

docs/routing-rules.md

@@ -6,13 +6,82 @@ By default, Trino Gateway reads the `X-Trino-Routing-Group` request header to
 route requests. If this header is not specified, requests are sent to default
 routing group (adhoc).
 
-The routing rules engine feature enables you to write custom logic to route
+The routing rules engine feature enables you to either write custom logic to route
 requests based on the request info such as any of the [request
-headers](https://trino.io/docs/current/develop/client-protocol.html#client-request-headers).
+headers](https://trino.io/docs/current/develop/client-protocol.html#client-request-headers),
+or set a URL address to make an HTTP POST request and route based on the returned result.
+
 Routing rules are separated from Trino Gateway application code to a
-configuration file, allowing for dynamic rule changes.
+configuration file or a separate service. This separate service is specified as a URL
+and can implement any dynamic rule changes or other behavior.
+
+### Enabling the routing rules engine
+
+To enable the routing rules engine, find the following lines in `gateway-ha-config.yml`.
 
-### Defining your routing rules
+* Set `rulesEngineEnabled` to `true`, then `rulesType` as `FILE` or `EXTERNAL`.
+* Then either add `rulesConfigPath` to the path to your rules config file or set `rulesExternalConfiguration`
+  to the URL of an external service for routing rules processing.
+  *`rulesType` is by default `FILE` unless specified.
+
+```yaml
+routingRules:
+    rulesEngineEnabled: true
+    rulesType: FILE
+    rulesConfigPath: "app/config/routing_rules.yml" # replace with actual path to your rules config file
+    rulesExternalConfiguration:
+        urlPath: https://router.example.com/gateway-rules # replace with your own API path
+        blacklistHeaders:
+            - 'Authorization'
+```
+
+* Redirect URLs are not supported
+* Optionally add headers to the `BlacklistHeaders` list to exclude requests with corresponding header values
+  from being sent in the POST request.
+
+If there is error parsing the routing rules configuration file, an error is logged,
+and requests are routed using the routing group header `X-Trino-Routing-Group` as default.
+
+### Use an external service for routing rules
+
+You can use an external service for processing your routing by setting the
+`rulesType` to `EXTERNAL` and configuring the `rulesExternalConfiguration`.
+
+Trino Gateway then sends all headers as a map in the body of a POST request to the external service.
+Headers specified in `blacklistHeaders` are excluded. If `requestAnalyzerConfig.isAnalyzeRequest` is set to `true`, 
+`TrinoRequestUser` and `TrinoQueryProperties` are also included. 
+
+Additionally, the following HTTP information is included:
+
+- `remoteUser`
+- `method`
+- `requestURI`
+- `queryString`
+- `session`
+- `remoteAddr`
+- `remoteHost`
+- `parameterMap`
+
+The external service can process the information in any way desired 
+and must return a result with the following criteria:
+
+* Response status code of OK (200)
+* Message in JSON format
+* Only one group can be returned
+* If errors is not null, then query would route to default routing group adhoc 
+
+```json
+{
+    "routingGroup": "test-group",
+    "errors": [
+        "Error1",
+        "Error2",
+        "Error3"
+    ]
+}
+```
+
+### Configure routing rules with a file
 
 To express and fire routing rules, we use the
 [easy-rules](https://github.com/j-easy/easy-rules) engine. These rules should be
@@ -354,18 +423,3 @@ actions:
       result.put(\"routingGroup\", \"etl\")
     }"
 ```
-
-### Enabling routing rules engine
-
-To enable routing rules engine, find the following lines in
-`gateway-ha-config.yml`. Set `rulesEngineEnabled` to True and `rulesConfigPath`
-to the path to your rules config file.
-
-```
-routingRules:
-  rulesEngineEnabled: true
-  rulesConfigPath: "src/test/resources/rules/routing_rules.yml" # replace with path to your rules config file
-```
-
-If there is error opening routing rules configuration file, then request is routed
-using routing group header `X-Trino-Routing-Group` as default.

gateway-ha/src/main/java/io/trino/gateway/ha/config/RoutingRulesConfiguration.java

@@ -16,7 +16,9 @@
 public class RoutingRulesConfiguration
 {
     private boolean rulesEngineEnabled;
+    private RulesType rulesType = RulesType.FILE;
     private String rulesConfigPath;
+    private RulesExternalConfiguration rulesExternalConfiguration;
 
     public RoutingRulesConfiguration() {}
 
@@ -30,6 +32,16 @@ public void setRulesEngineEnabled(boolean rulesEngineEnabled)
         this.rulesEngineEnabled = rulesEngineEnabled;
     }
 
+    public RulesType getRulesType()
+    {
+        return rulesType;
+    }
+
+    public void setRulesType(RulesType rulesType)
+    {
+        this.rulesType = rulesType;
+    }
+
     public String getRulesConfigPath()
     {
         return this.rulesConfigPath;
@@ -39,4 +51,14 @@ public void setRulesConfigPath(String rulesConfigPath)
     {
         this.rulesConfigPath = rulesConfigPath;
     }
+
+    public RulesExternalConfiguration getRulesExternalConfiguration()
+    {
+        return this.rulesExternalConfiguration;
+    }
+
+    public void setRulesExternalConfiguration(RulesExternalConfiguration rulesExternalConfiguration)
+    {
+        this.rulesExternalConfiguration = rulesExternalConfiguration;
+    }
 }

gateway-ha/src/main/java/io/trino/gateway/ha/config/RulesExternalConfiguration.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.trino.gateway.ha.config;
+
+import java.util.List;
+
+public class RulesExternalConfiguration
+{
+    private String urlPath;
+    private List<String> blackListHeaders;
+
+    public String getUrlPath()
+    {
+        return urlPath;
+    }
+
+    public void setUrlPath(String urlPath)
+    {
+        this.urlPath = urlPath;
+    }
+
+    public List<String> getBlackListHeaders()
+    {
+        return this.blackListHeaders;
+    }
+
+    public void setBlackListHeaders(List<String> blackListHeaders)
+    {
+        this.blackListHeaders = blackListHeaders;
+    }
+}

gateway-ha/src/main/java/io/trino/gateway/ha/config/RulesType.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.trino.gateway.ha.config;
+
+/**
+ * Specifies the sources of routing rules in the Trino Gateway's routing rules engine.
+ *
+ * <p>By default, requests are routed based on the `X-Trino-Routing-Group` header,
+ * or to the default routing group (adhoc) if the header is absent.</p>
+ *
+ * <p>Routing rules can be defined in two ways:</p>
+ * <ul>
+ *   <li><strong>FILE:</strong> Rules are specified in a configuration file.</li>
+ *   <li><strong>EXTERNAL:</strong> Rules are fetched from an external service via an HTTP POST request.</li>
+ * </ul>
+ */
+public enum RulesType
+{
+    /**
+     * Routing rules defined in a configuration file.
+     */
+    FILE,
+
+    /**
+     * Routing rules obtained from an external service.
+     * The service URL can implement dynamic rule changes.
+     */
+    EXTERNAL,
+}

gateway-ha/src/main/java/io/trino/gateway/ha/module/HaGatewayProviderModule.java

@@ -23,6 +23,7 @@
 import io.trino.gateway.ha.config.HaGatewayConfiguration;
 import io.trino.gateway.ha.config.OAuth2GatewayCookieConfigurationPropertiesProvider;
 import io.trino.gateway.ha.config.RoutingRulesConfiguration;
+import io.trino.gateway.ha.config.RulesExternalConfiguration;
 import io.trino.gateway.ha.config.UserConfiguration;
 import io.trino.gateway.ha.handler.RoutingTargetHandler;
 import io.trino.gateway.ha.router.BackendStateManager;
@@ -181,8 +182,21 @@ public RoutingGroupSelector getRoutingGroupSelector()
     {
         RoutingRulesConfiguration routingRulesConfig = configuration.getRoutingRules();
         if (routingRulesConfig.isRulesEngineEnabled()) {
-            String rulesConfigPath = routingRulesConfig.getRulesConfigPath();
-            return RoutingGroupSelector.byRoutingRulesEngine(rulesConfigPath, configuration.getRequestAnalyzerConfig());
+            try {
+                return switch (routingRulesConfig.getRulesType()) {
+                    case FILE -> {
+                        String rulesConfigPath = routingRulesConfig.getRulesConfigPath();
+                        yield RoutingGroupSelector.byRoutingRulesEngine(rulesConfigPath, configuration.getRequestAnalyzerConfig());
+                    }
+                    case EXTERNAL -> {
+                        RulesExternalConfiguration rulesExternalConfiguration = routingRulesConfig.getRulesExternalConfiguration();
+                        yield RoutingGroupSelector.byRoutingExternal(rulesExternalConfiguration, configuration.getRequestAnalyzerConfig());
+                    }
+                };
+            }
+            catch (Exception e) {
+                return RoutingGroupSelector.byRoutingGroupHeader();
+            }
         }
         return RoutingGroupSelector.byRoutingGroupHeader();
     }