global: big snapshot

crates/brk_server/README.md

@@ -6,16 +6,22 @@ HTTP API server for Bitcoin on-chain analytics.
 
 - **OpenAPI spec**: Auto-generated docs at `/api` with full spec at `/openapi.json`
 - **LLM-optimized**: Compact spec at `/api.json` for AI tools
-- **Response caching**: ETag-based with LRU cache (5000 entries)
+- **Response caching**: ETag-based with LRU cache (1000 entries by default, configurable via `ServerConfig::cache_size`)
 - **Compression**: Brotli, gzip, deflate, zstd
 - **Static files**: Optional web interface hosting
 
 ## Usage
 
 ```rust,ignore
-let server = Server::new(&async_query, data_path, Website::Filesystem(files_path));
-// Or Website::Default, or Website::Disabled
-server.serve().await?;
+let server = Server::new(
+    &async_query,
+    ServerConfig {
+        data_path,
+        website: Website::Filesystem(files_path),
+        ..Default::default()
+    },
+);
+server.serve(None).await?;
 ```
 
 ## Endpoints
@@ -35,10 +41,19 @@ server.serve().await?;
 
 ## Caching
 
-Uses ETag-based caching with `must-revalidate`:
-- **Height-indexed**: Invalidates when new block arrives
-- **Immutable**: 1-year cache for deeply-confirmed blocks/txs (6+ confirmations)
-- **Mempool**: Short max-age, no ETag
+ETag-based revalidation. Five strategies pick the etag scheme:
+
+- **Tip**: chain-state, etag = tip hash prefix (invalidates per block + reorgs)
+- **Immutable**: deeply-confirmed data, etag = format version
+- **BlockBound**: data tied to a specific block hash (reorg-safe)
+- **Deploy**: catalog/static data, etag = build version
+- **MempoolHash**: mempool data, etag = projected next-block hash
+
+Browser sees `Cache-Control: public, no-cache, stale-if-error=86400` (always
+revalidate, ETag makes it cheap). CDN sees a separate `CDN-Cache-Control`
+directive whose stable tier is selected by `CdnCacheMode` (`Live` revalidates
+every request; `Aggressive` caches up to a year as `immutable` and requires a
+purge on deploy).
 
 ## Configuration