distributed-cache

A distributed, in-memory key/value cache in Go.

I hand-coded the first implementation (internal/human) without AI, then had AI build its own version of the same thing (internal/ai), and studied the diff to learn from the AI's approach — concurrency patterns, consistent hashing, error handling, and test design.

What it does

• In-memory key/value store with LRU eviction and per-item TTL expiry.
• Consistent hashing over a ring so keys map to nodes with minimal reshuffling when nodes join or leave.
• HTTP-based cluster: each node owns a slice of the keyspace and forwards requests for keys it doesn't own to the peer that does.
• Two independent implementations behind one interface, so the human and AI versions can be run and compared file-for-file.

Requirements

• Go 1.26.4 or later
• Standard library only — no external dependencies.

Installation

git clone <this-repo>
cd distributed-cache
go build -o distributed-cache .

Running

Start a single node:

go run . -impl human -port :8080 -peers ""

Run a local cluster by starting several nodes on different ports and pointing each at its peers:

go run . -impl human -port :8080 -peers "localhost:8081,localhost:8082"
go run . -impl human -port :8081 -peers "localhost:8080,localhost:8082"
go run . -impl human -port :8082 -peers "localhost:8080,localhost:8081"

Flags:

• -impl — implementation to run: human (default) or ai.
• -port — HTTP server port (default :8080).
• -peers — comma-separated list of peer addresses.

Architecture

Each implementation is the same three layers:

• cache.go — the local store. A map plus a doubly-linked list for O(1) LRU eviction, guarded by a mutex, with TTL-based expiry on items.
• hash_ring.go — consistent hashing. Nodes are hashed onto a sorted ring; a key lookup binary-searches the ring to find its owning node.
• server.go — the coordination layer. An HTTP server that resolves each key to its owner via the ring, serving it locally or forwarding to the right peer.

main.go wires one implementation into a running server via a shared cacheServer interface, selected by the -impl flag.

internal/
  human/   hand-written implementation (cache, hash_ring, server + tests)
  ai/      AI-authored implementation of the same design