Extensions Overview
Higher-level abstractions built on the Grove KV Store interface -- distributed locks, rate limiters, sessions, counters, leaderboards, and job queues.
Grove KV extensions are application-level primitives built entirely on the *kv.Store interface. Because they only use the standard Store operations (Get, Set, Delete, Expire, Exists), every extension works with any backend driver -- Redis, Memcached, DynamoDB, BoltDB, or Badger -- with zero driver-specific code.
What Are Extensions?
Each extension is a standalone Go struct that wraps a *kv.Store and provides a focused, higher-level API for a common distributed-systems pattern. You create an extension by passing your existing store, and the extension handles key management, serialization, TTLs, and coordination logic internally.
import (
"github.com/xraph/grove/kv"
"github.com/xraph/grove/kv/plugins"
)
// Any Store, any driver.
store, _ := kv.Open(driver)
// Create extensions from the same store.
sessions := plugins.NewSessionStore(store)
limiter := plugins.NewRateLimiter(store, "api", 100, time.Minute)
lock := plugins.NewLock(store, "deploy", 10*time.Second)
counter := plugins.NewAtomicCounter(store, "visitors")
board := plugins.NewLeaderboard(store, "scores")
queue := plugins.NewQueue(store, "tasks")Driver-Agnostic by Design
Extensions depend only on the *kv.Store interface, not on any specific driver. This means:
- Swap backends freely -- switch from BoltDB in development to Redis in production without touching extension code.
- Test with any driver -- use an in-memory Badger store in tests and a real Redis cluster in production.
- Compose with hooks -- all Store-level hooks (logging, namespacing, compression, encryption) apply transparently to extension operations.
Available Extensions
| Extension | Constructor | Key Prefix | Description |
|---|---|---|---|
| Distributed Lock | NewLock | lock: | Mutual exclusion with TTL-based expiry and retry support |
| Rate Limiter | NewRateLimiter | custom | Sliding window counter for distributed rate limiting |
| Session Store | NewSessionStore | sess: (default) | HTTP session storage with auto-generated IDs and TTL |
| Atomic Counter | NewAtomicCounter | counter: | Distributed increment/decrement with get and reset |
| Leaderboard | NewLeaderboard | lb: | Sorted member/score leaderboard with ranking |
| Job Queue | NewQueue | queue: | FIFO job queue with visibility timeout and acknowledgment |
Next Steps
Session Store
HTTP session storage with cryptographically random IDs, configurable TTL, and touch support.
Rate Limiter
Sliding window rate limiting with remaining count and reset time.
Distributed Lock
Mutual exclusion lock with TTL expiry, retry logic, and extend support.
Atomic Counter
Distributed atomic increment/decrement counter with get, set, and reset.
Leaderboard
Sorted leaderboard with add, rank, top-N, and remove operations.
Job Queue
FIFO job queue with enqueue, dequeue, visibility timeout, and acknowledgment.