### Example Usage of Cache Interface

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/implementation-guide.md

Demonstrates how to initialize the cache and perform basic operations like putting and getting data with different TTL policies. Ensure context and store names are correctly provided.

```go
cache := NewHyperCache(config)

// Put user session in sessions store (TTL policy)
cache.Put(ctx, "sessions", []byte("user:123"), sessionData, 30*time.Minute)

// Put product data in hot_data store (LRU policy)  
cache.Put(ctx, "hot_data", []byte("product:456"), productData, 0)

// Get from specific store
value, err := cache.Get(ctx, "sessions", []byte("user:123"))
```

--------------------------------

### Quick 3-Node HyperCache Setup

Source: https://github.com/rishabhverma17/hypercache/blob/main/nginx/README.md

Steps to quickly set up a 3-node HyperCache cluster, including starting the cluster, verifying Nginx configuration, starting Nginx, and performing basic Redis tests.

```bash
# Start cluster
./scripts/start-cluster-enhanced.sh --nodes=3
```

```bash
# Verify nginx config matches your ports
cat nginx/hypercache.conf
```

```bash
# Start nginx
./scripts/start-nginx.sh
```

```bash
# Test
redis-cli -h localhost -p 6379 set test "hello"
redis-cli -h localhost -p 6379 get test
```

--------------------------------

### Build and Start Local HyperCache Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Commands to clone the repository, build the HyperCache binary, and start a local 3-node cluster. This setup is useful for development and testing.

```bash
git clone <your-repository-url>
cd Cache

# Build
make build

# Quick start — local 3-node cluster
./scripts/start-3node-local.sh
```

--------------------------------

### Start 3-Node Cluster with Multi-Node Demo

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/architecture/DISTRIBUTED_ARCHITECTURE_COMPLETE.md

Demonstrates how to start a 3-node cluster using the multi-node-demo application. The first node bootstraps the cluster, and subsequent nodes join by specifying the bootstrap node's address.

```bash
cd /Users/rishabhverma/Documents/HobbyProjects/Cache
./multi-node-demo 1
```

```bash
cd /Users/rishabhverma/Documents/HobbyProjects/Cache
./multi-node-demo 2 127.0.0.1:7946
```

```bash
cd /Users/rishabhverma/Documents/HobbyProjects/Cache
./multi-node-demo 3 127.0.0.1:7946
```

--------------------------------

### RESP GET Command Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/resp-protocol-specification.md

Illustrates the RESP request and response for the GET command. The client sends an array with GET and the key, and the server responds with a bulk string or null.

```resp
*2\r\n$3\r\nGET\r\n$7\r\nmykey\r\n
```

```resp
$11\r\nhello world\r\n
```

```resp
$-1\r\n
```

--------------------------------

### CLUSTER Command Examples

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/resp-protocol-specification.md

Illustrates how to get cluster information and node details using the CLUSTER command.

```RESP
Get Cluster Info:
*2
$7
CLUSTER
$4
INFO

→ ["CLUSTER", "INFO"]

Response:
$150
cluster_state:ok
cluster_slots_assigned:16384
cluster_known_nodes:3
cluster_size:3
cluster_current_epoch:6


```

```RESP
Get Cluster Nodes:
*2
$7
CLUSTER
$5
NODES
  
→ ["CLUSTER", "NODES"]

Response:
$200
07c37dfeb235213a872192d90877d0cd55635b91 192.168.1.1:7000 master - 0 1658389200000 1 connected 0-5460
279c37dfeb235213a872192d90877d0cd55635b92 192.168.1.2:7000 master - 0 1658389201000 2 connected 5461-10922


```

--------------------------------

### Start HyperCache Development Server

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/development-setup.md

Launch the HyperCache development server. You can start it with default configurations or provide a custom configuration file.

```bash
# Start with default configuration
./bin/hypercache

# Start with custom config
./bin/hypercache -config configs/test-config.yaml
```

--------------------------------

### Example Development Configuration

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/development-setup.md

An example YAML configuration file for HyperCache development. This file demonstrates key settings for server, cluster, persistence, and logging.

```yaml
server:
  host: "127.0.0.1"
  port: 6379
  timeout: "30s"

cluster:
  enabled: false
  node_id: "dev-node"

persistence:
  enabled: true
  type: "aof"
  sync_policy: "everysec"

logging:
  level: "debug"
  output: "console"
```

--------------------------------

### Start HyperCache Cluster with Docker Compose

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Instructions to start a HyperCache cluster using Docker Compose, including a full monitoring stack. This is suitable for a more comprehensive local setup.

```bash
# Or Docker with full monitoring stack
docker compose -f docker-compose.cluster.yml up -d
```

--------------------------------

### Install Go Dependencies

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/development-setup.md

Download and verify project dependencies using Go modules. Ensure you have a compatible Go version installed.

```bash
go mod download
go mod verify
```

--------------------------------

### Node Configuration Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/architecture/design-document.md

Provides an example of a YAML configuration file for a Hypercache node. This includes settings for node identification, network binding, data directory, cluster configuration, and storage parameters.

