arian/navidrome
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

feat(plugins): add TTL support, batch operations, and hardening to kvstore (#5127)

Browse Source 
* feat(plugins): add expires_at column to kvstore schema

* feat(plugins): filter expired keys in kvstore Get, Has, List

* feat(plugins): add periodic cleanup of expired kvstore keys

* feat(plugins): add SetWithTTL, DeleteByPrefix, and GetMany to kvstore

Add three new methods to the KVStore host service:

- SetWithTTL: store key-value pairs with automatic expiration
- DeleteByPrefix: remove all keys matching a prefix in one operation
- GetMany: retrieve multiple values in a single call

All methods include comprehensive unit tests covering edge cases,
expiration behavior, size tracking, and LIKE-special characters.

* feat(plugins): regenerate code and update test plugin for new kvstore methods

Regenerate host function wrappers and PDK bindings for Go, Python,
and Rust. Update the test-kvstore plugin to exercise SetWithTTL,
DeleteByPrefix, and GetMany.

* feat(plugins): add integration tests for new kvstore methods

Add WASM integration tests for SetWithTTL, DeleteByPrefix, and GetMany
operations through the plugin boundary, verifying end-to-end behavior
including TTL expiration, prefix deletion, and batch retrieval.

* fix(plugins): address lint issues in kvstore implementation

Handle tx.Rollback error return and suppress gosec false positive
for parameterized SQL query construction in GetMany.

* fix(plugins): Set clears expires_at when overwriting a TTL'd key

Previously, calling Set() on a key that was stored with SetWithTTL()
would leave the expires_at value intact, causing the key to silently
expire even though Set implies permanent storage.

Also excludes expired keys from currentSize calculation at startup.

* refactor(plugins): simplify kvstore by removing in-memory size cache

Replaced the in-memory currentSize cache (atomic.Int64), periodic cleanup
timer, and mutex with direct database queries for storage accounting.
This eliminates race conditions and cache drift issues at negligible
performance cost for plugin-sized datasets. Also unified Set and
SetWithTTL into a shared setValue method, simplified DeleteByPrefix to
use RowsAffected instead of a transaction, and added an index on
expires_at for efficient expiration filtering.

* feat(plugins): add generic SQLite migration helper and refactor kvstore schema

Add a reusable migrateDB helper that tracks schema versions via SQLite's
PRAGMA user_version and applies pending migrations transactionally. Replace
the ad-hoc createKVStoreSchema function in kvstore with a declarative
migrations slice, making it easy to add future schema changes. Remove the
now-redundant schema migration test since migrateDB has its own test suite
and every kvstore test exercises the migrations implicitly.

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(plugins): harden kvstore with explicit NULL handling, prefix validation, and cleanup timeout

- Use sql.NullString for expires_at to explicitly send NULL instead of
  relying on datetime('now', '') returning NULL by accident
- Reject empty prefix in DeleteByPrefix to prevent accidental data wipe
- Add 5s timeout context to cleanupExpired on Close
- Replace time.Sleep in unit tests with pre-expired timestamps

Signed-off-by: Deluan <deluan@navidrome.org>

* refactor(plugins): use batch processing in GetMany

Process keys in chunks of 200 using slice.CollectChunks to avoid
hitting SQLite's SQLITE_MAX_VARIABLE_NUMBER limit with large key sets.

* feat(plugins): add periodic cleanup goroutine for expired kvstore keys

Use the manager's context to control a background goroutine that purges
expired keys every hour, stopping naturally on shutdown when the context
is cancelled.

---------

Signed-off-by: Deluan <deluan@navidrome.org>
This commit is contained in:
Deluan Quintão
2026-02-28 23:12:17 -05:00
committed by GitHub
parent d9a215e1e3
commit 2471bb9cf6
12 changed files with 1528 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/pdk/go/host/nd_host_kvstore.go
+187 -21
View File
@@ -19,15 +19,20 @@ import (
//go:wasmimport extism:host/user kvstore_set
func kvstore_set(uint64) uint64
// kvstore_setwithttl is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_setwithttl
func kvstore_setwithttl(uint64) uint64
// kvstore_get is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_get
func kvstore_get(uint64) uint64
// kvstore_delete is the host function provided by Navidrome.
// kvstore_getmany is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_delete
func kvstore_delete(uint64) uint64
//go:wasmimport extism:host/user kvstore_getmany
func kvstore_getmany(uint64) uint64
// kvstore_has is the host function provided by Navidrome.
//
@@ -39,6 +44,16 @@ func kvstore_has(uint64) uint64
//go:wasmimport extism:host/user kvstore_list
func kvstore_list(uint64) uint64
// kvstore_delete is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_delete
func kvstore_delete(uint64) uint64
// kvstore_deletebyprefix is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_deletebyprefix
func kvstore_deletebyprefix(uint64) uint64
// kvstore_getstorageused is the host function provided by Navidrome.
//
//go:wasmimport extism:host/user kvstore_getstorageused
@@ -49,6 +64,12 @@ type kVStoreSetRequest struct {
Value []byte `json:"value"`
}
type kVStoreSetWithTTLRequest struct {
Key string `json:"key"`
Value []byte `json:"value"`
TtlSeconds int64 `json:"ttlSeconds"`
}
type kVStoreGetRequest struct {
Key string `json:"key"`
}
@@ -59,8 +80,13 @@ type kVStoreGetResponse struct {
Error string `json:"error,omitempty"`
}
type kVStoreDeleteRequest struct {
Key string `json:"key"`
type kVStoreGetManyRequest struct {
Keys []string `json:"keys"`
}
type kVStoreGetManyResponse struct {
Values map[string][]byte `json:"values,omitempty"`
Error string `json:"error,omitempty"`
}
type kVStoreHasRequest struct {
@@ -81,6 +107,19 @@ type kVStoreListResponse struct {
Error string `json:"error,omitempty"`
}
type kVStoreDeleteRequest struct {
Key string `json:"key"`
}
type kVStoreDeleteByPrefixRequest struct {
Prefix string `json:"prefix"`
}
type kVStoreDeleteByPrefixResponse struct {
DeletedCount int64 `json:"deletedCount,omitempty"`
Error string `json:"error,omitempty"`
}
type kVStoreGetStorageUsedResponse struct {
Bytes int64 `json:"bytes,omitempty"`
Error string `json:"error,omitempty"`
@@ -127,6 +166,52 @@ func KVStoreSet(key string, value []byte) error {
return nil
}
// KVStoreSetWithTTL calls the kvstore_setwithttl host function.
// SetWithTTL stores a byte value with the given key and a time-to-live.
//
// After ttlSeconds, the key is treated as non-existent and will be
// cleaned up lazily. ttlSeconds must be greater than 0.
//
// Parameters:
// - key: The storage key (max 256 bytes, UTF-8)
// - value: The byte slice to store
// - ttlSeconds: Time-to-live in seconds (must be > 0)
//
// Returns an error if the storage limit would be exceeded or the operation fails.
func KVStoreSetWithTTL(key string, value []byte, ttlSeconds int64) error {
// Marshal request to JSON
req := kVStoreSetWithTTLRequest{
Key: key,
Value: value,
TtlSeconds: ttlSeconds,
}
reqBytes, err := json.Marshal(req)
if err != nil {
return err
}
reqMem := pdk.AllocateBytes(reqBytes)
defer reqMem.Free()
// Call the host function
responsePtr := kvstore_setwithttl(reqMem.Offset())
// Read the response from memory
responseMem := pdk.FindMemory(responsePtr)
responseBytes := responseMem.ReadBytes()
// Parse error-only response
var response struct {
Error string `json:"error,omitempty"`
}
if err := json.Unmarshal(responseBytes, &response); err != nil {
return err
}
if response.Error != "" {
return errors.New(response.Error)
}
return nil
}
// KVStoreGet calls the kvstore_get host function.
// Get retrieves a byte value from storage.
//
@@ -167,43 +252,45 @@ func KVStoreGet(key string) ([]byte, bool, error) {
return response.Value, response.Exists, nil
}
// KVStoreDelete calls the kvstore_delete host function.
// Delete removes a value from storage.
// KVStoreGetMany calls the kvstore_getmany host function.
// GetMany retrieves multiple values in a single call.
//
// Parameters:
// - key: The storage key
// - keys: The storage keys to retrieve
//
// Returns an error if the operation fails. Does not return an error if the key doesn't exist.
func KVStoreDelete(key string) error {
// Returns a map of key to value for keys that exist and have not expired.
// Missing or expired keys are omitted from the result.
func KVStoreGetMany(keys []string) (map[string][]byte, error) {
// Marshal request to JSON
req := kVStoreDeleteRequest{
Key: key,
req := kVStoreGetManyRequest{
Keys: keys,
}
reqBytes, err := json.Marshal(req)
if err != nil {
return err
return nil, err
}
reqMem := pdk.AllocateBytes(reqBytes)
defer reqMem.Free()
// Call the host function
responsePtr := kvstore_delete(reqMem.Offset())
responsePtr := kvstore_getmany(reqMem.Offset())
// Read the response from memory
responseMem := pdk.FindMemory(responsePtr)
responseBytes := responseMem.ReadBytes()
// Parse error-only response
var response struct {
Error string `json:"error,omitempty"`
}
// Parse the response
var response kVStoreGetManyResponse
if err := json.Unmarshal(responseBytes, &response); err != nil {
return err
return nil, err
}
// Convert Error field to Go error
if response.Error != "" {
return errors.New(response.Error)
return nil, errors.New(response.Error)
}
return nil
return response.Values, nil
}
// KVStoreHas calls the kvstore_has host function.
@@ -286,6 +373,85 @@ func KVStoreList(prefix string) ([]string, error) {
return response.Keys, nil
}
// KVStoreDelete calls the kvstore_delete host function.
// Delete removes a value from storage.
//
// Parameters:
// - key: The storage key
//
// Returns an error if the operation fails. Does not return an error if the key doesn't exist.
func KVStoreDelete(key string) error {
// Marshal request to JSON
req := kVStoreDeleteRequest{
Key: key,
}
reqBytes, err := json.Marshal(req)
if err != nil {
return err
}
reqMem := pdk.AllocateBytes(reqBytes)
defer reqMem.Free()
// Call the host function
responsePtr := kvstore_delete(reqMem.Offset())
// Read the response from memory
responseMem := pdk.FindMemory(responsePtr)
responseBytes := responseMem.ReadBytes()
// Parse error-only response
var response struct {
Error string `json:"error,omitempty"`
}
if err := json.Unmarshal(responseBytes, &response); err != nil {
return err
}
if response.Error != "" {
return errors.New(response.Error)
}
return nil
}
// KVStoreDeleteByPrefix calls the kvstore_deletebyprefix host function.
// DeleteByPrefix removes all keys matching the given prefix.
//
// Parameters:
// - prefix: Key prefix to match (must not be empty)
//
// Returns the number of keys deleted. Includes expired keys.
func KVStoreDeleteByPrefix(prefix string) (int64, error) {
// Marshal request to JSON
req := kVStoreDeleteByPrefixRequest{
Prefix: prefix,
}
reqBytes, err := json.Marshal(req)
if err != nil {
return 0, err
}
reqMem := pdk.AllocateBytes(reqBytes)
defer reqMem.Free()
// Call the host function
responsePtr := kvstore_deletebyprefix(reqMem.Offset())
// Read the response from memory
responseMem := pdk.FindMemory(responsePtr)
responseBytes := responseMem.ReadBytes()
// Parse the response
var response kVStoreDeleteByPrefixResponse
if err := json.Unmarshal(responseBytes, &response); err != nil {
return 0, err
}
// Convert Error field to Go error
if response.Error != "" {
return 0, errors.New(response.Error)
}
return response.DeletedCount, nil
}
// KVStoreGetStorageUsed calls the kvstore_getstorageused host function.
// GetStorageUsed returns the total storage used by this plugin in bytes.
func KVStoreGetStorageUsed() (int64, error) {
plugins/pdk/go/host/nd_host_kvstore_stub.go
+67 -10
View File
@@ -37,6 +37,28 @@ func KVStoreSet(key string, value []byte) error {
return KVStoreMock.Set(key, value)
}
// SetWithTTL is the mock method for KVStoreSetWithTTL.
func (m *mockKVStoreService) SetWithTTL(key string, value []byte, ttlSeconds int64) error {
args := m.Called(key, value, ttlSeconds)
return args.Error(0)
}
// KVStoreSetWithTTL delegates to the mock instance.
// SetWithTTL stores a byte value with the given key and a time-to-live.
//
// After ttlSeconds, the key is treated as non-existent and will be
// cleaned up lazily. ttlSeconds must be greater than 0.
//
// Parameters:
// - key: The storage key (max 256 bytes, UTF-8)
// - value: The byte slice to store
// - ttlSeconds: Time-to-live in seconds (must be > 0)
//
// Returns an error if the storage limit would be exceeded or the operation fails.
func KVStoreSetWithTTL(key string, value []byte, ttlSeconds int64) error {
return KVStoreMock.SetWithTTL(key, value, ttlSeconds)
}
// Get is the mock method for KVStoreGet.
func (m *mockKVStoreService) Get(key string) ([]byte, bool, error) {
args := m.Called(key)
@@ -54,21 +76,22 @@ func KVStoreGet(key string) ([]byte, bool, error) {
return KVStoreMock.Get(key)
}
// Delete is the mock method for KVStoreDelete.
func (m *mockKVStoreService) Delete(key string) error {
args := m.Called(key)
return args.Error(0)
// GetMany is the mock method for KVStoreGetMany.
func (m *mockKVStoreService) GetMany(keys []string) (map[string][]byte, error) {
args := m.Called(keys)
return args.Get(0).(map[string][]byte), args.Error(1)
}
// KVStoreDelete delegates to the mock instance.
// Delete removes a value from storage.
// KVStoreGetMany delegates to the mock instance.
// GetMany retrieves multiple values in a single call.
//
// Parameters:
// - key: The storage key
// - keys: The storage keys to retrieve
//
// Returns an error if the operation fails. Does not return an error if the key doesn't exist.
func KVStoreDelete(key string) error {
return KVStoreMock.Delete(key)
// Returns a map of key to value for keys that exist and have not expired.
// Missing or expired keys are omitted from the result.
func KVStoreGetMany(keys []string) (map[string][]byte, error) {
return KVStoreMock.GetMany(keys)
}
// Has is the mock method for KVStoreHas.
@@ -105,6 +128,40 @@ func KVStoreList(prefix string) ([]string, error) {
return KVStoreMock.List(prefix)
}
// Delete is the mock method for KVStoreDelete.
func (m *mockKVStoreService) Delete(key string) error {
args := m.Called(key)
return args.Error(0)
}
// KVStoreDelete delegates to the mock instance.
// Delete removes a value from storage.
//
// Parameters:
// - key: The storage key
//
// Returns an error if the operation fails. Does not return an error if the key doesn't exist.
func KVStoreDelete(key string) error {
return KVStoreMock.Delete(key)
}
// DeleteByPrefix is the mock method for KVStoreDeleteByPrefix.
func (m *mockKVStoreService) DeleteByPrefix(prefix string) (int64, error) {
args := m.Called(prefix)
return args.Get(0).(int64), args.Error(1)
}
// KVStoreDeleteByPrefix delegates to the mock instance.
// DeleteByPrefix removes all keys matching the given prefix.
//
// Parameters:
// - prefix: Key prefix to match (must not be empty)
//
// Returns the number of keys deleted. Includes expired keys.
func KVStoreDeleteByPrefix(prefix string) (int64, error) {
return KVStoreMock.DeleteByPrefix(prefix)
}
// GetStorageUsed is the mock method for KVStoreGetStorageUsed.
func (m *mockKVStoreService) GetStorageUsed() (int64, error) {
args := m.Called()