FUSE Cache FS

A performant, scalable read-through caching filesystem built with FUSE, designed for high-performance workloads.

It simulates:

• NFS (slow, elastic, cheap storage) as the primary source
• SSD (fast, limited, expensive storage) as the shared cache

This FUSE-based filesystem transparently serves files from SSD if available, and otherwise reads from NFS with a 500ms delay, caching the result.

---

Features

• Read-through caching
• Single SSD cache shared across all projects
• LRU eviction (10 files or 100KB limit)
• SHA256-based content validation (stale SSD files auto-invalidated)
• Metrics exposed on localhost:8080/metrics
• Background-tested with a Python pytest test runner
• Benchmarking scripts for performance evaluation
• Works transparently with Python execution from the mount
• Robust error handling

---

Architecture

fuse-cache-fs/
├── benchmarks/
│   └── benchmark.py
├── cmd/
│   └── fusecache/
│       └── main.go
├── nfs/
│   ├── project-1/
│   │   ├── common-lib.py
│   │   ├── main.py
│   │   └── ... (test files)
│   └── project-2/
│       ├── entrypoint.py
│       └── common-lib.py
├── pkg/
│   ├── cache/
│   │   └── cache.go
│   ├── fusefs/
│   │   ├── file.go
│   │   └── fs.go
│   └── metrics/
│       └── metrics.go
├── tests/
│   └── test_runner.py
├── Makefile
├── go.mod
├── go.sum
├── README.md
└── requirements.txt

Project Structure Explanation

• benchmarks/: Python scripts to benchmark latency, concurrency, hit/miss
• cmd/fusecache/: FUSE server entry point
• nfs/: simulated slow storage
• pkg/cache/: LRU caching logic
• pkg/fusefs/: core FUSE read-through logic
• pkg/metrics/: exposes Prometheus-compatible metrics
• tests/: pytest-based test runner
• Makefile: repeatable developer automation
• go.mod / go.sum: Go dependencies
• requirements.txt: Python dependencies
• README.md: documentation

---

Setup

Requirements

• Go 1.21+
• Python 3.12+
• Linux with FUSE3 installed

Installation

sudo apt update && sudo apt install fuse3
git clone https://github.com/YOUR_USERNAME/fuse-cache-fs.git
cd fuse-cache-fs
make setup

---

Running

make run

Mountpoint:

/tmp/mnt/all-projects

---

Testing

make test

This runs:

• pytest with functional tests
• verifies caching
• verifies metrics

---

Benchmarking

make bench

Simulates concurrent reads, reporting:

• latency
• throughput
• cache hit/miss rates

---

Metrics

The metrics server is available at:

http://localhost:8080/metrics

Example output:

fuse_cache_hits 12
fuse_cache_misses 4
fuse_cache_evictions 2

---

Usage Example

cd /tmp/mnt/all-projects/project-1
python3 main.py

Example: File in nfs/project-1/common-lib.py

def foo():
   print("hello world from common-lib")

First read (cache miss)

Command:

cat /tmp/mnt/all-projects/project-1/common-lib.py

Expected output:

def foo():
   print("hello world from common-lib")

Expected logs:

Cache miss: nfs/project-1/common-lib.py. Reading from NFS with 500ms delay.

Second read (cache hit)

Command:

cat /tmp/mnt/all-projects/project-1/common-lib.py

Expected logs:

Cache hit (validated by hash): ssd/project-1/common-lib.py

Python execution

Command:

cd /tmp/mnt/all-projects/project-1
python3 main.py

Expected output:

Hello from FUSE mount!
Finished running from FUSE!

Metrics check

Command:

curl http://localhost:8080/metrics

Expected:

fuse_cache_hits 1
fuse_cache_misses 1
fuse_cache_evictions 0

---

Design Decisions

• Used SHA256 hashes to validate file contents for correctness
• Used LRU with file count and byte size limits
• Go bazil/fuse for robust kernel integration
• Python test runner for easy integration
• Makefile for repeatable workflows

---

Future Improvements

• Background prefetch
• Prometheus pushgateway
• Persistent SSD index on disk
• Unit tests with mocks
• Write support (currently read-only)