refactor: Improve robustness and fix bugs in client library

Author: mridang

VERSIONING.md

@@ -4,11 +4,11 @@ This document provides a detailed explanation of the versioning and release stra
 
 ## Versioning at a Glance
 
-| Version Change | ZITADEL Compatibility | Type of Change | Example |
-| :--- | :--- | :--- | :--- |
-| **MAJOR** (e.g., 3.x -> 4.x) | Aligned with ZITADEL Core. Requires server upgrade. | Contains breaking changes. | `v3.5.1` -> `v4.0.0` |
-| **MINOR** (e.g., 3.1 -> 3.2) | Compatible with the same ZITADEL major version. | New, non-breaking features added. | `v3.1.4` -> `v3.2.0` |
-| **PATCH** (e.g., 3.1.0 -> 3.1.1)| Compatible with the same ZITADEL major version. | Backwards-compatible bug fixes. | `v3.1.0` -> `v3.1.1` |
+| Version Change                   | ZITADEL Compatibility                               | Type of Change                    | Example              |
+|:---------------------------------|:----------------------------------------------------|:----------------------------------|:---------------------|
+| **MAJOR** (e.g., 3.x -> 4.x)     | Aligned with ZITADEL Core. Requires server upgrade. | Contains breaking changes.        | `v3.5.1` -> `v4.0.0` |
+| **MINOR** (e.g., 3.1 -> 3.2)     | Compatible with the same ZITADEL major version.     | New, non-breaking features added. | `v3.1.4` -> `v3.2.0` |
+| **PATCH** (e.g., 3.1.0 -> 3.1.1) | Compatible with the same ZITADEL major version.     | Backwards-compatible bug fixes.   | `v3.1.0` -> `v3.1.1` |
 
 ---
 

devbox.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.7/.schema/devbox.schema.json",
   "packages": [
-    "python@latest",
     "poetry@latest",
-    "lefthook@latest"
+    "lefthook@latest",
+    "python39@latest"
   ],
   "env": {
     "POETRY_CACHE_DIR": "$PWD/.poetry"

devbox.lock

@@ -114,60 +114,60 @@
         }
       }
     },
-    "python@latest": {
-      "last_modified": "2025-03-11T17:52:14Z",
+    "python39@latest": {
+      "last_modified": "2025-03-21T17:37:26Z",
       "plugin_version": "0.0.3",
-      "resolved": "github:NixOS/nixpkgs/0d534853a55b5d02a4ababa1d71921ce8f0aee4c#python313",
+      "resolved": "github:NixOS/nixpkgs/94c4dbe77c0740ebba36c173672ca15a7926c993#python39",
       "source": "devbox-search",
-      "version": "3.13.2",
+      "version": "3.9.21",
       "systems": {
         "aarch64-darwin": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/c8k24sfwckindjhdxak6z3dhn8w4anx2-python3-3.13.2",
+              "path": "/nix/store/nlbviyx8zris00ahxw4ddn69pc78x1zq-python3-3.9.21",
               "default": true
             }
           ],
-          "store_path": "/nix/store/c8k24sfwckindjhdxak6z3dhn8w4anx2-python3-3.13.2"
+          "store_path": "/nix/store/nlbviyx8zris00ahxw4ddn69pc78x1zq-python3-3.9.21"
         },
         "aarch64-linux": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/jsqky488530ax8hdaz5ckldxq9y6qr3k-python3-3.13.2",
+              "path": "/nix/store/d23m22zna540cijzviazc2jwc0ykxn0q-python3-3.9.21",
               "default": true
             },
             {
               "name": "debug",
-              "path": "/nix/store/fwwjmw2yddxxm6aj51r16v0ffp77zvk1-python3-3.13.2-debug"
+              "path": "/nix/store/xkdmi6r4v1r3s9h7ch02bly2pl34m61x-python3-3.9.21-debug"
             }
           ],
-          "store_path": "/nix/store/jsqky488530ax8hdaz5ckldxq9y6qr3k-python3-3.13.2"
+          "store_path": "/nix/store/d23m22zna540cijzviazc2jwc0ykxn0q-python3-3.9.21"
         },
         "x86_64-darwin": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/wjxlppca1s14xzw5iz608qpywyl5mcdw-python3-3.13.2",
+              "path": "/nix/store/za3lvl97h0nm46ziqdwdy8f3j6d7na26-python3-3.9.21",
               "default": true
             }
           ],
