feat(storage): add support for DirectPath over Interconnect

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageOptions.java

@@ -134,6 +134,8 @@ public final class GrpcStorageOptions extends StorageOptions
   private static final String GCS_SCOPE = "https://www.googleapis.com/auth/devstorage.full_control";
   private static final Set<String> SCOPES = ImmutableSet.of(GCS_SCOPE);
   private static final String DEFAULT_HOST = "https://storage.googleapis.com";
+  private static final String DEFAULT_HOST_NO_SCHEME = "storage.googleapis.com";
+  private static final String DEFAULT_HOST_DIRECT_PATH_NO_SCHEME = "storage-direct.googleapis.com";
   // If true, disable the bound-token-by-default feature for DirectPath.
   private static final boolean DIRECT_PATH_BOUND_TOKEN_DISABLED =
       Boolean.parseBoolean(
@@ -142,6 +144,7 @@ public final class GrpcStorageOptions extends StorageOptions
   private final GrpcRetryAlgorithmManager retryAlgorithmManager;
   private final java.time.Duration terminationAwaitDuration;
   private final boolean attemptDirectPath;
+  private final boolean attemptDirectPathXdsOverInterconnect;
   private final boolean enableGrpcClientMetrics;
 
   private final boolean grpcClientMetricsManuallyEnabled;
@@ -160,6 +163,7 @@ private GrpcStorageOptions(Builder builder, GrpcStorageDefaults serviceDefaults)
             builder.terminationAwaitDuration,
             serviceDefaults.getTerminationAwaitDurationJavaTime());
     this.attemptDirectPath = builder.attemptDirectPath;
+    this.attemptDirectPathXdsOverInterconnect = builder.attemptDirectPathXdsOverInterconnect;
     this.enableGrpcClientMetrics = builder.enableGrpcClientMetrics;
     this.grpcClientMetricsManuallyEnabled = builder.grpcMetricsManuallyEnabled;
     this.grpcInterceptorProvider = builder.grpcInterceptorProvider;
@@ -197,6 +201,23 @@ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundE
     this.openTelemetry = HttpStorageOptions.getDefaultInstance().getOpenTelemetry();
   }
 
