v2.2.8

NEWS.md

@@ -6,6 +6,15 @@ width: 128px;
 border-radius: 128px;
 " />
 
+## v2.2.8
+
+- Fixes
+    - Codex updates itself again, automatically or on demand, and announces new
+      versions.
+- Documentation
+    - Docs for passing through the Server: HTTP header so codex may be
+      identified by OPDS clients like Stump.
+
 ## v2.2.7
 
 - Fixes

README.md

@@ -651,6 +651,9 @@ location ^~ /codex {
     # If the nginx credentials are different than codex credentials use this line to
     #   not forward the authorization.
     proxy_set_header   Authorization "";
+    # Let clients see "Server: codex/<version>" instead of "Server: nginx".
+    # nginx hides the upstream Server header by default. See below.
+    proxy_pass_header  Server;
 }
 ```
 
@@ -666,6 +669,37 @@ of the `/codex` location with `auth_request`, exempt the API the way Codex's own
 examples do (`location /codex/api { auth_request off; ... }`); the `^~` note
 above is what keeps the static assets reachable.
 
+#### Preserving the Codex Server Header
+
+Codex identifies itself with a `Server: codex/<version>` response header, which
+is how OPDS clients, uptime monitors and support requests tell a Codex install
+apart from whatever is proxying it. nginx does **not** pass that header through:
+by default it hides `Date`, `Server`, `X-Accel-...` and `X-Pad` from the
+upstream response and substitutes its own `Server: nginx/<version>`. Add
+[`proxy_pass_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header)
+to the Codex location (as in the example above) to un-hide it:
+
+```nginx
+proxy_pass_header Server;
+```
+
+```console
+$ curl -sI https://example.com/codex/ | grep -i '^server'
+server: codex/2.2.8
+```
+
+Notes:
+
+- `server_tokens off;` is not a substitute. It only shortens nginx's own header
+  to `Server: nginx`; the Codex header is still discarded.
+- Like `proxy_set_header`, `proxy_pass_header` is inherited from the enclosing
+  `http {}` / `server {}` block **only if no `proxy_pass_header` is defined in
+  the location itself**. Keep it in the same block as the rest of the Codex
+  proxy headers.
+- Other reverse proxies have their own rules for the `Server` header; if
+  `curl -sI` shows something other than `codex/<version>`, check your proxy's
+  documentation for passing upstream response headers through.
+
 #### Nginx Reverse Proxy 502 when container refreshes
 
 Nginx requires a special trick to refresh dns when linked Docker containers

codex/librarian/bookmark/bookmarkd.py

@@ -146,7 +146,9 @@ def _process_task_immediately(self, task) -> None:
                 )
                 self._spawn_offline(
                     "latest-version",
-                    lambda: worker.update_latest_version(force=task.force),
+                    lambda: worker.update_latest_version(
+                        force=task.force, update=task.update
+                    ),
                 )
             case _:
                 self.log.warning(f"Unknown Bookmark task {task}")

codex/librarian/bookmark/latest_version.py

@@ -2,32 +2,96 @@
 
 import json
 from datetime import timedelta
-from typing import Final
+from threading import Lock
+from time import monotonic
+from typing import ClassVar, Final
 from urllib.request import urlopen
 
 from django.utils import timezone
 
+from codex.choices.admin import AdminFlagChoices
 from codex.librarian.scribe.janitor.status import JanitorCodexLatestVersionStatus
 from codex.librarian.scribe.janitor.tasks import JanitorCodexUpdateTask
 from codex.librarian.worker import WorkerStatusBase
-from codex.models import Timestamp
+from codex.models import AdminFlag, Timestamp
 from codex.version import PACKAGE_NAME
 
 _REPO_URL: Final = f"https://pypi.python.org/pypi/{PACKAGE_NAME}/json"
 _CACHE_EXPIRY: Final = timedelta(days=1) - timedelta(minutes=5)
 _REPO_TIMEOUT: Final = 5