```yaml
# hypercache.yaml
node:
  id: "node-1"
  bind_addr: "0.0.0.0:7000"
  data_dir: "/var/lib/hypercache"

cluster:
  seeds: ["node-1:7000", "node-2:7000"]
  replication_factor: 3
  consistency_level: "eventual"

storage:
  wal_sync_interval: "10ms"
  memtable_size: "64MB"
  compaction_threads: 4

cache:
  max_memory: "8GB"
  eviction_policy: "lru"
  cuckoo_filter_fpp: 0.01  # 1% false positive rate
```

--------------------------------

### Run HyperCache Persistence Demo

Source: https://github.com/rishabhverma17/hypercache/blob/main/examples/persistence-demo/README.md

Execute the main Go program to start the HyperCache persistence demonstration.

```bash
go run main.go
```

--------------------------------

### Install and Build HyperCache on VM

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/multi-vm-deployment-guide.md

Download Go, clone the repository, and build the binary on each virtual machine.

```bash
# Install Go
wget https://go.dev/dl/go1.23.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.23.2.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Clone and build HyperCache
git clone <your-repo> /opt/hypercache
cd /opt/hypercache
go build -o bin/hypercache cmd/hypercache/main.go

# Create directories
sudo mkdir -p /opt/hypercache/data
sudo mkdir -p /opt/hypercache/logs
sudo chown -R hypercache:hypercache /opt/hypercache
```

--------------------------------

### INFO Command Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/resp-protocol-specification.md

Demonstrates the INFO command for retrieving server status information.

```RESP
Client → Server:
*1
$4
INFO


Server → Client:
$200
# Server
redis_version:7.0.0
# Memory
used_memory:1024000
# Stats
total_commands_processed:1000


```

--------------------------------

### Cache Warming Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Batch loading configuration data into the cache.

```bash
# Batch load cache
curl -X POST http://localhost:9080/api/cache/batch/set \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"key": "config:app", "value": "{\"theme\":\"dark\"}", "ttl_hours": 168},
      {"key": "config:db", "value": "{\"pool_size\":10}", "ttl_hours": 168}
    ]
  }'
```

--------------------------------

### Start HyperCache 3-Node Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/testing/SANITY_TEST_SCENARIOS.md

Starts a 3-node HyperCache cluster. Node 1 bootstraps the cluster, while Nodes 2 and 3 join an existing cluster.

```bash
# Terminal 1 - Node 1 (Bootstrap)
./bin/multi-node-demo 1

# Terminal 2 - Node 2 (Join cluster)
./bin/multi-node-demo 2 127.0.0.1:7946

# Terminal 3 - Node 3 (Join cluster)  
./bin/multi-node-demo 3 127.0.0.1:7946
```

--------------------------------

### Start HyperCache Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/development/logging-infrastructure.md

Executes the build and run script to start the cluster.

```bash
./scripts/build-and-run.sh cluster
```

--------------------------------

### Configure Redis Client

Source: https://github.com/rishabhverma17/hypercache/blob/main/examples/resp-demo/README.md

Example of initializing a Redis client instance with connection and pool settings for HyperCache.

```go
// Create Redis client - works with any Redis-compatible server
client := redis.NewClient(&redis.Options{
    Addr:     "localhost:6379", // Change this to your server address
    Password: "",               // No password for demo
    DB:       0,               // Default DB
    
    // Connection settings
    DialTimeout:  5 * time.Second,
    ReadTimeout:  3 * time.Second,
    WriteTimeout: 3 * time.Second,
    
    // Pool settings for better performance
    PoolSize:           10,
    MinIdleConns:       3,
    MaxConnAge:         30 * time.Minute,
    PoolTimeout:        4 * time.Second,
    IdleTimeout:        5 * time.Minute,
    IdleCheckFrequency: time.Minute,
})
```

--------------------------------

### Install and Configure Filebeat for Elastic Cloud

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/development/logging-infrastructure.md

Commands to download and extract Filebeat, and instructions to configure it for Elastic Cloud. This is an alternative to the Docker Compose setup for production environments.

```bash
# Install Filebeat
curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.11.0-darwin-x86_64.tar.gz
tar xzvf filebeat-8.11.0-darwin-x86_64.tar.gz

# Configure for Elastic Cloud
vim filebeat.yml
```

--------------------------------

### Initialize HyperCache Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/redis-cli-testing-guide.md

Commands to start the cluster and verify environment readiness.

```bash
./scripts/build-and-run.sh cluster
```

```bash
sleep 5
```

```bash
# On macOS
brew install redis

# Or check if already installed
which redis-cli
```

--------------------------------

### Start HyperCache System

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/reference/SCRIPTS_README.md

Executes the master script to initialize the cluster and monitoring stack.

```bash
./scripts/start-system.sh
```

--------------------------------

### Start Docker Compose Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Use this command to download the compose file and start a 3-node HyperCache cluster along with Elasticsearch, Grafana, and Filebeat for monitoring.

```bash
curl -O https://raw.githubusercontent.com/rishabhverma17/HyperCache/main/docker-compose.cluster.yml
docker compose -f docker-compose.cluster.yml up -d
```

--------------------------------

### Repository Setup Commands

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/contribution-guidelines.md

Commands to fork, clone, and configure the upstream remote for local development.

```bash
# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/HyperCache.git
cd HyperCache
git remote add upstream https://github.com/rishabhverma17/HyperCache.git
```

--------------------------------

### HSTATS Command Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/resp-protocol-specification.md

Demonstrates retrieving statistics for a given store using the HSTATS command.

```RESP
Client → Server:
*2
$6
HSTATS
$7
mystore

→ ["HSTATS", "mystore"]

Server → Client:
*12

$4
keys
:1000

$8
memory_kb
:2048
  
$8
hit_ratio
$4
0.95

$13
evictions_total
:150

$12
filter_enabled
:1

$17
filter_false_positives
:5


Translation: {
  "keys": 1000,
  "memory_kb": 2048,
  "hit_ratio": "0.95", 
  "evictions_total": 150,
  "filter_enabled": 1,
  "filter_false_positives": 5
}
```

--------------------------------

### Logging Environment Configurations

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/development/LOGGING_SYSTEM.md

YAML configuration examples for development, production, and high-volume environments.

```yaml
logging:
  level: "debug"
  enable_console: true
  enable_file: true
  buffer_size: 100
```

```yaml
logging:
  level: "info"
  enable_console: false  # Only file logging
  enable_file: true
  buffer_size: 5000     # Larger buffer
  max_file_size: "500MB"
  max_files: 20         # Longer retention
```

```yaml
logging:
  level: "warn"         # Reduce volume
  enable_console: false
  enable_file: true
  buffer_size: 10000    # Large buffer
  max_file_size: "1GB"
  max_files: 50
```

--------------------------------

### Cuckoo Filter Configuration Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/cuckoo-filter-internals.md

Provides a YAML configuration example for enabling and tuning Cuckoo Filters on a per-store basis. This includes setting expected item counts, false positive rates, and memory budgets.

```yaml
# Per-store cuckoo filter configuration
stores:
  - name: "user-data-store"
    max_memory: 107374182400  # 100GB
    cuckoo_filter:
      enabled: true           # Opt-in basis
      expected_items: 8000000000    # 8 billion items
      false_positive_rate: 0.001    # 0.1%
      memory_budget_percent: 5      # 5% of store memory
      fingerprint_size: 12          # bits per fingerprint
      bucket_size: 4               # slots per bucket
      max_eviction_attempts: 500    # before resize

  - name: "session-store" 
    max_memory: 53687091200   # 50GB
    cuckoo_filter:
      enabled: false          # Disabled for this store
      
  - name: "analytics-store"
    max_memory: 21474836480   # 20GB  
    cuckoo_filter:
      enabled: true
      expected_items: 4000000000
      false_positive_rate: 0.005   # 0.5% (less memory)
      memory_budget_percent: 3
```

--------------------------------

### Manually Start HyperCache Nodes with Docker Run

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Provides commands to manually start individual HyperCache nodes using `docker run`. This includes creating a network, configuring volumes, and setting environment variables for cluster seeding.

```bash
# Create network
docker network create --driver bridge --subnet=172.20.0.0/16 hypercache-network

# Start Node 1 (bootstrap)
docker run -d --name hypercache-node1 \
  --network hypercache-network \
  --hostname hypercache-node1 \
  -p 8080:8080 -p 9080:9080 -p 7946:7946 \
  -v $(pwd)/configs/docker/node1-config.yaml:/config/hypercache.yaml:ro \
  -v hypercache_node1_data:/data \
  -v hypercache_logs:/app/logs \
  -e NODE_ID=node-1 \
  -e CLUSTER_SEEDS=hypercache-node1:7946 \
  hypercache/hypercache:latest

# Start Node 2
docker run -d --name hypercache-node2 \
  --network hypercache-network \
  --hostname hypercache-node2 \
  -p 8081:8080 -p 9081:9080 -p 7947:7946 \
  -v $(pwd)/configs/docker/node2-config.yaml:/config/hypercache.yaml:ro \
  -v hypercache_node2_data:/data \
  -e NODE_ID=node-2 \
  -e CLUSTER_SEEDS=hypercache-node1:7946,hypercache-node2:7946 \
  hypercache/hypercache:latest

# Start Node 3
docker run -d --name hypercache-node3 \
  --network hypercache-network \
  --hostname hypercache-node3 \
  -p 8082:8080 -p 9082:9080 -p 7948:7946 \
  -v $(pwd)/configs/docker/node3-config.yaml:/config/hypercache.yaml:ro \
  -v hypercache_node3_data:/data \
  -e NODE_ID=node-3 \
  -e CLUSTER_SEEDS=hypercache-node1:7946,hypercache-node2:7946,hypercache-node3:7946 \
  hypercache/hypercache:latest
```

--------------------------------

### Build and Run Docker Image Locally

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Build the HyperCache Docker image from the local source code and then start the stack.

```bash
make docker-build && make docker-up
```

