chore: Fix CI cleanup utility classpath issues

[jhamon]

Fix CI cleanup utility classpath issues and improve IndexCleanupUtility reliability

Problem

The CI cleanup workflows were failing with okhttp3/Interceptor classpath errors because they used build/libs/* which includes multiple JAR files (regular JAR, shadow JAR, javadoc, sources). When Java loads classes from multiple JARs, it can cause conflicts because the shadow JAR relocates packages like okhttp3 to io.pinecone.shadow.okhttp3.

Additionally, the IndexCleanupUtility was experiencing two issues:

1. Rate limiting: Deleting indexes too quickly was overwhelming the backend
2. Timeout errors: Delete operations were timing out with SocketTimeoutException because the default OkHttpClient uses ~10 second timeouts, which is insufficient for long-running delete operations on large indexes

Solution

1. Fix CI Workflow Classpath Issues

Files changed:

• .github/workflows/pr.yml
• .github/workflows/cleanup-test-resources.yml

Changes:

• Changed classpath from build/libs/* to build/libs/*-all.jar to use only the shadow JAR
• Removed unnecessary build/classes/java/main path from cleanup-test-resources.yml
• Fixed linting error: changed age_threshold_days default from string '1' to number 1

This ensures only the shadow JAR (which contains all dependencies with relocated packages) is used, preventing classpath conflicts.

2. Add Rate Limiting to IndexCleanupUtility

File changed: src/main/java/io/pinecone/helpers/IndexCleanupUtility.java

Changes:

• Increased delay between deletions from 1 second to 30 seconds
• Added informative log message: "Waiting 30 seconds before next deletion..."
• Applied to both index and collection deletion methods

This prevents overwhelming the backend when cleaning up many resources.

3. Add HTTP Timeout Configuration

File changed: src/main/java/io/pinecone/helpers/IndexCleanupUtility.java

Changes:

• Configure custom OkHttpClient with longer timeouts:
  • Connect timeout: 30 seconds
  • Read timeout: 120 seconds (accommodates long-running delete operations)
  • Write timeout: 30 seconds
• Pass custom client to Pinecone.Builder using withOkHttpClient()

This prevents SocketTimeoutException errors during delete operations on large indexes.

Testing

• ✅ Verified unit tests pass: ./gradlew test --tests IndexCleanupUtilityTest
• ✅ Built shadow JAR successfully: ./gradlew shadowJar
• ✅ Tested classpath fix locally: java -cp build/libs/*-all.jar io.pinecone.helpers.IndexCleanupUtility --dry-run
• ✅ Verified 30-second delays are working in actual cleanup runs
• ✅ Confirmed timeout configuration prevents SocketTimeoutException errors

Related Issues

• Fixes CI failures in: https://github.com/pinecone-io/pinecone-java-client/actions/runs/21010756941/job/60404772175
• Related Linear issue: SDK-65 (Improve default HTTP timeouts for control plane operations)

Example Usage

The cleanup utility can now be run reliably in CI:

# In CI workflows
java -cp "build/libs/*-all.jar" io.pinecone.helpers.IndexCleanupUtility

# With dry-run for testing
java -cp "build/libs/*-all.jar" io.pinecone.helpers.IndexCleanupUtility --dry-run

# With custom age threshold
java -cp "build/libs/*-all.jar" io.pinecone.helpers.IndexCleanupUtility --age-threshold-days 7

Impact

• CI Reliability: Cleanup workflows will no longer fail due to classpath conflicts
• Backend Protection: 30-second delays prevent overwhelming the backend during bulk deletions
• User Experience: Delete operations complete successfully without timeout errors, even for large indexes
• Maintainability: Centralized timeout configuration makes the utility more robust

Notes

The timeout configuration in IndexCleanupUtility is a temporary workaround. The root cause (default timeouts being too short) is being addressed in SDK-65, which will set reasonable defaults at the SDK level. Once that's implemented, the custom timeout configuration in IndexCleanupUtility can be removed.

---

Note

Sets sane HTTP timeout defaults in the Java SDK and stabilizes CI cleanup by relying on the shadow JAR and throttling deletions.

• SDK: Pinecone.buildOkHttpClient now defaults to 30s connect / 120s read / 30s write; integration tests simplified to use defaults
• Docs: Added README section for default timeouts and custom OkHttpClient; updated CHANGELOG
• CI: Workflows run cleanup via build/libs/*-all.jar and fix input default type; add .env.example and ignore .env
• Cleanup utility: Increase delay between deletions to 30s with log message to avoid backend pressure
• Tests: Tweak read capacity test sizing (1 shard/replica)

^{Written by Cursor Bugbot for commit ca731c6. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Undocumented test configuration change reduces test coverage

Low Severity

The ScalingConfigManual configuration was changed from shards(2).replicas(2) to shards(1).replicas(1) in the createServerlessIndexWithDedicatedReadCapacity test. This change is not mentioned in the PR description and appears unrelated to the PR's stated purpose of fixing CI cleanup utility classpath issues and adding timeout configuration. The test now validates a minimal dedicated read capacity configuration instead of testing multi-shard/multi-replica setups.