feat: add connection property for gRPC interceptor provider (#4149)

* feat: add connection property for gRPC interceptor provider

Add a connection property for setting a gRPC interceptor provider to use for connections.
This allows JDBC and PGAdapter users to set a gRPC interceptor that should be used for
the underlying Spanner client.

This property is a guarded property, as it dynamically invokes the constructor of the
class that is specified in the connection URL. A user must set the Java System property
ENABLE_GRPC_INTERCEPTOR_PROVIDER=true when using this connection property. It should
only be enabled in applications where an untrusted user cannot modify the connection URL
that is being used, as that would allow an untrusted user to dynamically invoke code on
the application host.

* chore: generate libraries at Wed Oct  8 08:52:47 UTC 2025

---------

Co-authored-by: cloud-java-bot <cloud-java-bot@google.com>

Author: olavloite

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ClientSideStatementValueConverters.java

@@ -20,6 +20,7 @@
 import static com.google.cloud.spanner.connection.ReadOnlyStalenessUtil.toChronoUnit;
 
 import com.google.api.gax.core.CredentialsProvider;
+import com.google.api.gax.grpc.GrpcInterceptorProvider;
 import com.google.cloud.spanner.Dialect;
 import com.google.cloud.spanner.ErrorCode;
 import com.google.cloud.spanner.Options.RpcPriority;
@@ -827,6 +828,54 @@ public CredentialsProvider convert(String credentialsProviderName) {
     }
   }
 
