🐍 SnakeCache

The slow and steady cache wins the race.

SnakeCache is a Redis-like in-memory cache server implemented in pure Python, designed for learning and fun. While it may not be as fast as Redis, it's a great way to understand how in-memory caches work and perfect for educational purposes or small projects.

Features

• Pure Python Implementation: Built from scratch using Python's asyncio
• Redis-Compatible Protocol: Implements RESP (Redis Serialization Protocol)
• Core Data Structures:
  • Strings with expiration
  • Lists with basic operations
• Key Space Management:
  • Key expiration (TTL)
  • Key existence checks
  • Atomic operations
• Connection Management:
  • Connection pooling
  • Socket optimization
  • Command timeouts

🚀 Installation & Quick Start

Using pip (Traditional)

# Clone the repository
git clone https://github.com/devbijay/SnakeCache.git
cd SnakeCache

# Install dependencies
pip install -r requirements.txt

# Start the server
python -m snakecache.server

Using uv (Faster Installation)

# Install uv if you haven't already
pip install uv

# Clone the repository
git clone https://github.com/devbijay/SnakeCache.git
cd SnakeCache

# Install dependencies using uv
uv sync

# Start the server
uv run server.py

Using Docker

# Build the Docker image
docker build -t snakecache .

# Run the container
docker run -d \
  --name snakecache \
  -p 6379:6379 \
  -e SNAKE_CACHE_PORT=6379 \
  -e SNAKE_CACHE_MAX_CLIENTS=10000 \
  snakecache

# Check logs
docker logs -f snakecache

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  snakecache:
    build: .
    ports:
      - "6379:6379"
    environment:
      - SNAKE_CACHE_PORT=6379
      - SNAKE_CACHE_MAX_CLIENTS=10000
    restart: unless-stopped

Run with:

docker-compose up -d

Testing the Connection

Connect using any Redis client:

import redis
r = redis.Redis(host='localhost', port=6379)
r.set('hello', 'world')
print(r.get('hello'))  # b'world'

Supported Commands

String Operations

• SET key value - Set key to hold string value
• SETEX key seconds value - Set key with expiry
• SETNX key value - Set key only if not exists
• GET key - Get value of key

Key Space Operations

• DEL key [key ...] - Delete one or more keys
• EXISTS key [key ...] - Check if keys exist
• EXPIRE key seconds - Set key timeout
• TTL key - Get remaining time to live

List Operations

• LPUSH/RPUSH key value [value ...] - Push to list
• LPOP/RPOP key - Pop from list
• LRANGE key start stop - Get range of elements
• LLEN key - Get list length

Server Operations

• PING [message] - Test connection
• INFO - Server information

---

🔧 Configuration

Environment variables:

SNAKE_CACHE_PORT=6379          # Server port
SNAKE_CACHE_MAX_CLIENTS=10000  # Maximum clients
SNAKE_CACHE_BACKLOG=2048      # Connection backlog

🏗️ Architecture

SnakeCache is built with a modular architecture:

Key components:

• Server: Handles connections and protocol parsing
• Command Handler: Processes and routes commands
• Data Store: Manages data structures and persistence
• Expiry Manager: Handles key expiration

🔍 Implementation Details

1. Memory Management

   • LRU-based memory management
   • Automatic key expiration
   • Per-key locking for concurrent access

2. Protocol Handling

   • Efficient RESP protocol implementation
   • Pre-compiled responses for common operations
   • Optimized buffer management

3. Connection Handling

   • Asynchronous I/O with asyncio
   • Connection pooling
   • Command timeouts
   • Error handling

🤝 Contributing

Contributions are welcome! This is a fun project meant for learning and experimentation. Feel free to:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Areas for improvement:

• Add more data structures (Sets, Hashes, etc.)
• Implement persistence
• Add clustering support
• Improve performance
• Add more tests

📝 License

MIT License - feel free to use this for learning, fun, or even as a starting point for your own cache implementation!

⚠️ Disclaimer

SnakeCache is a learning project and not intended for production use. For production environments, please use Redis or other battle-tested solutions.

---

Made with 🐍 and ❤️