google-auth 2.25.2__tar.gz → 2.26.0__tar.gz

{google-auth-2.25.2/google_auth.egg-info → google-auth-2.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-auth
-Version: 2.25.2
+Version: 2.26.0
 Summary: Google Authentication Library
 Home-page: https://github.com/googleapis/google-auth-library-python
 Author: Google Cloud Platform

google-auth-2.26.0/google/auth/_refresh_worker.py

@@ -0,0 +1,98 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import copy
+import logging
+import threading
+
+import google.auth.exceptions as e
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class RefreshThreadManager:
+    """
+    Organizes exactly one background job that refresh a token.
+    """
+
+    def __init__(self):
+        """Initializes the manager."""
+
+        self._worker = None
+        self._lock = threading.Lock()  # protects access to worker threads.
+
+    def start_refresh(self, cred, request):
+        """Starts a refresh thread for the given credentials.
+        The credentials are refreshed using the request parameter.
+        request and cred MUST not be None
+
+        Returns True if a background refresh was kicked off. False otherwise.
+
+        Args:
+            cred: A credentials object.
+            request: A request object.
+        Returns:
+          bool
+        """
+        if cred is None or request is None:
+            raise e.InvalidValue(
+                "Unable to start refresh. cred and request must be valid and instantiated objects."
+            )
+
+        with self._lock:
+            if self._worker is not None and self._worker._error_info is not None:
+                return False
+
+            if self._worker is None or not self._worker.is_alive():  # pragma: NO COVER
+                self._worker = RefreshThread(cred=cred, request=copy.deepcopy(request))
+                self._worker.start()
+        return True
+
+    def clear_error(self):
+        """
+      Removes any errors that were stored from previous background refreshes.
+      """
+        with self._lock:
+            if self._worker:
+                self._worker._error_info = None
+
+
+class RefreshThread(threading.Thread):
+    """
+    Thread that refreshes credentials.
+    """
+
+    def __init__(self, cred, request, **kwargs):
+        """Initializes the thread.
+
+        Args:
+            cred: A Credential object to refresh.
+            request: A Request object used to perform a credential refresh.
+            **kwargs: Additional keyword arguments.
+        """
+
+        super().__init__(**kwargs)
+        self._cred = cred
+        self._request = request
+        self._error_info = None
+
+    def run(self):
+        """
+        Perform the credential refresh.
+        """
+        try:
+            self._cred.refresh(self._request)
+        except Exception as err:  # pragma: NO COVER
+            _LOGGER.error(f"Background refresh failed due to: {err}")
+            self._error_info = err

{google-auth-2.25.2 → google-auth-2.26.0}/google/auth/credentials.py

@@ -16,11 +16,13 @@
 """Interfaces for credentials."""
 
 import abc
+from enum import Enum
 import os
 
 from google.auth import _helpers, environment_vars
 from google.auth import exceptions
 from google.auth import metrics
+from google.auth._refresh_worker import RefreshThreadManager
 
 
 class Credentials(metaclass=abc.ABCMeta):
@@ -59,6 +61,9 @@ class Credentials(metaclass=abc.ABCMeta):
         """Optional[str]: The universe domain value, default is googleapis.com
         """
 
+        self._use_non_blocking_refresh = False
+        self._refresh_worker = RefreshThreadManager()
+
     @property
     def expired(self):
         """Checks if the credentials are expired.
@@ -66,10 +71,12 @@ class Credentials(metaclass=abc.ABCMeta):
         Note that credentials can be invalid but not expired because
         Credentials with :attr:`expiry` set to None is considered to never
         expire.
+
+        .. deprecated:: v2.24.0
+          Prefer checking :attr:`token_state` instead.
         """
         if not self.expiry:
             return False
-
         # Remove some threshold from expiry to err on the side of reporting
         # expiration early so that we avoid the 401-refresh-retry loop.
         skewed_expiry = self.expiry - _helpers.REFRESH_THRESHOLD
@@ -81,9 +88,34 @@ class Credentials(metaclass=abc.ABCMeta):
 
         This is True if the credentials have a :attr:`token` and the token
         is not :attr:`expired`.
+
+        .. deprecated:: v2.24.0
+          Prefer checking :attr:`token_state` instead.
         """
         return self.token is not None and not self.expired
 
+    @property
+    def token_state(self):
+        """
+        See `:obj:`TokenState`
+        """
+        if self.token is None:
+            return TokenState.INVALID
+
+        # Credentials that can't expire are always treated as fresh.
+        if self.expiry is None:
+            return TokenState.FRESH
+
+        expired = _helpers.utcnow() >= self.expiry
+        if expired:
+            return TokenState.INVALID
+
+        is_stale = _helpers.utcnow() >= (self.expiry - _helpers.REFRESH_THRESHOLD)
+        if is_stale:
+            return TokenState.STALE
+
+        return TokenState.FRESH
+
     @property
     def quota_project_id(self):
         """Project to use for quota and billing purposes."""
@@ -154,6 +186,25 @@ class Credentials(metaclass=abc.ABCMeta):
         if self.quota_project_id:
             headers["x-goog-user-project"] = self.quota_project_id
 
+    def _blocking_refresh(self, request):
+        if not self.valid:
+            self.refresh(request)
+
+    def _non_blocking_refresh(self, request):
+        use_blocking_refresh_fallback = False
+
+        if self.token_state == TokenState.STALE:
+            use_blocking_refresh_fallback = not self._refresh_worker.start_refresh(
+                self, request
+            )
+
+        if self.token_state == TokenState.INVALID or use_blocking_refresh_fallback:
+            self.refresh(request)
+            # If the blocking refresh succeeds then we can clear the error info
+            # on the background refresh worker, and perform refreshes in a
+            # background thread.
+            self._refresh_worker.clear_error()
+
     def before_request(self, request, method, url, headers):
         """Performs credential-specific before request logic.
 
@@ -171,11 +222,17 @@ class Credentials(metaclass=abc.ABCMeta):
         # pylint: disable=unused-argument
         # (Subclasses may use these arguments to ascertain information about
         # the http request.)
-        if not self.valid:
-            self.refresh(request)
+        if self._use_non_blocking_refresh:
+            self._non_blocking_refresh(request)
+        else:
+            self._blocking_refresh(request)
+
         metrics.add_metric_header(headers, self._metric_header_for_usage())
         self.apply(headers)
 
+    def with_non_blocking_refresh(self):
+        self._use_non_blocking_refresh = True
+
 
 class CredentialsWithQuotaProject(Credentials):
     """Abstract base for credentials supporting ``with_quota_project`` factory"""
@@ -188,7 +245,7 @@ class CredentialsWithQuotaProject(Credentials):
                 billing purposes
 
         Returns:
-            google.oauth2.credentials.Credentials: A new credentials instance.
+            google.auth.credentials.Credentials: A new credentials instance.
         """
         raise NotImplementedError("This credential does not support quota project.")
 
@@ -209,11 +266,28 @@ class CredentialsWithTokenUri(Credentials):
             token_uri (str): The uri to use for fetching/exchanging tokens
 
         Returns:
-            google.oauth2.credentials.Credentials: A new credentials instance.
+            google.auth.credentials.Credentials: A new credentials instance.
         """
         raise NotImplementedError("This credential does not use token uri.")
 
 
+class CredentialsWithUniverseDomain(Credentials):
+    """Abstract base for credentials supporting ``with_universe_domain`` factory"""
+
+    def with_universe_domain(self, universe_domain):
+        """Returns a copy of these credentials with a modified universe domain.
+
+        Args:
+            universe_domain (str): The universe domain to use
+
+        Returns:
+            google.auth.credentials.Credentials: A new credentials instance.
+        """
+        raise NotImplementedError(
+            "This credential does not support with_universe_domain."
+        )
+
+
 class AnonymousCredentials(Credentials):
     """Credentials that do not provide any authentication information.
 
@@ -422,3 +496,16 @@ class Signing(metaclass=abc.ABCMeta):
         # pylint: disable=missing-raises-doc
         # (pylint doesn't recognize that this is abstract)
         raise NotImplementedError("Signer must be implemented.")
+
+
+class TokenState(Enum):
+    """
+    Tracks the state of a token.
+    FRESH: The token is valid. It is not expired or close to expired, or the token has no expiry.
+    STALE: The token is close to expired, and should be refreshed. The token can be used normally.
+    INVALID: The token is expired or invalid. The token cannot be used for a normal operation.
+    """
+
+    FRESH = 1
+    STALE = 2
+    INVALID = 3

{google-auth-2.25.2 → google-auth-2.26.0}/google/auth/external_account.py

@@ -415,16 +415,8 @@ class Credentials(
         new_cred._metrics_options = self._metrics_options
         return new_cred
 
+    @_helpers.copy_docstring(credentials.CredentialsWithUniverseDomain)
     def with_universe_domain(self, universe_domain):
-        """Create a copy of these credentials with the given universe domain.
-
-        Args:
-            universe_domain (str): The universe domain value.
-
-        Returns:
-            google.auth.external_account.Credentials: A new credentials
-                instance.
-        """
         kwargs = self._constructor_args()
         kwargs.update(universe_domain=universe_domain)
         new_cred = self.__class__(**kwargs)

{google-auth-2.25.2 → google-auth-2.26.0}/google/auth/external_account_authorized_user.py

@@ -43,6 +43,7 @@ from google.auth import exceptions
 from google.oauth2 import sts
 from google.oauth2 import utils
 
+_DEFAULT_UNIVERSE_DOMAIN = "googleapis.com"
 _EXTERNAL_ACCOUNT_AUTHORIZED_USER_JSON_TYPE = "external_account_authorized_user"
 
 
@@ -75,6 +76,7 @@ class Credentials(
         revoke_url=None,
         scopes=None,
         quota_project_id=None,
+        universe_domain=_DEFAULT_UNIVERSE_DOMAIN,
     ):
         """Instantiates a external account authorized user credentials object.
 
@@ -98,6 +100,8 @@ class Credentials(
         quota_project_id (str): The optional project ID used for quota and billing.
             This project may be different from the project used to
             create the credentials.
+        universe_domain (Optional[str]): The universe domain. The default value
+            is googleapis.com.
 
         Returns:
             google.auth.external_account_authorized_user.Credentials: The
@@ -116,6 +120,7 @@ class Credentials(
         self._revoke_url = revoke_url
         self._quota_project_id = quota_project_id
         self._scopes = scopes
+        self._universe_domain = universe_domain or _DEFAULT_UNIVERSE_DOMAIN
 
         if not self.valid and not self.can_refresh:
             raise exceptions.InvalidOperation(
@@ -162,6 +167,7 @@ class Credentials(
             "revoke_url": self._revoke_url,
             "scopes": self._scopes,
             "quota_project_id": self._quota_project_id,
+            "universe_domain": self._universe_domain,
         }
 
     @property
@@ -297,6 +303,12 @@ class Credentials(
         kwargs.update(token_url=token_uri)
         return self.__class__(**kwargs)
 
+    @_helpers.copy_docstring(credentials.CredentialsWithUniverseDomain)
+    def with_universe_domain(self, universe_domain):
+        kwargs = self.constructor_args()
+        kwargs.update(universe_domain=universe_domain)
+        return self.__class__(**kwargs)
+
     @classmethod
     def from_info(cls, info, **kwargs):
         """Creates a Credentials instance from parsed external account info.

{google-auth-2.25.2 → google-auth-2.26.0}/google/auth/impersonated_credentials.py

@@ -259,7 +259,10 @@ class Credentials(
         """
 
         # Refresh our source credentials if it is not valid.
-        if not self._source_credentials.valid:
+        if (
+            self._source_credentials.token_state == credentials.TokenState.STALE
+            or self._source_credentials.token_state == credentials.TokenState.INVALID
+        ):
             self._source_credentials.refresh(request)
 
         body = {

{google-auth-2.25.2 → google-auth-2.26.0}/google/auth/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.25.2"
+__version__ = "2.26.0"

{google-auth-2.25.2 → google-auth-2.26.0}/google/oauth2/credentials.py

@@ -160,7 +160,11 @@ class Credentials(credentials.ReadOnlyScoped, credentials.CredentialsWithQuotaPr
         # unpickling certain callables (lambda, functools.partial instances)
         # because they need to be importable.
         # Instead, the refresh_handler setter should be used to repopulate this.
-        del state_dict["_refresh_handler"]
+        if "_refresh_handler" in state_dict:
+            del state_dict["_refresh_handler"]
+
+        if "_refresh_worker" in state_dict:
+            del state_dict["_refresh_worker"]
         return state_dict
 
     def __setstate__(self, d):
@@ -183,6 +187,8 @@ class Credentials(credentials.ReadOnlyScoped, credentials.CredentialsWithQuotaPr
         self._universe_domain = d.get("_universe_domain") or _DEFAULT_UNIVERSE_DOMAIN
         # The refresh_handler setter should be used to repopulate this.
         self._refresh_handler = None
+        self._refresh_worker = None
+        self._use_non_blocking_refresh = d.get("_use_non_blocking_refresh", False)
 
     @property
     def refresh_token(self):
@@ -302,15 +308,8 @@ class Credentials(credentials.ReadOnlyScoped, credentials.CredentialsWithQuotaPr
             universe_domain=self._universe_domain,
         )
 
+    @_helpers.copy_docstring(credentials.CredentialsWithUniverseDomain)
     def with_universe_domain(self, universe_domain):
-        """Create a copy of the credential with the given universe domain.
-
-        Args:
-            universe_domain (str): The universe domain value.
-
-        Returns:
-            google.oauth2.credentials.Credentials: A new credentials instance.
-        """
 
         return self.__class__(
             self.token,

{google-auth-2.25.2 → google-auth-2.26.0}/google/oauth2/service_account.py

@@ -325,16 +325,8 @@ class Credentials(
         cred._always_use_jwt_access = always_use_jwt_access
         return cred
 
+    @_helpers.copy_docstring(credentials.CredentialsWithUniverseDomain)
     def with_universe_domain(self, universe_domain):
-        """Create a copy of these credentials with the given universe domain.
-
-        Args:
-            universe_domain (str): The universe domain value.
-
-        Returns:
-            google.auth.service_account.Credentials: A new credentials
-                instance.
-        """
         cred = self._make_copy()
         cred._universe_domain = universe_domain
         if universe_domain != _DEFAULT_UNIVERSE_DOMAIN:

{google-auth-2.25.2 → google-auth-2.26.0/google_auth.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-auth
-Version: 2.25.2
+Version: 2.26.0
 Summary: Google Authentication Library
 Home-page: https://github.com/googleapis/google-auth-library-python
 Author: Google Cloud Platform

{google-auth-2.25.2 → google-auth-2.26.0}/google_auth.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ google/auth/_exponential_backoff.py
 google/auth/_helpers.py
 google/auth/_jwt_async.py
 google/auth/_oauth2client.py
+google/auth/_refresh_worker.py
 google/auth/_service_account_info.py
 google/auth/api_key.py
 google/auth/app_engine.py
@@ -75,6 +76,7 @@ tests/test__default.py
 tests/test__exponential_backoff.py
 tests/test__helpers.py
 tests/test__oauth2client.py
+tests/test__refresh_worker.py
 tests/test__service_account_info.py
 tests/test_api_key.py
 tests/test_app_engine.py

{google-auth-2.25.2 → google-auth-2.26.0}/tests/oauth2/test_credentials.py

@@ -24,6 +24,7 @@ import pytest  # type: ignore
 from google.auth import _helpers
 from google.auth import exceptions
 from google.auth import transport
+from google.auth.credentials import TokenState
 from google.oauth2 import credentials
 
 
@@ -61,6 +62,7 @@ class TestCredentials(object):
         assert not credentials.expired
         # Scopes aren't required for these credentials
         assert not credentials.requires_scopes
+        assert credentials.token_state == TokenState.INVALID
         # Test properties
         assert credentials.refresh_token == self.REFRESH_TOKEN
         assert credentials.token_uri == self.TOKEN_URI
@@ -911,7 +913,11 @@ class TestCredentials(object):
         assert list(creds.__dict__).sort() == list(unpickled.__dict__).sort()
 
         for attr in list(creds.__dict__):
-            assert getattr(creds, attr) == getattr(unpickled, attr)
+            # Worker should always be None
+            if attr == "_refresh_worker":
+                assert getattr(unpickled, attr) is None
+            else:
+                assert getattr(creds, attr) == getattr(unpickled, attr)
 
     def test_pickle_and_unpickle_universe_domain(self):
         # old version of auth lib doesn't have _universe_domain, so the pickled
@@ -945,7 +951,7 @@ class TestCredentials(object):
         for attr in list(creds.__dict__):
             # For the _refresh_handler property, the unpickled creds should be
             # set to None.
-            if attr == "_refresh_handler":
+            if attr == "_refresh_handler" or attr == "_refresh_worker":
                 assert getattr(unpickled, attr) is None
             else:
                 assert getattr(creds, attr) == getattr(unpickled, attr)
@@ -957,6 +963,8 @@ class TestCredentials(object):
         # this mimics a pickle created with a previous class definition with
         # fewer attributes
         del creds.__dict__["_quota_project_id"]
+        del creds.__dict__["_refresh_handler"]
+        del creds.__dict__["_refresh_worker"]
 
         unpickled = pickle.loads(pickle.dumps(creds))
 

google-auth-2.26.0/tests/test__refresh_worker.py

@@ -0,0 +1,147 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import random
+import threading
+import time
+
+import mock
+import pytest  # type: ignore
+
+from google.auth import _refresh_worker, credentials, exceptions
+
+MAIN_THREAD_SLEEP_MS = 100 / 1000
+
+
+class MockCredentialsImpl(credentials.Credentials):
+    def __init__(self, sleep_seconds=None):
+        self.refresh_count = 0
+        self.token = None
+        self.sleep_seconds = sleep_seconds if sleep_seconds else None
+
+    def refresh(self, request):
+        if self.sleep_seconds:
+            time.sleep(self.sleep_seconds)
+        self.token = request
+        self.refresh_count += 1
+
+
+@pytest.fixture
+def test_thread_count():
+    return 25
+
+
+def _cred_spinlock(cred):
+    while cred.token is None:  # pragma: NO COVER
+        time.sleep(MAIN_THREAD_SLEEP_MS)
+
+
+def test_invalid_start_refresh():
+    w = _refresh_worker.RefreshThreadManager()
+    with pytest.raises(exceptions.InvalidValue):
+        w.start_refresh(None, None)
+
+
+def test_start_refresh():
+    w = _refresh_worker.RefreshThreadManager()
+    cred = MockCredentialsImpl()
+    request = mock.MagicMock()
+    assert w.start_refresh(cred, request)
+
+    assert w._worker is not None
+
+    _cred_spinlock(cred)
+
+    assert cred.token == request
+    assert cred.refresh_count == 1
+
+
+def test_nonblocking_start_refresh():
+    w = _refresh_worker.RefreshThreadManager()
+    cred = MockCredentialsImpl(sleep_seconds=1)
+    request = mock.MagicMock()
+    assert w.start_refresh(cred, request)
+
+    assert w._worker is not None
+    assert not cred.token
+    assert cred.refresh_count == 0
+
+
+def test_multiple_refreshes_multiple_workers(test_thread_count):
+    w = _refresh_worker.RefreshThreadManager()
+    cred = MockCredentialsImpl()
+    request = mock.MagicMock()
+
+    def _thread_refresh():
+        time.sleep(random.randrange(0, 5))
+        assert w.start_refresh(cred, request)
+
+    threads = [
+        threading.Thread(target=_thread_refresh) for _ in range(test_thread_count)
+    ]
+    for t in threads:
+        t.start()
+
+    _cred_spinlock(cred)
+
+    assert cred.token == request
+    # There is a chance only one thread has enough time to perform a refresh.
+    # Generally multiple threads will have time to perform a refresh
+    assert cred.refresh_count > 0
+
+
+def test_refresh_error():
+    w = _refresh_worker.RefreshThreadManager()
+    cred = mock.MagicMock()
+    request = mock.MagicMock()
+
+    cred.refresh.side_effect = exceptions.RefreshError("Failed to refresh")
+
+    assert w.start_refresh(cred, request)
+
+    while w._worker._error_info is None:  # pragma: NO COVER
+        time.sleep(MAIN_THREAD_SLEEP_MS)
+
+    assert w._worker is not None
+    assert isinstance(w._worker._error_info, exceptions.RefreshError)
+
+
+def test_refresh_error_call_refresh_again():
+    w = _refresh_worker.RefreshThreadManager()
+    cred = mock.MagicMock()
+    request = mock.MagicMock()
+
+    cred.refresh.side_effect = exceptions.RefreshError("Failed to refresh")
+
+    assert w.start_refresh(cred, request)
+
+    while w._worker._error_info is None:  # pragma: NO COVER
+        time.sleep(MAIN_THREAD_SLEEP_MS)
+
+    assert not w.start_refresh(cred, request)
+
+
+def test_refresh_dead_worker():
+    cred = MockCredentialsImpl()
+    request = mock.MagicMock()
+
+    w = _refresh_worker.RefreshThreadManager()
+    w._worker = None
+
+    w.start_refresh(cred, request)
+
+    _cred_spinlock(cred)
+
+    assert cred.token == request
+    assert cred.refresh_count == 1