fix(storage): Invocation ID is not retained on multipart upload retries

[thiyaguk09]

Hoists the generation of persistentInvocationId to the beginning of the
upload process in Bucket.upload and File.save. This ensures that retried multipart upload attempts reuse the same invocation ID in the x-goog-api-client header, rather than generating a new one for each attempt.

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

[gemini-code-assist]

Code Review

This pull request implements persistent invocationId tracking across the upload lifecycle and refactors the StorageTransport.makeRequest method to improve project ID resolution and header management. Feedback focuses on critical issues in the makeRequest refactor, including a bug where the request body is incorrectly assigned to an undefined property, thread-safety risks from unconditionally clearing shared interceptors, and an inconsistent response handler that mutates data and breaks return type expectations.

[gemini-code-assist]

The responseHandler introduces an inconsistency in the return type of makeRequest. If the response data is an object, it returns the data mutated with headers and status. If the response data is not an object (e.g., a string or null), it returns the entire GaxiosResponse object. This violates the expected return type T and will likely cause runtime errors in callers expecting raw data. Additionally, mutating the data object directly is risky as it might be a frozen object or a class instance that doesn't support these extra properties. It is recommended to return resp.data consistently as before.

      const responseHandler = (resp: GaxiosResponse<T>) => resp.data;

[thiyaguk09]

required for retry operations

[Dhriti07]

Please elaborate as stated in the above comment.

[thiyaguk09]

To preserve backward compatibility for legacy SDK methods that expect resource metadata objects to carry .headers and .status properties without introducing runtime errors or mutating binary data, we added a strict validation check to ensure these properties are strictly injected into plain JSON response objects and never onto Buffer or Stream payloads.

[Dhriti07]

I agree with using isPlanObject to avoid mutating Buffer or Stream payloads.

However the issue mentioned above refers to the fallback "return resp;" statement. If the payload is a Buffer or Stream and the check fails, returning the entire GaxiosResponse wrapper instead of the raw data might break backward compatibility for binary downloads, since it previously resolved with just the data.

What do you think about returning data instead in that fallback case to keep the return types consistent?

[thiyaguk09]

Great catch. Simply returning data broke resumable uploads, which rely on resp.headers.location when the API returns an empty string. I've updated the logic to handle all three scenarios correctly:

• Plain objects: Mutate and return data.
• Buffers/Streams (non-plain objects): Return raw data to protect binary downloads.
• Primitives (empty strings/null): Return the full resp wrapper so session URIs can still be read from the headers.

[Dhriti07]

Do we have any presubmits or checks to prevent such kind of breakages ?

[thiyaguk09]

Yes, our conformance test suite acts as the safety net for this (referenced in draft PR #7917). In fact, it was the conformance tests that caught this exact breakage. When I tested changing the fallback to just return data, the bucketUploadResumable test scenarios immediately failed because they couldn't extract the session URI from the headers. These test suites run during presubmit to prevent regressions like this from merging.

[thiyaguk09]

Moved to draft; its required PR is #8235 to merge.