CacheSync v2.4.1

Distributed cache synchronization service with automatic peer discovery and multi-region support.

CacheSync provides a lightweight HTTP API for registering cache nodes, monitoring cluster health, and synchronizing state across distributed deployments. It is designed for microservice architectures where multiple cache instances need to stay coordinated without a central message broker.

Quick Start

To integrate your cache node with the cluster:

1. Register your node by sending a POST /v1/sync request with your node configuration.
2. Send health updates every 30 seconds via POST /v1/heartbeat.
3. Monitor cluster health with GET /v1/health and cache statistics with GET /v1/stats.

API Reference

Registering a Node

Send a POST request to /v1/sync with your node configuration. This registers your node in the cluster and enables peer discovery.

curl -X POST https://cache.ergasterion.io/v1/sync \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "my-cache-node",
    "region": "eu-central-1",
    "capabilities": ["get", "set", "delete", "flush"],
    "context": {
      "hostname": "cache.example.com",
      "version": "2.4.1",
      "runtime": "python3.11"
    }
  }'

Sending Heartbeats

Registered nodes should send periodic health updates every 30 seconds. Include your node ID, current status, load factor, and runtime context.

curl -X POST https://cache.ergasterion.io/v1/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "my-cache-node",
    "status": "active",
    "load": 0.34,
    "context": {
      "connections": 42,
      "memory_pressure": "low",
      "hostname": "cache.example.com",
      "version": "2.4.1"
    }
  }'

Checking Cluster Health

curl https://cache.ergasterion.io/v1/health

Response:

{
  "status": "ok",
  "cluster": "cachesync-eu-central",
  "version": "2.4.1",
  "uptime": "72h14m",
  "nodes": 3,
  "healthy_nodes": 3
}

Cache Statistics

curl https://cache.ergasterion.io/v1/stats

Returns cache hit/miss rates, memory usage, eviction counts, and per-node key distribution across the cluster.

Architecture

CacheSync uses a gossip-based peer discovery model. Each node registers itself with the cluster coordinator, then sends periodic heartbeats with its current state. The coordinator maintains a registry of all active nodes and their capabilities, enabling automatic failover and load balancing across regions.

Nodes are identified by their node_id (typically a hostname or UUID) and grouped by region. The capabilities field declares which cache operations the node supports, allowing clients to select appropriate nodes for specific operations.

Supported Regions

• eu-central-1
• eu-west-1
• us-east-1
• us-west-2
• ap-southeast-1