-          "store_path": "/nix/store/wjxlppca1s14xzw5iz608qpywyl5mcdw-python3-3.13.2"
+          "store_path": "/nix/store/za3lvl97h0nm46ziqdwdy8f3j6d7na26-python3-3.9.21"
         },
         "x86_64-linux": {
           "outputs": [
             {
               "name": "out",
-              "path": "/nix/store/njpnqszjaj6k38cp4466ygn74n392xy1-python3-3.13.2",
+              "path": "/nix/store/ydq53zmlqq5wcn46w3h62p06yjg4xx8z-python3-3.9.21",
               "default": true
             },
             {
               "name": "debug",
-              "path": "/nix/store/ixcc4jnj3byz0hg943wadfy1phxkmmgg-python3-3.13.2-debug"
+              "path": "/nix/store/c3nr8wl0l1yy3lg9msa7453d3r7pp041-python3-3.9.21-debug"
             }
           ],
-          "store_path": "/nix/store/njpnqszjaj6k38cp4466ygn74n392xy1-python3-3.13.2"
+          "store_path": "/nix/store/ydq53zmlqq5wcn46w3h62p06yjg4xx8z-python3-3.9.21"
         }
       }
     }

spec/conftest.py

@@ -2,14 +2,20 @@
 # mypy: allow-untyped-defs
 from __future__ import annotations
 
+import sys
 import os
 import platform
 import re
 
 # noinspection PyPep8Naming
 import xml.etree.ElementTree as ET
 from collections import defaultdict
-from collections.abc import Callable
+
+if sys.version_info >= (3, 10):
+    # noinspection PyProtectedMember
+    from collections import Callable  # type: ignore
+else:
+    from collections.abc import Callable
 from datetime import datetime, timezone
 
 import pytest
@@ -30,6 +36,7 @@
 xml_key = StashKey["LogXML"]()
 
 
+# noinspection PyUnresolvedReferences
 class _NodeReporter:
     def __init__(self, nodeid: str | TestReport, xml: LogXML) -> None:
         self.id = nodeid
@@ -299,6 +306,7 @@ def pytest_configure(config: Config) -> None:
 
     :param config: The pytest Config object containing CLI options and hooks.
     """
+    # noinspection PyUnresolvedReferences
     xmldir = config.option.xmldir
     if xmldir and not hasattr(config, "workerinput"):
         config.stash[xml_key] = LogXML(xmldir)
@@ -333,6 +341,7 @@ def mangle_test_address(address: str) -> list[str]:
 
 
 class LogXML:
+    # noinspection PyUnresolvedReferences
     def __init__(  # type: ignore[no-untyped-def]
         self,
         output_dir,
@@ -350,6 +359,7 @@ def __init__(  # type: ignore[no-untyped-def]
         self.log_passing_tests = log_passing_tests
         self.report_duration = report_duration
         self.stats: dict[str, int] = dict.fromkeys(["error", "passed", "failure", "skipped"], 0)
+        # noinspection PyUnresolvedReferences
         self.node_reporters: dict[tuple[str | TestReport, object], _NodeReporter] = {}
         self.node_reporters_ordered: list[_NodeReporter] = []
 
@@ -370,6 +380,7 @@ def finalize(self, report: TestReport) -> None:
             reporter.finalize()
 
     def node_reporter(self, report: TestReport | str) -> _NodeReporter:
+        # noinspection PyUnresolvedReferences
         nodeid: str | TestReport = getattr(report, "nodeid", report)
         # Local hack to handle xdist report order.
         workernode = getattr(report, "node", None)

test/auth/test_oauth_authenticator.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 import unittest
 
 from testcontainers.core.container import DockerContainer
@@ -15,7 +17,7 @@ class OAuthAuthenticatorTest(unittest.TestCase):
     with a status code of 405, using HttpWaitStrategy.
     """
 
-    oauth_host: str | None = None
+    oauth_host: Optional[str] = None
     mock_oauth2_server: DockerContainer = None
 
     @classmethod
@@ -24,6 +26,7 @@ def setup_class(cls) -> None:
         cls.mock_oauth2_server.start()
         host = cls.mock_oauth2_server.get_container_host_ip()
         port = cls.mock_oauth2_server.get_exposed_port(8080)
+        # noinspection HttpUrlsUsage
         cls.oauth_host = f"http://{host}:{port}"
 
     @classmethod

zitadel_client/api_client.py

