perf(api-server): tune gallery load shedding

server-rs/crates/api-server/src/puzzle_gallery_cache.rs

@@ -10,7 +10,7 @@ use shared_contracts::{
     puzzle_works::PuzzleWorkSummaryResponse,
 };
 use tokio::{
-    sync::{Mutex, MutexGuard, RwLock},
+    sync::{Mutex, MutexGuard, OwnedMutexGuard, RwLock},
     time,
 };
 
@@ -69,6 +69,18 @@ impl PuzzleGalleryCache {
         })
     }
 
+    pub async fn read_stale_response(&self) -> Option<PuzzleGalleryCachedResponse> {
+        let guard = self.inner.read().await;
+        let entry = guard.as_ref()?;
+        Some(PuzzleGalleryCachedResponse {
+            data_json: entry.data_json.clone(),
+        })
+    }
+
+    pub fn try_acquire_owned_rebuild_guard(&self) -> Option<OwnedMutexGuard<()>> {
+        self.rebuild_lock.clone().try_lock_owned().ok()
+    }
+
     pub async fn store_response(
         &self,
         response: PuzzleGalleryResponse,
@@ -205,4 +217,36 @@ mod tests {
         assert!(!response.has_more);
         assert_eq!(response.next_cursor, None);
     }
+
+    #[tokio::test]
+    async fn stale_response_remains_readable_after_fresh_ttl() {
+        let cache = PuzzleGalleryCache::new();
+        let response =
+            build_puzzle_gallery_window_response((0..8).map(build_summary).collect::<Vec<_>>());
+        cache
+            .store_response(response)
+            .await
+            .expect("cache response should serialize");
+
+        {
+            let mut guard = cache.inner.write().await;
+            let entry = guard.as_mut().expect("cache entry should exist");
+            entry.built_at = Instant::now() - PUZZLE_GALLERY_CACHE_TTL - Duration::from_secs(1);
+        }
+
+        assert!(cache.read_fresh_response().await.is_none());
+        assert!(cache.read_stale_response().await.is_some());
+    }
+
+    #[tokio::test]
+    async fn try_owned_rebuild_guard_allows_only_one_refresher() {
+        let cache = PuzzleGalleryCache::new();
+        let first_guard = cache.try_acquire_owned_rebuild_guard();
+
+        assert!(first_guard.is_some());
+        assert!(cache.try_acquire_owned_rebuild_guard().is_none());
+
+        drop(first_guard);
+        assert!(cache.try_acquire_owned_rebuild_guard().is_some());
+    }
 }