+_FAILURE_BACKOFF: Final = 600.0
+
+
+class _FetchGate:
+    """
+    Process wide guard against stampeding PyPI fetches.
+
+    Every ``CodexLatestVersionTask`` builds a fresh updater on its own
+    daemon thread, so this state cannot live on the instance. While the
+    cache is empty *every* request to ``/api/v4/version`` queues a fetch
+    task, so without the lock a slow or unreachable PyPI means one
+    5 second outbound connection per request. ``next_attempt`` adds a
+    cooldown after a failure so an outage doesn't retry on every hit.
+    """
+
+    lock: ClassVar[Lock] = Lock()
+    next_attempt: ClassVar[float] = 0.0
 
 
 class CodexLatestVersionUpdater(WorkerStatusBase):
     """Methods for fetching the latest version."""
 
     @staticmethod
-    def _fetch_latest_version():
+    def _fetch_latest_version() -> str:
         """Fetch Latest Remotely."""
         response = urlopen(_REPO_URL, timeout=_REPO_TIMEOUT)
         source = response.read()
         decoded_source = source.decode("utf-8")
-        return json.loads(decoded_source)["info"]["version"]
+        latest_version = json.loads(decoded_source)["info"]["version"]
+        if not latest_version:
+            reason = "Bad latest version fetched."
+            raise ValueError(reason)
+        return latest_version
+
+    def _is_fetch_due(self, ts, *, force: bool) -> bool:
+        """Is the cached latest version stale enough to refetch."""
+        if not (
+            force or not ts.value or timezone.now() - ts.updated_at > _CACHE_EXPIRY
+        ):
+            self.log.debug("Not fetching new latest version, not expired.")
+            return False
+        if not force and monotonic() < _FetchGate.next_attempt:
+            self.log.debug("Not fetching new latest version, waiting after a failure.")
+            return False
+        return True
+
+    def _fetch_latest_version_into_cache(self, ts, *, force: bool) -> None:
+        """Fetch the latest version into the timestamp cache if it's due."""
+        if not self._is_fetch_due(ts, force=force):
+            return
+        if not _FetchGate.lock.acquire(blocking=False):
+            self.log.debug("Latest codex version fetch already in flight.")
+            return
+        try:
+            latest_version = self._fetch_latest_version()
+        except Exception:
+            _FetchGate.next_attempt = monotonic() + _FAILURE_BACKOFF
+            raise
+        finally:
+            _FetchGate.lock.release()
+        ts.value = latest_version
+        ts.save()
+        self.log.info(f"Saved new latest codex version {latest_version}.")
+
+    def _queue_update(self, ts) -> None:
+        """Chain into an update task if the admin enabled automatic updates."""
+        if not ts.value:
+            return
+        flag = AdminFlag.objects.only("on").get(key=AdminFlagChoices.AUTO_UPDATE.value)
+        if not flag.on:
+            self.log.debug("Auto update is disabled, not updating codex.")
+            return
+        self.librarian_queue.put(JanitorCodexUpdateTask())
 
     def update_latest_version(self, *, force: bool, update: bool = False) -> None:
         """Get the latest version from a remote repo using a cache."""
@@ -38,26 +102,10 @@ def update_latest_version(self, *, force: bool, update: bool = False) -> None:
         try:
             self.status_controller.start(status)
             ts = Timestamp.objects.get(key=Timestamp.Choices.CODEX_VERSION.value)
-            do_fetch = (
-                force
-                or not ts.value
-                or (timezone.now() - ts.updated_at > _CACHE_EXPIRY)
-            )
-            if do_fetch:
-                latest_version = self._fetch_latest_version()
-                if not latest_version:
-                    reason = "Bad latest version fetched."
-                    raise ValueError(reason)
-                ts.value = latest_version
-                ts.save()
-                level = "INFO"
-                log_txt = f"Saved new latest codex version {latest_version}."
-                if update:
-                    task = JanitorCodexUpdateTask()
-                    self.librarian_queue.put(task)
-            else:
-                level = "DEBUG"
-                log_txt = "Not fetching new latest version, not expired."
-            self.log.log(level, log_txt)
+            self._fetch_latest_version_into_cache(ts, force=force)
+            if update:
+                # Only after a completed fetch, so the update decision
+                # sees the version this run just learned about.
+                self._queue_update(ts)
         finally:
             self.status_controller.finish(status)

