2471bb9cf6
* 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>
|
||
|---|---|---|
| .. | ||
| src | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| README.md | ||
Navidrome Host Function Wrappers for Rust
This directory contains auto-generated Rust wrappers for Navidrome's host services. These wrappers provide idiomatic Rust APIs for interacting with Navidrome from WASM plugins.
⚠️ Auto-Generated Code
Do not edit these files manually. They are generated by the ndpgen tool.
To regenerate:
make gen
Usage
Add this crate as a dependency in your plugin's Cargo.toml:
[dependencies]
nd-host = { path = "../../pdk/rust/host" }
Then import the services you need:
use nd_host::{cache, scheduler, library};
use nd_host::library::Library; // Import the typed struct
#[plugin_fn]
pub fn my_callback(input: String) -> FnResult<String> {
// Use the cache service
cache::set("my_key", b"my_value", 3600)?;
// Schedule a recurring task
scheduler::schedule_recurring("@every 5m", "payload", "task_id")?;
// Access library data with typed structs
let libraries: Vec<Library> = library::get_all_libraries()?;
for lib in &libraries {
info!("Library: {} with {} songs", lib.name, lib.total_songs);
}
Ok("done".to_string())
}
Typed Structs
Services that work with domain objects provide typed Rust structs instead of
serde_json::Value. This enables compile-time type checking and IDE
autocompletion.
For example, the library module provides a Library struct:
use nd_host::library::Library;
let libs: Vec<Library> = library::get_all_libraries()?;
println!("First library: {} ({} songs)", libs[0].name, libs[0].total_songs);
All structs derive Debug, Clone, Serialize, and Deserialize for
convenient use with logging and serialization.
Available Services
| Module | Description |
|---|---|
artwork |
Access album and artist artwork |
cache |
Temporary key-value storage with TTL |
kvstore |
Persistent key-value storage |
library |
Access the music library (albums, artists, tracks) |
scheduler |
Schedule one-time and recurring tasks |
subsonicapi |
Make Subsonic API calls |
websocket |
Send real-time messages to clients |
Building Plugins
Rust plugins must be compiled to WebAssembly:
cargo build --target wasm32-wasip1 --release
See the webhook-rs example for a complete plugin implementation.