chore(spanner): deprecate experimental host option/parameter to replace with Spanner Omni (#13236)

This PR deprecates the `experimentalHost` / `isExperimentalHost` option
and property across the Cloud Spanner client libraries (`SpannerOptions`
and `ConnectionOptions`) and introduces a unified `type` option and
connection parameter (supporting the values `cloud`, `omni`,).

To connect to a Spanner Omni instance, users should now use the
`setType(InstanceType.OMNI)` builder option or pass the connection
string query parameter `?type=omni`.

Refer to discussion: [Spanner Client Library Configuration for
Omni](https://docs.google.com/document/d/1n-rsHkNAEwQbaICHKlFhPl3NN8a3QuOknn_tEhaowZQ/edit?resourcekey=0-LnCt0jSFXCoSuVttphq3FQ&tab=t.0)


Currently, setting the type to `cloud` or `emulator` acts as a **no-op**
(since the client library automatically resolves default behaviors for
standard cloud and emulator setups). However, introducing this option
makes the client library highly extendable, enabling us to enforce or
optimize custom behaviors tailored to specific Spanner instance types in
the future.

---------

Co-authored-by: rahul2393 <rahulyadavsep92@gmail.com>

Author: sagnghos

java-spanner/google-cloud-spanner/clirr-ignored-differences.xml

@@ -910,21 +910,21 @@
     <method>java.lang.Object runTransaction(com.google.cloud.spanner.connection.Connection$TransactionCallable)</method>
   </difference>
 
-  <!-- Added experimental host option -->
+  <!-- Added Spanner Omni option -->
   <difference>
     <differenceType>7012</differenceType>
     <className>com/google/cloud/spanner/SpannerOptions$SpannerEnvironment</className>
-    <method>com.google.auth.oauth2.GoogleCredentials getDefaultExperimentalHostCredentials()</method>
+    <method>com.google.auth.oauth2.GoogleCredentials getDefaultSpannerOmniCredentials()</method>
   </difference>
   <difference>
     <differenceType>7002</differenceType>
     <className>com/google/cloud/spanner/SpannerOptions$SpannerEnvironment</className>
-    <method>com.google.auth.oauth2.GoogleCredentials getDefaultExternalHostCredentials()</method>
+    <method>com.google.auth.oauth2.GoogleCredentials getDefaultSpannerOmniCredentials()</method>
   </difference>
   <difference>
     <differenceType>7002</differenceType>
     <className>com/google/cloud/spanner/SpannerOptions</className>
-    <method>com.google.auth.oauth2.GoogleCredentials getDefaultExternalHostCredentialsFromSysEnv()</method>
+    <method>com.google.auth.oauth2.GoogleCredentials getDefaultSpannerOmniCredentialsFromSysEnv()</method>
   </difference>
 
   <!-- Default sequence kind -->

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

@@ -127,7 +127,8 @@ public class SpannerOptions extends ServiceOptions<Spanner, SpannerOptions> {
   private static final String API_SHORT_NAME = "Spanner";
   private static final String SPANNER_SERVICE_NAME = "spanner";
   private static final String GOOGLE_DEFAULT_UNIVERSE = "googleapis.com";
-  private static final String EXPERIMENTAL_HOST_PROJECT_ID = "default";
+  public static final String SPANNER_OMNI_PROJECT_ID = "default";
+  public static final String DEFAULT_SPANNER_OMNI_INSTANCE_ID = "default";
 
   static final ImmutableSet<String> SCOPES =
       ImmutableSet.of(
@@ -318,6 +319,15 @@ enum TracingFramework {
     OPEN_TELEMETRY
   }
 
+  /**
+   * Specifies the type of Spanner instance to connect to (CLOUD or OMNI). Setting it to OMNI is
+   * mandatory when connecting to a Spanner Omni instance.
+   */
+  public enum InstanceType {
+    CLOUD,
+    OMNI
+  }
+
   private static final Object lock = new Object();
 
   @GuardedBy("lock")
@@ -871,14 +881,20 @@ public static CloseableExecutorProvider createAsyncExecutorProvider(
   }
 
   protected SpannerOptions(Builder builder) {
-    super(SpannerFactory.class, SpannerRpcFactory.class, builder, new SpannerDefaults());
+    super(
+        SpannerFactory.class,
+        SpannerRpcFactory.class,
+        Builder.prepareBuilder(builder),
+        new SpannerDefaults());
     numChannels = builder.numChannels == null ? DEFAULT_CHANNELS : builder.numChannels;
     Preconditions.checkArgument(
         numChannels >= 1 && numChannels <= MAX_CHANNELS,
         "Number of channels must fall in the range [1, %s], found: %s",
         MAX_CHANNELS,
         numChannels);
-
+    Preconditions.checkArgument(
+        builder.instanceType != InstanceType.OMNI || !Strings.isNullOrEmpty(builder.host),
+        "Host must be set for connecting to Spanner Omni instances");
     transportChannelExecutorThreadNameFormat = builder.transportChannelExecutorThreadNameFormat;
     channelProvider = builder.channelProvider;
     channelEndpointCacheFactory = builder.channelEndpointCacheFactory;
@@ -928,16 +944,17 @@ protected SpannerOptions(Builder builder) {
 
     // Dynamic channel pooling is disabled by default.
     // It is only enabled when:
-    // 1. enableDynamicChannelPool() was explicitly called (or experimentalHost is set and DCP was
+    // 1. enableDynamicChannelPool() was explicitly called (or instance is set to OMNI and DCP was
     //    not explicitly disabled), AND
     // 2. grpc-gcp extension is enabled, AND
     // 3. numChannels was not explicitly set
     boolean dcpRequested =
         builder.dynamicChannelPoolEnabled != null
             ? builder.dynamicChannelPoolEnabled
-            : builder.experimentalHost != null;
+            : builder.instanceType == InstanceType.OMNI;
     if (dcpRequested) {
-      // DCP was enabled (explicitly or via experimentalHost), but respect numChannels if set
+      // DCP was enabled (explicitly or via instance type being OMNI), but respect numChannels if
+      // set
       dynamicChannelPoolEnabled = grpcGcpExtensionEnabled && !builder.numChannelsExplicitlySet;
     } else {
       // DCP is disabled by default, or was explicitly disabled
@@ -980,14 +997,14 @@ protected SpannerOptions(Builder builder) {
     openTelemetry = builder.openTelemetry;
     enableApiTracing = builder.enableApiTracing;
     enableExtendedTracing = builder.enableExtendedTracing;
-    if (builder.experimentalHost != null) {
+    if (builder.instanceType == InstanceType.OMNI) {
       enableBuiltInMetrics = false;
     } else {
       enableBuiltInMetrics = builder.enableBuiltInMetrics;
     }
-    // Enable location API when experimental host is set, unless explicitly disabled
+    // Enable location API when InstanceType is OMNI, unless explicitly disabled
     // via GOOGLE_SPANNER_EXPERIMENTAL_LOCATION_API=false.
-    if (builder.experimentalHost != null) {
+    if (builder.instanceType == InstanceType.OMNI) {
       String locationApiEnvValue = System.getenv(EXPERIMENTAL_LOCATION_API_ENV_VAR);
       enableLocationApi = locationApiEnvValue == null || Boolean.parseBoolean(locationApiEnvValue);
     } else {
@@ -1091,13 +1108,12 @@ default String getMonitoringHost() {
       return null;
     }
 
-    default GoogleCredentials getDefaultExperimentalHostCredentials() {
+    default GoogleCredentials getDefaultSpannerOmniCredentials() {
       return null;
     }
   }
 
-  static final String DEFAULT_SPANNER_EXPERIMENTAL_HOST_CREDENTIALS =
-      "SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN";
+  static final String DEFAULT_SPANNER_OMNI_CREDENTIALS = "SPANNER_OMNI_AUTH_TOKEN";
 
   /**
    * Default implementation of {@link SpannerEnvironment}. Reads all configuration from environment
@@ -1205,14 +1221,33 @@ public String getMonitoringHost() {
     }
 
     @Override
-    public GoogleCredentials getDefaultExperimentalHostCredentials() {
-      return getOAuthTokenFromFile(System.getenv(DEFAULT_SPANNER_EXPERIMENTAL_HOST_CREDENTIALS));
+    public GoogleCredentials getDefaultSpannerOmniCredentials() {
+      return getOAuthTokenFromFile(System.getenv(DEFAULT_SPANNER_OMNI_CREDENTIALS));
     }
   }
 
   /** Builder for {@link SpannerOptions} instances. */
   public static class Builder
       extends ServiceOptions.Builder<Spanner, SpannerOptions, SpannerOptions.Builder> {
+    private static Builder prepareBuilder(Builder builder) {
+      if (builder.instanceType == InstanceType.OMNI) {
+        builder.enableBuiltInMetrics = false;
+        builder.setProjectId(SPANNER_OMNI_PROJECT_ID);
+        builder.configureOmniHost();
+        if (builder.sessionPoolOptions == null) {
+          builder.sessionPoolOptions =
+              SessionPoolOptions.newBuilder().setExperimentalHost().build();
+        } else {
+          builder.sessionPoolOptions =
+              builder.sessionPoolOptions.toBuilder().setExperimentalHost().build();
+        }
+        if (builder.credentials == null) {
+          builder.setCredentials(environment.getDefaultSpannerOmniCredentials());
+        }
+      }
+      return builder;
+    }
+
     static final int DEFAULT_PREFETCH_CHUNKS = 4;
     static final QueryOptions DEFAULT_QUERY_OPTIONS = QueryOptions.getDefaultInstance();
     static final DecodeMode DEFAULT_DECODE_MODE = DecodeMode.DIRECT;
@@ -1283,10 +1318,11 @@ public static class Builder
     private boolean enableLocationApi = SpannerOptions.environment.isEnableLocationApi();
     private String monitoringHost = SpannerOptions.environment.getMonitoringHost();
     private SslContext mTLSContext = null;
-    private String experimentalHost = null;
     private boolean usePlainText = false;
     private TransactionOptions defaultTransactionOptions = TransactionOptions.getDefaultInstance();
     private RequestOptions.ClientContext clientContext;
+    private InstanceType instanceType = InstanceType.CLOUD;
+    private String host = null;
     private boolean autoTaggingEnabled = false;
     private List<String> autoTaggingPackages = Collections.emptyList();
     private int autoTaggingTracerLimit = 50;
@@ -1829,29 +1865,50 @@ public Builder setDecodeMode(DecodeMode decodeMode) {
       return this;
     }
 
+    private void configureOmniHost() {
+      if (this.instanceType == InstanceType.OMNI
+          && !Strings.isNullOrEmpty(this.host)
+          && this.usePlainText) {
+        Preconditions.checkArgument(
+            !this.host.startsWith("https:"),
+            "Please remove the 'https:' protocol prefix from the host string when using plain text"
+                + " communication");
+        if (!this.host.startsWith("http")) {
+          this.host = "http://" + this.host;
+        }
+      }
+    }
+
     @Override
     public Builder setHost(String host) {
-      super.setHost(host);
+      this.host = host;
+      configureOmniHost();
+      super.setHost(this.host);
       // Setting a host should override any SPANNER_EMULATOR_HOST setting.
       setEmulatorHost(null);
       return this;
     }
 
+    /**
+     * @deprecated Use {@link #setType(InstanceType)} instead.
+     */
+    @Deprecated
+    @ObsoleteApi("Use setHost(String).setType(InstanceType.OMNI) instead")
     @ExperimentalApi("https://github.com/googleapis/java-spanner/pull/3676")
     public Builder setExperimentalHost(String host) {
-      if (this.usePlainText) {
-        Preconditions.checkArgument(
-            !host.startsWith("https:"),
-            "Please remove the 'https:' protocol prefix from the host string when using plain text"
-                + " communication");
-        if (!host.startsWith("http")) {
-          host = "http://" + host;
-        }
+      if (!Strings.isNullOrEmpty(host)) {
+        setType(InstanceType.OMNI);
       }
-      super.setHost(host);
-      super.setProjectId(EXPERIMENTAL_HOST_PROJECT_ID);
-      setSessionPoolOption(SessionPoolOptions.newBuilder().setExperimentalHost().build());
-      this.experimentalHost = host;
+      setHost(host);
+      return this;
+    }
+
+    /**
+     * Specifies the type of Spanner instance to connect to (CLOUD or OMNI). Setting it to OMNI is
+     * mandatory when connecting to a Spanner Omni instance.
+     */
+    public Builder setType(InstanceType instanceType) {
+      this.instanceType = instanceType;
       return this;
     }
 
@@ -1953,14 +2010,13 @@ public Builder setEmulatorHost(String emulatorHost) {
     }
 
     /**
-     * Configures mTLS authentication using the provided client certificate and key files. mTLS is
-     * only supported for experimental spanner hosts.
+     * Configures mTLS authentication using the provided client certificate and key files. mTLS via
+     * useClientCert is only supported for Spanner Omni instances.
      *
      * @param clientCertificate Path to the client certificate file.
      * @param clientCertificateKey Path to the client private key file.
      * @throws SpannerException If an error occurs while configuring the mTLS context
      */
-    @ExperimentalApi("https://github.com/googleapis/java-spanner/pull/3574")
     public Builder useClientCert(String clientCertificate, String clientCertificateKey) {
       try {
         this.mTLSContext =
@@ -1978,14 +2034,14 @@ public Builder useClientCert(String clientCertificate, String clientCertificateK
      * credentials to {@link com.google.cloud.NoCredentials} to avoid sending authentication over an
      * unsecured channel.
      */
-    @ExperimentalApi("https://github.com/googleapis/java-spanner/pull/4264")
     public Builder usePlainText() {
       this.usePlainText = true;
       this.setChannelConfigurator(ManagedChannelBuilder::usePlaintext)
           .setCredentials(NoCredentials.getInstance());
-      if (this.experimentalHost != null) {
+      if (this.instanceType == InstanceType.OMNI) {
         // Re-apply host settings to ensure http:// is prepended.
-        setExperimentalHost(this.experimentalHost);
+        configureOmniHost();
+        super.setHost(this.host);
       }
       return this;
     }
@@ -2191,7 +2247,7 @@ public Builder setAutoTaggingTracerLimit(int autoTaggingTracerLimit) {
     @Override
     public SpannerOptions build() {
       // Set the host of emulator has been set.
-      if (emulatorHost != null && experimentalHost == null) {
+      if (emulatorHost != null && this.instanceType != InstanceType.OMNI) {
         if (!emulatorHost.startsWith("http")) {
           emulatorHost = "http://" + emulatorHost;
         }
@@ -2201,8 +2257,6 @@ public SpannerOptions build() {
         this.setChannelConfigurator(ManagedChannelBuilder::usePlaintext);
         // As we are using plain text, we should never send any credentials.
         this.setCredentials(NoCredentials.getInstance());
-      } else if (experimentalHost != null && credentials == null) {
-        credentials = environment.getDefaultExperimentalHostCredentials();
       }
       if (this.numChannels == null) {
         this.numChannels =
@@ -2244,8 +2298,8 @@ public static void useDefaultEnvironment() {
   }
 
   @InternalApi
-  public static GoogleCredentials getDefaultExperimentalCredentialsFromSysEnv() {
-    return getOAuthTokenFromFile(System.getenv(DEFAULT_SPANNER_EXPERIMENTAL_HOST_CREDENTIALS));
+  public static GoogleCredentials getDefaultSpannerOmniCredentialsFromSysEnv() {
+    return getOAuthTokenFromFile(System.getenv(DEFAULT_SPANNER_OMNI_CREDENTIALS));
   }
 
   private static @Nullable GoogleCredentials getOAuthTokenFromFile(@Nullable String file) {

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

@@ -26,6 +26,7 @@
 import com.google.cloud.spanner.Options.RpcPriority;
 import com.google.cloud.spanner.SpannerException;
 import com.google.cloud.spanner.SpannerExceptionFactory;
+import com.google.cloud.spanner.SpannerOptions;
 import com.google.cloud.spanner.TimestampBound;
 import com.google.cloud.spanner.TimestampBound.Mode;
 import com.google.cloud.spanner.connection.PgTransactionMode.AccessMode;
@@ -895,4 +896,27 @@ public Dialect convert(String value) {
       return values.get(value);
     }
   }
+
+  static class InstanceTypeConverter
+      implements ClientSideStatementValueConverter<SpannerOptions.InstanceType> {
+    static final InstanceTypeConverter INSTANCE = new InstanceTypeConverter();
+
+    private final CaseInsensitiveEnumMap<SpannerOptions.InstanceType> values =
+        new CaseInsensitiveEnumMap<>(SpannerOptions.InstanceType.class);
+
+    private InstanceTypeConverter() {}
+
+    /** Constructor needed for reflection. */
+    public InstanceTypeConverter(String allowedValues) {}
+
+    @Override
+    public Class<SpannerOptions.InstanceType> getParameterClass() {
+      return SpannerOptions.InstanceType.class;
+    }
+
+    @Override
+    public SpannerOptions.InstanceType convert(String value) {
+      return values.get(value);
+    }
+  }
 }