--------------------------------

### Generate Dashboard Load and Documentation

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/reference/SCRIPTS_README.md

Populates test data for monitoring dashboards and opens the relevant guide.

```bash
# Generate test data for dashboards
./scripts/generate-dashboard-load.sh

# View detailed guide
open docs/grafana-dashboards-guide.md
```

--------------------------------

### CLI Operations

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Commands for building, starting, and testing HyperCache.

```bash
# Build the binary
make build

# Start single node with default config
./bin/hypercache --config configs/hypercache.yaml --protocol resp

# Start with custom node ID and port
./bin/hypercache \
  --config configs/hypercache.yaml \
  --protocol resp \
  --node-id node-1 \
  --port 8080

# Start a 3-node local cluster
make cluster

# Start a 5-node cluster
make cluster NODES=5

# Add a node to running cluster
./scripts/add-node.sh
./scripts/add-node.sh --node-name=node-6

# Stop cluster
make cluster-stop

# Full reset (stop + clean data + restart)
make cluster-stop && make clean && make cluster

# Run tests
make test-unit
make test-integration
make bench
```

--------------------------------

### Session Management Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Storing session data with a specific TTL.

```bash
# Store session data
curl -X PUT http://localhost:9080/api/cache/session:abc123 \
  -H "Content-Type: application/json" \
  -d '{"value": "{\"user_id\":123,\"expires\":1693234567}", "ttl_hours": 8}'
```

--------------------------------

### Scenario-Specific YAML Configurations

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/architecture/consistent-hashing-deep-dive.md

Example YAML configurations for different operational requirements.

```yaml
virtual_node_count: 64     # Fewer vnodes for faster lookups
replication_factor: 1      # No replication for maximum speed
lookup_cache_size: 50000   # Large cache for hot keys
hash_function: "xxhash64"  # Fastest hash function
```

```yaml
virtual_node_count: 512    # More vnodes for better distribution
replication_factor: 5      # High replication for fault tolerance
lookup_cache_size: 1000    # Smaller cache, more memory for data
health_check_interval: 10s # Frequent health checks
```

```yaml
virtual_node_count: 128    # Balanced vnode count
replication_factor: 3      # Standard replication
rebalance_rate: 50         # Slower rebalancing to reduce load
hash_function: "xxhash64"  # Consistent performance at scale
```

--------------------------------

### Configure Hypercache YAML

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/implementation-guide.md

Example configuration file defining node settings and individual store policies.

```yaml
# configs/hypercache.yaml
node:
  id: "hypercache-node-1"
  bind_addr: "127.0.0.1:7000"
  data_dir: "/tmp/hypercache"

stores:
  - name: "sessions"           # User sessions
    eviction_policy: "ttl"     # Expire automatically  
    max_memory: "1GB"
    default_ttl: "30m"
    
  - name: "hot_data"          # Frequently accessed data
    eviction_policy: "lru"     # Keep recent items
    max_memory: "4GB"
    default_ttl: "2h"
    
  - name: "analytics"         # Reporting data
    eviction_policy: "lfu"     # Keep frequent items
    max_memory: "2GB" 
    default_ttl: "24h"
```

--------------------------------

### Manage Service Lifecycle

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Commands for starting, stopping, and removing cluster services.

```bash
# Start / Stop / Restart
docker-compose -f docker-compose.cluster.yml start
docker-compose -f docker-compose.cluster.yml stop
docker-compose -f docker-compose.cluster.yml restart

# Selective service management
docker-compose -f docker-compose.cluster.yml stop hypercache-node2
docker-compose -f docker-compose.cluster.yml start hypercache-node2

# Complete removal
docker-compose -f docker-compose.cluster.yml down
docker-compose -f docker-compose.cluster.yml down -v  # Also remove volumes
```

--------------------------------

### Run Full System Test Workflow

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Automated sequence to build, start, test, and clean up the cluster environment.

```bash
# 1. Build and start
docker build -t hypercache/hypercache:latest .
docker-compose -f docker-compose.cluster.yml up -d

# 2. Wait for cluster formation
sleep 30

# 3. Test all operations
curl -X PUT http://localhost:9080/api/cache/e2e-test \
  -d '{"value":"full system test","ttl_hours":1}'
curl http://localhost:9081/api/cache/e2e-test
curl http://localhost:9082/api/cache/e2e-test

# 4. Check monitoring
open http://localhost:3000

# 5. Cleanup
docker-compose -f docker-compose.cluster.yml down -v
```

--------------------------------

### Start HyperCache Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/nginx/README.md

Commands to initialize the HyperCache cluster with a specified number of nodes and optional custom base ports.

```bash
# Start 3 nodes
./scripts/start-cluster-enhanced.sh --nodes=3

# Or start 5 nodes with custom ports
./scripts/start-cluster-enhanced.sh --nodes=5 --base-port=8000
```

--------------------------------

### HyperCache YAML Configuration

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Example configuration file for defining node, network, cluster, persistence, and cache settings.

