Make externalHeaders optional in external service response

Co-authored-by: Yuya Ebihara <[email protected]>

Author: EdenKik

docs/routing-rules.md

@@ -95,14 +95,26 @@ return a result with the following criteria:
 * Only one group can be returned
 * If errors is not null, then query would route to default routing group adhoc
 
+#### Request headers modification
+
+The external routing service can optionally return an `externalHeaders` map in its response
+to add or modify HTTP headers before the request is forwarded.
+
+This enables dynamic customization of request behavior, such as injecting session properties
+or setting client tags before the request reaches the Trino cluster.
+
 ```json
 {
     "routingGroup": "test-group",
     "errors": [
         "Error1",
         "Error2",
         "Error3"
-    ]
+    ],
+    "externalHeaders": {
+        "x-trino-client-tags": "['etl']",
+        "x-trino-session": "query_max_memory=50GB,optimize_metadata_queries=false"
+    }
 }
 ```
 

gateway-ha/src/main/java/io/trino/gateway/ha/router/schema/ExternalRouterResponse.java

@@ -28,10 +28,10 @@
 public record ExternalRouterResponse(
         @Nullable String routingGroup,
         List<String> errors,
-        Map<String, String> externalHeaders)
+        @Nullable Map<String, String> externalHeaders)
         implements RoutingGroupResponse
 {
     public ExternalRouterResponse {
-        externalHeaders = ImmutableMap.copyOf(externalHeaders);
+        externalHeaders = externalHeaders == null ? ImmutableMap.of() : ImmutableMap.copyOf(externalHeaders);
     }
 }

gateway-ha/src/test/java/io/trino/gateway/ha/router/TestRoutingGroupSelectorExternal.java

@@ -287,6 +287,23 @@ void testHeaderModificationWithErrors()
         assertThat(routingSelectorResponse.externalHeaders().get(headerKey)).isNull();
     }
 
+    @Test
+    void testHeaderModificationWithNoExternalHeaders()
+    {
+        RoutingGroupSelector selector = RoutingGroupSelector.byRoutingExternal(httpClient, provideRoutingRuleExternalConfig(), requestAnalyzerConfig);
+        HttpServletRequest mockRequest = prepareMockRequest();
+        setMockHeaders(mockRequest);
+
+        ExternalRouterResponse mockResponse = new ExternalRouterResponse("test-group", ImmutableList.of(), null);
+
+        when(httpClient.execute(any(), any())).thenReturn(mockResponse);
+
+        RoutingSelectorResponse routingSelectorResponse = selector.findRoutingDestination(mockRequest);
+
+        assertThat(routingSelectorResponse.routingGroup()).isEqualTo("test-group");
+        assertThat(routingSelectorResponse.externalHeaders()).isEmpty();
+    }
+
     @Test
     void testHeaderModificationWithEmptyRoutingGroup()
             throws Exception