Files
anchorage/internal/pkg/placement/rendezvous.go
T
57_Wolve 12bf35caf8 anchorage v1.0 initial tree
Greenfield Go multi-tenant IPFS Pinning Service wire-compatible with the
IPFS Pinning Services API spec. Paired 1:1 with Kubo over localhost RPC,
clustered via embedded NATS JetStream, Postgres source-of-truth with
RLS-enforced tenancy, Fiber + huma v2 for the HTTP surface, Authentik
OIDC for session login with kid-rotated HS256 JWT API tokens.

Feature-complete against the 22-milestone build plan, including the
ship-it v1.0 gap items:

  * admin CLIs: drain/uncordon, maintenance, mint-token, rotate-key,
    prune-denylist, rebalance --dry-run, cache-stats, cluster-presences
  * TTL leader election via NATS KV, fence tokens, JetStream dedup
  * rebalancer (plan/apply split), reconciler, requeue sweeper
  * ristretto caches with NATS-backed cross-node invalidation
    (placements live-nodes + token denylist)
  * maintenance watchdog for stuck cluster-pause flag
  * Prometheus /metrics with CIDR ACL, HTTP/pin/scheduler/cache gauges
  * rate limiting: session (10/min) + anonymous global (120/min)
  * integration tests: rebalance, refcount multi-org, RLS belt
  * goreleaser (tar + deb/rpm/apk + Alpine Docker) targeting Gitea

Stack: Cobra/Viper, Fiber v2 + huma v2, embedded NATS JetStream,
pgx/sqlc/golang-migrate, ristretto, TypeID, prometheus/client_golang,
testcontainers-go.
2026-04-16 18:13:36 -05:00

81 lines
2.4 KiB
Go

// Package placement selects which cluster nodes should hold a given pin.
//
// anchorage uses Rendezvous (Highest Random Weight, HRW) hashing over the
// tuple (orgID, cid, nodeID): every (node, pin) pair gets a deterministic
// score, and the top min(replicas, liveNodes) nodes are chosen.
//
// Properties:
//
// - Deterministic: any node can compute "where does this pin belong"
// without coordination, given the same live-node set.
// - Minimal disruption: when a node joins or leaves, only pins whose top
// replica set actually changes get moved; on average a fraction of
// 1/N pins migrate, not all of them.
// - No coordination: unlike consistent hashing with ring state, HRW is
// pure function of the inputs, so there's no "ring" to synchronize.
package placement
import (
"sort"
"github.com/zeebo/xxh3"
)
// Node is the minimal view of a cluster node that placement needs.
type Node struct {
ID string
// Status is used only by callers to pre-filter; placement treats
// every node it's given as eligible.
Status string
}
// Compute returns up to wantReplicas distinct node IDs chosen via HRW
// over (orgID, cid, nodeID). The returned slice is sorted by score
// descending; callers can take the first N for the replica set.
//
// If len(nodes) < wantReplicas, all nodes are returned (caller decides
// whether to accept under-replication).
func Compute(orgID, cid string, wantReplicas int, nodes []Node) []string {
if wantReplicas <= 0 || len(nodes) == 0 {
return nil
}
scored := make([]scoredNode, 0, len(nodes))
for _, n := range nodes {
scored = append(scored, scoredNode{id: n.ID, score: score(orgID, cid, n.ID)})
}
sort.Slice(scored, func(i, j int) bool {
if scored[i].score == scored[j].score {
return scored[i].id < scored[j].id
}
return scored[i].score > scored[j].score
})
n := wantReplicas
if n > len(scored) {
n = len(scored)
}
out := make([]string, n)
for i := 0; i < n; i++ {
out[i] = scored[i].id
}
return out
}
type scoredNode struct {
id string
score uint64
}
// score computes the HRW weight for a (org, cid, node) triple using
// xxh3, which is fast, 64-bit, and well-distributed. The scalar weight
// is the hash itself; higher = closer to the top.
func score(orgID, cid, nodeID string) uint64 {
h := xxh3.New()
_, _ = h.WriteString(orgID)
_, _ = h.WriteString("\x00")
_, _ = h.WriteString(cid)
_, _ = h.WriteString("\x00")
_, _ = h.WriteString(nodeID)
return h.Sum64()
}