feat: add ChannelFinder server interfaces #4293

rahul2393 · 2026-01-08T05:55:40Z

This commit adds the server abstraction interfaces for location-aware routing:

ChannelFinderServer: Interface representing a Spanner server endpoint with address, health check, and channel access
ChannelFinderServerFactory: Factory interface for creating and caching server connections
GrpcChannelFinderServerFactory: gRPC implementation that creates and manages gRPC channels for different server endpoints

These interfaces enable the client to maintain connections to multiple Spanner servers and route requests directly to the appropriate server based on key location information.

This is part of the experimental location-aware routing for improved latency.

gemini-code-assist · 2026-01-08T05:55:55Z

Summary of Changes

Hello @rahul2393, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces foundational interfaces and a gRPC-specific implementation to support an experimental location-aware routing feature within the Spanner client library. The new components enable the client to establish and manage connections to multiple Spanner server endpoints, facilitating intelligent request routing based on key location information. This enhancement is designed to improve overall latency by directing requests to the most geographically appropriate server.

Highlights

New Interface: ChannelFinderServer: Introduced the ChannelFinderServer interface, which defines a Spanner server endpoint. It includes methods to retrieve the server's address, check its health status, and access its underlying gRPC ManagedChannel.
New Interface: ChannelFinderServerFactory: Added the ChannelFinderServerFactory interface, designed to abstract the creation and caching mechanisms for ChannelFinderServer instances, providing a way to manage server connections.
New Implementation: GrpcChannelFinderServerFactory: Implemented GrpcChannelFinderServerFactory, a concrete gRPC-based factory that adheres to the ChannelFinderServerFactory interface. This class manages ManagedChannel connections to various Spanner server endpoints, supporting both a default server and dynamic creation for specific addresses, utilizing InstantiatingGrpcChannelProvider.Builder.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces new interfaces and an implementation for location-aware routing, which is a great step towards improving latency. The new abstractions ChannelFinderServer and ChannelFinderServerFactory are well-defined. My review includes suggestions for improving the Javadoc for these new interfaces to make them clearer. I've also identified a potential concurrency issue in GrpcChannelFinderServerFactory where a shared builder is mutated, and I've proposed a fix. Additionally, there are some minor points on error handling and code clarity.

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServer.java

gemini-code-assist · 2026-01-08T05:57:36Z

...-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServerFactory.java

+  ChannelFinderServer defaultServer();
+
+  ChannelFinderServer create(String address);


The methods in this interface should have Javadoc comments to explain their purpose, expected inputs, and what they return. This will improve the maintainability and usability of this new API.

/** Returns the default server that is used if no specific server can be found for a request. */ ChannelFinderServer defaultServer(); /** * Creates or returns a cached server for the given address. * * @param address The address of the server to connect to. * @return A {@link ChannelFinderServer} for the given address. */ ChannelFinderServer create(String address);

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

This commit adds the server abstraction interfaces for location-aware routing: - ChannelFinderServer: Interface representing a Spanner server endpoint with address, health check, and channel access - ChannelFinderServerFactory: Factory interface for creating and caching server connections - GrpcChannelFinderServerFactory: gRPC implementation that creates and manages gRPC channels for different server endpoints These interfaces enable the client to maintain connections to multiple Spanner servers and route requests directly to the appropriate server based on key location information. This is part of the experimental location-aware routing for improved latency.

olavloite · 2026-01-23T17:20:06Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServer.java

+ * @see ChannelFinderServerFactory
+ */
+@InternalApi
+public interface ChannelFinderServer {


I'm not sure if I'm messing up a naming scheme that might be consistent with the internal naming scheme, but I find this name really confusing. It sounds like this is a Server, but it is not. It is a Channel or Connection to a server, right? And why is it a ChannelFinder? It does not find any channel. It just wraps a channel and adds two additional methods.

Could we rename this to WrappedChannel? (Or something else, I'm open to suggestions)

olavloite · 2026-01-23T17:22:42Z

...-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServerFactory.java

+   * @return a server instance for the address, never null
+   * @throws com.google.cloud.spanner.SpannerException if the channel cannot be created
+   */
+  ChannelFinderServer create(String address);


The Javadoc says 'Creates or retrieves'. The method name is create, which sounds like it is creating a new one every time. Could we rename this to either get (or potentially createOrRetrieve, but get is more in line with standard methods for a cache).

olavloite · 2026-01-23T17:23:31Z

...-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServerFactory.java

+ * #create(String)} with different addresses.
+ */
+@InternalApi
+public interface ChannelFinderServerFactory {


This seems to be a cache or a pool, not a factory. Can we rename it to ChannelCache or ChannelPool?

olavloite · 2026-01-23T17:26:23Z

...-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/ChannelFinderServerFactory.java

+   *
+   * @return the default server, never null
+   */
+  ChannelFinderServer defaultServer();


Can we rename this to defaultChannel()?

olavloite · 2026-01-23T17:29:29Z

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

+    isShutdown = true;
+    for (GrpcChannelFinderServer server : servers.values()) {
+      shutdownServerGracefully(server);
+    }
+    servers.clear();


I think that you want to put some synchronization around this. I see that the servers map supports concurrency, but I'm not sure that calling this method from two threads at the same time will always give you the result you expect.

olavloite · 2026-01-23T17:29:55Z

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

+   * <p>First attempts a graceful shutdown, waiting for in-flight RPCs to complete. If the timeout
+   * is exceeded, forces immediate shutdown.
+   */
+  private void shutdownServerGracefully(GrpcChannelFinderServer server) {


This really shows why the naming needs to change. We are not shutting down the server. We are just closing a channel.

olavloite · 2026-01-23T17:40:02Z

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

+
+    channel.shutdown();
+    try {
+      if (!channel.awaitTermination(SHUTDOWN_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {


I don't think that you want to wait here in all cases (e.g. when evict is being called, I would expect this to be a shoot-and-forget operation).

olavloite · 2026-01-23T17:42:16Z

...ud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GrpcChannelFinderServerFactory.java

+      try {
+        ConnectivityState state = channel.getState(false);
+        return state != ConnectivityState.SHUTDOWN && state != ConnectivityState.TRANSIENT_FAILURE;
+      } catch (UnsupportedOperationException e) {


nit: rename e to ignore

rahul2393 requested review from a team as code owners January 8, 2026 05:55

product-auto-label bot added size: m Pull request size is medium. api: spanner Issues related to the googleapis/java-spanner API. labels Jan 8, 2026

gemini-code-assist bot reviewed Jan 8, 2026

View reviewed changes

product-auto-label bot added size: l Pull request size is large. and removed size: m Pull request size is medium. labels Jan 16, 2026

rahul2393 requested a review from olavloite January 16, 2026 08:16

rahul2393 added 3 commits January 20, 2026 14:52

incorporate changes

de62468

add tests

97bd6cf

rahul2393 force-pushed the feat/channel-finder-interfaces branch from 212f234 to 97bd6cf Compare January 20, 2026 09:38

olavloite reviewed Jan 23, 2026

View reviewed changes

		ChannelFinderServer defaultServer();

		ChannelFinderServer create(String address);

feat: add ChannelFinder server interfaces #4293

Are you sure you want to change the base?

feat: add ChannelFinder server interfaces #4293

Uh oh!

Conversation

rahul2393 commented Jan 8, 2026

Uh oh!

gemini-code-assist bot commented Jan 8, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants