kvstore

package
v8.0.76 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package kvstore provides a unified key-value storage abstraction and a local bbolt-backed implementation with binary TTL envelopes.

Index

Constants

This section is empty.

Variables

View Source
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

func ConfigureLocal(enabled bool, rawPath string) error

ConfigureLocal enables, reconfigures, or disables the local bbolt-backed KV store.

func DurationCeil

func DurationCeil(value time.Duration, unit time.Duration) int64

DurationCeil divides value by unit, rounding positive remainders up to the next integer unit.

func HashKeyPart

func HashKeyPart(value string) string

HashKeyPart returns the lowercase hex-encoded SHA-256 digest of value.

func KVDelBestEffort

func KVDelBestEffort(ctx context.Context, keys ...string) bool

KVDelBestEffort deletes keys from the active KV store, logging and swallowing errors.

func KVDelRequired

func KVDelRequired(ctx context.Context, keys ...string) (bool, int64, error)

KVDelRequired deletes keys from the active KV store if KV mode is enabled.

func KVExpireBestEffort

func KVExpireBestEffort(ctx context.Context, key string, ttl time.Duration) bool

KVExpireBestEffort updates key expiration in the active KV store, logging and swallowing errors.

func KVExpireRequired

func KVExpireRequired(ctx context.Context, key string, ttl time.Duration) (bool, error)

KVExpireRequired updates the expiration of key in the active KV store if KV mode is enabled.

func KVGetJSONBestEffort

func KVGetJSONBestEffort(ctx context.Context, key string, out any) (bool, bool)

KVGetJSONBestEffort fetches a JSON value from the active KV store, logging and swallowing errors.

func KVGetJSONRequired

func KVGetJSONRequired(ctx context.Context, key string, out any) (bool, bool, error)

KVGetJSONRequired fetches a JSON value from the active KV store if KV mode is enabled.

func KVSetBytesBestEffort

func KVSetBytesBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool

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

func KVSetJSONBestEffort(ctx context.Context, key string, value any, ttl time.Duration) bool

KVSetJSONBestEffort marshals and stores value in the active KV store, logging and swallowing errors.

func KVSetJSONRequired

func KVSetJSONRequired(ctx context.Context, key string, value any, ttl time.Duration) (bool, error)

KVSetJSONRequired marshals value as JSON and writes it to the active KV store if KV mode is enabled.

func KVSetNXBestEffort

func KVSetNXBestEffort(ctx context.Context, key string, value []byte, ttl time.Duration) bool

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

func RegisterHomeProvider(fn func() (KVClient, bool, error))

RegisterHomeProvider registers the callback used by CurrentKVClient to inspect whether Home mode is active and obtain the active Home KV client.

func ResolvePath

func ResolvePath(raw string) (string, error)

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

func ResolvePathWithAuthDir(rawPath, authDir string) (string, error)

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

func (s *BoltStore) Close() error

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

func (s *BoltStore) KVDel(ctx context.Context, keys ...string) (int64, error)

KVDel deletes one or more keys and returns the number of unexpired keys removed.

func (*BoltStore) KVExpire

func (s *BoltStore) KVExpire(ctx context.Context, key string, ttl time.Duration) (bool, error)

KVExpire updates the TTL of an existing unexpired key, or immediately deletes it if ttl <= 0.

func (*BoltStore) KVGet

func (s *BoltStore) KVGet(ctx context.Context, key string) ([]byte, bool, error)

KVGet retrieves the value for key if it exists and has not expired.

func (*BoltStore) KVIncrBy

func (s *BoltStore) KVIncrBy(ctx context.Context, key string, delta int64) (int64, error)

KVIncrBy atomically increments the base-10 integer value of key by delta.

func (*BoltStore) KVMGet

func (s *BoltStore) KVMGet(ctx context.Context, keys ...string) ([][]byte, []bool, error)

KVMGet retrieves multiple keys in a single read transaction.

func (*BoltStore) KVMSet

func (s *BoltStore) KVMSet(ctx context.Context, pairs map[string][]byte) error

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).

func (*BoltStore) KVTTL

func (s *BoltStore) KVTTL(ctx context.Context, key string) (time.Duration, bool, error)

KVTTL returns the remaining time-to-live of key. If key does not exist or has expired, it returns (0, false, nil). If key exists and has no expiration, it returns (0, true, nil).

func (*BoltStore) Path

func (s *BoltStore) Path() string

Path returns the resolved absolute file path of the underlying bbolt database.

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

func CurrentKVClient() (KVClient, bool, error)

CurrentKVClient returns the active KVClient using the three-tier routing order:

  1. Home KV when Home mode is active (never falling back to local bbolt).
  2. Local BoltStore when server.kv-store.disabled is false.
  3. (nil, false, nil) for default in-memory storage.

type KVSetOptions

type KVSetOptions struct {
	EX time.Duration
	PX time.Duration
	NX bool
	XX bool
}

KVSetOptions configures optional expiration and conditional write behavior for KVSet.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL