mirror of
https://github.com/navidrome/navidrome.git
synced 2026-10-18 07:30:29 +00:00
97e1f73cc8
* docs: point jftui client link to canonical repository * docs: fix relative path to webhook-rs example in nd-pdk-host README * docs: fix capability schema paths in plugin examples README --------- Co-authored-by: Deluan Quintão <deluan@navidrome.org>
88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
make gen
|
|
```
|
|
|
|
## Usage
|
|
|
|
Add this crate as a dependency in your plugin's `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
nd-host = { path = "../../pdk/rust/host" }
|
|
```
|
|
|
|
Then import the services you need:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```bash
|
|
cargo build --target wasm32-wasip1 --release
|
|
```
|
|
|
|
See the [webhook-rs](../../../examples/webhook-rs/) example for a complete plugin implementation.
|