```yaml
# configs/hypercache.yaml
node:
  id: "hypercache-node-1"
  data_dir: "/tmp/hypercache"

network:
  resp_bind_addr: "0.0.0.0"
  resp_port: 8080
  http_bind_addr: "0.0.0.0"
  http_port: 9080
  advertise_addr: ""           # Auto-detect for localhost
  gossip_port: 7946

cluster:
  seeds: ["127.0.0.1:7946"]
  seed_dns: ""                 # For K8s: "hypercache-headless.default.svc.cluster.local"
  seed_dns_port: 7946
  replication_factor: 3
  consistency_level: "eventual"

persistence:
  enabled: true
  strategy: "hybrid"           # "aof", "snapshot", "hybrid"
  sync_policy: "everysec"      # "always", "everysec", "no"
  sync_interval: "1s"
  snapshot_interval: "15m"
  max_log_size: "100MB"
  compression_level: 6
  retain_logs: 3

cache:
  max_memory: "8GB"
  default_ttl: "0"             # 0 = infinite
  cuckoo_filter_fpp: 0.01      # 1% false positive rate
  max_stores: 16

stores:
  - name: "default"
    eviction_policy: "lru"
    max_memory: "8GB"
    default_ttl: "0"
    cuckoo_filter: true
    persistence: "hybrid"

  - name: "sessions"
    eviction_policy: "ttl"
    max_memory: "1GB"
    default_ttl: "30m"
    cuckoo_filter: true
    persistence: "aof"

logging:
  level: "info"                # debug, info, warn, error, fatal
  enable_console: true
  enable_file: true
  log_dir: "logs"
  max_file_size: "100MB"
  max_files: 10
```

--------------------------------

### Batch Get CLI Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Example command to perform a batch get operation using curl.

```bash
curl -X POST http://localhost:9080/api/cache/batch/get \
  -H "Content-Type: application/json" \
  -d '{"keys": ["key1", "key2", "key3"]}'
```

--------------------------------

### Initialize Cache Instance

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/implementation-guide.md

Demonstrates the flow for creating a cache instance and registering stores based on configuration.

```go
// 1. Load configuration
config, err := config.Load("configs/hypercache.yaml")

// 2. Create cache instance
cache, err := cache.NewInstance(config)

// 3. For each store in config, create:
for _, storeConfig := range config.Stores {
    // a. Memory pool for the store
    memPool := NewMemoryPool(storeConfig.MaxMemory)
    
    // b. Eviction policy based on config
    var policy EvictionPolicy
    switch storeConfig.EvictionPolicy {
    case "lru":
        policy = NewLRUPolicy()
    case "lfu": 
        policy = NewLFUPolicy()
    case "ttl":
        policy = NewTTLPolicy()
    }
    
    // c. Create the store
    store := NewStore(storeConfig.Name, policy, memPool)
    cache.RegisterStore(store)
}
```

--------------------------------

### Clone HyperCache Repository

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/development-setup.md

Clone the HyperCache repository and navigate into the project directory. This is the first step to start development.

```bash
git clone https://github.com/rishabhverma17/HyperCache.git
cd HyperCache
```

--------------------------------

### Run the RESP Demo

Source: https://github.com/rishabhverma17/hypercache/blob/main/examples/resp-demo/README.md

Commands to initialize dependencies and execute the demonstration script.

```bash
# Navigate to the demo directory
cd examples/resp-demo

# Install dependencies
go mod tidy

# Run the demo
go run main.go
```

--------------------------------

### Generate Test Cache Operations with Curl

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/observability.md

Examples using curl to perform PUT, GET, DELETE, and batch GET operations on the HyperCache API for testing purposes.

```bash
# PUT
curl -X PUT -H "Content-Type: application/json" \
  -d '{"value":"test-value","ttl_hours":1.0}' \
  http://localhost:9080/api/cache/test-key

# GET
curl http://localhost:9080/api/cache/test-key

# DELETE
curl -X DELETE http://localhost:9080/api/cache/test-key

# Batch GET
curl -X POST -H "Content-Type: application/json" \
  -d '{"keys":["test-key","nonexistent"]}' \
  http://localhost:9080/api/cache/batch/get
```

--------------------------------

### Initialize and run project tests

Source: https://github.com/rishabhverma17/hypercache/blob/main/tests/README.md

Commands to download dependencies and execute unit, integration, and coverage tests.

```bash
# Install test dependencies
go mod download

# Run unit tests
./tests/scripts/run_unit_tests.sh

# Run integration tests
./tests/scripts/run_integration_tests.sh

# View coverage report
./tests/scripts/test_coverage.sh
open coverage.html
```

--------------------------------

### GET /api/config - Get Configuration

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Retrieves the current read-only configuration of the HyperCache node.

