feat: Add reset() method, gRPC keep-alive, and transport resilience

- Add public reset() method to SpiceClient for recovering from
  unrecoverable transport failures (SSL cert mismatch, persistent
  UNAVAILABLE errors, stale connections pinned to wrong backend IPs)
- Extract buildFlightClient() for reuse during construction and reset
- Configure HTTP/2 keep-alive (30s interval, 10s timeout) on the
  gRPC channel to detect dead/idle connections behind load balancers
- Add ensureFlightClient() guard in queryInternal() for safety
- Handle null flightClient in close() after reset
- Add ResetTest.java with 20 unit tests covering happy path, edge
  cases, concurrency, construction variants, and integration
- Document transport resilience and reset() usage in README

Author: lukekim

README.md

@@ -213,6 +213,38 @@ SpiceClient client = SpiceClient.builder()
     .build();
 ```
 
+### Long-lived Clients and Transport Resilience
+
+The `SpiceClient` is designed for long-lived reuse. The underlying gRPC channel uses `dns:///` resolution, which periodically re-resolves hostnames so clients automatically recover from load-balancer IP rotation (e.g. AWS NLB). HTTP/2 keep-alive is enabled by default (30s interval, 10s timeout) to detect dead connections quickly.
+
+For the rare case where the transport becomes permanently stuck (e.g. TLS handshake to a wrong backend, persistent `UNAVAILABLE` after retries), use `reset()` to discard the bad connection and immediately establish a fresh one:
+
+```java
+SpiceClient client = SpiceClient.builder()
+    .withApiKey(API_KEY)
+    .withSpiceCloud()
+    .build();
+
+// Long-lived usage with transport recovery
+try {
+    FlightStream stream = client.query(sql);
+    // process results...
+} catch (ExecutionException e) {
+    if (isTransportFailure(e.getCause())) {
+        client.reset();                     // discard bad transport, reconnect immediately
+        FlightStream stream = client.query(sql);  // no connection overhead
+    } else {
+        throw e;
+    }
+}
+```
+
+**DNS cache TTL:** The gRPC `DnsNameResolver` respects the JVM's DNS cache TTL. For more aggressive DNS refresh (recommended for cloud-deployed clients), set the JVM property:
+
+```bash
+-Dnetworkaddress.cache.ttl=30
+```
+
 ### Iterating Through Results
 
 For more control over query results, you can iterate through rows and access individual field values:

src/main/java/ai/spice/SpiceClient.java

@@ -39,6 +39,7 @@ of this software and associated documentation files (the "Software"), to deal
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
 
 import org.apache.arrow.adbc.core.AdbcConnection;
 import org.apache.arrow.adbc.core.AdbcDatabase;
