Valkey cluster cache provider

Valkey Cluster cache provider implementing cache.Provider against a sharded Valkey Cluster deployment, with hash-slot routing, optional replica reads, and the same tag semantics as the single-node provider.

Overview

Valkey Cluster is the sharded deployment topology for Valkey, the BSD-licensed Redis fork. The Piko provider wraps the official valkey-go client, discovering the cluster topology from the seed nodes in InitAddress and routing each command to the correct shard via CRC16 hash slots. The wire protocol and operational shape match Redis Cluster.

One provider holds a single shared cluster client. Every namespace you create reuses that one client, so adding a cache is a CreateNamespace call with no extra connection wiring.

Reach for Valkey Cluster when you have outgrown a single Valkey node and you want a permissively licensed cluster topology. Reach for Redis Cluster when you need Redis Stack module parity, Valkey when one node is enough, and Otter for in-process caching at single-instance scale.

Tag-based invalidation stays atomic in a sharded cluster. The provider wraps every tag key in hash-tag braces, {namespace+tag}, to force same-slot placement. Tag operations then run on a single node and you get single-node tag semantics for free. The SendToReplicas flag enables read-scaling by routing read-only commands to replica nodes.

Requirements

A reachable Valkey Cluster (at least one seed node in InitAddress).
Network egress to every cluster node, not just the seeds, the client connects directly to whichever shard owns each key.
A cache.EncodingRegistry for cache values.

Configuration

import (
    "os"
    "time"

    "piko.sh/piko/wdk/cache"
    "piko.sh/piko/wdk/cache/cache_encoder_json"
    "piko.sh/piko/wdk/cache/cache_provider_valkey_cluster"
)

registry := cache.NewEncodingRegistry(cache_encoder_json.New[any]())

provider, err := cache_provider_valkey_cluster.NewValkeyClusterProvider(cache_provider_valkey_cluster.Config{
    InitAddress: []string{ // required: at least one seed node
        "valkey-1.example.com:6379",
        "valkey-2.example.com:6379",
        "valkey-3.example.com:6379",
    },
    Username:         "",                           // ACL username; empty for default user
    Password:         os.Getenv("VALKEY_PASSWORD"), // empty for unauthenticated clusters
    Namespace:        "myapp:",                     // global key prefix
    ClientName:       "piko-app",                   // CLIENT SETNAME identifier
    IndexPrefix:      "index:",                     // Valkey Search index prefix
    DefaultTTL:       1 * time.Hour,                // entry expiry; default 1 hour
    OperationTimeout: 2 * time.Second,              // standard ops; default 2s
    SendToReplicas:   false,                        // route read commands to replicas
    Registry:         registry,                     // required: value encoder registry
    // TLSConfig: &tls.Config{...},                 // optional: enable TLS
})
if err != nil {
    return err
}

NewValkeyClusterProvider pings the cluster on construction and fails fast if it cannot reach any seed or if Registry is nil.

Config exposes further timeout and retry knobs with sensible defaults. These include AtomicOperationTimeout (5 seconds), BulkOperationTimeout (10 seconds), FlushTimeout (30 seconds), SearchTimeout (5 seconds), and MaxComputeRetries (10). Pass a KeyRegistry to encode struct keys. Without it, keys use fmt.Sprintf, which suits simple string and integer keys.

Cluster-wide invalidation

InvalidateAll clears the configured Namespace by scanning and deleting its keys. With no Namespace set, it refuses to run unless you also set AllowUnsafeFLUSHDB, which defaults to false. That flag gates a cluster-wide FLUSHDB across every master node, which deletes ALL keys on ALL nodes, not just your namespace. Leave it off unless this application owns the whole cluster.

Bootstrap

ssr := piko.New(
    piko.WithCacheProvider("valkey-cluster", provider),
    piko.WithDefaultCacheProvider("valkey-cluster"),
)