codex/librarian/bookmark/tasks.py

@@ -50,6 +50,15 @@ class ClearLibrarianStatusTask(BookmarkTask):
 
 @dataclass
 class CodexLatestVersionTask(BookmarkTask):
-    """Get the latest version."""
+    """
+    Get the latest version.
+
+    ``update`` requests that a successful fetch chain into a
+    ``JanitorCodexUpdateTask`` if the Auto Update admin flag is on.
+    Only the nightly janitor sets it. Chaining (rather than queueing
+    both tasks up front) keeps the update from racing ahead of the
+    fetch that tells it whether an update is even available.
+    """
 
     force: bool = False
+    update: bool = False

codex/librarian/scribe/janitor/janitor.py

@@ -86,26 +86,30 @@
     RemoveCoversStatus,
 )
 
-_NIGHTLY_TASK_CLASSES: Final[tuple[type[LibrarianTask], ...]] = (
-    CodexLatestVersionTask,
-    JanitorAdoptOrphanFoldersTask,
-    JanitorForeignKeyCheckTask,
-    JanitorFolderRelationsCheckTask,
-    JanitorIntegrityCheckTask,
-    JanitorFTSIntegrityCheckTask,
-    JanitorCleanFKsTask,
-    JanitorCleanCoversTask,
-    JanitorCleanupSessionsTask,
-    JanitorCleanupBookmarksTask,
-    JanitorCleanupSettingsTask,
-    JanitorCleanupFavoritesTask,
-    JanitorCleanupTaggingStateTask,
-    SearchIndexSyncTask,
-    SearchIndexOptimizeTask,
-    JanitorVacuumTask,
-    JanitorBackupTask,
-    JanitorDumpUserDataTask,
-    CoverRemoveOrphansTask,
+_NIGHTLY_TASKS: Final[tuple[LibrarianTask, ...]] = (
+    # Instances, not classes: the version check carries arguments. It
+    # forces a fetch (the nightly run is the daily refresh) and asks the
+    # fetcher to chain into an update task, which it does only if the
+    # Auto Update admin flag is on.
+    CodexLatestVersionTask(force=True, update=True),
+    JanitorAdoptOrphanFoldersTask(),
+    JanitorForeignKeyCheckTask(),
+    JanitorFolderRelationsCheckTask(),
+    JanitorIntegrityCheckTask(),
+    JanitorFTSIntegrityCheckTask(),
+    JanitorCleanFKsTask(),
+    JanitorCleanCoversTask(),
+    JanitorCleanupSessionsTask(),
+    JanitorCleanupBookmarksTask(),
+    JanitorCleanupSettingsTask(),
+    JanitorCleanupFavoritesTask(),
+    JanitorCleanupTaggingStateTask(),
+    SearchIndexSyncTask(),
+    SearchIndexOptimizeTask(),
+    JanitorVacuumTask(),
+    JanitorBackupTask(),
+    JanitorDumpUserDataTask(),
+    CoverRemoveOrphansTask(),
 )
 _JANITOR_METHOD_MAP: Final[MappingProxyType[type, str]] = MappingProxyType(
     {
@@ -147,8 +151,8 @@ def queue_nightly_tasks(self) -> None:
         """Queue all the janitor tasks."""
         try:
             self.status_controller.start_many(_JANITOR_STATII)
-            for task_class in _NIGHTLY_TASK_CLASSES:
-                self.librarian_queue.put(task_class())
+            for task in _NIGHTLY_TASKS:
+                self.librarian_queue.put(task)
             Timestamp.touch(Timestamp.Choices.JANITOR)
         except Exception:
             self.log.exception(f"In {self.__class__.__name__}")