A high-performance distributed blob cache system built with C++20 and the Elio coroutine library.

• Multi-level caching: Memory -> Disk -> Distributed cluster hierarchy
• Partial read support: Access any byte range of cached values up to 20TB
• Decentralized architecture: No single point of failure, nodes discover each other via gossip
• High throughput: Lock-free data structures, async I/O with io_uring
• Flexible APIs: HTTP REST API and zero-dependency C SDK
• Prometheus metrics: Built-in metrics export for monitoring

mkdir build && cd build
cmake ..
make -j$(nproc)

# Start with default settings (1GB memory cache)
./elcached

# Custom configuration
./elcached -m 4096 -p 8080 -d /var/cache/elcache -D 100

# With config file
./elcached -c /etc/elcache/elcache.json

# Store a value
curl -X PUT http://localhost:8080/cache/mykey -d "Hello, World!"

# Retrieve a value
curl http://localhost:8080/cache/mykey

# Partial read (bytes 0-4)
curl -H "Range: bytes=0-4" http://localhost:8080/cache/mykey

# Delete a value
curl -X DELETE http://localhost:8080/cache/mykey

# Check health
curl http://localhost:8080/health

# Get metrics (Prometheus format)
curl http://localhost:8080/metrics

#include <elcache/elcache_sdk.h>

int main() {
    elcache_client_t* client = elcache_client_create();
    elcache_client_connect_unix(client, "/var/run/elcache/elcache.sock");
    
    // Store
    elcache_client_put(client, "key", 3, "value", 5, NULL);
    
    // Retrieve
    char buffer[1024];
    size_t len;
    elcache_client_get(client, "key", 3, buffer, sizeof(buffer), &len, NULL);
    
    elcache_client_destroy(client);
    return 0;
}

ElCache uses a multi-level cache architecture:

┌─────────────────────────────────────────────────────────────────┐
│                         Client Request                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Cache Coordinator                          │
│   - Routes requests to appropriate cache level                  │
│   - Handles partial reads across chunks                         │
│   - Manages cache promotion/demotion                            │
└─────────────────────────────────────────────────────────────────┘
                                │
            ┌───────────────────┼───────────────────┐
            ▼                   ▼                   ▼
    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
    │ Memory Cache  │   │  Disk Cache   │   │    Cluster    │
    │   (ARC)       │   │  (LRU + Disk) │   │   (Gossip)    │
    │               │   │               │   │               │
    │ - Fast access │   │ - Large cap.  │   │ - Distributed │
    │ - ARC eviction│   │ - Persistent  │   │ - Replicated  │
    └───────────────┘   └───────────────┘   └───────────────┘

Large values are split into 4MB chunks for efficient partial caching:

• Content-addressed chunks (128-bit hash)
• Partial reads fetch only required chunks
• Chunks can be distributed across cluster nodes
• Fine-grained cache eviction

Nodes form a decentralized cluster using:

• Gossip protocol: Node discovery and failure detection
• Consistent hashing: Balanced data distribution with virtual nodes
• Replication: Configurable replication factor for durability

See config/elcache.json.example for all options.

Key settings:

• Architecture Guide
• HTTP API Reference
• C SDK Guide

ElCache is designed for high throughput:

• Memory cache: Millions of ops/sec with ARC eviction
• Disk cache: Async I/O with io_uring (Linux 5.1+)
• Network: Lock-free message passing, zero-copy where possible
• Partial reads: Only fetch needed chunks, not entire values

• C++20 compiler (GCC 11+, Clang 14+)
• CMake 3.20+
• Linux (for io_uring support, optional)
• OpenSSL (for TLS)

MIT License