```APIDOC
## GET /api/config

### Description
Retrieve current node configuration (read-only).

### Method
GET

### Endpoint
`/api/config`

### Response
#### Success Response (200)
- **node** (object) - Node-specific configuration.
  - **id** (string) - The unique identifier for the node.
  - **data_dir** (string) - The directory where node data is stored.
- **network** (object) - Network-related configuration.
  - **resp_port** (integer) - The port for RESP protocol.
  - **http_port** (integer) - The port for HTTP API.
  - **gossip_port** (integer) - The port for cluster gossip communication.
- **cluster** (object) - Cluster-wide configuration.
  - **seeds** (array) - List of initial cluster seed nodes.
  - **replication_factor** (integer) - The configured replication factor.
  - **consistency_level** (string) - The configured consistency level.
- **cache** (object) - Cache-specific configuration.
  - **max_memory** (string) - The maximum memory allocated for the cache.
  - **default_ttl** (string) - The default time-to-live for cache entries.
  - **cuckoo_filter_fpp** (number) - The desired false positive probability for cuckoo filters.
- **correlation_id** (string) - A unique identifier for the request.

#### Response Example
```json
{
  "node": {
    "id": "node-1",
    "data_dir": "/tmp/hypercache/node-1"
  },
  "network": {
    "resp_port": 8080,
    "http_port": 9080,
    "gossip_port": 7946
  },
  "cluster": {
    "seeds": ["127.0.0.1:7946", "127.0.0.1:7947", "127.0.0.1:7948"],
    "replication_factor": 3,
    "consistency_level": "eventual"
  },
  "cache": {
    "max_memory": "8GB",
    "default_ttl": "1h",
    "cuckoo_filter_fpp": 0.01
  },
  "correlation_id": "uuid-here"
}
```
```

--------------------------------

### Initialize and Use HyperCache Client

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Demonstrates how to initialize the HyperCache client and perform basic cache operations like setting, getting, and deleting keys. Ensure the HyperCache server is running at the specified base URL.

```javascript
const axios = require('axios');

class HyperCache {
  constructor(baseUrl = 'http://localhost:9080') {
    this.baseUrl = baseUrl;
  }

  async get(key) {
    try {
      const response = await axios.get(`${this.baseUrl}/api/cache/${key}`);
      return response.data;
    } catch (error) {
      return null;
    }
  }

  async set(key, value, ttlHours = 1.0) {
    try {
      const response = await axios.put(`${this.baseUrl}/api/cache/${key}`, {
        value,
        ttl_hours: ttlHours
      });
      return response.status === 200;
    } catch (error) {
      return false;
    }
  }

  async delete(key) {
    try {
      const response = await axios.delete(`${this.baseUrl}/api/cache/${key}`);
      return response.status === 200;
    } catch (error) {
      return false;
    }
  }
}

// Usage
const cache = new HyperCache();
await cache.set('user:123', JSON.stringify({name: 'John', age: 30}), 2.0);
const user = await cache.get('user:123');
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/contribution-guidelines.md

Examples of commit messages following the Conventional Commits specification.

```bash
# Examples of good commit messages
git commit -m "feat: add support for Redis SCAN command"
git commit -m "fix: resolve race condition in cluster membership"
git commit -m "docs: update API documentation with new commands"
git commit -m "perf: optimize hash ring lookup performance"
git commit -m "test: add integration tests for persistence layer"
```

--------------------------------

### Batch Set CLI Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Example command to perform a batch set operation using curl.

```bash
curl -X POST http://localhost:9080/api/cache/batch/set \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"key": "key1", "value": "value1", "ttl_hours": 2.0},
      {"key": "key2", "value": "value2", "ttl_hours": 1.0}
    ]
  }'
```

--------------------------------

### HyperCache JSON Log Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/development/logging-infrastructure.md

This is an example of the structured JSON log format produced by HyperCache, suitable for ingestion into Elasticsearch.

```json
{
  "@timestamp": "2025-08-21T17:53:16.266861Z",
  "level": "INFO",
  "message": "Cache PUT operation started",
  "correlation_id": "9eaf6608-1f28-4f9b-a03e-16dff296d49b",
  "node_id": "node-1",
  "component": "cache",
  "action": "put_request",
  "fields": {
    "key": "mykey",
    "node_id": "node-1"
  },
  "file": "/path/to/file.go",
  "line": 447,
  "function": "main.function"
}
```

--------------------------------

### Start Scaled Local Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Start a local HyperCache cluster with a specified number of nodes using the NODES environment variable.

```bash
make cluster NODES=5
```

--------------------------------

### Configure System Startup Options

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/reference/SCRIPTS_README.md

Provides flags to control specific components or perform cleanup/rebuild tasks during startup.

```bash
./scripts/start-system.sh --cluster      # Start only HyperCache cluster
./scripts/start-system.sh --monitor      # Start only monitoring stack  
./scripts/start-system.sh --clean        # Clean data first, then start
./scripts/start-system.sh --rebuild      # Rebuild binaries, then start
```

--------------------------------

### Retrieve Data with GET API

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/HYPERCACHE_DOCUMENTATION.md

Use the GET /api/cache/{key} endpoint to retrieve data associated with a specific key. The response includes the cached data and information about the node and primary.

```bash
curl http://localhost:8080/api/cache/{key}
```

```json
{
  "success": true,
  "data": {
    "key": "your-key",
    "value": "your-data"
  },
  "node": "1",
  "primary": "node-2",
  "local": true,
  "forwarded": false
}
```

--------------------------------

### Structured JSON Log Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/development/LOGGING_SYSTEM.md

This is an example of a structured log entry in JSON format. It includes timestamp, level, message, correlation ID, node ID, component, action, duration, and contextual fields.

```json
{
  "@timestamp": "2025-08-21T20:30:15.123Z",
  "level": "INFO",
  "message": "HTTP request started",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "node_id": "node-1",
  "component": "http",
  "action": "request",
  "duration_ms": 45,
  "fields": {
    "method": "GET",
    "path": "/cache/default/key1",
    "status_code": 200,
    "remote_ip": "127.0.0.1:54321"
  },
  "file": "main.go",
  "line": 234,
  "function": "handleCacheRequest"
}
```

--------------------------------

### Start Local Cluster

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Build and run a local HyperCache cluster using make commands. Defaults to a 3-node cluster.

```bash
make cluster
```

--------------------------------

### GET /api/cluster/members

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Retrieves information about all nodes in the cluster.

```APIDOC
## GET /api/cluster/members

