Bump version to 6.2.0, resolve integration test flakiness (#219)

## Problem
We need to bump version packaging and constants for releasing v6.2.0.
There's also a significant amount of integration test flakiness to
address, and the suite was taking ~20 minutes to run.

## Solution

**Version bump**

Bump version to 6.2.0 in `gradle.properties` and `CHANGELOG.md`.

**NOTE: All of the following changes are within the integration testing
harness, so none of the client code is actually touched. I spent a bit
of time working with claude to tighten up the testing harness itself.
Test execution went from 20-24mins per run to 7-8mins, it looks like.
Primarily, this was achieved through parallelizing the test classes
since a lot of them are reusing the TestResourcesManagerSingle already.
The singleton class also needed a lot of work to make it a bit more
robust when being accessed by parallel testing threads. I summarized
most of this with claude since it was done across numerous commits.**

**Parallel test execution**

Added `junit-platform.properties` enabling concurrent class-level
execution at parallelism 4, with methods within each class remaining
sequential. This alone brought the suite runtime from ~20 minutes to ~8
minutes.

**AssertRetry — exception handling gap**

The retry helper only caught `AssertionError`, `ExecutionException`, and
`IOException`. Any other exception (most commonly `NullPointerException`
when a namespace key is absent from the stats map during eventual
consistency) escaped the retry loop immediately. Widened the catch and
the `AssertionRunnable` interface to `Exception`. Also added
explicit `InterruptedException` re-throw before the broad catch so that
cancellation signals propagate correctly rather than being silently
retried.

**TestResourcesManager — thread safety**

Enabling parallel class execution exposed multiple races in the shared
singleton:
- `getInstance()` was unsynchronized; two classes could both see `null`
and construct duplicate instances. Fixed with `volatile` +
`synchronized`.
- `getOrCreatePodIndex()`, `getOrCreateServerlessIndex()`, and
`getOrCreateCollection()` had check-then-act races where two threads
could both pass the null guard and create duplicate indexes. All marked
`synchronized`.
- `getOrCreate*Connection()` methods now cache their results and are
`synchronized`, ensuring parallel classes that both call
`getOrCreateServerlessIndexConnection()` share the same `Index` object
rather than creating duplicate channels.
- `cleanupResources()` now closes all cached connections before deleting
indexes.
- Fixed a string identity comparison bug (`!= "ready"`) in the
collection-readiness loop that caused it to always run to the full
120-second timeout. Fixed to `!"ready".equals(...)`.

**Parallel tests closing shared connections early**

`Index.close()` shuts down the underlying `PineconeConnection`, which is
shared via a `static final ConcurrentHashMap` keyed by index name across
all `Pinecone` instances. With parallel class execution, one class
calling `close()` in `@AfterAll` could terminate the channel while
another class was mid-request. Removed `close()` calls from
`@AfterAll` in all test classes that obtained connections from
`TestResourcesManager`. Connections are now closed exclusively in
`TestResourcesManager.cleanupResources()` at the end of the run.

**ResponseMetadata tests — static connection map race**

The `ResponseMetadata*` tests create their own `Pinecone` client with a
listener interceptor, but `getIndexConnection()` uses `computeIfAbsent`
on the shared static map — whichever class first creates a connection
for the shared index name wins. If another class won the race, the
`ResponseMetadata*` tests got a listener-less connection and
captured nothing. Fixed by constructing `PineconeConnection` directly
(bypassing `computeIfAbsent`) using a host exposed via
`TestResourcesManager.getOrCreateServerlessIndexHost()`. Each
`ResponseMetadata*` test now owns its connection and closes it in its
own `@AfterAll`.

**UpsertDescribeIndexStatsAndDeletePodTest / ...ServerlessTest — shared
mutable counter**

A `static namespaceVectorCount` field was shared and mutated across all
test methods. Each test now creates its own isolated namespace and
tracks its own local count, with null-safe assertions for the case where
a deleted namespace is removed from the stats map.

**NamespacesTest — cross-test namespace count interference**

Both sync and async tests asserted on exact total namespace counts
against the same shared index. Each test now uses a unique random prefix
and counts only its own namespaces via prefix-filtered `listNamespaces`,
making assertions fully isolated. `Thread.sleep` replaced with
`assertWithRetry`. Async upserts now properly await with `.get()`.

**ListEndpointTest — concurrent write interference**

Count assertions against the shared serverless index were vulnerable to
concurrent writes from parallel classes inflating the results. All
assertions now use prefix-filtered `list()` calls that only count
vectors seeded by `TestResourcesManager` under known prefixes.

**ReadCapacityAndSchemaTest — unnecessary waits + missing cleanup**

Removed `waitUntilIndexIsReady` from tests 1–5 (assertions are on the
create response, not index state). Added `@AfterAll` that deletes all
indexes created by the class, with logged warnings on deletion failure
rather than silent swallowing.

**ConfigureIndexTest — parallel isolation**

Added `@Isolated` since this test mutates a shared pod index's replica
count and pod type, which cannot safely run concurrently with any other
class. Also fixed a string identity comparison (`!= "ready"`) in the
local readiness poll.

**ConnectionsMapTest — size assertions replaced**

`assertEquals(size, 1)` / `assertEquals(size, 2)` assumed the static map
contained only this test's entries, which breaks under parallel
execution when other classes have their own connections in the map.
Replaced with key-presence checks (`assertFalse(containsKey(...))`) and
object-identity checks (`assertSame`) to verify connection reuse without
counting map entries. Also replaced bare `assert` keywords (silently
skipped without `-ea`) with `assertFalse`/`assertSame`. Fixed a
pre-existing typo where `config1.setHost(host2)` was overwriting the
wrong config.

**UpsertAndSearchRecordsTest — cleanup masking failures**

`createIndexForModel` was called before the `try` block, so if it failed
the `finally` clause would call `deleteIndex` on a non-existent index,
replacing the original exception with a not-found error. Moved creation
inside `try` with an `indexCreated` flag so `deleteIndex` only runs when
there is actually an index to clean up. Also replaced
hardcoded sleeps with `waitUntilIndexIsReady` and `assertWithRetry`.

Author: austin-denoble

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 [comment]: <> (When bumping [pc:VERSION_LATEST_RELEASE] create a new entry below)
 ### Unreleased version
+### 6.2.0
+- Add readUnits, upsertedCount, and matchedRecords to ResponseMetadata
+- Add List operation to ResponseMetadataInterceptor 
+
 ### 6.1.0
 - Add ResponseMetadataListener for dataplane operation observability
 

gradle.properties

@@ -1 +1 @@
-pineconeClientVersion = 6.1.0
+pineconeClientVersion = 6.2.0

src/integration/java/io/pinecone/clients/ConnectionsMapTest.java

@@ -14,6 +14,8 @@
 
 import static io.pinecone.helpers.TestUtilities.waitUntilIndexIsReady;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 public class ConnectionsMapTest {
@@ -78,59 +80,36 @@ public void testMultipleIndexesWithMultipleClients() throws InterruptedException
 
         // Create config2 for getting index connection and set the host
         PineconeConfig config2 = new PineconeConfig(System.getenv("PINECONE_API_KEY"));
-        config1.setHost(host2);
+        config2.setHost(host2);
 
 
         // Establish grpc connection for index-1
         Index index1_1 = pinecone1.getIndexConnection(indexName1);
         // Get connections map
-        ConcurrentHashMap<String, PineconeConnection> connectionsMap1_1 = pinecone1.getConnectionsMap();
+        ConcurrentHashMap<String, PineconeConnection> connectionsMap = pinecone1.getConnectionsMap();
 
-        // Verify connectionsMap contains only one <indexName, connection> pair i.e. for index1 and its connection
-        assertEquals(pinecone1.getConnectionsMap().size(), 1);
-        // Verify the value for index1 by comparing its value with host1 in the connectionsMap
-        assertEquals(host1, connectionsMap1_1.get(indexName1).toString());
+        // Verify indexName1 is in the map with the correct host
+        assertEquals(host1, connectionsMap.get(indexName1).toString());
 
         // Establish grpc connection for index-2
         Index index1_2 = pinecone1.getIndexConnection(indexName2);
-        // Get connections map after establishing second connection
-        ConcurrentHashMap<String, PineconeConnection> connectionsMap1_2 = pinecone1.getConnectionsMap();
-
-        // Verify connectionsMap contains two <indexName, connection> pairs i.e. for index1 and index2
-        assertEquals(connectionsMap1_2.size(), 2);
-        // Verify the values by checking host for both indexName1 and indexName2
-        assertEquals(host1, connectionsMap1_2.get(indexName1).toString());
-        assertEquals(host2, connectionsMap1_2.get(indexName2).toString());
-
-        // Establishing connections with index1 and index2 using another pinecone client
-        pinecone2.getConnection(indexName1, config1);
-        ConcurrentHashMap<String, PineconeConnection> connectionsMap2_1 = pinecone1.getConnectionsMap();
-        // Verify the new connections map is pointing to the same reference
-        assert connectionsMap2_1 == connectionsMap1_2;
-        // Verify the size of connections map is still 2 since the connection for index2 was not closed
-        assertEquals(2, connectionsMap2_1.size());
-        // Verify the connection value for index1 is host1
-        assertEquals(host1, connectionsMap2_1.get(indexName1).toString());
-
-        pinecone2.getConnection(indexName2, config2);
-        ConcurrentHashMap<String, PineconeConnection> connectionsMap2_2 = pinecone1.getConnectionsMap();
-        // Verify the new connections map is pointing to the same reference
-        assert connectionsMap2_1 == connectionsMap2_2;
-        // Verify the size of connections map is still 2 since the connections are not closed
-        assertEquals(2, connectionsMap2_2.size());
-        // Verify the values by checking host for both indexName1 and indexName2
-        assertEquals(host1, connectionsMap2_2.get(indexName1).toString());
-        assertEquals(host2, connectionsMap2_2.get(indexName2).toString());
+
+        // Verify both indexes are now in the map with the correct hosts
+        assertEquals(host1, connectionsMap.get(indexName1).toString());
+        assertEquals(host2, connectionsMap.get(indexName2).toString());
+
+        // Connecting a second client to the same indexes should reuse the existing map entries
+        assertSame(connectionsMap, pinecone2.getConnectionsMap());
+        assertSame(connectionsMap.get(indexName1), pinecone2.getConnection(indexName1, config1));
+        assertSame(connectionsMap.get(indexName2), pinecone2.getConnection(indexName2, config2));
 
         // Close the connections
         index1_1.close();
         index1_2.close();
 
-        // Verify the map size is now 0
-        assertEquals(connectionsMap1_1.size(), 0);
-        assertEquals(connectionsMap1_2.size(), 0);
-        assertEquals(connectionsMap2_1.size(), 0);
-        assertEquals(connectionsMap2_2.size(), 0);
+        // Verify the specific entries for this test's indexes were removed
+        assertFalse(connectionsMap.containsKey(indexName1));
+        assertFalse(connectionsMap.containsKey(indexName2));
 
         // Delete the indexes
         pinecone1.deleteIndex(indexName1);

src/integration/java/io/pinecone/helpers/AssertRetry.java

@@ -2,18 +2,15 @@
 
 import io.pinecone.exceptions.PineconeException;
 
-import java.io.IOException;
-import java.util.concurrent.ExecutionException;
-
 public class AssertRetry {
     private static final int maxRetry = 4;
     private static final int delay = 1500;
 
-    public static void assertWithRetry(AssertionRunnable assertionRunnable) throws InterruptedException, PineconeException {
+    public static void assertWithRetry(AssertionRunnable assertionRunnable) throws Exception {
         assertWithRetry(assertionRunnable, 2);
     }
 
-    public static void assertWithRetry(AssertionRunnable assertionRunnable, int backOff) throws AssertionError, InterruptedException {
+    public static void assertWithRetry(AssertionRunnable assertionRunnable, int backOff) throws Exception {
         int retryCount = 0;
         int delayCount = delay;
         boolean success = false;
@@ -23,7 +20,10 @@ public static void assertWithRetry(AssertionRunnable assertionRunnable, int back
             try {
                 assertionRunnable.run();
                 success = true;
-            } catch (AssertionError | ExecutionException | IOException e) {
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                throw e;
+            } catch (AssertionError | Exception e) {
                 errorMessage = e.getLocalizedMessage();
                 retryCount++;
                 delayCount*=backOff;
@@ -38,6 +38,6 @@ public static void assertWithRetry(AssertionRunnable assertionRunnable, int back
 
     @FunctionalInterface
     public interface AssertionRunnable {
-        void run() throws AssertionError, ExecutionException, InterruptedException, IOException, PineconeException;
+        void run() throws Exception;
     }
 }

src/integration/java/io/pinecone/helpers/TestResourcesManager.java

@@ -42,7 +42,7 @@
  */
 public class TestResourcesManager {
     private static final Logger logger = LoggerFactory.getLogger(TestUtilities.class);
-    private static TestResourcesManager instance;
+    private static volatile TestResourcesManager instance;
     private static final String apiKey = System.getenv("PINECONE_API_KEY");
     private final int dimension = System.getenv("DIMENSION") == null
             ? 4
@@ -66,6 +66,10 @@ public class TestResourcesManager {
     private String serverlessIndexName;
     private String collectionName;
     private CollectionModel collectionModel;
+    private Index serverlessIndexConnection;
+    private AsyncIndex serverlessAsyncIndexConnection;
+    private Index podIndexConnection;
+    private AsyncIndex podAsyncIndexConnection;
     private final List<String> vectorIdsForDefaultNamespace = Arrays.asList("def-id1", "def-id2", "def-prefix-id3", "def-prefix-id4");
     private final List<String> vectorIdsForCustomNamespace = Arrays.asList("cus-id1", "cus-id2", "cus-prefix-id3", "cus" +
             "-prefix-id4");
@@ -85,7 +89,7 @@ private TestResourcesManager() {
      *
      * @return the {@link TestResourcesManager} instance.
      */
-    public static TestResourcesManager getInstance() {
+    public static synchronized TestResourcesManager getInstance() {
         if (instance == null) {
             instance = new TestResourcesManager();
         }
@@ -185,8 +189,22 @@ public List<String> getVectorIdsFromCustomNamespace() {
      *
      * @return a {@link Index} connection to the serverless index.
      */
-    public  Index getOrCreateServerlessIndexConnection() throws InterruptedException {
-        return getInstance().pineconeClient.getIndexConnection(getOrCreateServerlessIndex());
+    /**
+     * Gets the host for the shared serverless index. Creates the index first if it doesn't exist.
+     * Used by tests that need to construct their own PineconeConnection (e.g. to attach a custom listener)
+     * without going through the shared static connection cache.
+     *
+     * @return the host URL of the shared serverless index.
+     */
+    public synchronized String getOrCreateServerlessIndexHost() throws InterruptedException {
+        return pineconeClient.describeIndex(getOrCreateServerlessIndex()).getHost();
+    }
+
+    public synchronized Index getOrCreateServerlessIndexConnection() throws InterruptedException {
+        if (serverlessIndexConnection == null) {
+            serverlessIndexConnection = pineconeClient.getIndexConnection(getOrCreateServerlessIndex());
+        }
+        return serverlessIndexConnection;
     }
 
     /**
@@ -195,8 +213,11 @@ public  Index getOrCreateServerlessIndexConnection() throws InterruptedException
      *
      * @return a {@link AsyncIndex} connection to the serverless index.
      */
-    public AsyncIndex getOrCreateServerlessAsyncIndexConnection() throws InterruptedException {
-        return getInstance().pineconeClient.getAsyncIndexConnection(getOrCreateServerlessIndex());
+    public synchronized AsyncIndex getOrCreateServerlessAsyncIndexConnection() throws InterruptedException {
+        if (serverlessAsyncIndexConnection == null) {
+            serverlessAsyncIndexConnection = pineconeClient.getAsyncIndexConnection(getOrCreateServerlessIndex());
+        }
+        return serverlessAsyncIndexConnection;
     }
 
     /**
@@ -205,8 +226,11 @@ public AsyncIndex getOrCreateServerlessAsyncIndexConnection() throws Interrupted
      *
      * @return a {@link Index} connection to the pod index.
      */
-    public  Index getOrCreatePodIndexConnection() throws InterruptedException {
-        return getInstance().pineconeClient.getIndexConnection(getOrCreatePodIndex());
+    public synchronized Index getOrCreatePodIndexConnection() throws InterruptedException {
+        if (podIndexConnection == null) {
+            podIndexConnection = pineconeClient.getIndexConnection(getOrCreatePodIndex());
+        }
+        return podIndexConnection;
     }
 
     /**
@@ -215,8 +239,11 @@ public  Index getOrCreatePodIndexConnection() throws InterruptedException {
      *
      * @return a {@link AsyncIndex} connection to the pod index.
      */
-    public AsyncIndex getOrCreatePodAsyncIndexConnection() throws InterruptedException {
-        return getInstance().pineconeClient.getAsyncIndexConnection(getOrCreatePodIndex());
+    public synchronized AsyncIndex getOrCreatePodAsyncIndexConnection() throws InterruptedException {
+        if (podAsyncIndexConnection == null) {
+            podAsyncIndexConnection = pineconeClient.getAsyncIndexConnection(getOrCreatePodIndex());
+        }
+        return podAsyncIndexConnection;
     }
 
     /**
@@ -225,7 +252,7 @@ public AsyncIndex getOrCreatePodAsyncIndexConnection() throws InterruptedExcepti
      *
      * @return the {@link IndexModel} of the pod index.
      */
-    public IndexModel getOrCreatePodIndexModel() throws InterruptedException {
+    public synchronized IndexModel getOrCreatePodIndexModel() throws InterruptedException {
         podIndexModel = pineconeClient.describeIndex(getOrCreatePodIndex());
         return podIndexModel;
     }
@@ -236,7 +263,7 @@ public IndexModel getOrCreatePodIndexModel() throws InterruptedException {
      *
      * @return the {@link IndexModel} of the serverless index.
      */
-    public IndexModel getOrCreateServerlessIndexModel() throws InterruptedException {
+    public synchronized IndexModel getOrCreateServerlessIndexModel() throws InterruptedException {
         serverlessIndexModel = pineconeClient.describeIndex(getOrCreateServerlessIndex());
         return serverlessIndexModel;
     }
@@ -247,7 +274,7 @@ public IndexModel getOrCreateServerlessIndexModel() throws InterruptedException
      *
      * @return the {@link CollectionModel} of the serverless index.
      */
-    public CollectionModel getOrCreateCollectionModel() throws InterruptedException {
+    public synchronized CollectionModel getOrCreateCollectionModel() throws InterruptedException {
         collectionModel = pineconeClient.describeCollection(getOrCreateCollection());
         return collectionModel;
     }
@@ -257,6 +284,19 @@ public CollectionModel getOrCreateCollectionModel() throws InterruptedException
      * after all tests have finished running.
      */
     public void cleanupResources() {
+        if (serverlessIndexConnection != null) {
+            serverlessIndexConnection.close();
+        }
+        if (serverlessAsyncIndexConnection != null) {
+            serverlessAsyncIndexConnection.close();
+        }
+        if (podIndexConnection != null) {
+            podIndexConnection.close();
+        }
+        if (podAsyncIndexConnection != null) {
+            podAsyncIndexConnection.close();
+        }
+
         if (podIndexName != null) {
             pineconeClient.deleteIndex(podIndexName);
         }
@@ -280,7 +320,7 @@ public void cleanupResources() {
      * @throws InterruptedException if the thread is interrupted while waiting for the index to be ready.
      * @throws PineconeException if the API encounters an error during index creation or if any of the arguments are invalid.
      */
-    public String getOrCreatePodIndex() throws InterruptedException, PineconeException {
+    public synchronized String getOrCreatePodIndex() throws InterruptedException, PineconeException {
         if (podIndexName != null) {
             return podIndexName;
         }
@@ -311,7 +351,7 @@ public String getOrCreatePodIndex() throws InterruptedException, PineconeExcepti
      * @throws InterruptedException if the thread is interrupted while waiting for the index to be ready.
      * @throws PineconeException if the API encounters an error during index creation or if any of the arguments are invalid.
      */
-    public String getOrCreateServerlessIndex() throws InterruptedException, PineconeException {
+    public synchronized String getOrCreateServerlessIndex() throws InterruptedException, PineconeException {
         if (this.serverlessIndexName != null) {
             return this.serverlessIndexName;
         }
@@ -344,7 +384,7 @@ public String getOrCreateServerlessIndex() throws InterruptedException, Pinecone
      * @throws InterruptedException if the thread is interrupted while waiting for the collection to be ready.
      * @throws PineconeException if the API encounters an error during collection creation.
      */
-    public String getOrCreateCollection() throws InterruptedException, PineconeException {
+    public synchronized String getOrCreateCollection() throws InterruptedException, PineconeException {
         if (collectionName != null) {
             return collectionName;
         }
@@ -359,13 +399,13 @@ public String getOrCreateCollection() throws InterruptedException, PineconeExcep
         // Wait until collection is ready
         int timeWaited = 0;
         String collectionReady = collectionModel.getStatus().toLowerCase();
-        while (collectionReady != "ready" && timeWaited < 120000) {
+        while (!"ready".equals(collectionReady) && timeWaited < 120000) {
             logger.info("Waiting for collection " + collectionName + " to be ready. Waited " + timeWaited + " " +
                     "milliseconds...");
             Thread.sleep(5000);
             timeWaited += 5000;
             collectionModel = pineconeClient.describeCollection(collectionName);
-            collectionReady = collectionModel.getStatus();
+            collectionReady = collectionModel.getStatus().toLowerCase();
         }
 
         if (timeWaited > 120000) {

src/integration/java/io/pinecone/integration/controlPlane/pod/CollectionTest.java

@@ -41,23 +41,23 @@ public class CollectionTest {
     private static String namespace;
 
     @BeforeAll
-    public static void setUp() throws InterruptedException {
+    public static void setUp() throws Exception {
         indexName = indexManager.getOrCreatePodIndex();
         collectionName = indexManager.getOrCreateCollection();
         collection = indexManager.getOrCreateCollectionModel();
         namespace = indexManager.getDefaultNamespace();
     }
 
     @AfterAll
-    public static void cleanUp() throws InterruptedException {
+    public static void cleanUp() throws Exception {
         // Clean up indexes
         for (String index : indexesToCleanUp) {
             pineconeClient.deleteIndex(index);
         }
     }
 
     @Test
-    public void testIndexFromCollectionHappyPath() throws InterruptedException {
+    public void testIndexFromCollectionHappyPath() throws Exception {
         // Verify collection is listed
         List<CollectionModel> collectionList = pineconeClient.listCollections().getCollections();
         boolean collectionFound = false;
@@ -115,7 +115,7 @@ public void testIndexFromCollectionHappyPath() throws InterruptedException {
     }
 
     @Test
-    public void testCreateIndexFromCollectionWithDiffMetric() throws InterruptedException {
+    public void testCreateIndexFromCollectionWithDiffMetric() throws Exception {
         // Use a different metric than the source index
         String[] metrics = {
                 "cosine",
@@ -232,7 +232,7 @@ public void testCreateIndexWithMismatchedDimension() {
     }
 
     @Test
-    public void testCreateCollectionFromNotReadyIndex() throws InterruptedException {
+    public void testCreateCollectionFromNotReadyIndex() throws Exception {
         String notReadyIndexName = RandomStringBuilder.build("from-coll", 8);
         String newCollectionName = RandomStringBuilder.build("coll-", 8);
         try {