@@ -215,6 +216,26 @@ public SpiceClient(String appId, String apiKey, URI flightAddress, URI httpAddre
                 : memoryLimitMB * BYTES_PER_MB;
         this.allocator = new RootAllocator(memoryLimitBytes);
 
+        // Build the Flight client (channel + auth handshake)
+        buildFlightClient();
+
+        // Initialize cached retryers (immutable, built once)
+        initRetryers();
+
+        logger.debug("SpiceClient initialized - flightAddress={}, appId={}", this.flightAddress, this.appId);
+    }
+    
+    /**
+     * Builds or rebuilds the Flight client, including the gRPC channel and auth handshake.
+     * This method is called during construction and after {@link #reset()}.
+     *
+     * <p>The gRPC channel is configured with:</p>
+     * <ul>
+     *   <li>{@code dns:///} target scheme for periodic DNS re-resolution behind load balancers</li>
+     *   <li>HTTP/2 keep-alive (30s interval, 10s timeout) to detect dead connections quickly</li>
+     * </ul>
+     */
+    private synchronized void buildFlightClient() {
         // Build a gRPC channel using forTarget() with the "dns:///" scheme so that
         // gRPC's DnsNameResolver periodically re-resolves the hostname. This is critical
         // for long-lived clients connecting to load-balanced endpoints (e.g. AWS ALBs)
@@ -246,15 +267,18 @@ public SpiceClient(String appId, String apiKey, URI flightAddress, URI httpAddre
             channelBuilder.usePlaintext();
         }
         channelBuilder
+                // HTTP/2 keep-alive to detect dead/idle connections behind load balancers
+                .keepAliveTime(30, TimeUnit.SECONDS)
+                .keepAliveTimeout(10, TimeUnit.SECONDS)
+                .keepAliveWithoutCalls(true)
                 .maxInboundMessageSize(Integer.MAX_VALUE)
                 .maxInboundMetadataSize(Integer.MAX_VALUE);
         ManagedChannel channel = channelBuilder.build();
 
         if (Strings.isNullOrEmpty(apiKey)) {
             FlightClient client = FlightGrpcUtils.createFlightClient(allocator, channel);
             this.flightClient = new FlightSqlClient(client);
-            initRetryers();
-            logger.debug("SpiceClient initialized (unauthenticated) - flightAddress={}, target={}", this.flightAddress, target);
+            logger.debug("Flight client built (unauthenticated) - target={}", target);
             return;
         }
 
@@ -282,13 +306,69 @@ public SpiceClient(String appId, String apiKey, URI flightAddress, URI httpAddre
         client.handshake(new CredentialCallOption(new BasicAuthCredentialWriter(this.appId, this.apiKey)));
         this.authCallOptions = authFactory.getCredentialCallOption();
         this.flightClient = new FlightSqlClient(client);
-        
-        // Initialize cached retryers (immutable, built once)
-        initRetryers();
-        
-        logger.debug("SpiceClient initialized (authenticated) - flightAddress={}, appId={}, target={}", this.flightAddress, this.appId, target);
+
+        logger.debug("Flight client built (authenticated) - target={}, appId={}", target, this.appId);
     }
-    
+
+    /**
+     * Ensures the Flight client is connected, rebuilding it if necessary
+     * (e.g. after a {@link #reset()} call).
+     */
+    private synchronized void ensureFlightClient() {
+        if (this.flightClient == null) {
+            buildFlightClient();
+        }
+    }
+
+    /**
+     * Resets the underlying gRPC transport by closing the current Flight client and ADBC connections,
+     * then immediately establishes a fresh connection with a new DNS lookup and TLS handshake.
+     * This ensures the next {@link #query(String)} or {@link #queryWithParams(String, Object...)}
+     * call does not incur connection setup overhead.
+     *
+     * <p>Use this method to recover from unrecoverable transport failures such as:</p>
+     * <ul>
+     *   <li>SSLHandshakeException with mismatched certificates (e.g. load-balancer routing to wrong backend)</li>
+     *   <li>Persistent UNAVAILABLE errors after exhausting retries</li>
+     *   <li>Stale connections pinned to decommissioned backend IPs</li>
+     * </ul>
+     *
+     * <p>Example usage for long-lived clients:</p>
+     * <pre>{@code
+     * try {
+     *     return client.query(sql);
+     * } catch (ExecutionException e) {
+     *     if (isTransportFailure(e.getCause())) {
+     *         client.reset();
+     *         return client.query(sql); // retry with fresh connection
+     *     }
+     *     throw e;
+     * }
+     * }</pre>
+     */
+    public synchronized void reset() {
+        logger.info("Resetting SpiceClient transport");
+
+        // Close ADBC resources (they maintain a separate Flight connection)
+        closeADBC();
+
+        // Close Flight client (this also shuts down the underlying gRPC channel)
+        if (this.flightClient != null) {
+            try {
+                this.flightClient.close();
+            } catch (Exception e) {
+                logger.warn("Error closing Flight client during reset: {}", e.getMessage());
+            }
+            this.flightClient = null;
+        }
+        this.authCallOptions = null;
+
+        // Eagerly re-establish the connection so the next query has no setup overhead
+        buildFlightClient();
+
+        logger.info("SpiceClient transport reset and reconnected.");
+    }
+
     /**
      * Initializes the cached retryer instances.
      * Called from constructor and must be called after maxRetries is set.
@@ -907,6 +987,7 @@ public void refreshDataset(String dataset, RefreshOptions refreshOptions) throws
     }
 
     private FlightStream queryInternal(String sql) {
+        ensureFlightClient();
         FlightInfo flightInfo = this.flightClient.execute(sql, authCallOptions);
         Ticket ticket = flightInfo.getEndpoints().get(0).getTicket();
         return this.flightClient.getStream(ticket, authCallOptions);
@@ -942,12 +1023,14 @@ public void close() throws Exception {
         }
 
         // Close Flight client
-        try {
-            this.flightClient.close();
-            logger.debug("Flight client closed");
-        } catch (Exception e) {
-            logger.warn("Error closing Flight client: {}", e.getMessage());
-            exceptions.add(e);
+        if (this.flightClient != null) {
+            try {
+                this.flightClient.close();
+                logger.debug("Flight client closed");
+            } catch (Exception e) {
+                logger.warn("Error closing Flight client: {}", e.getMessage());
+                exceptions.add(e);
+            }
         }
 
         // Close allocator