### Description
Get information about all nodes in the cluster including their status and addresses.

### Method
GET

### Endpoint
http://localhost:9080/api/cluster/members

### Response
#### Success Response (200)
- **members** (array) - List of cluster nodes
- **total_count** (integer) - Total number of nodes

#### Response Example
{
  "members": [
    {"id": "node-1", "address": "127.0.0.1:7946", "status": "alive"},
    {"id": "node-2", "address": "127.0.0.1:7947", "status": "alive"},
    {"id": "node-3", "address": "127.0.0.1:7948", "status": "alive"}
  ],
  "total_count": 3,
  "node": "node-1",
  "correlation_id": "abc-123-uuid"
}
```

--------------------------------

### Reproduce Performance Benchmarks

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/production/PITCH_DECK_OUTLINE.md

Commands to clone the repository and execute the standard benchmark and stress test suites.

```bash
git clone ... && cd HyperCache
go test -bench=BenchmarkWorkload -benchmem ./tests/benchmarks/...
go test -v -run TestStress ./tests/stress/...
```

--------------------------------

### GET /api/stores

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

List all configured cache stores.

```APIDOC
## GET /api/stores

### Description
List all named stores with their independent configurations.

### Method
GET

### Endpoint
/api/stores
```

--------------------------------

### GET /api/cache/{key}

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Retrieve a value from the cache.

```APIDOC
## GET /api/cache/{key}

### Description
Retrieve a value from the cache. If the key isn't found locally, HyperCache performs read-repair by querying hash-ring replicas.

### Method
GET

### Endpoint
/api/cache/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The cache key to retrieve

### Response
#### Success Response (200)
- **success** (boolean) - Operation status
- **data** (object) - The retrieved key and value
- **node** (string) - Node that processed the request
- **local** (boolean) - Whether the key was found locally
- **correlation_id** (string) - Unique request identifier

#### Response Example
{
  "success": true,
  "data": {"key": "user:123", "value": "John Doe"},
  "node": "node-1",
  "local": true,
  "correlation_id": "abc-123-uuid"
}
```

--------------------------------

### Get Configuration

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Retrieve the current read-only node configuration.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "node": {
    "id": "node-1",
    "data_dir": "/tmp/hypercache/node-1"
  },
  "network": {
    "resp_port": 8080,
    "http_port": 9080,
    "gossip_port": 7946
  },
  "cluster": {
    "seeds": ["127.0.0.1:7946", "127.0.0.1:7947", "127.0.0.1:7948"],
    "replication_factor": 3,
    "consistency_level": "eventual"
  },
  "cache": {
    "max_memory": "8GB",
    "default_ttl": "1h",
    "cuckoo_filter_fpp": 0.01
  },
  "correlation_id": "uuid-here"
}
```

```bash
curl -X GET http://localhost:9080/api/config
```

--------------------------------

### GET /api/filter/stats

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Retrieves statistics for the probabilistic Cuckoo filter.

```APIDOC
## GET /api/filter/stats

### Description
Query the probabilistic Cuckoo filter for fast negative lookups.

### Method
GET

### Endpoint
http://localhost:9080/api/filter/stats

### Response
#### Success Response (200)
- **stats** (object) - Filter statistics including size, capacity, and false positive rate

#### Response Example
{
  "node": "node-1",
  "stats": {
    "size": 1523,
    "capacity": 1000000,
    "load_factor": 0.15,
    "false_positive_rate": 0.0033,
    "lookup_operations": 8745,
    "add_operations": 1523,
    "delete_operations": 45
  }
}
```

--------------------------------

### Troubleshoot Container Startup

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Commands to diagnose and fix common container initialization issues, including permissions and configuration errors.

```bash
# Check logs
docker logs hypercache-node1

# Permission denied for logs directory
docker volume create hypercache_logs
docker run --rm -v hypercache_logs:/app/logs alpine sh -c "chmod 755 /app/logs && chown 1000:1000 /app/logs"

# Config file not found
docker exec hypercache-node1 ls -la /config/

# Rebuild cleanly
docker-compose -f docker-compose.cluster.yml down
docker build --no-cache -t hypercache/hypercache:latest .
docker-compose -f docker-compose.cluster.yml up -d
```

