feat: Implement cache eviction with LRU, LFU, and TTL policies (#68)

* feat: Implement cache eviction with LRU, LFU, and TTL policies

Add automatic cache eviction to prevent unbounded disk usage. When the cache
exceeds the configured max_size, Fabrik automatically removes objects based
on the configured eviction policy.

## Features

- Three eviction policies: LRU (Least Recently Used), LFU (Least Frequently
  Used, default), and TTL (Time To Live)
- Configurable max cache size with human-readable format (5GB, 100MB, etc.)
- Configurable TTL with duration format (7d, 24h, 30m, etc.)
- Target ratio eviction (evicts until 90% of max_size)
- Metadata tracking: size, created_at, accessed_at, access_count

## Integration

Eviction is now integrated across all Fabrik surfaces:
- daemon command
- server command
- exec command
- cas CLI command
- kv CLI command
- C API (with new fabrik_cache_init_with_eviction function)

## Configuration

```toml
[cache]
dir = ".fabrik/cache"
max_size = "5GB"
eviction_policy = "lfu"  # lru | lfu | ttl
default_ttl = "7d"
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: Add async background eviction task

- Add EvictableStorage trait for storage backends to support eviction
- Implement background eviction task that runs every 30 seconds
- Remove blocking eviction from put() operations
- Update daemon, server, and exec commands to spawn eviction task
- Add graceful shutdown handling for background eviction
- Update documentation to explain async eviction behavior

Eviction now runs asynchronously in a dedicated tokio task, ensuring
that put() operations are never blocked by eviction. The task
periodically checks cache size and evicts objects according to the
configured policy (LRU, LFU, or TTL) when needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: Remove redundant [fabrik] prefix from log messages

The custom FabrikFormatter in src/logging.rs already adds (fabrik) to
all log output, so the manual [fabrik] prefix in log messages was
redundant.

Also:
- Move docs/c-api.md to docs/reference/c-api.md
- Add C API to documentation sidebar
- Add logging conventions to CLAUDE.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: pepicrft

CLAUDE.md

@@ -2150,6 +2150,12 @@ fabrik config show --config config.toml --config-upstream s3://override
 - Use `clippy` for linting (zero warnings policy)
 - Prioritize safety, idiomatic patterns, and zero-cost abstractions
 
+### Logging Conventions
+- Use the `tracing` crate (`info!`, `debug!`, `warn!`, `error!`) for all logging
+- **Do NOT add `[fabrik]` prefix to log messages** - the custom `FabrikFormatter` in `src/logging.rs` automatically adds `(fabrik)` to all log output
+- For CLI output (`println!`/`eprintln!`), use `fabrik_prefix()` from `src/cli_utils.rs` which provides colored output
+- Use structured fields for machine-parseable logs (see `src/logging.rs` for field constants)
+
 ### Project Principles
 - **Performance**: Low latency (target: <10ms p99), high throughput
 - **Reliability**: Data integrity, fault tolerance, graceful degradation

docs/.vitepress/config.mts

@@ -25,6 +25,7 @@ export default defineConfig({
       {
         text: "Cache",
         items: [
+          { text: "Eviction", link: "/cache/eviction" },
           { text: "Peer to Peer", link: "/cache/p2p" },
           {
             text: "Build Systems",
@@ -104,6 +105,7 @@ export default defineConfig({
           { text: "CLI Commands", link: "/reference/cli" },
           { text: "Configuration File", link: "/reference/config-file" },
           { text: "API Reference", link: "/reference/api" },
+          { text: "C API", link: "/reference/c-api" },
         ],
       },
     ],

docs/cache/eviction.md

@@ -0,0 +1,158 @@
+# Cache Eviction
+
+Fabrik provides automatic cache eviction to prevent unbounded disk usage. When the cache exceeds the configured `max_size`, Fabrik automatically removes objects based on the configured eviction policy.
+
+## Configuration
+
+Configure eviction in your `fabrik.toml`:
+
+```toml
+[cache]
+dir = ".fabrik/cache"
+max_size = "5GB"           # Maximum cache size
+eviction_policy = "lfu"    # lru | lfu | ttl
+default_ttl = "7d"         # Default time-to-live for TTL policy
+```
+
+## Eviction Policies
+
+### LFU (Least Frequently Used) - Default
+
+The LFU policy evicts objects with the lowest access count first. This is the default policy because it tends to preserve frequently-accessed build artifacts.
+
+```toml
+[cache]
+eviction_policy = "lfu"
+```
+
+**Best for:**
+- Build caches with stable dependency trees
+- Projects where common artifacts are accessed repeatedly
+- CI environments with shared caches
+
+### LRU (Least Recently Used)
+
+The LRU policy evicts objects that haven't been accessed for the longest time.
+
+```toml
+[cache]
+eviction_policy = "lru"
+```
+
+**Best for:**
+- Development environments with rapidly changing dependencies
+- Projects with distinct build phases
+- When recent builds are more important than frequency
+
+### TTL (Time To Live)
+
+The TTL policy evicts objects older than the configured TTL. Objects are evicted based on creation time, not access time.
+
+```toml
+[cache]
+eviction_policy = "ttl"
+default_ttl = "7d"  # Evict objects older than 7 days
+```
+
+**Best for:**
+- Compliance requirements with data retention limits
+- Ensuring cache freshness
+- Periodic cache invalidation scenarios
+
+## How Eviction Works
+
+Eviction runs **asynchronously in a background task**, ensuring that `put()` operations are never blocked by eviction:
+
+1. **Background Task**: A dedicated tokio task periodically checks cache size (default: every 30 seconds)
+2. **Trigger**: When cache exceeds `max_size`, the background task evicts objects
+3. **Target**: Fabrik evicts until the cache is at 90% of `max_size` (configurable via `target_ratio`)
+4. **Selection**: Objects are selected based on the configured policy
+5. **Batch Processing**: Up to 1000 objects are evicted per run to avoid overwhelming the system
+6. **Non-blocking**: `put()` operations proceed immediately without waiting for eviction
+
+### Metadata Tracking
+
+Fabrik tracks the following metadata for each cached object:
+- **Size**: Object size in bytes
+- **Created At**: When the object was first cached
+- **Accessed At**: Last access timestamp (updated on get/exists)
+- **Access Count**: Number of times the object was accessed
+
+This metadata is stored efficiently in RocksDB secondary indexes for fast eviction candidate selection.
+
+## Size Format
+
+The `max_size` configuration accepts human-readable size strings:
+
+| Format | Example | Bytes |
+|--------|---------|-------|
+| Terabytes | `1TB` | 1,099,511,627,776 |
+| Gigabytes | `5GB` | 5,368,709,120 |
+| Megabytes | `500MB` | 524,288,000 |
+| Kilobytes | `512KB` | 524,288 |
+| Bytes | `1024` | 1,024 |
+
+## TTL Format
+
+The `default_ttl` configuration accepts duration strings:
+
+| Format | Example | Seconds |
+|--------|---------|---------|
+| Days | `7d` | 604,800 |
+| Hours | `24h` | 86,400 |
+| Minutes | `30m` | 1,800 |
+| Seconds | `3600s` or `3600` | 3,600 |
+
+## Monitoring Eviction
+
+Fabrik logs eviction activity at the INFO level:
+
+```
+INFO [fabrik] Eviction manager initialized: policy=lfu, max_size=5120MB, target_ratio=0.9
+INFO [fabrik] Eviction complete: evicted 42 objects (128 MB) in 25ms
+```
+
+## Environment Variable Overrides
+
+You can override eviction settings via environment variables:
+
+```bash
+# Override max cache size
+export FABRIK_CONFIG_CACHE_MAX_SIZE=10GB
+
+# Override eviction policy
+export FABRIK_CONFIG_CACHE_EVICTION_POLICY=lru
+
+# Override default TTL
+export FABRIK_CONFIG_CACHE_DEFAULT_TTL=14d
+```
+
+## C API Support
+
+The C API provides two initialization functions:
+
+```c
+// Basic initialization with default eviction (5GB, LFU, 7 days)
+FabrikCache* cache = fabrik_cache_init("/path/to/cache");
+
+// Custom eviction settings
+FabrikCache* cache = fabrik_cache_init_with_eviction(
+    "/path/to/cache",
+    10ULL * 1024 * 1024 * 1024,  // 10GB max size
+    1,                           // 0=LRU, 1=LFU, 2=TTL
+    7 * 24 * 60 * 60            // 7 days TTL
+);
+```
+
+## Best Practices
+
+1. **Set realistic limits**: Choose a `max_size` that fits your available disk space while leaving room for other applications
+2. **Choose the right policy**: LFU works best for most build caches, but LRU may be better for development
+3. **Monitor eviction**: Watch the logs to ensure eviction is working as expected and adjust settings if needed
+4. **Consider TTL for compliance**: Use TTL policy when you need predictable cache expiration
+
+> [!NOTE]
+> Eviction runs asynchronously in the background every 30 seconds. The cache may temporarily exceed `max_size` between eviction runs.
+
+> [!WARNING]
+> Setting `max_size` too low may cause frequent eviction and reduce cache hit rates. Monitor your cache performance after changing eviction settings.

docs/c-api.md docs/reference/c-api.mddocs/c-api.md renamed to docs/reference/c-api.md

@@ -2,15 +2,6 @@
 
 The Fabrik C API provides a thread-safe interface for integrating Fabrik cache into C/C++ applications and other toolchains.
 
-## Features
-
-- ✅ Thread-safe operations
-- ✅ Content-addressed storage
-- ✅ Simple error handling
-- ✅ Cross-platform (Linux, macOS, Windows)
-- ✅ Zero-copy where possible
-- ✅ Comprehensive error messages
-
 ## Installation
 
 ### From Releases
@@ -132,7 +123,7 @@ typedef struct FabrikCache FabrikCache;
 
 #### `fabrik_cache_init`
 
-Initialize a new cache instance.
+Initialize a new cache instance with default eviction settings (5GB max size, LFU policy, 7 days TTL).
 
 ```c
 FabrikCache* fabrik_cache_init(const char *cache_dir);
@@ -155,6 +146,50 @@ if (!cache) {
 
 ---
 
+#### `fabrik_cache_init_with_eviction`
+
+Initialize a new cache instance with custom eviction settings.
+
+```c
+FabrikCache* fabrik_cache_init_with_eviction(
+    const char *cache_dir,
+    uint64_t max_size_bytes,
+    int eviction_policy,
+    uint64_t ttl_seconds
+);
+```
+
+**Parameters:**
+- `cache_dir`: Path to cache directory (NULL-terminated C string)
+- `max_size_bytes`: Maximum cache size in bytes (0 for default: 5GB)
+- `eviction_policy`: Eviction policy (0=LRU, 1=LFU, 2=TTL)
+- `ttl_seconds`: Default TTL in seconds (0 for default: 7 days)
+
+**Returns:**
+- Pointer to `FabrikCache` on success
+- `NULL` on error (use `fabrik_last_error()` for details)
+
+**Example:**
+```c
+// 10GB cache with LRU eviction and 14 day TTL
+FabrikCache *cache = fabrik_cache_init_with_eviction(
+    "/home/user/.cache/fabrik",
+    10ULL * 1024 * 1024 * 1024,  // 10GB
+    0,                           // LRU
+    14 * 24 * 60 * 60           // 14 days
+);
+if (!cache) {
+    fprintf(stderr, "Init failed: %s\n", fabrik_last_error());
+}
+```
+
+**Eviction Policies:**
+- `0` (LRU): Least Recently Used - evicts objects not accessed for longest time
+- `1` (LFU): Least Frequently Used - evicts objects with lowest access count (default)
+- `2` (TTL): Time To Live - evicts objects older than specified TTL
+
+---
+
 #### `fabrik_cache_free`
 
 Free a cache instance.

include/fabrik.h

@@ -96,6 +96,7 @@
  - Async batched access tracking (touch operations)
  - Snappy compression for metadata
  - Column families for efficient indexing (LRU/LFU eviction)
+ - Automatic eviction when cache exceeds max_size
  */
 typedef struct FabrikFilesystemStorage FabrikFilesystemStorage;
 
@@ -122,6 +123,29 @@ typedef struct FabrikFabrikCache {
  */
 fabrik_ struct FabrikFabrikCache *fabrik_cache_init(const char *aCacheDir);
 
+/*
+ Initialize a new Fabrik cache instance with custom eviction settings
+
+ # Arguments
+ * `cache_dir` - Path to cache directory (NULL-terminated C string)
+ * `max_size_bytes` - Maximum cache size in bytes (0 for default: 5GB)
+ * `eviction_policy` - Eviction policy: 0=LRU, 1=LFU, 2=TTL (default: LFU)
+ * `ttl_seconds` - Default TTL in seconds (0 for default: 7 days)
+
+ # Returns
+ * Pointer to FabrikCache on success
+ * NULL on error (use `fabrik_last_error()` to get error message)
+
+ # Safety
+ * `cache_dir` must be a valid NULL-terminated C string
+ * Returned pointer must be freed with `fabrik_cache_free()`
+ */
+fabrik_
+struct FabrikFabrikCache *fabrik_cache_init_with_eviction(const char *aCacheDir,
+                                                          uint64_t aMaxSizeBytes,
+                                                          int aEvictionPolicy,
+                                                          uint64_t aTtlSeconds);
+
 /*
  Free a Fabrik cache instance
 

src/auth/provider.rs

@@ -284,7 +284,7 @@ impl AuthProvider {
                 self.oauth2_url.as_ref().expect("OAuth2 URL should be set")
             );
             if let Ok(Some(_)) = wrapper.get_token(&token_key) {
-                tracing::debug!("[fabrik] Auto-detected OAuth2 (token found in storage)");
+                tracing::debug!("Auto-detected OAuth2 (token found in storage)");
                 return Ok(ConfigAuthProvider::OAuth2);
             }
         }
@@ -372,7 +372,7 @@ impl AuthProvider {
             ))?
             .clone();
 
-        tracing::info!("[fabrik] Starting OAuth2 device authorization flow (RFC 8628)");
+        tracing::info!("Starting OAuth2 device authorization flow (RFC 8628)");
 
         let oauth2_url = self.oauth2_url.clone();
 
@@ -402,7 +402,7 @@ impl AuthProvider {
             .await
             .map_err(|e| AuthenticationError::OAuth2Error(format!("Task join error: {}", e)))??;
 
-        tracing::info!("[fabrik] Successfully authenticated");
+        tracing::info!("Successfully authenticated");
 
         Ok(())
     }
@@ -426,12 +426,12 @@ impl AuthProvider {
                 );
                 wrapper.delete_token(&token_key)?;
 
-                tracing::info!("[fabrik] Successfully logged out");
+                tracing::info!("Successfully logged out");
                 Ok(())
             }
             ConfigAuthProvider::Token => {
                 // For token-based auth, we don't store anything, so nothing to delete
-                tracing::info!("[fabrik] Token-based authentication doesn't require logout");
+                tracing::info!("Token-based authentication doesn't require logout");
                 Ok(())
             }
         }