chore: add request-response log helpers (#1685)

* chore: add request-response log helpers

* fix presubmit

Author: ohmayr

google/auth/_helpers.py

@@ -19,7 +19,9 @@
 import datetime
 from email.message import Message
 import hashlib
+import logging
 import sys
+from typing import Optional, Dict, Any
 import urllib
 
 from google.auth import exceptions
@@ -28,15 +30,8 @@
 # expiry.
 REFRESH_THRESHOLD = datetime.timedelta(minutes=3, seconds=45)
 
-_SENSITIVE_FIELDS = {
-    "accessToken",
-    "access_token",
-    "id_token",
-    "client_id",
-    "refresh_token",
-    "client_secret",
-}
-
+# TODO(https://github.com/googleapis/google-auth-library-python/issues/1684): Audit and update the list below.
+_SENSITIVE_FIELDS = {"accessToken", "access_token", "id_token", "client_id", "refresh_token", "client_secret"}
 
 def copy_docstring(source_class):
     """Decorator that copies a method's docstring from another class.
@@ -311,3 +306,34 @@ def _hash_value(value, field_name: str) -> str:
     hash_object.update(encoded_value)
     hex_digest = hash_object.hexdigest()
     return f"hashed_{field_name}-{hex_digest}"
+
+
+def request_log(logger: logging.Logger, method: str, url: str, body: Optional[Any], headers: Optional[Dict[str, str]]) -> None:
+    """
+    Logs an HTTP request at the DEBUG level.
+
+    Args:
+        logger: The logging.Logger instance to use.
+        method: The HTTP method (e.g., "GET", "POST").
+        url: The URL of the request.
+        body: The request body (can be None).
+        headers: The request headers (can be None).
+    """
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1680): Log only if enabled.
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1682): Add httpRequest extra to log event.
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1681): Hash sensitive information.
+    logger.debug("Making request: %s %s", method, url)
+
+
+def response_log(logger: logging.Logger, response: Any) -> None:
+    """
+    Logs an HTTP response at the DEBUG level.
+
+    Args:
+        logger: The logging.Logger instance to use.
+        response: The HTTP response object to log.
+    """
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1680): Log only if enabled.
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1683): Add httpResponse extra to log event.
+    # TODO(https://github.com/googleapis/google-auth-library-python/issues/1681): Hash sensitive information.
+    logger.debug("Response received...")

google/auth/aio/transport/aiohttp.py

@@ -16,6 +16,7 @@
 """
 
 import asyncio
+import logging
 from typing import AsyncGenerator, Mapping, Optional
 
 try:
@@ -29,6 +30,8 @@
 from google.auth import exceptions
 from google.auth.aio import transport
 
+_LOGGER = logging.getLogger(__name__)
+
 
 class Response(transport.Response):
     """
@@ -155,6 +158,7 @@ async def __call__(
                 self._session = aiohttp.ClientSession()
 
             client_timeout = aiohttp.ClientTimeout(total=timeout)
+            _helpers.request_log(_LOGGER, method, url, body, headers)
             response = await self._session.request(
                 method,
                 url,
@@ -163,6 +167,7 @@ async def __call__(
                 timeout=client_timeout,
                 **kwargs,
             )
+            _helpers.response_log(_LOGGER, response)
             return Response(response)
 
         except aiohttp.ClientError as caught_exc:

google/auth/transport/_aiohttp_requests.py

@@ -24,12 +24,17 @@
 import functools
 
 import aiohttp  # type: ignore
+import logging
 import urllib3  # type: ignore
 
 from google.auth import exceptions
 from google.auth import transport
+from google.auth import _helpers
 from google.auth.transport import requests
 
+
+_LOGGER = logging.getLogger(__name__)
+
 # Timeout can be re-defined depending on async requirement. Currently made 60s more than
 # sync timeout.
 _DEFAULT_TIMEOUT = 180  # in seconds
@@ -182,10 +187,11 @@ async def __call__(
                 self.session = aiohttp.ClientSession(
                     auto_decompress=False
                 )  # pragma: NO COVER
-            requests._LOGGER.debug("Making request: %s %s", method, url)
+            _helpers.request_log(_LOGGER, method, url, body, headers)
             response = await self.session.request(
                 method, url, data=body, headers=headers, timeout=timeout, **kwargs
             )
+            _helpers.response_log(_LOGGER, response)
             return _CombinedResponse(response)
 
         except aiohttp.ClientError as caught_exc:

google/auth/transport/_http_client.py

@@ -21,6 +21,7 @@
 
 from google.auth import exceptions
 from google.auth import transport
+from google.auth import _helpers
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -99,10 +100,11 @@ def __call__(
         connection = http_client.HTTPConnection(parts.netloc, timeout=timeout)
 
         try:
-            _LOGGER.debug("Making request: %s %s", method, url)
 
+            _helpers.request_log(_LOGGER, method, url, body, headers)
             connection.request(method, path, body=body, headers=headers, **kwargs)
             response = connection.getresponse()
+            _helpers.response_log(_LOGGER, response)
             return Response(response)
 
         except (http_client.HTTPException, socket.error) as caught_exc:

google/auth/transport/requests.py

@@ -37,6 +37,7 @@
 from google.auth import environment_vars
 from google.auth import exceptions
 from google.auth import transport
+from google.auth import _helpers
 import google.auth.transport._mtls_helper
 from google.oauth2 import service_account
 
@@ -182,10 +183,11 @@ def __call__(
             google.auth.exceptions.TransportError: If any exception occurred.
         """
         try:
-            _LOGGER.debug("Making request: %s %s", method, url)
+            _helpers.request_log(_LOGGER, method, url, body, headers)
             response = self.session.request(
                 method, url, data=body, headers=headers, timeout=timeout, **kwargs
             )
+            _helpers.response_log(_LOGGER, response)
             return _Response(response)
         except requests.exceptions.RequestException as caught_exc:
             new_exc = exceptions.TransportError(caught_exc)

google/auth/transport/urllib3.py

@@ -45,6 +45,7 @@
 from google.auth import environment_vars
 from google.auth import exceptions
 from google.auth import transport
+from google.auth import _helpers
 from google.oauth2 import service_account
 
 if version.parse(urllib3.__version__) >= version.parse("2.0.0"):  # pragma: NO COVER
@@ -136,10 +137,11 @@ def __call__(
             kwargs["timeout"] = timeout
 
         try:
-            _LOGGER.debug("Making request: %s %s", method, url)
+            _helpers.request_log(_LOGGER, method, url, body, headers)
             response = self.http.request(
                 method, url, body=body, headers=headers, **kwargs
             )
+            _helpers.response_log(_LOGGER, response)
             return _Response(response)
         except urllib3.exceptions.HTTPError as caught_exc:
             new_exc = exceptions.TransportError(caught_exc)