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

Improves CI cleanup reliability and makes deletion operations more resilient.

• CI: Update pr.yml and cleanup-test-resources.yml to run IndexCleanupUtility with build/libs/*-all.jar (shadow JAR only) and fix input default types
• Helper: In IndexCleanupUtility.java, configure a custom OkHttpClient with longer timeouts and add a 30s delay (with logs) after index/collection deletions
• Repo hygiene: Add .env.example with PINECONE_API_KEY and ignore .env files; minor wording fix in .cursor docs

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