Per-Request Auth Token Refresh (#103)

* refactor: simplify token acquisition by removing async calls and unused tests

* Introduce TokenData class

* Passing () to avoid type checking problems

* Test fixups

* fix: update test cases to suppress unused return value warnings, now only scanning relevant files

* Address PR review feedback: preserve token scheme casing and fix documentation (#106)

* Initial plan

* fix: address PR review comments - token scheme, docs, and tests

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* chore: remove 'include' and revert removal of .venv from exclude list for pyright

* chore: remove some extraneous comments

* test: consistent casing in assertions and provided mock data

* Address review feedback: require issued_at field and prevent refresh stampede (#107)

* Initial plan

* Implement background token refresh for old tokens

- Add issued_at field to TokenData to track token creation time
- Add is_old() method to check if token should be refreshed (< 50% lifetime)
- Trigger non-blocking background refresh when token is old but valid
- Keep blocking refresh for expired tokens
- Add comprehensive tests for background refresh behavior

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* fix: update tests to match preserved token scheme casing

Tests were expecting capitalized schemes but implementation was
changed in 4b7e73a to preserve server-provided casing.

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* Address code review feedback

- Add logging for background refresh failures
- Improve comments explaining magic numbers
- Add test for server casing preservation
- Add comment explaining test tolerance

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* Address PR review comments

- Make issued_at a required field (remove default value)
- Remove fallback logic for legacy tokens in is_old()
- Add stampede prevention in _background_refresh
- Remove obsolete tests for fallback logic
- Add test for stampede prevention

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* Revert Bearer/DPoP test assertion changes from c50327d

The target branch now properly fixes the test by providing "Bearer"
in the mock data. Reverting my previous fix that changed the assertion
to match the old mock data.

Co-authored-by: anna-singleton-resolver <199753965+anna-singleton-resolver@users.noreply.github.com>

* fix: start refresh thread checks for already refreshed token

* chore: remove extraneous comment

* feat: reduce eagerness of background refresh from at 50% remaining to 25% remaining

* doc: update is_old docstring

* fix: correct boolean logic in _start_background_refresh

Changed from OR to AND logic: refresh should start if
(refresh_not_active AND token_needs_refresh), not if any
condition is true. This prevents unnecessary refresh attempts.

Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>

* test: fix test assertions to be on 25% instead of 50%

* feat: allow configurable proactive_refresh_threshold

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>
Co-authored-by: anna-singleton-resolver <199753965+anna-singleton-resolver@users.noreply.github.com>
Co-authored-by: anna-singleton-resolver <anna.singleton@resolver.com>

* refactor: TokenData as frozen dataclass and param validity checks at init

* doc: remove old part of docstring

---------

Co-authored-by: Carl Patchett <carl.patchett@kroll.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: iwillspeak <1004401+iwillspeak@users.noreply.github.com>
Co-authored-by: anna-singleton-resolver <anna.singleton@resolver.com>
Co-authored-by: anna-singleton-resolver <199753965+anna-singleton-resolver@users.noreply.github.com>

Author: 6 people

docs/api/exceptions.rst

@@ -129,7 +129,8 @@ OAuth Error Handling
             client_id=client_id,
             client_secret=client_secret
         )
-        token = await credential_helper.get_token()
+        token_data = credential_helper.get_token()
+        access_token = token_data.access_token
     except OAuthError as e:
         logger.error(f"OAuth authentication failed: {e}")
         # Handle OAuth failure - check credentials

docs/authentication.rst

@@ -76,14 +76,6 @@ Set these environment variables for OAuth authentication:
             audience=os.getenv("OAUTH_AUDIENCE", "crisp-athena-live"),
         )
 
-        # Test token acquisition
-        try:
-            token = await credential_helper.get_token()
-            print(f"Successfully acquired token (length: {len(token)})")
-        except Exception as e:
-            print(f"Failed to acquire OAuth token: {e}")
-            return
-
         # Create authenticated channel
         channel = await create_channel_with_credentials(
             host=os.getenv("ATHENA_HOST"),
@@ -258,11 +250,12 @@ Handle OAuth-specific errors gracefully:
 
 .. code-block:: python
 
-    from resolver_athena_client.client.exceptions import AuthenticationError
+    from resolver_athena_client.client.exceptions import OAuthError
 
     try:
-        token = await credential_helper.get_token()
-    except AuthenticationError as e:
+        token_data = credential_helper.get_token()
+        access_token = token_data.access_token
+    except OAuthError as e:
         logger.error(f"OAuth authentication failed: {e}")
         # Handle authentication failure
     except Exception as e:
@@ -356,8 +349,8 @@ Test your authentication setup:
                 client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
             )
 
-            token = await credential_helper.get_token()
-            print(f"✓ Authentication successful (token length: {len(token)})")
+            token_data = credential_helper.get_token()
+            print(f"✓ Authentication successful (token length: {len(token_data.access_token)})")
             return True
 
         except Exception as e:

examples/classify_single_example.py

@@ -213,15 +213,6 @@ async def main() -> int:
         audience=audience,
     )
 
-    # Test token acquisition
-    try:
-        logger.info("Acquiring OAuth token...")
-        token = await credential_helper.get_token()
-        logger.info("Successfully acquired token (length: %d)", len(token))
-    except Exception:
-        logger.exception("Failed to acquire OAuth token")
-        return 1
-
     # Configure client options
     options = AthenaOptions(
         host=host,

examples/example.py

@@ -163,15 +163,6 @@ async def main() -> int:
         audience=audience,
     )
 
-    # Test token acquisition
-    try:
-        logger.info("Acquiring OAuth token...")
-        token = await credential_helper.get_token()
-        logger.info("Successfully acquired token (length: %d)", len(token))
-    except Exception:
-        logger.exception("Failed to acquire OAuth token")
-        return 1
-
     # Get available deployment
     channel = await create_channel_with_credentials(host, credential_helper)
     async with DeploymentSelector(channel) as deployment_selector:

src/resolver_athena_client/client/__init__.py

@@ -5,6 +5,7 @@
 
 from resolver_athena_client.client.channel import (
     CredentialHelper,
+    TokenData,
     create_channel_with_credentials,
 )
 from resolver_athena_client.client.exceptions import (
@@ -26,6 +27,7 @@
     "CredentialError",
     "CredentialHelper",
     "OAuthError",
+    "TokenData",
     "TokenExpiredError",
     "create_channel_with_credentials",
     "get_output_error_summary",