OCache

High-performance cache service with dual-storage architecture, supporting both gRPC and HTTP interfaces. Optimized for mixed workloads with intelligent routing between RocksDB (small objects) and disk storage (large objects).

Features

• Dual Storage: RocksDB for small objects, segmented disk storage for large objects
• Cluster Mode: Distributed caching with consistent hashing across multiple nodes
• Smart Routing: Client-side routing with automatic topology discovery
• Multiple Interfaces: gRPC for high performance, HTTP REST for easy integration
• TTL Support: Automatic expiration with background cleanup
• LRU Eviction: Optional disk usage limits with automatic eviction
• Connection Pooling: Efficient resource utilization for high concurrency
• High Performance: Optimized for throughput and low latency

Quick Start

Prerequisites: Go 1.24+, protoc, and RocksDB (with a C++ toolchain, since OCache links RocksDB via cgo). make install-deps installs protoc and the Go plugins; make install-rocksdb installs RocksDB. See the Installation Guide for platform details and static-build options. Always build and test through the make targets — they set the required CGO flags.

Single Node

# Clone and build
git clone https://github.com/tigrisdata/ocache.git
cd ocache
make install-deps
make install-rocksdb   # or see docs/installation.md for a static build
make all

# Run the server
./ocache -disk /tmp/cache -listen-addr :9000 -listen-http :9001

# Test with CLI
./ocachecli put mykey "hello world"
./ocachecli get mykey

Cluster Mode

# Start a 3-node cluster
./ocache -cluster-enabled -node-id node1 -listen-addr :9001 \
  -cluster-addr :7001 -seeds "localhost:7002,localhost:7003"

./ocache -cluster-enabled -node-id node2 -listen-addr :9002 \
  -cluster-addr :7002 -seeds "localhost:7001,localhost:7003"

./ocache -cluster-enabled -node-id node3 -listen-addr :9003 \
  -cluster-addr :7003 -seeds "localhost:7001,localhost:7002"

# Use with cluster-aware client
./ocachecli --addr "localhost:9001,localhost:9002,localhost:9003" \
  put mykey "distributed value"

Docker

# Single node
docker run -d -p 9000:9000 -p 9001:9001 \
  -v ocache-data:/data tigrisdata/ocache:latest

# Or use docker-compose
docker-compose -f docker/docker-compose.yml up -d

# 3-node cluster
docker-compose -f docker/docker-compose-cluster.yml up -d

See Docker Guide for detailed configuration options.

Documentation

• Installation Guide - Build options and dependencies
• Docker Guide - Docker deployment and configuration
• Cluster Mode - Distributed caching setup and operations
• Client Documentation - Go client library
• Embedded Client - Embed OCache in your Go application
• CLI Client - Command-line client usage
• HTTP API Reference - HTTP REST API
• Configuration - Server flags and tuning
• Testing Guide - Running and writing tests
• Benchmark Guide - Running benchmarks
• Metrics Guide - Prometheus metrics
• Static Builds - Building static binaries

Basic Usage

HTTP API

# Store data
curl -X POST "http://localhost:9001/v1/cache/mykey" \
  -d '{"data":"aGVsbG8gd29ybGQ=","ttl_seconds":3600}'

# Retrieve data
curl "http://localhost:9001/v1/cache/mykey"

# Delete data
curl -X DELETE "http://localhost:9001/v1/cache/mykey"

CLI Client

# Store, retrieve, delete
./ocachecli put key1 "value1"
./ocachecli get key1
./ocachecli del key1

# Run benchmarks
./ocachecli bench --workload B --num-ops 100000

Configuration

Key configuration flags:

Flag	Default	Description
-listen-addr	:9000	gRPC server listen address
-listen-http	:9001	HTTP server listen address
-disk	/var/cache	Storage directory
-ttl	0	Default global TTL (seconds)
-max-disk-usage	0	Max disk usage (0=unlimited)
-metadata-cache-size	1073741824	Maximum size of the metadata cache in bytes (1GB)
-cluster-enabled	false	Enable cluster mode
-cluster-addr	:7000	Cluster address
-seeds	""	Comma-separated list of seed nodes (required for cluster)
-node-id	""	Unique node identifier (required for cluster)

See Configuration Guide for complete options.

Testing

Run tests with make test for unit tests or make test-all for the complete suite. You can run specific tests using TEST=TestName or TESTRUN=Pattern variables:

# Run all tests
make test-all

# Run specific test
make test TEST=TestCacheService_PutObjectAndGet

# Run tests matching pattern
make test-integration TESTRUN=Compaction

See Testing Guide for comprehensive testing documentation.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md. We use the Developer Certificate of Origin — sign off your commits with git commit -s. This project follows the Code of Conduct.

Security

To report a security vulnerability, please follow SECURITY.md. Do not open public issues for security reports.

License

OCache is licensed under the Apache License 2.0. See NOTICE for third-party attributions.