nik/navidrome
1
0
Fork 0
mirror of https://github.com/navidrome/navidrome.git synced 2026-08-31 07:30:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance README with Extism plugin development resources and recommendations

Browse Source 
Signed-off-by: Deluan <deluan@navidrome.org>
This commit is contained in:
Deluan 2025-12-29 09:57:03 -05:00
parent b970ef6b26
commit 628e0b58b7
2 changed files with 31 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
plugins/README.md
View File

@ -2,6 +2,16 @@
Navidrome supports WebAssembly (Wasm) plugins for extending functionality. Plugins run in a secure sandbox and can provide metadata agents, scrobblers, and other integrations through host services like scheduling, caching, WebSockets, and Subsonic API access. Navidrome supports WebAssembly (Wasm) plugins for extending functionality. Plugins run in a secure sandbox and can provide metadata agents, scrobblers, and other integrations through host services like scheduling, caching, WebSockets, and Subsonic API access.
The plugin system is built on **[Extism](https://extism.org/)**, a cross-language framework for building WebAssembly plugins. This means you can write plugins in any language that Extism supports (Go, Rust, Python, TypeScript, and more) using their Plugin Development Kits (PDKs).
**Essential Extism Resources:**
- [Extism Documentation](https://extism.org/docs/overview) – Core concepts and architecture
- [Plugin Development Kits (PDKs)](https://extism.org/docs/concepts/pdk) – Language-specific libraries for writing plugins
- [Go PDK](https://github.com/extism/go-pdk) – Recommended for Go plugins with TinyGo
- [Rust PDK](https://github.com/extism/rust-pdk) – For Rust plugins
- [Python PDK](https://github.com/extism/python-pdk) – Experimental Python support
- [JavaScript PDK](https://github.com/extism/js-pdk) – For TypeScript/JavaScript plugins
## Table of Contents ## Table of Contents
- [Quick Start](#quick-start) - [Quick Start](#quick-start)
@ -243,7 +253,7 @@ Host services let your plugin call back into Navidrome for advanced functionalit
### HTTP Requests ### HTTP Requests
Make HTTP requests using the [Extism PDK](https://extism.org/docs/concepts/pdk). Navidrome controls which hosts are accessible. Make HTTP requests using the Extism PDK's built-in HTTP support. See your [Extism PDK documentation](https://extism.org/docs/concepts/pdk) for more details on making requests.
**Manifest permission:** **Manifest permission:**
@ -672,12 +682,14 @@ if !ok {
### Supported Languages ### Supported Languages
Plugins can be written in any language that compiles to WebAssembly. We recommend: Plugins can be written in any language that Extism supports. Each language has its own PDK (Plugin Development Kit) that provides the APIs for I/O, logging, configuration, and HTTP requests. See the [Extism PDK documentation](https://extism.org/docs/concepts/pdk) for details.
- **Go** – Best experience with TinyGo We recommend:
- **Rust** – Excellent performance
- **Python** – Via extism-py (experimental) - **Go** – Best experience with [TinyGo](https://tinygo.org/) and the [Go PDK](https://github.com/extism/go-pdk)
- **TypeScript** – Via extism-js - **Rust** – Excellent performance with the [Rust PDK](https://github.com/extism/rust-pdk)
- **Python** – Experimental support via [extism-py](https://github.com/extism/python-pdk)
- **TypeScript** – Experimental support via [extism-js](https://github.com/extism/js-pdk)
### Go with TinyGo (Recommended) ### Go with TinyGo (Recommended)
@ -746,20 +758,22 @@ Generated SDKs for calling host services are in `plugins/host/go/` and `plugins/
See [examples/](examples/) for complete working plugins: See [examples/](examples/) for complete working plugins:
| Plugin | Language | Capabilities | Description | | Plugin | Language | Capabilities | Host Services | Description |
|----------------------------------------------------------|----------|------------------------------------------|--------------------------------| |----------------------------------------------------------|----------|-------------------------|---------------------------------------------|--------------------------------|
| [minimal](examples/minimal/) | Go | MetadataAgent | Basic structure example | | [minimal](examples/minimal/) | Go | MetadataAgent | – | Basic structure example |
| [wikimedia](examples/wikimedia/) | Go | MetadataAgent | Wikidata/Wikipedia integration | | [wikimedia](examples/wikimedia/) | Go | MetadataAgent | HTTP | Wikidata/Wikipedia integration |
| [discord-rich-presence](examples/discord-rich-presence/) | Go | Scrobbler, Scheduler, WebSocket | Discord integration | | [coverartarchive-py](examples/coverartarchive-py/) | Python | MetadataAgent | HTTP | Cover Art Archive |
| [coverartarchive-py](examples/coverartarchive-py/) | Python | MetadataAgent | Cover Art Archive | | [webhook-rs](examples/webhook-rs/) | Rust | Scrobbler | HTTP | HTTP webhooks |
| [webhook-rs](examples/webhook-rs/) | Rust | Scrobbler | HTTP webhooks | | [nowplaying-py](examples/nowplaying-py/) | Python | Lifecycle | Scheduler, SubsonicAPI | Periodic now-playing logger |
| [library-inspector](examples/library-inspector/) | Rust | Library, Scheduler | Periodic library stats logging | | [library-inspector](examples/library-inspector/) | Rust | Lifecycle | Library, Scheduler | Periodic library stats logging |
| [crypto-ticker](examples/crypto-ticker/) | Go | Lifecycle | WebSocket, Scheduler | Real-time crypto prices demo |
| [discord-rich-presence](examples/discord-rich-presence/) | Go | Scrobbler | HTTP, WebSocket, Cache, Scheduler, Artwork | Discord integration |
--- ---
## Security ## Security
Plugins run in a secure WebAssembly sandbox: Plugins run in a secure WebAssembly sandbox provided by [Extism](https://extism.org/) and the [Wazero](https://wazero.io/) runtime:
1. **Host Allowlisting** – Only explicitly allowed hosts are accessible via HTTP/WebSocket 1. **Host Allowlisting** – Only explicitly allowed hosts are accessible via HTTP/WebSocket
2. **Limited File System** – Plugins can only access library directories when explicitly granted the `library.filesystem` permission, and access is read-only 2. **Limited File System** – Plugins can only access library directories when explicitly granted the `library.filesystem` permission, and access is read-only
@ -768,6 +782,7 @@ Plugins run in a secure WebAssembly sandbox:
5. **Memory Limits** – Controlled by the WebAssembly runtime 5. **Memory Limits** – Controlled by the WebAssembly runtime
6. **SubsonicAPI Restrictions** – Configurable user/admin access controls 6. **SubsonicAPI Restrictions** – Configurable user/admin access controls
--- ---
## Runtime Management ## Runtime Management

2
plugins/examples/discord-rich-presence/README.md
View File

@ -22,7 +22,7 @@ It relies on several host services declared in the manifest:
## Architecture ## Architecture
Each call from Navidrome creates a new plugin instance. The plugin registers capabilities by exporting the required functions: The plugin registers capabilities by exporting the required functions:
```go ```go
// Scrobbler capability // Scrobbler capability