feat(gax): surface actionable error messages with upload session URL and stream requirements

[whowes]

Augments terminal failure exceptions with the active upload session URL to aid debugging and session recovery. Clarifies error messages when a server committed offset falls below the buffer base offset.

[gemini-code-assist]

Code Review

This pull request refactors error handling and status tracking during resumable uploads by augmenting exceptions with the upload URL or endpoint to make them more actionable. It also simplifies synchronization in ResumableUploadChunkCoordinator, improves error messages for stream rewinding, and adds comprehensive unit tests. The review feedback highlights two critical issues: first, removing synchronization from closePayload() introduces a potential race condition on payloadClosed, which should be resolved using an explicit lock; second, recreating exceptions in augmentWithUrl discards the original stack trace, which should be preserved by copying it to the new exception instance.

[gemini-code-assist]

Removing the lock from closePayload() introduces a potential race condition and visibility issues on the payloadClosed field. Since this is performance-sensitive code, prefer using an explicit lock over the synchronized keyword to protect the shared state while ensuring thread safety and visibility.

  private @Nullable IOException closePayload() {
    lock.lock();
    try {
      if (payloadClosed) {
        return null;
      }
      payloadClosed = true;
    } finally {
      lock.unlock();
    }

References

1. In performance-sensitive code, prefer using explicit locks over the 'synchronized' keyword to protect shared state while ensuring thread safety and visibility.

[gemini-code-assist]

When recreating the exception with the augmented message, the original stack trace of t is lost because a new exception instance is constructed and its stack trace is initialized to the current thread's execution point. To preserve the original stack trace for easier debugging, we should copy the stack trace from the original exception t to the augmented exception.

Suggested change

	if (augmented != t) {
	for (Throwable suppressed : t.getSuppressed()) {
	augmented.addSuppressed(suppressed);
	}
	payloadClosed = true;
	}
	if (augmented != t) {
	augmented.setStackTrace(t.getStackTrace());
	for (Throwable suppressed : t.getSuppressed()) {
	augmented.addSuppressed(suppressed);
	}
	}

[sonarqubecloud]

Quality Gate passed for 'gapic-generator-java-root'

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
82.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud