perf(file): cache the wiki's allowed file extensions for 24 h

- WtSite.get_allowed_file_extensions() caches the siteinfo lookup for
  ALLOWED_FILE_EXTENSIONS_TTL, so a failed upload no longer re-queries
- clear_allowed_file_extensions_cache() resets it explicitly; the page
  cache and clear_cache() stay independent
- a failed or malformed lookup is never cached and never propagates
- the rejected-extension ValueError now names the fetch time, the cache
  lifetime and the reset call
- reraise_upload_error takes the WtSite instead of the raw mwclient site

Author: LukasGold

src/osw/controller/file/wiki.py

@@ -11,21 +11,21 @@
 from osw.wtsite import WtSite
 
 
-def get_allowed_file_extensions(mw_site) -> Optional[List[str]]:
-    """Queries the file extensions the wiki accepts, None if unavailable"""
-    try:
-        result = mw_site.api(
-            "query", meta="siteinfo", siprop="fileextensions", formatversion=2
-        )
-    except Exception:
-        # only used to enrich an error message, never worth failing over
-        return None
-    extensions = result.get("query", {}).get("fileextensions", [])
-    return [entry["ext"] for entry in extensions if "ext" in entry]
+def format_allowed_extensions(allowed: WtSite.AllowedFileExtensionsResult) -> str:
+    """Renders the allowed-extensions hint for a rejected-upload error message"""
+    if not allowed.extensions or allowed.fetched_at is None:
+        return ""
+    ttl_hours = int(WtSite.ALLOWED_FILE_EXTENSIONS_TTL.total_seconds() // 3600)
+    return (
+        f" Extensions allowed there, read {allowed.fetched_at:%Y-%m-%d %H:%M:%S} and "
+        f"cached for {ttl_hours} h: {', '.join(sorted(allowed.extensions))}. "
+        "Call osw.site.clear_allowed_file_extensions_cache() to re-read the list "
+        "if the wiki configuration changed since."
+    )
 
 
 def reraise_upload_error(
-    error: mwclient.errors.APIError, mw_site, title: str, suffix: Optional[str]
+    error: mwclient.errors.APIError, site: WtSite, title: str, suffix: Optional[str]
 ) -> None:
     """Turns a rejected file extension into a readable error, re-raises the rest
 
@@ -34,15 +34,11 @@ def reraise_upload_error(
     """
     if "filetype" not in str(getattr(error, "code", "")):
         raise error
-    allowed = get_allowed_file_extensions(mw_site)
-    hint = (
-        f" Extensions allowed on this wiki: {', '.join(sorted(allowed))}."
-        if allowed
-        else ""
-    )
+    allowed = site.get_allowed_file_extensions()
+    hint = format_allowed_extensions(allowed)
     raise ValueError(
         f"Upload of '{title}' was rejected because the file extension "
-        f"'{suffix}' is not allowed on {mw_site.host}.{hint}"
+        f"'{suffix}' is not allowed on {site.mw_site.host}.{hint}"
     ) from error
 
 
@@ -216,7 +212,7 @@ def put(self, file: IO, **kwargs: Dict[str, Any]):
                 ignore=True,
             )
         except mwclient.errors.APIError as e:
-            reraise_upload_error(e, self.osw.mw_site, self.title, self.suffix)
+            reraise_upload_error(e, self.osw.site, self.title, self.suffix)
         assert_upload_success(result, self.title, self.osw.mw_site.host)
         self.osw.store_entity(
             OSW.StoreEntityParam(

src/osw/wtsite.py

@@ -10,7 +10,7 @@
 import warnings
 import xml.etree.ElementTree as et
 from copy import deepcopy
-from datetime import datetime
+from datetime import datetime, timedelta
 from io import StringIO
 from pathlib import Path
 from pprint import pprint
@@ -79,6 +79,9 @@ class WtSiteLegacyConfig(OswBaseModel):
         class Config:
             arbitrary_types_allowed = True
 
+    ALLOWED_FILE_EXTENSIONS_TTL = timedelta(hours=24)
+    """how long a fetched list of accepted file extensions stays valid"""
+
     def __init__(self, config: Union[WtSiteConfig, WtSiteLegacyConfig]):
         """creates a new WtSite instance from a WtSiteConfig
 
@@ -161,6 +164,10 @@ def __init__(self, config: Union[WtSiteConfig, WtSiteLegacyConfig]):
         self._page_cache = {}
         self._cache_enabled = False
 
+        # The file extensions the wiki accepts, read on demand and reused for
+        #  ALLOWED_FILE_EXTENSIONS_TTL
+        self._allowed_file_extensions = None
+
     def _get_session_lock(self) -> threading.RLock:
         """Return the session lock, lazily creating it if absent.
 
@@ -492,6 +499,68 @@ def clear_cache(self):
         del self._page_cache
         self._page_cache = {}
 
+    class AllowedFileExtensionsResult(OswBaseModel):
+        """The file extensions a wiki accepts and when that list was read"""
+
+        extensions: Optional[List[str]]
+        """the accepted extensions, None if the lookup failed"""
+        fetched_at: Optional[datetime]
+        """when the list was read from the wiki, None if the lookup failed"""
+
+    def get_allowed_file_extensions(
+        self, refresh: bool = False
+    ) -> AllowedFileExtensionsResult:
+        """Returns the file extensions the wiki accepts, from cache if possible
+
+        The list only changes when the wiki configuration changes, so it is
+        cached for ALLOWED_FILE_EXTENSIONS_TTL instead of being read on every
+        call. A failed lookup is never cached, so the next call retries; a
+        failed refresh leaves any previously cached list in place.
+
+        Parameters
+        ----------
+        refresh:
+            if True, bypasses the cache and re-reads the list from the wiki
+
+        Returns
+        -------
+            an AllowedFileExtensionsResult with the accepted extensions and
+            when they were read, or with both fields None if the lookup failed
+        """
+        cached = getattr(self, "_allowed_file_extensions", None)
+        if (
+            cached is not None
+            and not refresh
+            and cached.fetched_at is not None
+            and datetime.now() - cached.fetched_at < self.ALLOWED_FILE_EXTENSIONS_TTL
+        ):
+            return cached
+        try:
+            result = self.mw_site.api(
+                "query", meta="siteinfo", siprop="fileextensions", formatversion=2
+            )
+            extensions = [
+                entry["ext"]
+                for entry in result.get("query", {}).get("fileextensions", [])
+                if "ext" in entry
+            ]
+        except Exception:
+            # only used to enrich an error message, never worth failing over
+            return WtSite.AllowedFileExtensionsResult(extensions=None, fetched_at=None)
+        self._allowed_file_extensions = WtSite.AllowedFileExtensionsResult(
+            extensions=extensions, fetched_at=datetime.now()
+        )
+        return self._allowed_file_extensions
+
+    def clear_allowed_file_extensions_cache(self):
+        """Clears the cached list of file extensions the wiki accepts
+
+        The next get_allowed_file_extensions() call reads the list from the
+        wiki again. Use this when the wiki's upload configuration changed
+        within ALLOWED_FILE_EXTENSIONS_TTL.
+        """
+        self._allowed_file_extensions = None
+
     def _clear_cookies(self):
         # see https://github.com/mwclient/mwclient/issues/221
         # Iterate a snapshot (list(...)) so mutating the jar mid-loop is safe, and

tests/test_wiki_file_upload_errors.py

@@ -13,25 +13,38 @@
 
 from osw.controller.file.wiki import (
     assert_upload_success,
-    get_allowed_file_extensions,
+    format_allowed_extensions,
     reraise_upload_error,
     store_params_for_upload,
 )
+from osw.wtsite import WtSite
 
 
-class _FakeSite:
+class _FakeMwSite:
+    """Stands in for the mwclient.Site behind WtSite.mw_site."""
+
     host = "wiki.example.org"
 
     def __init__(self, extensions=None, fail=False):
-        self._extensions = extensions
+        self._extensions = extensions or []
         self._fail = fail
+        self.api_calls = 0
 
     def api(self, *args, **kwargs):
+        self.api_calls += 1
         if self._fail:
             raise RuntimeError("siteinfo unavailable")
         return {"query": {"fileextensions": [{"ext": e} for e in self._extensions]}}
 
 
+def _fake_site(extensions=None, fail=False):
+    """Builds a minimal WtSite carrying a fake mwclient site, bypassing __init__."""
+    ws = WtSite.__new__(WtSite)
+    ws._site = _FakeMwSite(extensions=extensions, fail=fail)
+    ws._allowed_file_extensions = None
+    return ws
+
+
 def _api_error(code):
     return mwclient.errors.APIError(code, "info", {})
 
@@ -40,7 +53,7 @@ def _api_error(code):
     "code", ["filetype-banned", "filetype-banned-type", "filetype-badtype"]
 )
 def test_rejected_extension_names_the_extension(code):
-    site = _FakeSite(extensions=["png", "pdf"])
+    site = _fake_site(extensions=["png", "pdf"])
 
     with pytest.raises(ValueError) as exc_info:
         reraise_upload_error(_api_error(code), site, "OSW123.exe", ".exe")
@@ -53,7 +66,7 @@ def test_rejected_extension_names_the_extension(code):
 
 
 def test_original_error_is_chained():
-    site = _FakeSite(extensions=["png"])
+    site = _fake_site(extensions=["png"])
     original = _api_error("filetype-banned")
 
     with pytest.raises(ValueError) as exc_info:
@@ -63,7 +76,7 @@ def test_original_error_is_chained():
 
 
 def test_unrelated_api_error_is_reraised_unchanged():
-    site = _FakeSite(extensions=["png"])
+    site = _fake_site(extensions=["png"])
     original = _api_error("readapidenied")
 
     with pytest.raises(mwclient.errors.APIError) as exc_info:
@@ -74,23 +87,50 @@ def test_unrelated_api_error_is_reraised_unchanged():
 
 def test_message_omits_the_hint_when_siteinfo_fails():
     """A failing siteinfo lookup must not mask the upload error."""
-    site = _FakeSite(fail=True)
+    site = _fake_site(fail=True)
+
+    with pytest.raises(ValueError) as exc_info:
+        reraise_upload_error(_api_error("filetype-banned"), site, "a.exe", ".exe")
+
+    message = str(exc_info.value)
+    assert "Extensions allowed" not in message
+    assert "clear_allowed_file_extensions_cache" not in message
+    assert ".exe" in message
+
+
+def test_message_names_the_fetch_time_and_the_reset_hint():
+    site = _fake_site(extensions=["png", "pdf"])
 
     with pytest.raises(ValueError) as exc_info:
         reraise_upload_error(_api_error("filetype-banned"), site, "a.exe", ".exe")
 
-    assert "allowed on this wiki" not in str(exc_info.value)
-    assert ".exe" in str(exc_info.value)
+    message = str(exc_info.value)
+    fetched_at = site.get_allowed_file_extensions().fetched_at
+    assert f"{fetched_at:%Y-%m-%d %H:%M:%S}" in message
+    assert "osw.site.clear_allowed_file_extensions_cache()" in message
+
+
+def test_a_second_rejected_upload_does_not_query_the_wiki_again():
+    site = _fake_site(extensions=["png", "pdf"])
+
+    with pytest.raises(ValueError):
+        reraise_upload_error(_api_error("filetype-banned"), site, "a.exe", ".exe")
+    with pytest.raises(ValueError):
+        reraise_upload_error(_api_error("filetype-banned"), site, "b.exe", ".exe")
+
+    assert site.mw_site.api_calls == 1
+
 
+def test_format_allowed_extensions_is_empty_when_extensions_is_none():
+    allowed = WtSite.AllowedFileExtensionsResult(extensions=None, fetched_at=None)
 
-def test_get_allowed_file_extensions_returns_none_on_failure():
-    assert get_allowed_file_extensions(_FakeSite(fail=True)) is None
+    assert format_allowed_extensions(allowed) == ""
 
 
-def test_get_allowed_file_extensions_reads_siteinfo():
-    site = _FakeSite(extensions=["png", "jpg"])
+def test_format_allowed_extensions_is_empty_when_extensions_is_empty():
+    allowed = WtSite.AllowedFileExtensionsResult(extensions=[], fetched_at=None)
 
-    assert get_allowed_file_extensions(site) == ["png", "jpg"]
+    assert format_allowed_extensions(allowed) == ""
 
 
 def test_successful_upload_passes():