fix(csharp): apply cached feature flags on connect (warm cache)

PR #500 changed the connection-open feature-flag merge to fire-and-forget:
`MergeWithEnvironmentConfigAndFeatureFlags` kicked off the async merge in a
discarded `Task.Run` and returned the env-config-only properties, so server
feature flags (e.g. `adbc.databricks.enable_fast_metadata_query`) were never
applied to any connection. The synchronous applier existed but had no callers,
so neither the first nor any subsequent connection ever received the flags.

Add `FeatureFlagCache.TryMergeWarmFeatureFlags`: if the per-host cache is warm,
merge the cached flags synchronously (local properties win); if cold, kick off
a background warm-up and return null so `Connect()` proceeds unblocked and a
subsequent connection to the same host picks up the flags. Never performs a
blocking network fetch, and honors the negative-cache backoff.

Co-authored-by: Isaac

Author: Jade Wang

csharp/src/DatabricksDatabase.cs

@@ -162,22 +162,22 @@ public override AdbcConnection Connect(IReadOnlyDictionary<string, string>? opti
         }
 
         /// <summary>
-        /// Merges properties with environment config and fires a background feature flag warm-up.
+        /// Merges properties with environment config and server feature flags.
         /// This is the single place where all property merging happens for both Thrift and REST connections.
         /// </summary>
         /// <param name="properties">Properties to merge.</param>
-        /// <returns>Merged properties dictionary (feature flags applied on subsequent connections once cached).</returns>
+        /// <returns>Merged properties dictionary with any warm-cache feature flags applied.</returns>
         private static IReadOnlyDictionary<string, string> MergeWithEnvironmentConfigAndFeatureFlags(IReadOnlyDictionary<string, string> properties)
         {
             var mergedWithEnvConfig = MergeWithDefaultEnvironmentConfig(properties);
 
-            // Fire-and-forget: warm the feature flag cache in the background.
-            // On a cache hit the task completes immediately; on a miss it fetches and caches
-            // so subsequent Connect() calls get flags applied synchronously (cache hit path).
-            _ = Task.Run(() => FeatureFlagCache.GetInstance()
-                .MergePropertiesWithFeatureFlagsAsync(mergedWithEnvConfig, s_assemblyVersion));
-
-            return mergedWithEnvConfig;
+            // Apply server feature flags without ever blocking Connect(): if the per-host cache
+            // is already warm, the flags are merged in synchronously (no network, local props win);
+            // if it is cold, a background warm-up is kicked off so a subsequent connection to the
+            // same host picks them up, and this connection proceeds with the unmodified properties.
+            return FeatureFlagCache.GetInstance()
+                .TryMergeWarmFeatureFlags(mergedWithEnvConfig, s_assemblyVersion)
+                ?? mergedWithEnvConfig;
         }
 
         /// <summary>

csharp/src/FeatureFlagCache.cs

@@ -412,6 +412,56 @@ public IReadOnlyDictionary<string, string> MergePropertiesWithFeatureFlags(
                 .GetResult();
         }
 
+        /// <summary>
+        /// Non-blocking feature-flag application for the connection-open path.
+        /// <para>
+        /// If flags for the host are already cached (warm), returns <paramref name="localProperties"/>
+        /// merged with them (local properties win) so the connection sees the server flags immediately.
+        /// If the cache is cold, this starts a background warm-up so a subsequent connection to the same
+        /// host applies the flags, and returns <c>null</c> to signal the caller to proceed with the
+        /// unmodified properties for this connection.
+        /// </para>
+        /// <para>
+        /// Never performs a blocking network fetch, so it never stalls <c>Connect()</c>. Returns
+        /// <c>null</c> when the cache is disabled (<see cref="DatabricksParameters.FeatureFlagCacheEnabled"/>
+        /// explicitly <c>false</c>) or when no host can be determined.
+        /// </para>
+        /// </summary>
+        /// <param name="localProperties">The connection properties (already merged with environment config).</param>
+        /// <param name="assemblyVersion">Driver version, used when warming the cache.</param>
+        /// <returns>The merged properties when the cache is warm; otherwise <c>null</c>.</returns>
+        public IReadOnlyDictionary<string, string>? TryMergeWarmFeatureFlags(
+            IReadOnlyDictionary<string, string> localProperties,
+            string assemblyVersion)
+        {
+            // Respect the enable flag (default true; only an explicit, parseable "false" disables).
+            if (localProperties.TryGetValue(DatabricksParameters.FeatureFlagCacheEnabled, out string? enabledStr) &&
+                bool.TryParse(enabledStr, out bool parsedEnabled) && !parsedEnabled)
+            {
+                return null;
+            }
+
+            var host = TryGetHost(localProperties);
+            if (string.IsNullOrEmpty(host))
+            {
+                return null;
+            }
+
+            // Warm cache (or negatively-cached failure): apply whatever flags are cached, synchronously.
+            // A negative entry has no flags, so this is a no-op merge and — importantly — does NOT
+            // trigger another fetch, honoring the negative-cache backoff.
+            if (TryGetContext(host!, out var context) && context != null)
+            {
+                var flags = context.GetAllFlags();
+                return flags.Count > 0 ? MergeProperties(flags, localProperties) : localProperties;
+            }
+
+            // Cold cache: warm it in the background so the next connection to this host gets flags.
+            // This connection proceeds without them (never blocks).
+            _ = Task.Run(() => MergePropertiesWithFeatureFlagsAsync(localProperties, assemblyVersion));
+            return null;
+        }
+
 
         /// <summary>
         /// Tries to extract the host from properties without throwing.