Refresh OverDrive collection token every 30 days (PP-3937) (#3204)

## Description
Add a two-layer cache for OverDrive collection tokens so they are
automatically refreshed as OverDrive rotates them, without requiring a
process restart or configuration change.
## Motivation and Context
OverDrive is retiring legacy collection tokens within the next 3–4
months
and moving to a model where tokens must be refreshed periodically.
`collectionToken` is embedded in the library account response
(`GET /v1/libraries/{id}`) and is required for all collection-scoped API
calls (search, product listings, availability, metadata).
Two problems existed in the prior implementation:
1. **DB cache had no TTL.** `get_library()` and
`get_advantage_accounts()`
called `Representation.get()` with no `max_age`, so the library document
   (and the `collectionToken` within it) could persist in the
   `representations` table indefinitely.
2. **In-memory cache was unbounded.** `_collection_token` was a plain
   `str | None` set once and never cleared. Flask workers hold one
`OverdriveAPI` instance per collection for the entire process lifetime
(`CirculationManager.load_settings`), so a rotated token would never be
   picked up without a full process restart or an admin config change.
### Solution: two-layer cache
| Layer | Constant | TTL | Purpose |
|---|---|---|---|
| In-memory (`_cached_collection_token`) | `COLLECTION_TOKEN_MAX_AGE` |
5 minutes | Avoids a DB hit on every request |
| DB (`representations` table) | `LIBRARY_MAX_AGE` | 30 days | Avoids a
network hit on every 5-minute miss |
A long-lived Flask worker re-checks the DB every 5 minutes and the DB
re-fetches from OverDrive every 30 days. Rotated tokens are picked up
within 5 minutes.
## How Has This Been Tested?
- `test_collection_token` — verifies the in-memory cache is populated on
first access and reused on subsequent calls within
`COLLECTION_TOKEN_MAX_AGE`.
- `test_collection_token_cache_expires` — verifies that aging the
in-memory cache past `COLLECTION_TOKEN_MAX_AGE` causes `get_library` to
  be called again and returns the new token.
- `test_collection_token_error` — verifies that an `errorCode` in the
  library response raises `CannotLoadConfiguration`.
- `test_get_library_passes_max_age` — verifies `LIBRARY_MAX_AGE` is
  forwarded to `Representation.get()` in `get_library()`.
- `test_get_library_refreshes_stale_token` — end-to-end DB staleness
test:
ages the `Representation` record past `LIBRARY_MAX_AGE` and verifies the
  next call re-fetches from the network.
- `test_get_advantage_accounts_passes_max_age` — verifies
`LIBRARY_MAX_AGE`
is also forwarded in the advantage accounts `Representation.get()` call.
## Checklist
- [x] I have updated the documentation accordingly.
- [x] All new and existing tests passed.

Author: dbernstein

src/palace/manager/integration/license/overdrive/api.py

@@ -241,6 +241,19 @@ class OverdriveAPI(
 
     EVENT_DELAY = datetime.timedelta(minutes=120)
 
+    # Maximum age of the cached library document before it is re-fetched
+    # from the OverDrive API. OverDrive periodically rotates collection tokens,
+    # so this ensures the representations table cache doesn't serve a stale
+    # token indefinitely.
+    LIBRARY_MAX_AGE: datetime.timedelta = datetime.timedelta(days=30)
+
+    # How long to keep the collection token in the in-memory cache before
+    # re-checking the representations table. Kept short so that long-lived
+    # Flask worker processes (which hold one OverdriveAPI instance per
+    # collection for the process lifetime) pick up rotated tokens within a
+    # reasonable window without hitting the DB on every request.
+    COLLECTION_TOKEN_MAX_AGE: datetime.timedelta = datetime.timedelta(minutes=5)
+
     TIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
 
     NEXT_REL = "next"
@@ -309,8 +322,11 @@ def __init__(self, _db: Session, collection: Collection) -> None:
         # This is set by access to ._client_oauth_token
         self._cached_client_oauth_token: OverdriveToken | None = None
 
-        # This is set by access to .collection_token
-        self._collection_token: str | None = None
+        # In-memory cache for the collectionToken extracted from the library
+        # document. Expires after COLLECTION_TOKEN_MAX_AGE so that long-lived
+        # instances (e.g. Flask workers) transparently re-fetch a rotated token
+        # without a process restart. See the collection_token property.
+        self._cached_collection_token: OverdriveToken | None = None
         self.overdrive_bibliographic_coverage_provider = (
             OverdriveBibliographicCoverageProvider(collection, api=self)
         )
@@ -381,22 +397,33 @@ def _refresh_client_oauth_token(self) -> OverdriveToken:
     def collection_token(self) -> str:
         """Get the token representing this particular Overdrive collection.
 
-        As a side effect, this will verify that the Overdrive
+        The token is cached in memory for :attr:`COLLECTION_TOKEN_MAX_AGE`
+        (5 minutes) to avoid a DB lookup on every request. Once that expires,
+        :meth:`get_library` is called, which uses the ``representations`` table
+        as a second cache layer refreshed at most once every
+        :attr:`LIBRARY_MAX_AGE` (30 days).
+
+        As a side effect of a cache miss, this verifies that the OverDrive
         credentials are working.
         """
-        collection_token = self._collection_token
-        if not collection_token:
-            library = self.get_library()
-            error = library.get("errorCode")
-            if error:
-                message = library.get("message")
-                raise CannotLoadConfiguration(
-                    "Overdrive credentials are valid but could not fetch library: %s"
-                    % message
-                )
-            collection_token = cast(str, library["collectionToken"])
-            self._collection_token = collection_token
-        return collection_token
+        cached = self._cached_collection_token
+        if cached is not None and utc_now() < cached.expires:
+            return cached.token
+
+        library = self.get_library()
+        error = library.get("errorCode")
+        if error:
+            message = library.get("message")
+            raise CannotLoadConfiguration(
+                "Overdrive credentials are valid but could not fetch library: %s"
+                % message
+            )
+        token = cast(str, library["collectionToken"])
+        self._cached_collection_token = OverdriveToken(
+            token=token,
+            expires=utc_now() + self.COLLECTION_TOKEN_MAX_AGE,
+        )
+        return token
 
     @property
     def data_source(self) -> DataSource:
@@ -531,6 +558,11 @@ def _library_endpoint(self) -> str:
     def get_library(self) -> dict[str, Any]:
         """Get basic information about the collection, including
         a link to the titles in the collection.
+
+        The response is cached in the ``representations`` table and refreshed
+        at most once every :attr:`LIBRARY_MAX_AGE`. This ensures the
+        ``collectionToken`` embedded in the response stays current, since
+        OverDrive periodically rotates collection tokens.
         """
         url = self._library_endpoint
         with self.lock:
@@ -539,12 +571,17 @@ def get_library(self) -> dict[str, Any]:
                 url,
                 self.get,
                 exception_handler=Representation.reraise_exception,
+                max_age=self.LIBRARY_MAX_AGE,
             )
             return json.loads(representation.content)  # type: ignore[no-any-return]
 
     def get_advantage_accounts(self) -> Generator[OverdriveAdvantageAccount]:
         """Find all the Overdrive Advantage accounts managed by this library.
 
+        The advantage accounts response is cached in the ``representations``
+        table and refreshed at most once every :attr:`LIBRARY_MAX_AGE`,
+        matching the same cadence as :meth:`get_library`.
+
         :yield: A sequence of OverdriveAdvantageAccount objects.
         """
         library = self.get_library()
@@ -561,6 +598,7 @@ def get_advantage_accounts(self) -> Generator[OverdriveAdvantageAccount]:
                 advantage_url,
                 self.get,
                 exception_handler=Representation.reraise_exception,
+                max_age=self.LIBRARY_MAX_AGE,
             )
             yield from OverdriveAdvantageAccount.from_representation(
                 representation.content

tests/manager/integration/license/overdrive/test_api.py

@@ -27,7 +27,10 @@
 from palace.manager.api.config import Configuration
 from palace.manager.core.config import CannotLoadConfiguration
 from palace.manager.core.exceptions import BasePalaceException, IntegrationException
-from palace.manager.integration.license.overdrive.api import OverdriveAPI
+from palace.manager.integration.license.overdrive.api import (
+    OverdriveAPI,
+    OverdriveToken,
+)
 from palace.manager.integration.license.overdrive.constants import OverdriveConstants
 from palace.manager.integration.license.overdrive.exception import (
     OverdriveValidationError,
@@ -1548,20 +1551,53 @@ def test_collection_token(self, db: DatabaseTransactionFixture) -> None:
         mock_get_library = MagicMock(return_value={"collectionToken": "abc"})
         api.get_library = mock_get_library
 
-        # If the collection token is set, we just return that
-        api._collection_token = "123"
-        assert api.collection_token == "123"
-        mock_get_library.assert_not_called()
-
-        # If its not we get it from the get_library method
-        api._collection_token = None
+        # Cache is empty on first access — get_library is called.
+        assert api._cached_collection_token is None
         assert api.collection_token == "abc"
         mock_get_library.assert_called_once()
 
-        # Calling again returns the cached value
+        # Subsequent calls within COLLECTION_TOKEN_MAX_AGE return the cached
+        # value without calling get_library again.
         assert api.collection_token == "abc"
         mock_get_library.assert_called_once()
 
+    def test_collection_token_cache_expires(
+        self, db: DatabaseTransactionFixture
+    ) -> None:
+        """After COLLECTION_TOKEN_MAX_AGE has elapsed the in-memory cache is
+        bypassed and get_library is called again to pick up a rotated token."""
+        api = OverdriveAPI(db.session, db.collection(protocol=OverdriveAPI))
+        mock_get_library = MagicMock(
+            side_effect=[
+                {"collectionToken": "old-token"},
+                {"collectionToken": "new-token"},
+            ]
+        )
+        api.get_library = mock_get_library
+
+        assert api.collection_token == "old-token"
+        mock_get_library.assert_called_once()
+
+        # Age the in-memory cache past COLLECTION_TOKEN_MAX_AGE.
+        assert api._cached_collection_token is not None
+        api._cached_collection_token = OverdriveToken(
+            token=api._cached_collection_token.token,
+            expires=utc_now() - timedelta(seconds=1),
+        )
+
+        # The next access should bypass the cache and call get_library again.
+        assert api.collection_token == "new-token"
+        assert mock_get_library.call_count == 2
+
+    def test_collection_token_error(self, db: DatabaseTransactionFixture) -> None:
+        """An errorCode in the library response raises CannotLoadConfiguration."""
+        api = OverdriveAPI(db.session, db.collection(protocol=OverdriveAPI))
+        api.get_library = MagicMock(
+            return_value={"errorCode": "NotFound", "message": "bad credentials"}
+        )
+        with pytest.raises(CannotLoadConfiguration, match="bad credentials"):
+            api.collection_token
+
     def test_circulation_lookup(
         self, overdrive_api_fixture: OverdriveAPIFixture, db: DatabaseTransactionFixture
     ):

tests/manager/integration/license/overdrive/test_script.py

@@ -2,20 +2,25 @@
 
 import csv
 import os
+from datetime import timedelta
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
 
 from palace.manager.integration.license.overdrive.advantage import (
     OverdriveAdvantageAccount,
 )
-from palace.manager.integration.license.overdrive.api import OverdriveAPI
+from palace.manager.integration.license.overdrive.api import (
+    OverdriveAPI,
+    OverdriveToken,
+)
 from palace.manager.integration.license.overdrive.script import (
     GenerateOverdriveAdvantageAccountList,
     ImportCollection,
     ImportCollectionGroup,
 )
 from palace.manager.sqlalchemy.model.collection import Collection
+from palace.manager.util.datetime_helpers import utc_now
 from tests.fixtures.database import DatabaseTransactionFixture
 from tests.fixtures.overdrive import OverdriveAPIFixture
 
@@ -70,7 +75,9 @@ def test_generate_od_advantage_account_list(
             ),
         ]
         overdrive_api.get_advantage_accounts = mock_get_advantage_accounts
-        overdrive_api._collection_token = library_token
+        overdrive_api._cached_collection_token = OverdriveToken(
+            library_token, utc_now() + timedelta(hours=1)
+        )
 
         with patch.object(
             GenerateOverdriveAdvantageAccountList, "_create_overdrive_api"

tests/mocks/overdrive.py

@@ -19,7 +19,9 @@ def __init__(self, _db: Session, collection: Collection) -> None:
 
         # Initialize some variables that are normally set when they are first accessed,
         # since most tests will access them.
-        self._collection_token = "fake collection token"
+        self._cached_collection_token = OverdriveToken(
+            "fake collection token", utc_now() + timedelta(hours=1)
+        )
         self._cached_client_oauth_token = OverdriveToken(
             "fake client oauth token", utc_now() + timedelta(hours=1)
         )