[PATCH proxmox v8 4/6] token shadow: add TTL window to token secret cache

[Samuel Rufinatscha <s.rufinatscha@proxmox.com>]

cached_secret_valid() currently stats the file on every request, which
performs a metadata() call on token.shadow each time. Under load this
adds unnecessary overhead, considering also the file usually should
rarely change.

This patch introduces a TTL boundary, controlled by
TOKEN_SECRET_CACHE_TTL_SECS. File metadata is only re-loaded once the
TTL has expired.

Signed-off-by: Samuel Rufinatscha <s.rufinatscha@proxmox.com>
---
Changes from v7 to v8:
* TTL fast path (read lock) and write-lock re-check now return
  cache.secret_matches(tokenid, secret) instead of just true, following
  the cached_secret_valid() merge from the previous patch
* Adjusted commit message

Changes from v6 to v7:
* Rebased

Changes from v5 to v6:
* Rebased

Changes from v4 to v5:
* Rebased
* Introduce shadow_check_within_ttl() helper

Changes from v3 to v4:
* Adjusted commit message

Changes from v2 to v3:
* Refactored refresh_cache_if_file_changed TTL logic.
* Remove had_prior_state check (replaced by last_checked logic).
* Improve TTL bound checks.
* Reword documentation warning for clarity.

Changes from v1 to v2:
* Add TOKEN_SECRET_CACHE_TTL_SECS and last_checked.
* Implement double-checked TTL: check with try_read first; only attempt
  refresh with try_write if expired/unknown.
* Fix TTL bookkeeping: update last_checked on the “file unchanged” path
  and after API mutations.
* Add documentation warning about TTL-delayed effect of manual
  token.shadow edits.

 proxmox-access-control/src/token_shadow.rs | 33 +++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/proxmox-access-control/src/token_shadow.rs b/proxmox-access-control/src/token_shadow.rs
index 810ff0c3..4185351e 100644
--- a/proxmox-access-control/src/token_shadow.rs
+++ b/proxmox-access-control/src/token_shadow.rs
@@ -27,6 +27,8 @@ static TOKEN_SECRET_CACHE: LazyLock<RwLock<ApiTokenSecretCache>> = LazyLock::new
         file_info: None,
     })
 });
+/// Max age in seconds of the token secret cache before checking for file changes.
+const TOKEN_SECRET_CACHE_TTL_SECS: i64 = 60;
 
 // Get exclusive lock
 fn lock_config() -> Result<ApiLockGuard, Error> {
@@ -57,15 +59,31 @@ fn write_file(data: HashMap<Authid, String>) -> Result<(), Error> {
 /// tokens for in-flight requests may still validate against the previous
 /// generation.
 ///
+/// If the cache file metadata's TTL has expired, will revalidate and invalidate the cache if
+/// needed.
+///
 /// Returns true if secret is cached and cache is still valid
 fn cached_secret_valid(tokenid: &Authid, secret: &str) -> bool {
     let now = epoch_i64();
 
-    // Best-effort refresh under write lock.
+    // Fast path: cache is fresh if generation matches and TTL not expired.
+    if let (Some(cache), Some(read_gen)) =
+        (TOKEN_SECRET_CACHE.try_read(), token_shadow_generation())
+    {
+        if cache.cached_gen == read_gen && cache.shadow_check_within_ttl(now) {
+            return cache.secret_matches(tokenid, secret);
+        }
+        // read lock drops here
+    } else {
+        return false;
+    }
+
+    // Slow path: best-effort refresh under write lock.
     let Some(mut cache) = TOKEN_SECRET_CACHE.try_write() else {
         return false;
     };
 
+    // Re-read generation after acquiring the lock (may have changed meanwhile).
     let Some(current_gen) = token_shadow_generation() else {
         return false;
     };
@@ -75,6 +93,12 @@ fn cached_secret_valid(tokenid: &Authid, secret: &str) -> bool {
         cache.reset_and_set_gen(current_gen);
     }
 
+    // TTL check again after acquiring the lock
+    let now = epoch_i64();
+    if cache.shadow_check_within_ttl(now) {
+        return cache.secret_matches(tokenid, secret);
+    }
+
     // Stat the file to detect manual edits.
     let Ok((new_mtime, new_len)) = shadow_mtime_len() else {
         return false;
@@ -224,6 +248,13 @@ impl ApiTokenSecretCache {
         self.cached_gen = new_gen;
     }
 
+    /// Returns true if cached token.shadow metadata exists and was checked within the TTL window.
+    fn shadow_check_within_ttl(&self, now: i64) -> bool {
+        self.file_info.as_ref().is_some_and(|cached| {
+            now >= cached.last_checked && (now - cached.last_checked) < TOKEN_SECRET_CACHE_TTL_SECS
+        })
+    }
+
     /// Returns true if there is a matching cached entry
     fn secret_matches(&self, tokenid: &Authid, secret: &str) -> bool {
         let Some(entry) = self.secrets.get(tokenid) else {
-- 
2.47.3