Rendezvous Hashing Library

A high-performance, thread-safe implementation of rendezvous (consistent) hashing in Go for distributed systems.

Features

• Consistent Hashing: Minimal key redistribution when nodes are added/removed
• Multiple Hash Functions: FNV, SHA256, CRC32 support
• Thread-Safe: Concurrent operations with read-write locks
• Configurable: Virtual nodes, replication factor, logging
• Production Ready: Comprehensive test coverage and benchmarks

Installation

go get github.com/l00pss/rendezvous

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/l00pss/rendezvous"
)

func main() {
    // Create rendezvous instance
    rv := rendezvous.NewRendezvous(nil) // Uses default config
    defer rv.Close()

    ctx := context.Background()

    // Register peers
    rv.RegisterPeer(ctx, "server1", "192.168.1.1:8080")
    rv.RegisterPeer(ctx, "server2", "192.168.1.2:8080")
    rv.RegisterPeer(ctx, "server3", "192.168.1.3:8080")

    // Find responsible peer for a key
    addr, err := rv.FindPeer(ctx, "user123")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Key 'user123' -> %s\n", addr)
}

Configuration

config := rendezvous.NewConfigBuilder().
    WithHashFunction(rendezvous.SHA256HashFunction).
    WithVirtualNodes(150).
    WithReplicationFactor(3).
    Build()

rv := rendezvous.NewRendezvous(config)

API Methods

• RegisterPeer(ctx, peerID, address) - Add a new peer
• UnregisterPeer(ctx, peerID) - Remove a peer
• FindPeer(ctx, key) - Find responsible peer for a key
• GetPeers(ctx) - Get all registered peers
• Health(ctx) - Health check
• Close() - Graceful shutdown

Examples

See examples/main.go for a comprehensive demonstration including:

• Load balancing scenarios
• Peer addition/removal consistency
• Concurrent operations
• Performance testing

Run the example:

cd examples && go run main.go

Testing

# Run tests
go test -v

# Run benchmarks
go test -bench=.

# Test coverage
go test -cover

Performance

Benchmarks on Apple M1 Pro:

• FindPeer: ~171 ns/op
• RegisterPeer: ~17.5ms/op (due to ring sorting)

License

Licensed under LICENSE.

Built with ❤️ and Go

⭐ Star this project if you find it useful!