+  static class GrpcInterceptorProviderConverter
+      implements ClientSideStatementValueConverter<GrpcInterceptorProvider> {
+    static final GrpcInterceptorProviderConverter INSTANCE = new GrpcInterceptorProviderConverter();
+
+    private GrpcInterceptorProviderConverter() {}
+
+    @Override
+    public Class<GrpcInterceptorProvider> getParameterClass() {
+      return GrpcInterceptorProvider.class;
+    }
+
+    @Override
+    public GrpcInterceptorProvider convert(String interceptorProviderName) {
+      if (!Strings.isNullOrEmpty(interceptorProviderName)) {
+        try {
+          Class<? extends GrpcInterceptorProvider> clazz =
+              (Class<? extends GrpcInterceptorProvider>) Class.forName(interceptorProviderName);
+          Constructor<? extends GrpcInterceptorProvider> constructor =
+              clazz.getDeclaredConstructor();
+          return constructor.newInstance();
+        } catch (ClassNotFoundException classNotFoundException) {
+          throw SpannerExceptionFactory.newSpannerException(
+              ErrorCode.INVALID_ARGUMENT,
+              "Unknown or invalid GrpcInterceptorProvider class name: " + interceptorProviderName,
+              classNotFoundException);
+        } catch (NoSuchMethodException noSuchMethodException) {
+          throw SpannerExceptionFactory.newSpannerException(
+              ErrorCode.INVALID_ARGUMENT,
+              "GrpcInterceptorProvider "
+                  + interceptorProviderName
+                  + " does not have a public no-arg constructor.",
+              noSuchMethodException);
+        } catch (InvocationTargetException
+            | InstantiationException
+            | IllegalAccessException exception) {
+          throw SpannerExceptionFactory.newSpannerException(
+              ErrorCode.INVALID_ARGUMENT,
+              "Failed to create an instance of "
+                  + interceptorProviderName
+                  + ": "
+                  + exception.getMessage(),
+              exception);
+        }
+      }
+      return null;
+    }
+  }
+
   /** Converter for converting strings to {@link Dialect} values. */
   static class DialectConverter implements ClientSideStatementValueConverter<Dialect> {
     static final DialectConverter INSTANCE = new DialectConverter();

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionOptions.java

@@ -33,6 +33,7 @@
 import static com.google.cloud.spanner.connection.ConnectionProperties.ENABLE_EXTENDED_TRACING;
 import static com.google.cloud.spanner.connection.ConnectionProperties.ENCODED_CREDENTIALS;
 import static com.google.cloud.spanner.connection.ConnectionProperties.ENDPOINT;
+import static com.google.cloud.spanner.connection.ConnectionProperties.GRPC_INTERCEPTOR_PROVIDER;
 import static com.google.cloud.spanner.connection.ConnectionProperties.IS_EXPERIMENTAL_HOST;
 import static com.google.cloud.spanner.connection.ConnectionProperties.LENIENT;
 import static com.google.cloud.spanner.connection.ConnectionProperties.MAX_COMMIT_DELAY;
@@ -59,6 +60,7 @@
 
 import com.google.api.core.InternalApi;
 import com.google.api.gax.core.CredentialsProvider;
+import com.google.api.gax.grpc.GrpcInterceptorProvider;
 import com.google.api.gax.rpc.TransportChannelProvider;
 import com.google.auth.Credentials;
 import com.google.auth.oauth2.AccessToken;
@@ -75,6 +77,7 @@
 import com.google.cloud.spanner.SpannerException;
 import com.google.cloud.spanner.SpannerExceptionFactory;
 import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.connection.ClientSideStatementValueConverters.GrpcInterceptorProviderConverter;
 import com.google.cloud.spanner.connection.StatementExecutor.StatementExecutorType;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
@@ -256,6 +259,9 @@ public class ConnectionOptions {
 
   public static final String ENABLE_CHANNEL_PROVIDER_SYSTEM_PROPERTY = "ENABLE_CHANNEL_PROVIDER";
 
+  public static final String ENABLE_GRPC_INTERCEPTOR_PROVIDER_SYSTEM_PROPERTY =
+      "ENABLE_GRPC_INTERCEPTOR_PROVIDER";
+
   /** Custom user agent string is only for other Google libraries. */
   static final String USER_AGENT_PROPERTY_NAME = "userAgent";
 
@@ -656,19 +662,6 @@ private ConnectionOptions(Builder builder) {
     // Create the initial connection state from the parsed properties in the connection URL.
     this.initialConnectionState = new ConnectionState(connectionPropertyValues);
 
-    // Check that at most one of credentials location, encoded credentials, credentials provider and
-    // OUAuth token has been specified in the connection URI.
-    Preconditions.checkArgument(
-        Stream.of(
-                    getInitialConnectionPropertyValue(CREDENTIALS_URL),
-                    getInitialConnectionPropertyValue(ENCODED_CREDENTIALS),
-                    getInitialConnectionPropertyValue(CREDENTIALS_PROVIDER),
-                    getInitialConnectionPropertyValue(OAUTH_TOKEN))
-                .filter(Objects::nonNull)
-                .count()
-            <= 1,
-        "Specify only one of credentialsUrl, encodedCredentials, credentialsProvider and OAuth"
-            + " token");
     checkGuardedProperty(
         getInitialConnectionPropertyValue(ENCODED_CREDENTIALS),
         ENABLE_ENCODED_CREDENTIALS_SYSTEM_PROPERTY,
@@ -683,6 +676,23 @@ private ConnectionOptions(Builder builder) {
         getInitialConnectionPropertyValue(CHANNEL_PROVIDER),
         ENABLE_CHANNEL_PROVIDER_SYSTEM_PROPERTY,
         CHANNEL_PROVIDER_PROPERTY_NAME);
+    checkGuardedProperty(
+        getInitialConnectionPropertyValue(GRPC_INTERCEPTOR_PROVIDER),
+        ENABLE_GRPC_INTERCEPTOR_PROVIDER_SYSTEM_PROPERTY,
+        GRPC_INTERCEPTOR_PROVIDER.getName());
+    // Check that at most one of credentials location, encoded credentials, credentials provider and
+    // OUAuth token has been specified in the connection URI.
+    Preconditions.checkArgument(
+        Stream.of(
+                    getInitialConnectionPropertyValue(CREDENTIALS_URL),
+                    getInitialConnectionPropertyValue(ENCODED_CREDENTIALS),
+                    getInitialConnectionPropertyValue(CREDENTIALS_PROVIDER),
+                    getInitialConnectionPropertyValue(OAUTH_TOKEN))
+                .filter(Objects::nonNull)
+                .count()
+            <= 1,
+        "Specify only one of credentialsUrl, encodedCredentials, credentialsProvider and OAuth"
+            + " token");
 
     boolean usePlainText =
         getInitialConnectionPropertyValue(AUTO_CONFIG_EMULATOR)
@@ -999,6 +1009,19 @@ public TransportChannelProvider getChannelProvider() {
     }
   }
 
+  String getGrpcInterceptorProviderName() {
+    return getInitialConnectionPropertyValue(GRPC_INTERCEPTOR_PROVIDER);
+  }
+
+  /** Returns the gRPC interceptor provider that has been configured. */
+  public GrpcInterceptorProvider getGrpcInterceptorProvider() {
+    String interceptorProvider = getInitialConnectionPropertyValue(GRPC_INTERCEPTOR_PROVIDER);
+    if (interceptorProvider == null) {
+      return null;
+    }
+    return GrpcInterceptorProviderConverter.INSTANCE.convert(interceptorProvider);
+  }
+
   /**
    * The database role that is used for this connection. Assigning a role to a connection can be
    * used to for example restrict the access of a connection to a specific set of tables.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionProperties.java

@@ -75,6 +75,7 @@
 import static com.google.cloud.spanner.connection.ConnectionOptions.ENABLE_API_TRACING_PROPERTY_NAME;
 import static com.google.cloud.spanner.connection.ConnectionOptions.ENABLE_END_TO_END_TRACING_PROPERTY_NAME;
 import static com.google.cloud.spanner.connection.ConnectionOptions.ENABLE_EXTENDED_TRACING_PROPERTY_NAME;
+import static com.google.cloud.spanner.connection.ConnectionOptions.ENABLE_GRPC_INTERCEPTOR_PROVIDER_SYSTEM_PROPERTY;
 import static com.google.cloud.spanner.connection.ConnectionOptions.ENCODED_CREDENTIALS_PROPERTY_NAME;
 import static com.google.cloud.spanner.connection.ConnectionOptions.ENDPOINT_PROPERTY_NAME;
 import static com.google.cloud.spanner.connection.ConnectionOptions.IS_EXPERIMENTAL_HOST_PROPERTY_NAME;
@@ -101,6 +102,7 @@
 import static com.google.cloud.spanner.connection.ConnectionProperty.castProperty;
 
 import com.google.api.gax.core.CredentialsProvider;
+import com.google.api.gax.grpc.GrpcInterceptorProvider;
 import com.google.cloud.spanner.Dialect;
 import com.google.cloud.spanner.DmlBatchUpdateCountVerificationFailedException;
 import com.google.cloud.spanner.Options.RpcPriority;
@@ -286,6 +288,23 @@ public class ConnectionProperties {
           null,
           CredentialsProviderConverter.INSTANCE,
           Context.STARTUP);
+  static final ConnectionProperty<String> GRPC_INTERCEPTOR_PROVIDER =
+      create(
+          "grpc_interceptor_provider",
+          "The class name of a "
+              + GrpcInterceptorProvider.class.getName()
+              + " implementation that should be used to provide interceptors for the underlying"
+              + " Spanner client. This is a guarded property that can only be set if the Java"
+              + " System Property "
+              + ENABLE_GRPC_INTERCEPTOR_PROVIDER_SYSTEM_PROPERTY
+              + " has been set to true. This property should only be set to true on systems where"
+              + " an untrusted user cannot modify the connection URL, as using this property will"
+              + " dynamically invoke the constructor of the class specified. This means that any"
+              + " user that can modify the connection URL, can also dynamically invoke code on the"
+              + " host where the application is running.",
+          null,
+          StringValueConverter.INSTANCE,
+          Context.STARTUP);
 
   static final ConnectionProperty<String> USER_AGENT =
       create(

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/SpannerPool.java

@@ -166,6 +166,7 @@ static class SpannerPoolKey {
     private final boolean isExperimentalHost;
     private final Boolean enableDirectAccess;
     private final String universeDomain;
+    private final String grpcInterceptorProvider;
 
     @VisibleForTesting
     static SpannerPoolKey of(ConnectionOptions options) {
@@ -202,6 +203,7 @@ private SpannerPoolKey(ConnectionOptions options) throws IOException {
       this.isExperimentalHost = options.isExperimentalHost();
       this.enableDirectAccess = options.isEnableDirectAccess();
       this.universeDomain = options.getUniverseDomain();
+      this.grpcInterceptorProvider = options.getGrpcInterceptorProviderName();
     }
 
     @Override
@@ -229,7 +231,8 @@ public boolean equals(Object o) {
           && Objects.equals(this.clientCertificateKey, other.clientCertificateKey)
           && Objects.equals(this.isExperimentalHost, other.isExperimentalHost)
           && Objects.equals(this.enableDirectAccess, other.enableDirectAccess)
-          && Objects.equals(this.universeDomain, other.universeDomain);
+          && Objects.equals(this.universeDomain, other.universeDomain)
+          && Objects.equals(this.grpcInterceptorProvider, other.grpcInterceptorProvider);
     }
 
     @Override
@@ -253,7 +256,8 @@ public int hashCode() {
           this.clientCertificateKey,
           this.isExperimentalHost,
           this.enableDirectAccess,
-          this.universeDomain);
+          this.universeDomain,
+          this.grpcInterceptorProvider);
     }
   }
 
@@ -426,6 +430,9 @@ Spanner createSpanner(SpannerPoolKey key, ConnectionOptions options) {
     if (key.universeDomain != null) {
       builder.setUniverseDomain(key.universeDomain);
     }
+    if (key.grpcInterceptorProvider != null) {
+      builder.setInterceptorProvider(options.getGrpcInterceptorProvider());
+    }
     if (options.getConfigurator() != null) {
       options.getConfigurator().configure(builder);
     }

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/GrpcInterceptorProviderTest.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2025 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.spanner.connection;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+import com.google.api.gax.grpc.GrpcInterceptorProvider;
+import com.google.cloud.spanner.ErrorCode;
+import com.google.cloud.spanner.ResultSet;
+import com.google.cloud.spanner.SpannerException;
+import com.google.common.collect.ImmutableList;
+import io.grpc.CallOptions;
+import io.grpc.Channel;
+import io.grpc.ClientCall;
+import io.grpc.ClientInterceptor;
+import io.grpc.MethodDescriptor;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicBoolean;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public class GrpcInterceptorProviderTest extends AbstractMockServerTest {
+  private static final AtomicBoolean INTERCEPTOR_CALLED = new AtomicBoolean(false);
+
+  public static final class TestGrpcInterceptorProvider implements GrpcInterceptorProvider {
+    @Override
+    public List<ClientInterceptor> getInterceptors() {
+      return ImmutableList.of(
+          new ClientInterceptor() {
+            @Override
+            public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
+                MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
+              INTERCEPTOR_CALLED.set(true);
+              return next.newCall(method, callOptions);
+            }
+          });
+    }
+  }
+
+  @Before
+  public void clearInterceptorUsedFlag() {
+    INTERCEPTOR_CALLED.set(false);
+  }
+
+  @Test
+  public void testGrpcInterceptorProviderIsNotUsedByDefault() {
+    assertFalse(INTERCEPTOR_CALLED.get());
+    try (Connection connection = createConnection()) {
+      try (ResultSet resultSet = connection.executeQuery(SELECT1_STATEMENT)) {
+        while (resultSet.next()) {
+          // ignore
+        }
+      }
+    }
+    assertFalse(INTERCEPTOR_CALLED.get());
+  }
+
+  @Test
+  public void testGrpcInterceptorProviderIsUsedWhenConfigured() {
+    System.setProperty("ENABLE_GRPC_INTERCEPTOR_PROVIDER", "true");
+    assertFalse(INTERCEPTOR_CALLED.get());
+    try (Connection connection =
+        createConnection(
+            ";grpc_interceptor_provider=" + TestGrpcInterceptorProvider.class.getName())) {
+      try (ResultSet resultSet = connection.executeQuery(SELECT1_STATEMENT)) {
+        while (resultSet.next()) {
+          // ignore
+        }
+      }
+    } finally {
+      System.clearProperty("ENABLE_GRPC_INTERCEPTOR_PROVIDER");
+    }
+    assertTrue(INTERCEPTOR_CALLED.get());
+  }
+
+  @Test
+  public void testGrpcInterceptorProviderRequiresSystemProperty() {
+    assertFalse(INTERCEPTOR_CALLED.get());
+    SpannerException exception =
+        assertThrows(
+            SpannerException.class,
+            () ->
+                createConnection(
+                    ";grpc_interceptor_provider=" + TestGrpcInterceptorProvider.class.getName()));
+    assertEquals(ErrorCode.FAILED_PRECONDITION, exception.getErrorCode());
+    assertTrue(
+        exception.getMessage(),
+        exception
+            .getMessage()
+            .contains(
+                "grpc_interceptor_provider can only be used if the system property"
+                    + " ENABLE_GRPC_INTERCEPTOR_PROVIDER has been set to true. Start the"
+                    + " application with the JVM command line option"
+                    + " -DENABLE_GRPC_INTERCEPTOR_PROVIDER=true"));
+    assertFalse(INTERCEPTOR_CALLED.get());
+  }
+}