--------------------------------

### Deploy Full HyperCache Cluster with Monitoring

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Builds the Docker image and starts a full cluster including 3 cache nodes and ELK stack for monitoring using docker-compose. Also shows how to monitor logs and check container status.

```bash
# Build and start (3 nodes + ELK monitoring)
docker build -t hypercache/hypercache:latest .
docker-compose -f docker-compose.cluster.yml up -d

# Monitor startup
docker-compose -f docker-compose.cluster.yml logs -f

# Check all containers
docker-compose -f docker-compose.cluster.yml ps
```

--------------------------------

### Retrieve Server Information

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/redis-cli-testing-guide.md

Get server metadata and status information.

```bash
# Get server info (if implemented)
redis-cli -h localhost -p 8080 INFO
```

--------------------------------

### Deploy Basic HyperCache Cluster (No Monitoring)

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Starts a basic HyperCache cluster with three nodes using docker-compose, omitting the monitoring stack.

```bash
docker-compose -f docker-compose.cluster.yml up -d \
  hypercache-node1 hypercache-node2 hypercache-node3
```

--------------------------------

### Dockerfile Multi-Stage Build Example

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/guides/docker-guide.md

Illustrates a multi-stage Docker build process. The first stage (`builder`) is used for building the application, and the second stage uses a minimal Alpine image for the final runtime.

```dockerfile
FROM golang:1.23.2-alpine AS builder
# ... build process ...
FROM alpine:3.18  # Final minimal runtime
```

--------------------------------

### Retrieve Cache Value

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/http-api-documentation.md

Retrieve a value from the cache using a GET request.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "mykey",
  "value": "myvalue",
  "ttl_remaining": "3540s",
  "node": "node-1",
  "correlation_id": "uuid-here"
}
```

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Key not found",
  "key": "nonexistent",
  "correlation_id": "uuid-here"
}
```

```bash
curl -X GET http://localhost:9080/api/cache/mykey
```

--------------------------------

### Initialize Static Nginx Configuration

Source: https://github.com/rishabhverma17/hypercache/blob/main/nginx/README.md

Steps to apply the static Nginx configuration and connect to the load balancer via redis-cli.

```bash
# Edit the nginx config to match your nodes
vim nginx/hypercache.conf

# Start nginx
./scripts/start-nginx.sh

# Connect via load balancer
redis-cli -h localhost -p 6379
```

--------------------------------

### Manage Stores via CLI

Source: https://context7.com/rishabhverma17/hypercache/llms.txt

Use the SELECT command to switch between different data stores or return to the default store.

```text
127.0.0.1:8080> SELECT sessions
OK

# Now all operations target the "sessions" store
127.0.0.1:8080> SET user:token:123 "abc123"
OK
127.0.0.1:8080> GET user:token:123
"abc123"

# Switch back to default (SELECT 0 also works)
127.0.0.1:8080> SELECT default
OK
127.0.0.1:8080> SELECT 0
OK
```

--------------------------------

### Retrieve Data (GET)

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/api/HYPERCACHE_DOCUMENTATION.md

Retrieves data from the cache associated with a given key.

```APIDOC
## GET /api/cache/{key}

### Description
Retrieves data from the cache associated with a given key.

### Method
GET

### Endpoint
/api/cache/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the data to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - An object containing the cached key and value.
  - **key** (string) - The key of the cached item.
  - **value** (string) - The value of the cached item.
- **node** (string) - The identifier of the node that served the request.
- **primary** (string) - The identifier of the primary node in the cluster.
- **local** (boolean) - Indicates if the data was retrieved from the local node.
- **forwarded** (boolean) - Indicates if the request was forwarded to another node.

#### Response Example
```json
{
  "success": true,
  "data": {
    "key": "your-key",
    "value": "your-data"
  },
  "node": "1",
  "primary": "node-2",
  "local": true,
  "forwarded": false
}
```
```

--------------------------------

### Manage Cluster Lifecycle

Source: https://github.com/rishabhverma17/hypercache/blob/main/README.md

Commands to start and stop local or Docker-based clusters.

```bash
# Start 3-node local cluster for development/testing
./scripts/start-3node-local.sh

# Start custom N-node cluster
make cluster NODES=5

# Stop cluster
make cluster-stop
pkill -f bin/hypercache

# Docker cluster with full monitoring stack
docker compose -f docker-compose.cluster.yml up -d
docker compose -f docker-compose.cluster.yml down
```

--------------------------------

### Update Go Modules and Build Project

Source: https://github.com/rishabhverma17/hypercache/blob/main/docs/markdown/testing/SANITY_TEST_SCENARIOS.md

Ensure your Go modules are up-to-date and then build the multi-node demo application. This is useful for resolving build issues.

```bash
go mod tidy
```

```bash
go build -o bin/multi-node-demo cmd/multi-node-demo/main.go
```