server: ms endpoint fixes

crates/brk_server/src/cache.rs

@@ -1,19 +1,28 @@
 use axum::http::HeaderMap;
+use brk_types::{BlockHashPrefix, Version};
 
 use crate::{VERSION, extended::HeaderMapExtended};
 
 /// Cache strategy for HTTP responses.
 pub enum CacheStrategy {
-    /// Data that changes with each new block (addresses, mining stats, txs, outspends)
-    /// Etag = VERSION-{height}, Cache-Control: must-revalidate
-    Height,
+    /// Chain-dependent data (addresses, mining stats, txs, outspends).
+    /// Etag = {tip_hash_prefix:x}. Invalidates on any tip change including reorgs.
+    Tip,
 
-    /// Static/immutable data (blocks by hash, validate-address, series catalog)
-    /// Etag = VERSION only, Cache-Control: must-revalidate
+    /// Immutable data identified by hash in the URL (blocks by hash, confirmed tx data).
+    /// Etag = {version}. Permanent; only bumped when response format changes.
+    Immutable(Version),
+
+    /// Static non-chain data (validate-address, series catalog, pool list).
+    /// Etag = CARGO_PKG_VERSION. Invalidates on deploy.
     Static,
 
-    /// Mempool data - etag from next projected block hash + short max-age
-    /// Etag = VERSION-m{hash:x}, Cache-Control: max-age=1, must-revalidate
+    /// Immutable data bound to a specific block (confirmed tx data, block status).
+    /// Etag = {version}-{block_hash_prefix:x}. Invalidates naturally on reorg.
+    BlockBound(Version, BlockHashPrefix),
+
+    /// Mempool data — etag from next projected block hash.
+    /// Etag = m{hash:x}. Invalidates on mempool change.
     MempoolHash(u64),
 }
 
@@ -24,9 +33,12 @@ pub struct CacheParams {
 }
 
 impl CacheParams {
-    /// Cache params using VERSION as etag
-    pub fn version() -> Self {
-        Self::resolve(&CacheStrategy::Static, || unreachable!())
+    /// Cache params using CARGO_PKG_VERSION as etag (for openapi.json etc.)
+    pub fn static_version() -> Self {
+        Self {
+            etag: Some(format!("s{VERSION}")),
+            cache_control: "public, max-age=1, must-revalidate".into(),
+        }
     }
 
     pub fn etag_str(&self) -> &str {
@@ -39,20 +51,28 @@ impl CacheParams {
             .is_some_and(|etag| headers.has_etag(etag))
     }
 
-    pub fn resolve(strategy: &CacheStrategy, height: impl FnOnce() -> u32) -> Self {
-        use CacheStrategy::*;
+    pub fn resolve(strategy: &CacheStrategy, tip: impl FnOnce() -> BlockHashPrefix) -> Self {
+        let cache_control = "public, max-age=1, must-revalidate".into();
         match strategy {
-            Height => Self {
-                etag: Some(format!("{VERSION}-{}", height())),
-                cache_control: "public, max-age=1, must-revalidate".into(),
+            CacheStrategy::Tip => Self {
+                etag: Some(format!("t{:x}", *tip())),
+                cache_control,
             },
-            Static => Self {
-                etag: Some(VERSION.to_string()),
-                cache_control: "public, max-age=1, must-revalidate".into(),
+            CacheStrategy::Immutable(v) => Self {
+                etag: Some(format!("i{v}")),
+                cache_control,
             },
-            MempoolHash(hash) => Self {
-                etag: Some(format!("{VERSION}-m{hash:x}")),
-                cache_control: "public, max-age=1, must-revalidate".into(),
+            CacheStrategy::BlockBound(v, prefix) => Self {
+                etag: Some(format!("b{v}-{:x}", **prefix)),
+                cache_control,
+            },
+            CacheStrategy::Static => Self {
+                etag: Some(format!("s{VERSION}")),
+                cache_control,
+            },
+            CacheStrategy::MempoolHash(hash) => Self {
+                etag: Some(format!("m{hash:x}")),
+                cache_control,
             },
         }
     }