From 19add6d18bb959e32da188af86cc3ed4ce475cc7 Mon Sep 17 00:00:00 2001
From: Jeff Erickson <16201464+jee7s@users.noreply.github.com>
Date: Sat, 20 Jun 2026 11:00:49 -0500
Subject: [PATCH] perf: make guest-user and nav-tree cache TTLs configurable
 (longer defaults)

Two periodic DB reads fire on anonymous/crawler page views, both *under*
Aurora Serverless v2's idle/pause window, so they keep the cluster awake
during scrapes:

- the guest user was reloaded from the DB every 1 minute (hardcoded)
- the sidebar nav tree was cached for only 300s (5 min)

Make both configurable and default them to 1 hour, so they no longer pin the
DB awake under sustained anonymous traffic (1h >> the 8-min pause window) and
the DB can idle between refreshes. Cuts guest-reload queries ~60x and nav
queries ~12x on scrape traffic.

Both stay correct: changing group permissions force-refreshes the guest user
immediately (flushGuestUser), and the admin "Flush Cache" clears the nav cache.

Env knobs (with defaults): AUTH_GUEST_CACHE_TTL=3600, NAV_CACHE_TTL=3600.
---
 config.sample.yml           | 15 +++++++++++++++
 dev/build/config.yml        |  3 +++
 server/app/data.yml         |  2 ++
 server/core/auth.js         |  2 +-
 server/models/navigation.js |  2 +-
 5 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/config.sample.yml b/config.sample.yml
index 579a64495e..e963e90807 100644
--- a/config.sample.yml
+++ b/config.sample.yml
@@ -37,6 +37,16 @@ db:
   # Optional - How often (in ms) the /healthz endpoint checks the DB (default: 14400000 = 4 hours)
   # healthCheckInterval: 14400000
 
+# ---------------------------------------------------------------------
+# Navigation
+# ---------------------------------------------------------------------
+
+# nav:
+  # Optional - How long (in seconds) to cache the sidebar navigation tree (default: 3600 = 1 hour)
+  # A longer TTL means fewer periodic DB queries (helps Aurora Serverless idle/pause);
+  # admin "Flush Cache" forces an immediate refresh.
+  # cacheTTL: 3600
+
 # ---------------------------------------------------------------------
 # Analytics
 # ---------------------------------------------------------------------
@@ -53,6 +63,11 @@ db:
   # Optional - How long (in seconds) to cache deserialized users (default: 14400 = 4 hours, 0 to disable)
   # userCacheTTL: 14400
 
+  # Optional - How long (in seconds) to cache the guest user + its permissions (default: 3600 = 1 hour)
+  # A longer TTL means fewer periodic DB queries on anonymous/crawler traffic; changing group
+  # permissions force-refreshes it immediately.
+  # guestCacheTTL: 3600
+
   # Optional - PostgreSQL / MySQL / MariaDB only:
   # -> Uncomment lines you need below and set `auto` to false
   # -> Full list of accepted options: https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options
diff --git a/dev/build/config.yml b/dev/build/config.yml
index 392a236839..cbb360b19c 100644
--- a/dev/build/config.yml
+++ b/dev/build/config.yml
@@ -22,7 +22,10 @@ ssl:
 logLevel: $(LOG_LEVEL:info)
 logFormat: $(LOG_FORMAT:default)
 ha: $(HA_ACTIVE)
+nav:
+  cacheTTL: $(NAV_CACHE_TTL:3600)
 analytics:
   cacheTTL: $(ANALYTICS_CACHE_TTL:86400)
 auth:
   userCacheTTL: $(AUTH_USER_CACHE_TTL:14400)
+  guestCacheTTL: $(AUTH_GUEST_CACHE_TTL:3600)
diff --git a/server/app/data.yml b/server/app/data.yml
index 495518ed0a..74e0ded123 100644
--- a/server/app/data.yml
+++ b/server/app/data.yml
@@ -58,6 +58,7 @@ defaults:
       verifySSL: true
     nav:
       mode: 'MIXED'
+      cacheTTL: 3600
     theming:
       theme: 'default'
       iconset: 'md'
@@ -74,6 +75,7 @@ defaults:
       tokenExpiration: '30m'
       tokenRenewal: '14d'
       userCacheTTL: 14400
+      guestCacheTTL: 3600
     editShortcuts:
       editFab: true
       editMenuBar: false
diff --git a/server/core/auth.js b/server/core/auth.js
index 1da18ae5d6..788820c80a 100644
--- a/server/core/auth.js
+++ b/server/core/auth.js
@@ -181,7 +181,7 @@ module.exports = {
       if (!user) {
         if (WIKI.auth.guest.cacheExpiration <= DateTime.utc()) {
           WIKI.auth.guest = await WIKI.models.users.getGuestUser()
-          WIKI.auth.guest.cacheExpiration = DateTime.utc().plus({ minutes: 1 })
+          WIKI.auth.guest.cacheExpiration = DateTime.utc().plus({ seconds: WIKI.config.auth.guestCacheTTL })
         }
         req.user = WIKI.auth.guest
         return next()
diff --git a/server/models/navigation.js b/server/models/navigation.js
index 41bc05cacd..7669eaceb0 100644
--- a/server/models/navigation.js
+++ b/server/models/navigation.js
@@ -45,7 +45,7 @@ module.exports = class Navigation extends Model {
 
       for (const tree of navTree.config) {
         if (cache) {
-          await WIKI.cache.set(`nav:sidebar:${tree.locale}`, tree.items, 300)
+          await WIKI.cache.set(`nav:sidebar:${tree.locale}`, tree.items, WIKI.config.nav.cacheTTL)
         }
       }
       if (bypassAuth) {