chore: improve metadata service error handling (#1902)

Improved error handling in `google/auth/compute_engine/_metadata.py` to
provide more informative error messages when retries are exhausted.

The logic now handles two distinct failure modes:
1.  **Connection Errors (Exceptions):**
- Exceptions caught during the request (e.g., connection refused) are
stored in `last_exception`.
- If the retry loop exhausts and `last_exception` is set, a
`TransportError` is raised that chains the original exception. This
preserves the stack trace and specific error type for debugging.

2.  **Retryable HTTP Status Codes:**
- If a request completes but returns a retryable status code (e.g., 500,
503), `last_exception` is cleared (set to `None`).
- If the retry loop exhausts due to repeated retryable status codes, a
`TransportError` is raised that includes the `response.status` and the
response body (`error_details`). This ensures the specific server error
message is visible.

This addresses feedback from PR 1637 by ensuring that "Ran out of
retries" scenarios provide the most relevant context: either the
underlying exception or the final HTTP error response.

---
*PR created automatically by Jules for task
[6226991344715693997](https://jules.google.com/task/6226991344715693997)
started by @chalmerlowe*

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: Chalmer Lowe <chalmerlowe@google.com>

Author: google-labs-jules[bot]

google/auth/compute_engine/_metadata.py

@@ -294,7 +294,7 @@ def get(
     url = _helpers.update_query(base_url, query_params)
 
     backoff = ExponentialBackoff(total_attempts=retry_count)
-    failure_reason = None
+    last_exception = None
     for attempt in backoff:
         try:
             response = request(
@@ -308,13 +308,10 @@ def get(
                     retry_count,
                     response.status,
                 )
-                failure_reason = (
-                    response.data.decode("utf-8")
-                    if hasattr(response.data, "decode")
-                    else response.data
-                )
+                last_exception = None
                 continue
             else:
+                last_exception = None
                 break
 
         except exceptions.TransportError as e:
@@ -325,14 +322,27 @@ def get(
                 retry_count,
                 e,
             )
-            failure_reason = e
+            last_exception = e
     else:
-        raise exceptions.TransportError(
-            "Failed to retrieve {} from the Google Compute Engine "
-            "metadata service. Compute Engine Metadata server unavailable due to {}".format(
-                url, failure_reason
+        if last_exception:
+            raise exceptions.TransportError(
+                "Failed to retrieve {} from the Google Compute Engine "
+                "metadata service. Compute Engine Metadata server unavailable. "
+                "Last exception: {}".format(url, last_exception)
+            ) from last_exception
+        else:
+            error_details = (
+                response.data.decode("utf-8")
+                if hasattr(response.data, "decode")
+                else response.data
+            )
+            raise exceptions.TransportError(
+                "Failed to retrieve {} from the Google Compute Engine "
+                "metadata service. Compute Engine Metadata server unavailable. "
+                "Response status: {}\nResponse details:\n{}".format(
+                    url, response.status, error_details
+                )
             )
-        )
 
     content = _helpers.from_bytes(response.data)
 

tests/compute_engine/test__metadata.py

@@ -407,7 +407,7 @@ def test_get_failure_connection_failed(mock_sleep):
         _metadata.get(request, PATH)
 
     assert excinfo.match(
-        r"Compute Engine Metadata server unavailable due to failure message"
+        r"Compute Engine Metadata server unavailable. Last exception: failure message"
     )
 
     request.assert_called_with(
@@ -426,7 +426,7 @@ def test_get_too_many_requests_retryable_error_failure():
         _metadata.get(request, PATH)
 
     assert excinfo.match(
-        r"Compute Engine Metadata server unavailable due to too many requests"
+        r"Compute Engine Metadata server unavailable. Response status: 429\nResponse details:\ntoo many requests"
     )
 
     request.assert_called_with(