+  private static String rewriteHost(String endpoint, String oldHost, String newHost) {
+    String prefix = "";
+    String rest = endpoint;
+    int schemeIndex = endpoint.indexOf("://");
+    if (schemeIndex >= 0) {
+      prefix = endpoint.substring(0, schemeIndex + 3);
+      rest = endpoint.substring(schemeIndex + 3);
+    }
+    if (rest.startsWith(oldHost)) {
+      int len = oldHost.length();
+      if (rest.length() == len || rest.charAt(len) == ':' || rest.charAt(len) == '/') {
+        return prefix + newHost + rest.substring(len);
+      }
+    }
+    return endpoint;
+  }
+
   /**
    * We have to perform several introspections and detections to cross-wire/support several features
    * that are either gapic primitives, ServiceOption primitives or GCS semantic requirements.
@@ -230,6 +251,9 @@ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundE
    */
   private Tuple<StorageSettings, Opts<UserProject>> resolveSettingsAndOpts() throws IOException {
     String endpoint = getHost();
+    if (attemptDirectPathXdsOverInterconnect) {
+      endpoint = rewriteHost(endpoint, DEFAULT_HOST_NO_SCHEME, DEFAULT_HOST_DIRECT_PATH_NO_SCHEME);
+    }
     URI uri = URI.create(endpoint);
     String scheme = uri.getScheme();
     int port = uri.getPort();
@@ -322,7 +346,8 @@ private Tuple<StorageSettings, Opts<UserProject>> resolveSettingsAndOpts() throw
         InstantiatingGrpcChannelProvider.newBuilder()
             .setEndpoint(endpoint)
             .setAllowNonDefaultServiceAccount(true)
-            .setAttemptDirectPath(attemptDirectPath);
+            .setAttemptDirectPath(attemptDirectPath || attemptDirectPathXdsOverInterconnect)
+            .setAttemptDirectPathXdsOverInterconnect(attemptDirectPathXdsOverInterconnect);
 
     if (!DIRECT_PATH_BOUND_TOKEN_DISABLED) {
       channelProviderBuilder.setAllowHardBoundTokenTypes(
@@ -428,6 +453,7 @@ public int hashCode() {
         retryAlgorithmManager,
         terminationAwaitDuration,
         attemptDirectPath,
+        attemptDirectPathXdsOverInterconnect,
         enableGrpcClientMetrics,
         grpcInterceptorProvider,
         blobWriteSessionConfig,
@@ -445,6 +471,7 @@ public boolean equals(Object o) {
     }
     GrpcStorageOptions that = (GrpcStorageOptions) o;
     return attemptDirectPath == that.attemptDirectPath
+        && attemptDirectPathXdsOverInterconnect == that.attemptDirectPathXdsOverInterconnect
         && enableGrpcClientMetrics == that.enableGrpcClientMetrics
         && Objects.equals(retryAlgorithmManager, that.retryAlgorithmManager)
         && Objects.equals(terminationAwaitDuration, that.terminationAwaitDuration)
@@ -494,6 +521,7 @@ public static final class Builder extends StorageOptions.Builder {
     private StorageRetryStrategy storageRetryStrategy;
     private java.time.Duration terminationAwaitDuration;
     private boolean attemptDirectPath = GrpcStorageDefaults.INSTANCE.isAttemptDirectPath();
+    private boolean attemptDirectPathXdsOverInterconnect = false;
     private boolean enableGrpcClientMetrics =
         GrpcStorageDefaults.INSTANCE.isEnableGrpcClientMetrics();
     private GrpcInterceptorProvider grpcInterceptorProvider =
@@ -512,6 +540,7 @@ public static final class Builder extends StorageOptions.Builder {
       this.storageRetryStrategy = gso.getRetryAlgorithmManager().retryStrategy;
       this.terminationAwaitDuration = gso.getTerminationAwaitDuration();
       this.attemptDirectPath = gso.attemptDirectPath;
+      this.attemptDirectPathXdsOverInterconnect = gso.attemptDirectPathXdsOverInterconnect;
       this.enableGrpcClientMetrics = gso.enableGrpcClientMetrics;
       this.grpcInterceptorProvider = gso.grpcInterceptorProvider;
       this.blobWriteSessionConfig = gso.blobWriteSessionConfig;
@@ -556,6 +585,19 @@ public GrpcStorageOptions.Builder setAttemptDirectPath(boolean attemptDirectPath
       return this;
     }
 
+    /**
+     * Option for whether this client should attempt to use DirectPath over Interconnect (on-premise
+     * xDS name resolution).
+     *
+     * @since 2.72.0
+     */
+    @BetaApi
+    public GrpcStorageOptions.Builder setAttemptDirectPathXdsOverInterconnect(
+        boolean attemptDirectPathXdsOverInterconnect) {
+      this.attemptDirectPathXdsOverInterconnect = attemptDirectPathXdsOverInterconnect;
+      return this;
+    }
+
     /**
      * Option for whether this client should emit internal gRPC client internal metrics to Cloud
      * Monitoring. To disable metric reporting, set this to false. True by default. Emitting metrics

java-storage/google-cloud-storage/src/test/java/com/google/cloud/storage/StorageOptionsBuilderTest.java

@@ -69,6 +69,63 @@ public void grpc() throws Exception {
         () -> assertThat(rebuilt.hashCode()).isEqualTo(base.hashCode()));
   }
 
+  @Test
+  public void grpc_attemptDirectPathXdsOverInterconnect() throws Exception {
+    com.google.auth.Credentials mockCreds = com.google.cloud.NoCredentials.getInstance();
+    GrpcStorageOptions options =
+        GrpcStorageOptions.grpc()
+            .setCredentials(mockCreds)
+            .setAttemptDirectPathXdsOverInterconnect(true)
+            .build();
+
+    GrpcStorageOptions rebuilt = options.toBuilder().build();
+    assertAll(
+        () -> assertThat(rebuilt).isEqualTo(options),
+        () -> assertThat(rebuilt.hashCode()).isEqualTo(options.hashCode()));
+
+    com.google.storage.v2.StorageSettings settings = options.getStorageSettings();
+    assertThat(settings.getEndpoint()).isEqualTo("storage-direct.googleapis.com:443");
+
+    com.google.api.gax.rpc.TransportChannelProvider tcp = settings.getTransportChannelProvider();
+    assertThat(tcp).isInstanceOf(com.google.api.gax.grpc.InstantiatingGrpcChannelProvider.class);
+    com.google.api.gax.grpc.InstantiatingGrpcChannelProvider provider =
+        (com.google.api.gax.grpc.InstantiatingGrpcChannelProvider) tcp;
+
+    assertThat(provider.isAttemptDirectPathXdsOverInterconnect()).isTrue();
+    com.google.api.core.ApiFunction<io.grpc.ManagedChannelBuilder, io.grpc.ManagedChannelBuilder>
+        configurator = provider.toBuilder().getChannelConfigurator();
+    if (configurator != null) {
+      io.grpc.ManagedChannelBuilder<?> fakeBuilder =
+          io.grpc.ManagedChannelBuilder.forAddress("foo", 80);
+      io.grpc.ManagedChannelBuilder<?> appliedBuilder = configurator.apply(fakeBuilder);
+      String authority = extractAuthorityFromChannelBuilder(appliedBuilder);
+      assertThat(authority).isNull();
+    }
+  }
+
+  @Test
+  public void grpc_fallbackFromDirectPathXdsOverInterconnect_doesNotOverrideAuthority()
+      throws Exception {
+    GrpcStorageOptions options =
+        GrpcStorageOptions.grpc()
+            .setHost("https://storage.my-universe.com")
+            .setAttemptDirectPathXdsOverInterconnect(true)
+            .setCredentials(com.google.cloud.NoCredentials.getInstance())
+            .build();
+    com.google.api.gax.grpc.InstantiatingGrpcChannelProvider provider =
+        (com.google.api.gax.grpc.InstantiatingGrpcChannelProvider)
+            options.getStorageSettings().getTransportChannelProvider();
+    com.google.api.core.ApiFunction<io.grpc.ManagedChannelBuilder, io.grpc.ManagedChannelBuilder>
+        configurator = provider.toBuilder().getChannelConfigurator();
+    if (configurator != null) {
+      io.grpc.ManagedChannelBuilder<?> fakeBuilder =
+          io.grpc.ManagedChannelBuilder.forAddress("foo", 80);
+      io.grpc.ManagedChannelBuilder<?> appliedBuilder = configurator.apply(fakeBuilder);
+      String authority = extractAuthorityFromChannelBuilder(appliedBuilder);
+      assertThat(authority).isNull();
+    }
+  }
+
   @Test
   public void useJwtAccessWithScope_defaultsToFalse() {
     HttpStorageOptions httpOptions = HttpStorageOptions.http().build();
@@ -90,4 +147,42 @@ public ResultRetryAlgorithm<?> getNonidempotentHandler() {
       return null;
     }
   }
+
+  private static String extractAuthorityFromChannelBuilder(
+      io.grpc.ManagedChannelBuilder<?> channelBuilder) {
+    try {
+      Object current = channelBuilder;
+      while (current != null) {
+        Class<?> clazz = current.getClass();
+        java.lang.reflect.Field field = null;
+        while (clazz != null) {
+          try {
+            field = clazz.getDeclaredField("authority");
+            break;
+          } catch (NoSuchFieldException e) {
+            try {
+              field = clazz.getDeclaredField("overrideAuthority");
+              break;
+            } catch (Exception ignored) {
+            }
+            clazz = clazz.getSuperclass();
+          }
+        }
+        if (field != null) {
+          field.setAccessible(true);
+          return (String) field.get(current);
+        }
+        try {
+          java.lang.reflect.Field delegate = current.getClass().getDeclaredField("delegate");
+          delegate.setAccessible(true);
+          current = delegate.get(current);
+        } catch (Exception e) {
+          break;
+        }
+      }
+      return null;
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
 }

java-storage/google-cloud-storage/src/test/java/com/google/cloud/storage/it/ITGrpcDirectPathTest.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.cloud.storage.it;
+
+import static org.junit.Assume.assumeTrue;
+
+import com.google.cloud.storage.Storage;
+import com.google.cloud.storage.StorageOptions;
+import com.google.cloud.storage.TransportCompatibility.Transport;
+import com.google.cloud.storage.it.runner.StorageITRunner;
+import com.google.cloud.storage.it.runner.annotations.Backend;
+import com.google.cloud.storage.it.runner.annotations.Inject;
+import com.google.cloud.storage.it.runner.annotations.SingleBackend;
+import com.google.cloud.storage.it.runner.annotations.StorageFixture;
+import org.junit.Ignore;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+@RunWith(StorageITRunner.class)
+@SingleBackend(Backend.PROD)
+public final class ITGrpcDirectPathTest {
+
+  @Inject
+  @StorageFixture(Transport.GRPC)
+  public Storage storage;
+
+  @Ignore(
+      "Bypassed because DirectPath over Interconnect (GCI) requires a specialized hybrid network environment (Interconnect and Traffic Director configured for storage-direct) and cannot be validated in standard CI or local workstations.")
+  @Test
+  public void clientShouldWork_directPathXdsOverInterconnect() throws Exception {
+    assumeTrue(
+        "Environment cannot resolve storage-direct.googleapis.com", canResolveDirectPathAddress());
+    StorageOptions options =
+        StorageOptions.grpc()
+            .setCredentials(storage.getOptions().getCredentials())
+            .setAttemptDirectPathXdsOverInterconnect(true)
+            .setEnableGrpcClientMetrics(false)
+            .build();
+    try (Storage client = options.getService()) {
+      client.list(Storage.BucketListOption.pageSize(1));
+    }
+  }
+
+  private static boolean canResolveDirectPathAddress() {
+    try {
+      java.net.InetAddress.getAllByName("storage-direct.googleapis.com");
+      return true;
+    } catch (java.net.UnknownHostException e) {
+      return false;
+    }
+  }
+}

java-storage/google-cloud-storage/src/test/java/com/google/cloud/storage/it/ITStorageOptionsTest.java

@@ -84,6 +84,17 @@ public void clientShouldConstructCleanly_directPath() throws Exception {
     doTest(options);
   }
 
+  @Test
+  public void clientShouldConstructCleanly_directPathXdsOverInterconnect() throws Exception {
+    StorageOptions options =
+        StorageOptions.grpc()
+            .setCredentials(credentials)
+            .setAttemptDirectPathXdsOverInterconnect(true)
+            .setEnableGrpcClientMetrics(false)
+            .build();
+    doTest(options);
+  }
+
   @Test
   public void lackOfProjectIdDoesNotPreventConstruction_http() throws Exception {
     StorageOptions options = StorageOptions.http().setCredentials(credentials).build();

sdk-platform-java/gax-java/gax-grpc/BUILD.bazel

@@ -37,6 +37,7 @@ _COMPILE_DEPS = [
 
 _TEST_COMPILE_DEPS = [
     "@org_junit_jupiter_junit_jupiter_api//jar",
+    "@org_junit_jupiter_junit_jupiter_params//jar",
     "@org_mockito_mockito_core//jar",
     "@org_mockito_mockito_junit_jupiter//jar",
     "@com_google_truth_truth//jar",

sdk-platform-java/gax-java/gax-grpc/pom.xml

@@ -123,6 +123,12 @@
       <version>${junit.version}</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <version>${junit.version}</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>com.google.http-client</groupId>
       <artifactId>google-http-client</artifactId>
@@ -158,7 +164,7 @@
         <artifactId>maven-surefire-plugin</artifactId>
         <configuration>
           <!-- These tests require an Env Var to be set. Use -PenvVarTest to ONLY run these tests -->
-          <test>!InstantiatingGrpcChannelProviderTest#testLogDirectPathMisconfig_AttemptDirectPathNotSetAndAttemptDirectPathXdsSetViaEnv_warns,!InstantiatingGrpcChannelProviderTest#canUseDirectPath_directPathEnvVarNotSet_attemptDirectPathIsTrue,InstantiatingGrpcChannelProviderTest#testLogDirectPathMisconfigWrongCredential</test>
+          <test>!InstantiatingGrpcChannelProviderTest#testLogDirectPathMisconfig_AttemptDirectPathNotSetAndAttemptDirectPathXdsSetViaEnv_warns,!InstantiatingGrpcChannelProviderTest#canUseDirectPath_directPathEnvVarNotSet_attemptDirectPathIsTrue</test>
           <!-- <test>!InstantiatingGrpcChannelProviderTest#testLogDirectPathMisconfig_AttemptDirectPathNotSetAndAttemptDirectPathXdsSetViaEnv_warns</test> -->
         </configuration>
       </plugin>