GitHub - wutlu/boltcache: BoltCache is a modern, fast, and scalable in-memory cache system built in Go. It provides Redis-like functionality with better performance, RESTful API support, and enterprise-grade features.

BoltCache 🚀

Note: This project was coded by vibe.

High-performance, Redis-compatible in-memory cache with RESTful API

BoltCache is a modern, fast, and scalable in-memory cache system built in Go. It provides Redis-like functionality with better performance, RESTful API support, and enterprise-grade features.

Keywords: redis, cache, in-memory, golang, rest-api, pub-sub, high-performance, microservices, docker, kubernetes

✨ Features

• ⚡ High Performance: Optimized for write-heavy workloads (up to 2x faster SET operations than Redis)
• 🌐 RESTful API: Modern HTTP/JSON interface alongside TCP protocol
• 🔄 Pub/Sub Messaging: Real-time messaging with WebSocket support
• ⏰ TTL Support: Automatic key expiration and cleanup
• 🔒 Thread-Safe: Concurrent operations with lock-free data structures
• 💾 Persistence: JSON-based disk storage with backup support
• 🔗 Clustering: Master-slave replication and high availability
• 📊 Complex Data Types: String, List, Set, Hash support
• 🔧 Lua Scripting: Execute custom scripts for complex operations
• 🛡️ Security: Token-based authentication and rate limiting
• 📈 Monitoring: Built-in metrics, health checks, and profiling
• ⚙️ Configuration: YAML-based configuration management

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Git

Installation

# Clone the repository
git clone https://github.com/wutlu/boltcache.git
cd boltcache

# Install dependencies
go mod download

# Generate default configuration
make generate-config

# Start the server
make run-dev

The server will start on:

• REST API: http://localhost:8090
• TCP Server: localhost:6380
• GNet Server: localhost:6381 (High Performance)

Quick Test

# Health check
curl http://localhost:8090/ping

# Set a value
curl -X PUT http://localhost:8090/cache/hello \
  -H "Content-Type: application/json" \
  -d '{"value": "world"}'

# Get the value
curl http://localhost:8090/cache/hello

# Test TCP protocol
telnet localhost 6380
SET mykey myvalue
GET mykey
PING

📖 Usage

REST API

BoltCache provides a comprehensive RESTful API:

String Operations

# Set value
PUT /cache/{key}
{"value": "data", "ttl": "5m"}

# Get value
GET /cache/{key}

# Delete key
DELETE /cache/{key}

List Operations

# Push to list
POST /list/{key}
["item1", "item2"]

# Pop from list
DELETE /list/{key}

Set Operations

# Add to set
POST /set/{key}
["member1", "member2"]

# Get set members
GET /set/{key}

Hash Operations

# Set hash field
PUT /hash/{key}/{field}
{"value": "data"}

# Get hash field
GET /hash/{key}/{field}

Pub/Sub Operations

# Publish message
POST /publish/{channel}
{"message": "Hello World"}

# Subscribe (WebSocket)
GET /subscribe/{channel}

Lua Scripting

# Execute script
POST /eval
{
  "script": "redis.call('SET', KEYS[1], ARGV[1])",
  "keys": ["mykey"],
  "args": ["myvalue"]
}

Configuration

BoltCache uses YAML configuration files:

# config.yaml
server:
  mode: "rest"  # tcp, rest, both
  rest:
    port: 8090
    cors_enabled: true
  tcp:
    port: 6380

cache:
  max_memory: "1GB"
  cleanup_interval: "1m"
  eviction_policy: "lru"

persistence:
  enabled: true
  file: "./data/cache.json"
  interval: "30s"

security:
  auth:
    enabled: true
    tokens: ["your-secret-token"]

Environment-Specific Configs

# Development
make run-dev

# Production
make run-prod

# Custom config
go run . server --config custom.yaml

🔧 Development

Available Commands

# Server operations
make run              # Run with default config
make run-dev          # Run development mode
make run-prod         # Run production mode
make build            # Build binary

# Configuration
make generate-config  # Generate default config
make validate-config  # Validate configuration
make show-config      # Show current config

# Testing
make test-rest        # Test REST API
make test-auth        # Test authentication
make test-pubsub      # Test Pub/Sub messaging
# Web client: http://localhost:8090/rest-client.html

# Clustering
make cluster-master   # Start cluster master
make cluster-slave    # Start cluster slave

Testing Tools

1. Web Client: Interactive browser-based client

   # Start server
   make run-dev
   
   # Open web client
   open http://localhost:8090/rest-client.html

2. Postman Collection: Import BoltCache.postman_collection.json

3. cURL Scripts:

   ./examples/rest-examples.sh
   ./examples/auth-examples.sh
   ./examples/test-pubsub.sh

4. Interactive Client:

    go run . client interactive --addr :6380

🛡️ Security

Authentication

BoltCache supports token-based authentication:

# Using Authorization header
curl -H "Authorization: Bearer your-token" \
  http://localhost:8090/cache/key

# Using X-API-Token header
curl -H "X-API-Token: your-token" \
  http://localhost:8090/cache/key

# Using query parameter
curl "http://localhost:8090/cache/key?token=your-token"

Configuration

security:
  auth:
    enabled: true
    method: "token"
    tokens:
      - "production-token-1"
      - "production-token-2"
  rate_limit:
    enabled: true
    requests_per_second: 1000
    burst: 100

📊 Performance

Benchmarks

BoltCache outperforms Redis significantly in write-heavy operations, especially when using pipelining.

Test Environment: MacBook Pro M1/M2/M3 (Localhost loopback) Concurrency: 100 clients, 100,000 operations Pipelining: Batch size 100

Benchmark Scripts: You can verify these results yourself using the provided benchmark tools:

• Standard Benchmark (No Pipeline)
• Pipelined Benchmark

Performance Tuning

performance:
  max_goroutines: 10000
  gc_percent: 100
  connection_pool:
    max_idle: 100
    max_active: 1000

🏗️ Architecture

Core Components

• Storage Engine: Lock-free sync.Map for concurrent access
• Network Layer: HTTP/REST and TCP protocol support
• Pub/Sub System: Channel-based non-blocking messaging
• Persistence Layer: JSON-based storage with compression
• Authentication: Token-based security middleware
• Configuration: YAML-based configuration management

Data Flow

Client Request → Auth Middleware → Router → Cache Engine → Storage
                                      ↓
Pub/Sub System ← Background Tasks ← Persistence Layer

🐳 Docker Deployment

Single Node

# Build image
docker build -t boltcache .

# Run container
docker run -p 8090:8090 -v ./data:/app/data boltcache

Docker Compose

# Start cluster
docker-compose up

Kubernetes

# Deploy to Kubernetes
kubectl apply -f k8s/

📚 Documentation

• API Reference
• Configuration Guide
• Authentication Guide
• Postman Collection

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Redis architecture
• Built with Go's excellent concurrency primitives
• Uses Gorilla WebSocket and Mux libraries

📞 Support

• 🐛 Issues: GitHub Issues
• 📧 Email: mutlu@etsetra.com
• 🌐 Website: etsetra.com
• 💼 LinkedIn: Alper Mutlu Toksöz

Created by Alper Mutlu Toksöz with ❤️