Documentation
¶
Overview ¶
Package kvstore provides a unified key-value storage abstraction and a local bbolt-backed implementation with binary TTL envelopes.
Index ¶
- Variables
- func BuildSetArgs(key string, value []byte, opts KVSetOptions) ([]any, error)
- func ConfigureLocal(enabled bool, rawPath string) error
- func DurationCeil(value time.Duration, unit time.Duration) int64
- func HashKeyPart(value string) string
- func KVDelBestEffort(ctx context.Context, keys ...string) bool
- func KVDelRequired(ctx context.Context, keys ...string) (bool, int64, error)
- func KVExpireBestEffort(ctx context.Context, key string, ttl time.Duration) bool
- func KVExpireRequired(ctx context.Context, key string, ttl time.Duration) (bool, error)
- func KVGetJSONBestEffort(ctx context.Context, key string, out any) (bool, bool)
- func KVGetJSONRequired(ctx context.Context, key string, out any) (bool, bool, error)
- func KVSetBytesBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool
- func KVSetBytesRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
- func KVSetJSONBestEffort(ctx context.Context, key string, value any, ttl time.Duration) bool
- func KVSetJSONRequired(ctx context.Context, key string, value any, ttl time.Duration) (bool, error)
- func KVSetNXBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool
- func KVSetNXRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, bool, error)
- func RegisterHomeProvider(fn func() (KVClient, bool, error))
- func ResolvePath(raw string) (string, error)
- func ResolvePathWithAuthDir(rawPath, authDir string) (string, error)
- func ShutdownLocal() error
- type BoltStore
- func (s *BoltStore) Close() error
- func (s *BoltStore) KVCompareAndSwap(ctx context.Context, key string, expected []byte, expectedExists bool, ...) (bool, error)
- func (s *BoltStore) KVDel(ctx context.Context, keys ...string) (int64, error)
- func (s *BoltStore) KVExpire(ctx context.Context, key string, ttl time.Duration) (bool, error)
- func (s *BoltStore) KVGet(ctx context.Context, key string) ([]byte, bool, error)
- func (s *BoltStore) KVIncrBy(ctx context.Context, key string, delta int64) (int64, error)
- func (s *BoltStore) KVMGet(ctx context.Context, keys ...string) ([][]byte, []bool, error)
- func (s *BoltStore) KVMSet(ctx context.Context, pairs map[string][]byte) error
- func (s *BoltStore) KVSet(ctx context.Context, key string, value []byte, opts KVSetOptions) (bool, error)
- func (s *BoltStore) KVSetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
- func (s *BoltStore) KVTTL(ctx context.Context, key string) (time.Duration, bool, error)
- func (s *BoltStore) Path() string
- type BoltStoreOption
- type KVClient
- type KVSetOptions
Constants ¶
This section is empty.
Variables ¶
var ErrCompareAndSwapUnsupported = errors.New("kvstore: compare-and-swap command is not supported")
ErrCompareAndSwapUnsupported reports that the backing KV store does not support CAS.
Functions ¶
func BuildSetArgs ¶
func BuildSetArgs(key string, value []byte, opts KVSetOptions) ([]any, error)
BuildSetArgs validates KVSet arguments and builds the canonical Redis-style argument list.
func ConfigureLocal ¶
ConfigureLocal enables, reconfigures, or disables the local bbolt-backed KV store.
func DurationCeil ¶
DurationCeil divides value by unit, rounding positive remainders up to the next integer unit.
func HashKeyPart ¶
HashKeyPart returns the lowercase hex-encoded SHA-256 digest of value.
func KVDelBestEffort ¶
KVDelBestEffort deletes keys from the active KV store, logging and swallowing errors.
func KVDelRequired ¶
KVDelRequired deletes keys from the active KV store if KV mode is enabled.
func KVExpireBestEffort ¶
KVExpireBestEffort updates key expiration in the active KV store, logging and swallowing errors.
func KVExpireRequired ¶
KVExpireRequired updates the expiration of key in the active KV store if KV mode is enabled.
func KVGetJSONBestEffort ¶
KVGetJSONBestEffort fetches a JSON value from the active KV store, logging and swallowing errors.
func KVGetJSONRequired ¶
KVGetJSONRequired fetches a JSON value from the active KV store if KV mode is enabled.
func KVSetBytesBestEffort ¶
KVSetBytesBestEffort stores raw bytes in the active KV store, logging and swallowing errors.
func KVSetBytesRequired ¶
func KVSetBytesRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
KVSetBytesRequired writes raw bytes to the active KV store if KV mode is enabled.
func KVSetJSONBestEffort ¶
KVSetJSONBestEffort marshals and stores value in the active KV store, logging and swallowing errors.
func KVSetJSONRequired ¶
KVSetJSONRequired marshals value as JSON and writes it to the active KV store if KV mode is enabled.
func KVSetNXBestEffort ¶
KVSetNXBestEffort conditionally stores value if key does not exist, logging and swallowing errors.
func KVSetNXRequired ¶
func KVSetNXRequired(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, bool, error)
KVSetNXRequired conditionally writes value only if key does not exist in the active KV store.
func RegisterHomeProvider ¶
RegisterHomeProvider registers the callback used by CurrentKVClient to inspect whether Home mode is active and obtain the active Home KV client.
func ResolvePath ¶
ResolvePath normalizes the configured bbolt database file path into an absolute file path. Empty values default to config.DefaultKVStorePath ("kv.db") in the current working directory.
func ResolvePathWithAuthDir ¶
ResolvePathWithAuthDir resolves rawPath when non-empty, or falls back to "<auth-dir>/kv.db" (using config.DefaultAuthDir when authDir is empty).
func ShutdownLocal ¶
func ShutdownLocal() error
ShutdownLocal closes any open local BoltStore and resets local KV state to disabled.
Types ¶
type BoltStore ¶
type BoltStore struct {
// contains filtered or unexported fields
}
BoltStore implements KVClient backed by a local bbolt database file.
func OpenBoltStore ¶
func OpenBoltStore(path string, opts ...BoltStoreOption) (*BoltStore, error)
OpenBoltStore resolves path, creates parent directories, opens the bbolt file, ensures the KV bucket exists, and starts the background expiration sweeper.
func (*BoltStore) Close ¶
Close stops the background sweeper and closes the underlying bbolt database. Calling Close multiple times is safe and idempotent.
func (*BoltStore) KVCompareAndSwap ¶
func (s *BoltStore) KVCompareAndSwap(ctx context.Context, key string, expected []byte, expectedExists bool, value []byte, ttl time.Duration) (bool, error)
KVCompareAndSwap atomically updates key to value if its current state matches expectedExists and expected.
func (*BoltStore) KVDel ¶
KVDel deletes one or more keys and returns the number of unexpired keys removed.
func (*BoltStore) KVExpire ¶
KVExpire updates the TTL of an existing unexpired key, or immediately deletes it if ttl <= 0.
func (*BoltStore) KVIncrBy ¶
KVIncrBy atomically increments the base-10 integer value of key by delta.
func (*BoltStore) KVMSet ¶
KVMSet writes multiple non-expiring key-value pairs in a single write transaction.
func (*BoltStore) KVSet ¶
func (s *BoltStore) KVSet(ctx context.Context, key string, value []byte, opts KVSetOptions) (bool, error)
KVSet stores key and value with optional TTL and NX/XX conditions.
func (*BoltStore) KVSetNX ¶
func (s *BoltStore) KVSetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
KVSetNX stores value only when key does not currently exist (or has expired).
type BoltStoreOption ¶
type BoltStoreOption func(*BoltStore)
BoltStoreOption configures optional behavior on BoltStore.
func WithNowFunc ¶
func WithNowFunc(fn func() time.Time) BoltStoreOption
WithNowFunc overrides the clock function used for TTL evaluation.
func WithSweepBatchSize ¶
func WithSweepBatchSize(batchSize int) BoltStoreOption
WithSweepBatchSize sets the maximum number of expired keys deleted per sweep batch.
func WithSweepInterval ¶
func WithSweepInterval(interval time.Duration) BoltStoreOption
WithSweepInterval sets the background expired-key sweep interval. A non-positive interval disables the background sweeper goroutine.
type KVClient ¶
type KVClient interface {
KVGet(ctx context.Context, key string) ([]byte, bool, error)
KVSet(ctx context.Context, key string, value []byte, opts KVSetOptions) (bool, error)
KVSetNX(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
KVCompareAndSwap(ctx context.Context, key string, expected []byte, expectedExists bool, value []byte, ttl time.Duration) (bool, error)
KVDel(ctx context.Context, keys ...string) (int64, error)
KVExpire(ctx context.Context, key string, ttl time.Duration) (bool, error)
KVTTL(ctx context.Context, key string) (time.Duration, bool, error)
KVIncrBy(ctx context.Context, key string, delta int64) (int64, error)
KVMGet(ctx context.Context, keys ...string) ([][]byte, []bool, error)
KVMSet(ctx context.Context, pairs map[string][]byte) error
}
KVClient defines the key-value storage contract shared by Home KV and local BoltStore.
func CurrentKVClient ¶
CurrentKVClient returns the active KVClient using the three-tier routing order:
- Home KV when Home mode is active (never falling back to local bbolt).
- Local BoltStore when server.kv-store.disabled is false.
- (nil, false, nil) for default in-memory storage.