Skip to content

feat(storage): append troubleshooting hints to fetch/TLS and 401 errors - #9875

Draft
thiyaguk09 wants to merge 3 commits into
googleapis:mainfrom
thiyaguk09:feat/improve-tls-error-handling
Draft

thiyaguk09 wants to merge 3 commits into
googleapis:mainfrom
thiyaguk09:feat/improve-tls-error-handling

Conversation

@thiyaguk09

Copy link
Copy Markdown
Contributor

Description

Appends CPU starvation hints to fetch/TLS timeout and 401 storage errors.

Impact

Helps Kubernetes users diagnose event-loop starvation behind timeouts and expired tokens.

Changes

  • Added augmentError and appendErrorHint in handwritten/storage/src/util.ts to append troubleshooting hints without rewrapping errors or losing original prototypes, stack traces, or cause properties:
    • Native fetch / undici timeouts (TypeError: fetch failed with cause.code === 'UND_ERR_CONNECT_TIMEOUT' or cause.message.includes('TLS'), both direct and GaxiosError-wrapped).
    • 401 Invalid Credentials responses (err.code === 401 or err.status === 401).
  • Wired augmentError into StorageTransport#makeRequest (handwritten/storage/src/storage-transport.ts), Upload#makeRequest / Upload#makeRequestStream / Upload#responseHandler (handwritten/storage/src/resumable-upload.ts), and XMLMultiPartUploadHelper (handwritten/storage/src/transfer-manager.ts).
  • Added a Troubleshooting: Timeouts and 401 Invalid Credentials section to handwritten/storage/README.md detailing event-loop starvation in constrained Kubernetes pods and recommended mitigations.

Testing

  • Added unit tests in handwritten/storage/test/storage-transport.ts verifying:
    • fetch failed errors with UND_ERR_CONNECT_TIMEOUT and TLS handshake cause messages include the CPU starvation hint while preserving TypeError prototype, stack, and cause.
    • GaxiosError-wrapped fetch failed errors include the CPU starvation hint while preserving GaxiosError prototype and cause.
    • fetch failed errors with unrelated causes (e.g., ECONNREFUSED) are left unchanged.
    • 401 responses include the in-flight token expiration hint while preserving GaxiosError prototype, stack, and cause.
    • Frozen error objects are safely reconstructed with original prototype, stack, and cause intact.
  • Verified CJS/ESM compilation, pnpm test, and pnpm run lint in handwritten/storage.

… 401 errors

Appends actionable CPU starvation troubleshooting hints to native fetch/undici connection or TLS handshake timeouts and 401 Invalid Credentials errors while preserving original error prototypes, stack traces, and cause properties. Also documents troubleshooting guidance in README.md and adds unit tests in test/storage-transport.ts.
@product-auto-label product-auto-label Bot added the api: storage Issues related to the Cloud Storage API. label Nov 17, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces error augmentation to append troubleshooting hints for native fetch/TLS timeouts and 401 Invalid Credentials errors, particularly targeting issues seen in constrained environments like Kubernetes. It adds a troubleshooting section to the README, implements the augmentError utility to safely append hints without losing error metadata (even for frozen objects), integrates this utility across several modules, and adds comprehensive unit tests. The review feedback correctly identifies a potential runtime crash in storage-transport.ts where directly mutating err.code on a frozen error object would throw a TypeError in strict mode, and suggests wrapping the assignment in a try/catch block.

Guards err.code, err.message, and err.errors assignments in decorateError via setErrorProperty so frozen or read-only error objects do not throw TypeError in strict mode while preserving prototype, symbol keys, stack, and cause.
@thiyaguk09

Copy link
Copy Markdown
Contributor Author

/Gemini review

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces error augmentation functionality to append helpful troubleshooting hints (such as CPU starvation or token expiration warnings) to native fetch/TLS timeouts and 401 Invalid Credentials errors. It updates resumable-upload.ts, storage-transport.ts, and transfer-manager.ts to utilize these new utilities, documents the troubleshooting steps in the README, and adds comprehensive unit tests. The review feedback highlights two key improvement opportunities in util.ts: first, ensuring that all copied descriptors (including accessors) are marked as configurable when cloning frozen or non-configurable error objects to prevent runtime TypeErrors; second, making the wrapped fetch error detection more robust by removing the strict outer message check.

Comment thread handwritten/storage/src/util.ts Resolved
Comment thread handwritten/storage/src/util.ts Resolved
…h errors

Marks accessor descriptors as configurable when cloning frozen errors in setErrorProperty and removes the strict outer message check when detecting GaxiosError-wrapped TypeError('fetch failed') errors.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api: storage Issues related to the Cloud Storage API.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant