server: snapshot

crates/brk_server/src/cache.rs

@@ -0,0 +1,108 @@
+use axum::http::HeaderMap;
+
+use crate::{VERSION, extended::HeaderMapExtended};
+
+/// Minimum confirmations before data is considered immutable
+pub const MIN_CONFIRMATIONS: u32 = 6;
+
+/// Cache strategy for HTTP responses.
+///
+/// # Future optimization: Immutable caching for blocks/txs
+///
+/// The `Immutable` variant supports caching deeply-confirmed blocks/txs forever
+/// (1 year, `immutable` directive). To use it, you need the confirmation count:
+///
+/// ```ignore
+/// // Example: cache block by hash as immutable if deeply confirmed
+/// let confirmations = current_height - block_height + 1;
+/// let prefix = *BlockHashPrefix::from(&hash);
+/// state.cached_json(&headers, CacheStrategy::immutable(prefix, confirmations), |q| q.block(&hash)).await
+/// ```
+///
+/// Currently all block/tx handlers use `Height` for simplicity since determining
+/// confirmations requires knowing the block height upfront (an extra lookup).
+/// This could be optimized by either:
+/// 1. Including confirmation count in the response type
+/// 2. Doing a lightweight height lookup before the main query
+pub enum CacheStrategy {
+    /// Immutable data (blocks by hash with 6+ confirmations)
+    /// Etag = VERSION-{prefix:x}, Cache-Control: immutable, 1yr
+    /// Falls back to Height if < 6 confirmations
+    Immutable { prefix: u64, confirmations: u32 },
+
+    /// Data that changes with each new block (addresses, block-by-height)
+    /// Etag = VERSION-{height}, Cache-Control: must-revalidate
+    Height,
+
+    /// Data that changes with height + depends on parameter
+    /// Etag = VERSION-{height}-{suffix}, Cache-Control: must-revalidate
+    HeightWith(String),
+
+    /// Static data (validate-address, metrics catalog)
+    /// Etag = VERSION only, Cache-Control: 1hr
+    Static,
+
+    /// Volatile data (mempool) - no etag, just max-age
+    /// Cache-Control: max-age={seconds}
+    MaxAge(u64),
+}
+
+impl CacheStrategy {
+    /// Create Immutable strategy - pass *prefix (deref BlockHashPrefix/TxidPrefix to u64)
+    pub fn immutable(prefix: u64, confirmations: u32) -> Self {
+        Self::Immutable {
+            prefix,
+            confirmations,
+        }
+    }
+
+    /// Create HeightWith from any Display type
+    pub fn height_with(suffix: impl std::fmt::Display) -> Self {
+        Self::HeightWith(suffix.to_string())
+    }
+}
+
+/// Resolved cache parameters
+pub struct CacheParams {
+    pub etag: Option<String>,
+    pub cache_control: String,
+}
+
+impl CacheParams {
+    pub fn etag_str(&self) -> &str {
+        self.etag.as_deref().unwrap_or("")
+    }
+
+    pub fn matches_etag(&self, headers: &HeaderMap) -> bool {
+        self.etag.as_ref().is_some_and(|etag| headers.has_etag(etag))
+    }
+
+    pub fn resolve(strategy: &CacheStrategy, height: impl FnOnce() -> u32) -> Self {
+        use CacheStrategy::*;
+        match strategy {
+            Immutable {
+                prefix,
+                confirmations,
+            } if *confirmations >= MIN_CONFIRMATIONS => Self {
+                etag: Some(format!("{VERSION}-{prefix:x}")),
+                cache_control: "public, max-age=31536000, immutable".into(),
+            },
+            Immutable { .. } | Height => Self {
+                etag: Some(format!("{VERSION}-{}", height())),
+                cache_control: "public, max-age=1, must-revalidate".into(),
+            },
+            HeightWith(suffix) => Self {
+                etag: Some(format!("{VERSION}-{}-{suffix}", height())),
+                cache_control: "public, max-age=1, must-revalidate".into(),
+            },
+            Static => Self {
+                etag: Some(VERSION.to_string()),
+                cache_control: "public, max-age=1, must-revalidate".into(),
+            },
+            MaxAge(secs) => Self {
+                etag: None,
+                cache_control: format!("public, max-age={secs}"),
+            },
+        }
+    }
+}