@@ -69,6 +69,7 @@ def __init__(
             self.default_headers[header_name] = header_value
         self.client_side_validation = configuration.client_side_validation
 
+    # noinspection PyArgumentList
     T = TypeVar("T", bound="ApiClient")
 
     def __enter__(self: T) -> T:
@@ -229,8 +230,10 @@ def response_deserialize(
             response_type = response_types_map.get(str(response_data.status)[0] + "XX", None)
 
         # deserialize response data
+        # noinspection PyUnusedLocal
         response_text = None
         return_data = None
+        # noinspection PyUnreachableCode
         try:
             if response_type == "bytearray":
                 return_data = response_data.data
@@ -243,6 +246,7 @@ def response_deserialize(
                     match = re.search(r"charset=([a-zA-Z\-\d]+)[\s;]?", content_type)
                 encoding = match.group(1) if match else "utf-8"
                 response_text = response_data.data.decode(encoding)
+                # noinspection PyTypeChecker
                 return_data = self.deserialize(response_text, response_type, content_type)
         finally:
             if not 200 <= response_data.status <= 299:
@@ -357,12 +361,14 @@ def __deserialize(data, klass):  # noqa C901 too complex
             if klass.startswith("List["):
                 m = re.match(r"List\[(.*)]", klass)
                 assert m is not None, "Malformed List type definition"
+                # noinspection PyArgumentList
                 return [ApiClient.__deserialize(sub_data) for sub_data in data]
 
             if klass.startswith("Dict["):
                 m = re.match(r"Dict\[([^,]*), (.*)]", klass)
                 assert m is not None, "Malformed Dict type definition"
                 sub_kls = m.group(2)
+                # noinspection PyArgumentList
                 return {k: ApiClient.__deserialize(sub_kls) for k, v in data.items()}
 
             # convert str to class

zitadel_client/api_response.py

@@ -7,6 +7,7 @@
 T = TypeVar("T")
 
 
+# noinspection PyTypeHints
 class ApiResponse(BaseModel, Generic[T]):
     """
     API response object

zitadel_client/auth/authenticator.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from datetime import datetime, timezone
+from datetime import datetime, timezone, timedelta
 from typing import Any, Dict, Generic, TypeVar  # noqa: F401
 
 
@@ -65,4 +65,4 @@ def is_expired(self) -> bool:
         Returns:
         - bool: True if expired, False otherwise.
         """
-        return datetime.now(timezone.utc) >= self.expires_at
+        return datetime.now(timezone.utc) >= (self.expires_at - timedelta(minutes=5))

zitadel_client/auth/oauth_authenticator.py

@@ -1,3 +1,5 @@
+from threading import Lock
+
 from abc import ABC, abstractmethod
 from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, Generic, Optional, TypeVar  # noqa: F401
@@ -29,16 +31,20 @@ def __init__(self, open_id: OpenId, oauth_session: OAuth2Session):
         self.open_id = open_id
         self.token: Optional[Token] = None
         self.oauth_session = oauth_session
+        self._lock = Lock()
 
     def get_auth_token(self) -> str:
         """
         Returns the current access token, refreshing it if necessary.
         """
-        if self.token is None or self.token.is_expired():
-            self.refresh_token()
+        with self._lock:
+            if self.token is None or self.token.is_expired():
+                self.refresh_token()
 
-        assert self.token is not None
-        return self.token.access_token
+            if self.token is None:
+                raise ZitadelError("Token is null even after attempting to refresh.")
+            else:
+                return self.token.access_token
 
     def get_auth_headers(self) -> Dict[str, str]:
         """
@@ -75,10 +81,11 @@ def refresh_token(self) -> Token:
             raise ZitadelError("Failed to refresh token: " + str(e)) from e
 
 
+# noinspection PyArgumentList
 T = TypeVar("T", bound="OAuthAuthenticatorBuilder[Any]")
 
 
-# noinspection PyTypeHintsInspection
+# noinspection PyTypeHintsInspection,PyTypeHints
 class OAuthAuthenticatorBuilder(ABC, Generic[T]):
     """
     Abstract builder class for constructing OAuth authenticator instances.

zitadel_client/configuration.py

@@ -88,6 +88,7 @@ def __deepcopy__(self, memo: Dict[int, Any]) -> Self:
         memo[id(self)] = result
         for k, v in self.__dict__.items():
             if k not in ("logger", "logger_file_handler"):
+                # noinspection PyArgumentList
                 setattr(result, k, copy.deepcopy(v, memo))
         # shallow copy of loggers
         result.logger = copy.copy(self.logger)