feat(plugins): New Plugin System with multi-language PDK support (#4833)
* chore(plugins): remove the old plugins system implementation Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement new plugin system with using Extism Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add capability detection for plugins based on exported functions Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add auto-reload functionality for plugins with file watcher support Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add auto-reload functionality for plugins with file watcher support Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): standardize variable names and remove superfluous wrapper functions Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): improve error handling and logging in plugin manager Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): implement plugin function call helper and refactor MetadataAgent methods Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): race condition in plugin manager * tests(plugins): change BeforeEach to BeforeAll in MetadataAgent tests Signed-off-by: Deluan <deluan@navidrome.org> * tests(plugins): optimize tests Signed-off-by: Deluan <deluan@navidrome.org> * tests(plugins): more optimizations Signed-off-by: Deluan <deluan@navidrome.org> * test(plugins): ignore goroutine leaks from notify library in tests Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add Wikimedia plugin for Navidrome to fetch artist metadata Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): enhance plugin logging and set User-Agent header Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement scrobbler plugin with authorization and scrobbling capabilities Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): integrate logs Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): clean up manifest struct and improve plugin loading logic Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add metadata agent and scrobbler schemas for bootstrapping plugins Signed-off-by: Deluan <deluan@navidrome.org> * feat(hostgen): add hostgen tool for generating Extism host function wrappers - Implemented hostgen tool to generate wrappers from annotated Go interfaces. - Added command-line flags for input/output directories and package name. - Introduced parsing and code generation logic for host services. - Created test data for various service interfaces and expected generated code. - Added documentation for host services and annotations for code generation. - Implemented SubsonicAPI service with corresponding generated code. * feat(subsonicapi): update Call method to return JSON string response Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement SubsonicAPI host function integration with permissions Signed-off-by: Deluan <deluan@navidrome.org> * fix(generator): error-only methods in response handling Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): generate client wrappers for host functions Signed-off-by: Deluan <deluan@navidrome.org> * refactor(generator): remove error handling for response.Error in client templates Signed-off-by: Deluan <deluan@navidrome.org> * feat(scheduler): add Scheduler service interface with host function wrappers for scheduling tasks * feat(plugins): add WASI build constraints to client wrapper templates, to avoid lint errors Signed-off-by: Deluan <deluan@navidrome.org> * feat(scheduler): implement Scheduler service with one-time and recurring scheduling capabilities Signed-off-by: Deluan <deluan@navidrome.org> * refactor(manifest): remove unused ConfigPermission from permissions schema Signed-off-by: Deluan <deluan@navidrome.org> * feat(scheduler): add scheduler callback schema and implementation for plugins Signed-off-by: Deluan <deluan@navidrome.org> * refactor(scheduler): streamline scheduling logic and remove unused callback tracking Signed-off-by: Deluan <deluan@navidrome.org> * refactor(scheduler): add Close method for resource cleanup on plugin unload Signed-off-by: Deluan <deluan@navidrome.org> * docs(scheduler): clarify SchedulerCallback requirement for scheduling functions Signed-off-by: Deluan <deluan@navidrome.org> * fix: update wasm build rule to include all Go files in the directory Signed-off-by: Deluan <deluan@navidrome.org> * feat: rewrite the wikimedia plugin using the XTP CLI Signed-off-by: Deluan <deluan@navidrome.org> * refactor(scheduler): replace uuid with id.NewRandom for schedule ID generation Signed-off-by: Deluan <deluan@navidrome.org> * refactor: capabilities registration Signed-off-by: Deluan <deluan@navidrome.org> * test: add scheduler service isolation test for plugin instances Signed-off-by: Deluan <deluan@navidrome.org> * refactor: update plugin manager initialization and encapsulate logic Signed-off-by: Deluan <deluan@navidrome.org> * feat: add WebSocket service definitions for plugin communication Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement WebSocket service for plugin integration and connection management Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Crypto Ticker example plugin for real-time cryptocurrency price updates via Coinbase WebSocket API Also add the lifecycle capability Signed-off-by: Deluan <deluan@navidrome.org> * fix: use context.Background() in invokeCallback for scheduled tasks Signed-off-by: Deluan <deluan@navidrome.org> * refactor: rename plugin.create() to plugin.instance() Signed-off-by: Deluan <deluan@navidrome.org> * refactor: rename pluginInstance to plugin for consistency across the codebase Signed-off-by: Deluan <deluan@navidrome.org> * refactor: simplify schedule cloning in Close method and enhance plugin cleanup error handling Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement Artwork service for generating artwork URLs in Navidrome plugins - WIP Signed-off-by: Deluan <deluan@navidrome.org> * refactor: moved public URL builders to avoid import cycles Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Cache service for in-memory TTL-based caching in plugins Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Discord Rich Presence example plugin for Navidrome integration Signed-off-by: Deluan <deluan@navidrome.org> * refactor: host function wrappers to use structured request and response types - Updated the host function signatures in `nd_host_artwork.go`, `nd_host_scheduler.go`, `nd_host_subsonicapi.go`, and `nd_host_websocket.go` to accept a single parameter for JSON requests. - Introduced structured request and response types for various cache operations in `nd_host_cache.go`. - Modified cache functions to marshal requests to JSON and unmarshal responses, improving error handling and code clarity. - Removed redundant memory allocation for string parameters in favor of JSON marshaling. - Enhanced error handling in WebSocket and cache operations to return structured error responses. * refactor: error handling in various plugins to convert response.Error to Go errors - Updated error handling in `nd_host_scheduler.go`, `nd_host_websocket.go`, `nd_host_artwork.go`, `nd_host_cache.go`, and `nd_host_subsonicapi.go` to convert string errors from responses into Go errors. - Removed redundant error checks in test data plugins for cleaner code. - Ensured consistent error handling across all plugins to improve reliability and maintainability. * refactor: rename fake plugins to test plugins for clarity in integration tests Signed-off-by: Deluan <deluan@navidrome.org> * feat: add help target to Makefile for plugin usage instructions Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Cover Art Archive plugin as an example of Python plugin Signed-off-by: Deluan <deluan@navidrome.org> * feat: update Makefile and README to clarify Go plugin usage Signed-off-by: Deluan <deluan@navidrome.org> * feat: include plugin capabilities in loading log message Signed-off-by: Deluan <deluan@navidrome.org> * feat: add trace logging for plugin availability and error handling in agents Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Now Playing Logger plugin to showcase calling host functions from Python plugins Signed-off-by: Deluan <deluan@navidrome.org> * feat: generate Python client wrappers for various host services Signed-off-by: Deluan <deluan@navidrome.org> * feat: add generated host function wrappers for Scheduler and SubsonicAPI services Signed-off-by: Deluan <deluan@navidrome.org> * feat: update Python plugin documentation and usage instructions for host function wrappers Signed-off-by: Deluan <deluan@navidrome.org> * feat: add Webhook Scrobbler plugin in Rust to send HTTP notifications on scrobble events Signed-off-by: Deluan <deluan@navidrome.org> * feat: enable parallel loading of plugins during startup Signed-off-by: Deluan <deluan@navidrome.org> * docs: update README to include WebSocket callback schema in plugin documentation Signed-off-by: Deluan <deluan@navidrome.org> * feat: extend plugin watcher with improved logging and debounce duration adjustment Signed-off-by: Deluan <deluan@navidrome.org> * add trace message for plugin recompiles Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement plugin cache purging functionality Signed-off-by: Deluan <deluan@navidrome.org> * test: move purgeCacheBySize unit tests Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): add plugin repository and database support Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): add plugin management routes and middleware Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): implement plugin synchronization with database for add, update, and remove actions Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): add PluginList and PluginShow components with plugin management functionality Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): optimize plugin change detection Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins UI): improve PluginList structure Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): enhance PluginShow with author, website, and permissions display Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): refactor to use MUI and RA components Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins UI): add error handling for plugin enable/disable actions Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): inject PluginManager into native API Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update GetManager to accept DataStore parameter Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add subsonicRouter to Manager and refactor host service registration Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): enhance debug logging for plugin actions and recompile logic Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): break manager.go into smaller, focused files Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): streamline error handling and improve plugin retrieval logic Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update newWebSocketService to use WebSocketPermission for allowed hosts Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): introduce ToggleEnabledSwitch for managing plugin enable/disable state Signed-off-by: Deluan <deluan@navidrome.org> * docs: update READMEs Signed-off-by: Deluan <deluan@navidrome.org> * feat(library): add Library service for metadata access and filesystem integration Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add Library Inspector plugin for periodic library inspection and file size logging Signed-off-by: Deluan <deluan@navidrome.org> * docs: update README to reflect JSON configuration format for plugins Signed-off-by: Deluan <deluan@navidrome.org> * fix(build): update target to wasm32-wasip1 for improved WASI support Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement configuration management UI with key-value pairs support Signed-off-by: Deluan <deluan@navidrome.org> * feat(ui): adjust grid layout in InfoRow component for improved responsiveness Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): rename ErrorIndicator to EnabledOrErrorField and enhance error handling logic Signed-off-by: Deluan <deluan@navidrome.org> * feat(i18n): add Portuguese translations for plugin management and notifications Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add support for .ndp plugin packages and update build process Signed-off-by: Deluan <deluan@navidrome.org> * docs: update README for .ndp plugin packaging and installation instructions Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement KVStore service for persistent key-value storage Signed-off-by: Deluan <deluan@navidrome.org> * docs: enhance README with Extism plugin development resources and recommendations Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): integrate event broker into plugin manager Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): update config handling in PluginShow to track last record state Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add Rust host function library and example implementation of Discord Rich Presence plugin in Rust Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): generate Rust lib.rs file to expose host function wrappers Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update JSON field names to camelCase for consistency Signed-off-by: Deluan <deluan@navidrome.org> * refactor: reduce cyclomatic complexity by refactoring main function Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): enhance Rust code generation with typed struct support and improved type handling Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add Go client library with host function wrappers and documentation Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): generate Go client stubs for non-WASM platforms Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): update client template file names for consistency Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add initial implementation of the Navidrome Plugin Development Kit code generator - Pahse 1 Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implementation of the Navidrome Plugin Development Kit with generated client wrappers and service interfaces - Phase 2 Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implementation of the Navidrome Plugin Development Kit with generated client wrappers and service interfaces - Phase 2 (2) Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implementation of the Navidrome Plugin Development Kit with generated client wrappers and service interfaces - Phase 3 Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implementation of the Navidrome Plugin Development Kit with generated client wrappers and service interfaces - Phase 4 Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implementation of the Navidrome Plugin Development Kit with generated client wrappers and service interfaces - Phase 5 Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): consistent naming/types across PDK Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): streamline plugin function signatures and error handling Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update scrobbler interface to return errors directly instead of response structs Signed-off-by: Deluan <deluan@navidrome.org> * test: make all test plugins use the PDK Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): reorganize and sort type definitions for consistency Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update error handling for methods to return errors directly Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update function signatures to return values directly instead of response structs Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update request/response types to use private naming conventions Signed-off-by: Deluan <deluan@navidrome.org> * build: mark .wasm files as intermediate for cleanup after building .ndp Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): consolidate PDK module path and update Go version to 1.25 Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement Rust PDK Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): reorganize Rust output structure to follow standard conventions Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update Discord Rich Presence and Library Inspector plugins to use nd-pdk for service calls and implement lifecycle management Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update macro names for websocket and metadata registration to improve clarity and consistency Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): rename scheduler callback methods for consistency and clarity Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update export wrappers to use `//go:wasmexport` for WebAssembly compatibility Signed-off-by: Deluan <deluan@navidrome.org> * docs: update plugin registration docs Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): generate host wrappers Signed-off-by: Deluan <deluan@navidrome.org> * test(plugins): conditionally run goleak checks based on CI environment Signed-off-by: Deluan <deluan@navidrome.org> * docs: update README to reflect changes in plugin import paths Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): update plugin instance creation to accept context for cancellation support Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): update return types in metadata interfaces to use pointers Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): enhance type handling for Rust and XTP output in capability generation Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): update IsAuthorized method to return boolean instead of response object Signed-off-by: Deluan <deluan@navidrome.org> * test(plugins): add unit tests for rustOutputType and isPrimitiveRustType functions Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): implement XTP JSONSchema validation for generated schemas Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): update response types in testMetadataAgent methods to use pointers Signed-off-by: Deluan <deluan@navidrome.org> * docs: update Go and Rust plugin developer sections for clarity Signed-off-by: Deluan <deluan@navidrome.org> * docs: correct example link for library inspector in README Signed-off-by: Deluan <deluan@navidrome.org> * docs: clarify artwork URL generation capabilities in service descriptions Signed-off-by: Deluan <deluan@navidrome.org> * docs: update README to include Rust PDK crate information for plugin developers Signed-off-by: Deluan <deluan@navidrome.org> * fix: handle URL parsing errors and use atomic upsert in plugin repository Added proper error handling for url.Parse calls in PublicURL and AbsoluteURL functions. When parsing fails, PublicURL now falls back to AbsoluteURL, and AbsoluteURL logs the error and returns an empty string, preventing malformed URLs from being generated. Replaced the non-atomic UPDATE-then-INSERT pattern in plugin repository Put method with a single atomic INSERT ... ON CONFLICT statement. This eliminates potential race conditions and improves consistency with the upsert pattern already used in host_kvstore.go. * feat: implement mock service instances for non-WASM builds using testify/mock Signed-off-by: Deluan <deluan@navidrome.org> * refactor: Discord RPC struct to encapsulate WebSocket logic Signed-off-by: Deluan <deluan@navidrome.org> * feat: add support for experimental WebAssembly threads Signed-off-by: Deluan <deluan@navidrome.org> * feat: add PDK abstraction layer with mock support for non-WASM builds Signed-off-by: Deluan <deluan@navidrome.org> * feat: add unit tests for Discord plugin and RPC functionality Signed-off-by: Deluan <deluan@navidrome.org> * fix: update return types in minimalPlugin and wikimediaPlugin methods to use pointers Signed-off-by: Deluan <deluan@navidrome.org> * fix: context cancellation and implement WebSocket callback timeout for improved error handling Signed-off-by: Deluan <deluan@navidrome.org> * feat: conditionally include error handling in generated client code templates Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement ConfigService for plugin configuration management Signed-off-by: Deluan <deluan@navidrome.org> * feat: enhance plugin manager to support metrics recording Signed-off-by: Deluan <deluan@navidrome.org> * refactor: make MockPDK private Signed-off-by: Deluan <deluan@navidrome.org> * refactor: update interface types to use 'any' in plugin repository methods Signed-off-by: Deluan <deluan@navidrome.org> * refactor: rename List method to Keys for clarity in configuration management Signed-off-by: Deluan <deluan@navidrome.org> * test: add ndpgen plugin tests in the pipeline and update Makefile Signed-off-by: Deluan <deluan@navidrome.org> * feat: add users permission management to plugin system Signed-off-by: Deluan <deluan@navidrome.org> * refactor: streamline users integration tests and enhance plugin user management Signed-off-by: Deluan <deluan@navidrome.org> * refactor: remove UserID from scrobbler request structure Signed-off-by: Deluan <deluan@navidrome.org> * test: add integration tests for UsersService enable gate behavior Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement user permissions for SubsonicAPI and scrobbler plugins Signed-off-by: Deluan <deluan@navidrome.org> * fix: show proper error in the UI when enabling a plugin fails Signed-off-by: Deluan <deluan@navidrome.org> * feat: add library permission management to plugin system Signed-off-by: Deluan <deluan@navidrome.org> * feat: add user permission for processing scrobbles in Discord Rich Presence plugin Signed-off-by: Deluan <deluan@navidrome.org> * fix: implement dynamic loading for buffered scrobbler plugins Signed-off-by: Deluan <deluan@navidrome.org> * feat: add GetAdmins method to retrieve admin users from the plugin Signed-off-by: Deluan <deluan@navidrome.org> * feat: update Portuguese translations for user and library permissions Signed-off-by: Deluan <deluan@navidrome.org> * reorder migrations Signed-off-by: Deluan <deluan@navidrome.org> * fix: remove unnecessary bulkActionButtons prop from PluginList component * feat: add manual plugin rescan functionality and corresponding UI action Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement user/library and plugin management integration with cleanup on deletion Signed-off-by: Deluan <deluan@navidrome.org> * feat: replace core mock services with test-specific implementations to avoid import cycles * feat: add ID fields to Artist and Song structs and enhance track loading logic by prioritizing ID matches Signed-off-by: Deluan <deluan@navidrome.org> * feat: update plugin permissions from allowedHosts to requiredHosts for better clarity and consistency * feat: refactor plugin host permissions to use RequiredHosts directly for improved clarity * fix: don't record metrics for plugin calls that aren't implemented at all Signed-off-by: Deluan <deluan@navidrome.org> * fix: enhance connection management with improved error handling and cleanup logic Signed-off-by: Deluan <deluan@navidrome.org> * feat: introduce ArtistRef struct for better artist representation and update track metadata handling Signed-off-by: Deluan <deluan@navidrome.org> * feat: update user configuration handling to use user key prefix for improved clarity Signed-off-by: Deluan <deluan@navidrome.org> * feat: enhance ConfigCard input fields with multiline support and vertical resizing Signed-off-by: Deluan <deluan@navidrome.org> * fix: rust plugin compilation error Signed-off-by: Deluan <deluan@navidrome.org> * feat: implement IsOptionPattern method for better return type handling in Rust PDK generation Signed-off-by: Deluan <deluan@navidrome.org> --------- Signed-off-by: Deluan <deluan@navidrome.org>
This commit is contained in:
Deluan Quintão
@@ -0,0 +1,87 @@
|
||||
# Navidrome Plugin Capabilities
|
||||
|
||||
This directory contains the Go interface definitions for Navidrome plugin capabilities. These interfaces are the **source of truth** for plugin development and are used to generate:
|
||||
|
||||
1. **Go PDK packages** (`pdk/go/*/`) - Type-safe wrappers for Go plugin developers
|
||||
2. **Rust PDK crates** (`pdk/rust/*/`) - Type-safe wrappers for Rust plugin developers
|
||||
3. **XTP YAML schemas** (`*.yaml`) - Schema files for other [Extism plugin languages](https://extism.org/docs/concepts/pdk/) (TypeScript, Python, C#, Zig, C++, ...)
|
||||
|
||||
## For Go Plugin Developers
|
||||
|
||||
Go developers should use the generated PDK packages in `plugins/pdk/go/`. See the example Go plugins in `plugins/examples/` for usage patterns.
|
||||
|
||||
## For Rust Plugin Developers
|
||||
|
||||
Rust developers should use the generated PDK crate in `plugins/pdk/rust/nd-pdk`. See the example Rust plugins in `plugins/examples` for usage patterns.
|
||||
|
||||
## For Non-Go Plugin Developers
|
||||
|
||||
If you're developing plugins in other languages (TypeScript, Rust, Python, C#, Zig, C++), you can use the XTP CLI to generate type-safe bindings from the YAML schema files in this directory.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Install the XTP CLI:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install dylibso/tap/xtp
|
||||
|
||||
# Other platforms - see https://docs.xtp.dylibso.com/docs/cli
|
||||
curl https://static.dylibso.com/cli/install.sh | bash
|
||||
```
|
||||
|
||||
### Generating Plugin Scaffolding
|
||||
|
||||
Use the XTP CLI to generate plugin boilerplate from any capability schema:
|
||||
|
||||
```bash
|
||||
# TypeScript
|
||||
xtp plugin init --schema-file plugins/capabilities/metadata_agent.yaml \
|
||||
--template typescript --path my-plugin
|
||||
|
||||
# Rust
|
||||
xtp plugin init --schema-file plugins/capabilities/scrobbler.yaml \
|
||||
--template rust --path my-plugin
|
||||
|
||||
# Python
|
||||
xtp plugin init --schema-file plugins/capabilities/lifecycle.yaml \
|
||||
--template python --path my-plugin
|
||||
|
||||
# C#
|
||||
xtp plugin init --schema-file plugins/capabilities/scheduler_callback.yaml \
|
||||
--template csharp --path my-plugin
|
||||
|
||||
# Go (alternative to using the PDK packages)
|
||||
xtp plugin init --schema-file plugins/capabilities/websocket_callback.yaml \
|
||||
--template go --path my-plugin
|
||||
```
|
||||
|
||||
### Available Capabilities
|
||||
|
||||
| Capability | Schema File | Description |
|
||||
|--------------------|---------------------------|-------------------------------------------------------------|
|
||||
| Metadata Agent | `metadata_agent.yaml` | Fetch artist biographies, album images, and similar artists |
|
||||
| Scrobbler | `scrobbler.yaml` | Report listening activity to external services |
|
||||
| Lifecycle | `lifecycle.yaml` | Plugin initialization callbacks |
|
||||
| Scheduler Callback | `scheduler_callback.yaml` | Scheduled task execution |
|
||||
| WebSocket Callback | `websocket_callback.yaml` | Real-time WebSocket message handling |
|
||||
|
||||
### Building Your Plugin
|
||||
|
||||
After generating the scaffolding, implement the required functions and build your plugin as a WebAssembly module. The exact build process depends on your chosen language - see the [Extism PDK documentation](https://extism.org/docs/concepts/pdk) for language-specific guides.
|
||||
|
||||
## XTP Schema Generation
|
||||
|
||||
The YAML schemas in this package are automatically generated from the capability Go interfaces using `ndpgen`.
|
||||
To regenerate the schemas after modifying the interfaces, run:
|
||||
|
||||
```bash
|
||||
cd plugins/cmd/ndpgen && go run . -schemas -input=./plugins/capabilities
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [XTP Documentation](https://docs.xtp.dylibso.com/)
|
||||
- [XTP Bindgen Repository](https://github.com/dylibso/xtp-bindgen)
|
||||
- [Extism Plugin Development Kit](https://extism.org/docs/concepts/pdk)
|
||||
- [XTP Schema Definition](https://raw.githubusercontent.com/dylibso/xtp-bindgen/5090518dd86ba5e734dc225a33066ecc0ed2e12d/plugin/schema.json)
|
||||
@@ -0,0 +1,56 @@
|
||||
// Package capabilities defines Go interfaces for Navidrome plugin capabilities.
|
||||
//
|
||||
// These interfaces serve as the source of truth for capability definitions.
|
||||
// The ndpgen tool generates:
|
||||
// - Go export wrappers in plugins/pdk/go/<capability>/ for Go plugins
|
||||
// - XTP YAML schemas for non-Go plugins (Rust, TypeScript, etc.)
|
||||
//
|
||||
// Each capability is defined as an annotated interface:
|
||||
//
|
||||
// //nd:capability name=metadata
|
||||
// type MetadataAgent interface {
|
||||
// //nd:export name=nd_get_artist_biography
|
||||
// GetArtistBiography(ArtistRequest) (*ArtistBiographyResponse, error)
|
||||
// }
|
||||
//
|
||||
// Annotation Reference:
|
||||
//
|
||||
// //nd:capability name=<pkg> [required=true]
|
||||
// - Marks an interface as a capability
|
||||
// - name: Generated package name (e.g., name=metadata → pdk/go/metadata/)
|
||||
// - required: If true, all methods must be implemented (default: false)
|
||||
//
|
||||
// //nd:export name=<func>
|
||||
// - Marks a method as an exported WASM function
|
||||
// - name: The export name (e.g., nd_get_artist_biography)
|
||||
//
|
||||
// Generated Code Structure:
|
||||
//
|
||||
// For a capability like MetadataAgent with required=false:
|
||||
//
|
||||
// package metadata
|
||||
//
|
||||
// // Agent is the marker interface
|
||||
// type Agent interface{}
|
||||
//
|
||||
// // Optional provider interfaces
|
||||
// type ArtistBiographyProvider interface {
|
||||
// GetArtistBiography(ArtistRequest) (*ArtistBiographyResponse, error)
|
||||
// }
|
||||
//
|
||||
// // Registration function
|
||||
// func Register(impl Agent) { ... }
|
||||
//
|
||||
// For a capability with required=true:
|
||||
//
|
||||
// package scrobbler
|
||||
//
|
||||
// // Scrobbler requires all methods
|
||||
// type Scrobbler interface {
|
||||
// IsAuthorized(IsAuthorizedRequest) (bool, error)
|
||||
// NowPlaying(NowPlayingRequest) error
|
||||
// Scrobble(ScrobbleRequest) error
|
||||
// }
|
||||
//
|
||||
// func Register(impl Scrobbler) { ... }
|
||||
package capabilities
|
||||
@@ -0,0 +1,19 @@
|
||||
package capabilities
|
||||
|
||||
// Lifecycle provides plugin lifecycle hooks.
|
||||
// This capability allows plugins to perform initialization when loaded,
|
||||
// such as establishing connections, starting background processes, or
|
||||
// validating configuration.
|
||||
//
|
||||
// The OnInit function is called once when the plugin is loaded, and is NOT
|
||||
// called when the plugin is hot-reloaded. Plugins should not assume this
|
||||
// function will be called on every startup.
|
||||
//
|
||||
//nd:capability name=lifecycle
|
||||
type Lifecycle interface {
|
||||
// OnInit is called after a plugin is fully loaded with all services registered.
|
||||
// Plugins can use this function to perform one-time initialization tasks.
|
||||
// Errors are logged but will not prevent the plugin from being loaded.
|
||||
//nd:export name=nd_on_init
|
||||
OnInit() error
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
version: v1-draft
|
||||
exports:
|
||||
nd_on_init:
|
||||
description: |-
|
||||
OnInit is called after a plugin is fully loaded with all services registered.
|
||||
Plugins can use this function to perform one-time initialization tasks.
|
||||
Errors are logged but will not prevent the plugin from being loaded.
|
||||
@@ -0,0 +1,167 @@
|
||||
package capabilities
|
||||
|
||||
// MetadataAgent provides artist and album metadata retrieval.
|
||||
// This capability allows plugins to provide external metadata for artists and albums,
|
||||
// such as biographies, images, similar artists, and top songs.
|
||||
//
|
||||
// Plugins implementing this capability can choose which methods to implement.
|
||||
// Each method is optional - plugins only need to provide the functionality they support.
|
||||
//
|
||||
//nd:capability name=metadata
|
||||
type MetadataAgent interface {
|
||||
// GetArtistMBID retrieves the MusicBrainz ID for an artist.
|
||||
//nd:export name=nd_get_artist_mbid
|
||||
GetArtistMBID(ArtistMBIDRequest) (*ArtistMBIDResponse, error)
|
||||
|
||||
// GetArtistURL retrieves the external URL for an artist.
|
||||
//nd:export name=nd_get_artist_url
|
||||
GetArtistURL(ArtistRequest) (*ArtistURLResponse, error)
|
||||
|
||||
// GetArtistBiography retrieves the biography for an artist.
|
||||
//nd:export name=nd_get_artist_biography
|
||||
GetArtistBiography(ArtistRequest) (*ArtistBiographyResponse, error)
|
||||
|
||||
// GetSimilarArtists retrieves similar artists for a given artist.
|
||||
//nd:export name=nd_get_similar_artists
|
||||
GetSimilarArtists(SimilarArtistsRequest) (*SimilarArtistsResponse, error)
|
||||
|
||||
// GetArtistImages retrieves images for an artist.
|
||||
//nd:export name=nd_get_artist_images
|
||||
GetArtistImages(ArtistRequest) (*ArtistImagesResponse, error)
|
||||
|
||||
// GetArtistTopSongs retrieves top songs for an artist.
|
||||
//nd:export name=nd_get_artist_top_songs
|
||||
GetArtistTopSongs(TopSongsRequest) (*TopSongsResponse, error)
|
||||
|
||||
// GetAlbumInfo retrieves album information.
|
||||
//nd:export name=nd_get_album_info
|
||||
GetAlbumInfo(AlbumRequest) (*AlbumInfoResponse, error)
|
||||
|
||||
// GetAlbumImages retrieves images for an album.
|
||||
//nd:export name=nd_get_album_images
|
||||
GetAlbumImages(AlbumRequest) (*AlbumImagesResponse, error)
|
||||
}
|
||||
|
||||
// ArtistMBIDRequest is the request for GetArtistMBID.
|
||||
type ArtistMBIDRequest struct {
|
||||
// ID is the internal Navidrome artist ID.
|
||||
ID string `json:"id"`
|
||||
// Name is the artist name.
|
||||
Name string `json:"name"`
|
||||
}
|
||||
|
||||
// ArtistMBIDResponse is the response for GetArtistMBID.
|
||||
type ArtistMBIDResponse struct {
|
||||
// MBID is the MusicBrainz ID for the artist.
|
||||
MBID string `json:"mbid"`
|
||||
}
|
||||
|
||||
// ArtistRequest is the common request for artist-related functions.
|
||||
type ArtistRequest struct {
|
||||
// ID is the internal Navidrome artist ID.
|
||||
ID string `json:"id"`
|
||||
// Name is the artist name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the artist (if known).
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
}
|
||||
|
||||
// ArtistURLResponse is the response for GetArtistURL.
|
||||
type ArtistURLResponse struct {
|
||||
// URL is the external URL for the artist.
|
||||
URL string `json:"url"`
|
||||
}
|
||||
|
||||
// ArtistBiographyResponse is the response for GetArtistBiography.
|
||||
type ArtistBiographyResponse struct {
|
||||
// Biography is the artist biography text.
|
||||
Biography string `json:"biography"`
|
||||
}
|
||||
|
||||
// SimilarArtistsRequest is the request for GetSimilarArtists.
|
||||
type SimilarArtistsRequest struct {
|
||||
// ID is the internal Navidrome artist ID.
|
||||
ID string `json:"id"`
|
||||
// Name is the artist name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the artist (if known).
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
// Limit is the maximum number of similar artists to return.
|
||||
Limit int32 `json:"limit"`
|
||||
}
|
||||
|
||||
// SimilarArtistsResponse is the response for GetSimilarArtists.
|
||||
type SimilarArtistsResponse struct {
|
||||
// Artists is the list of similar artists.
|
||||
Artists []ArtistRef `json:"artists"`
|
||||
}
|
||||
|
||||
// ImageInfo represents an image with URL and size.
|
||||
type ImageInfo struct {
|
||||
// URL is the URL of the image.
|
||||
URL string `json:"url"`
|
||||
// Size is the size of the image in pixels (width or height).
|
||||
Size int32 `json:"size"`
|
||||
}
|
||||
|
||||
// ArtistImagesResponse is the response for GetArtistImages.
|
||||
type ArtistImagesResponse struct {
|
||||
// Images is the list of artist images.
|
||||
Images []ImageInfo `json:"images"`
|
||||
}
|
||||
|
||||
// TopSongsRequest is the request for GetArtistTopSongs.
|
||||
type TopSongsRequest struct {
|
||||
// ID is the internal Navidrome artist ID.
|
||||
ID string `json:"id"`
|
||||
// Name is the artist name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the artist (if known).
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
// Count is the maximum number of top songs to return.
|
||||
Count int32 `json:"count"`
|
||||
}
|
||||
|
||||
// SongRef is a reference to a song with name and optional MBID.
|
||||
type SongRef struct {
|
||||
// ID is the internal Navidrome mediafile ID (if known).
|
||||
ID string `json:"id,omitempty"`
|
||||
// Name is the song name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the song.
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
}
|
||||
|
||||
// TopSongsResponse is the response for GetArtistTopSongs.
|
||||
type TopSongsResponse struct {
|
||||
// Songs is the list of top songs.
|
||||
Songs []SongRef `json:"songs"`
|
||||
}
|
||||
|
||||
// AlbumRequest is the common request for album-related functions.
|
||||
type AlbumRequest struct {
|
||||
// Name is the album name.
|
||||
Name string `json:"name"`
|
||||
// Artist is the album artist name.
|
||||
Artist string `json:"artist"`
|
||||
// MBID is the MusicBrainz ID for the album (if known).
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
}
|
||||
|
||||
// AlbumInfoResponse is the response for GetAlbumInfo.
|
||||
type AlbumInfoResponse struct {
|
||||
// Name is the album name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the album.
|
||||
MBID string `json:"mbid"`
|
||||
// Description is the album description/notes.
|
||||
Description string `json:"description"`
|
||||
// URL is the external URL for the album.
|
||||
URL string `json:"url"`
|
||||
}
|
||||
|
||||
// AlbumImagesResponse is the response for GetAlbumImages.
|
||||
type AlbumImagesResponse struct {
|
||||
// Images is the list of album images.
|
||||
Images []ImageInfo `json:"images"`
|
||||
}
|
||||
@@ -0,0 +1,275 @@
|
||||
version: v1-draft
|
||||
exports:
|
||||
nd_get_artist_mbid:
|
||||
description: GetArtistMBID retrieves the MusicBrainz ID for an artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/ArtistMBIDRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/ArtistMBIDResponse'
|
||||
contentType: application/json
|
||||
nd_get_artist_url:
|
||||
description: GetArtistURL retrieves the external URL for an artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/ArtistRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/ArtistURLResponse'
|
||||
contentType: application/json
|
||||
nd_get_artist_biography:
|
||||
description: GetArtistBiography retrieves the biography for an artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/ArtistRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/ArtistBiographyResponse'
|
||||
contentType: application/json
|
||||
nd_get_similar_artists:
|
||||
description: GetSimilarArtists retrieves similar artists for a given artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/SimilarArtistsRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/SimilarArtistsResponse'
|
||||
contentType: application/json
|
||||
nd_get_artist_images:
|
||||
description: GetArtistImages retrieves images for an artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/ArtistRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/ArtistImagesResponse'
|
||||
contentType: application/json
|
||||
nd_get_artist_top_songs:
|
||||
description: GetArtistTopSongs retrieves top songs for an artist.
|
||||
input:
|
||||
$ref: '#/components/schemas/TopSongsRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/TopSongsResponse'
|
||||
contentType: application/json
|
||||
nd_get_album_info:
|
||||
description: GetAlbumInfo retrieves album information.
|
||||
input:
|
||||
$ref: '#/components/schemas/AlbumRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/AlbumInfoResponse'
|
||||
contentType: application/json
|
||||
nd_get_album_images:
|
||||
description: GetAlbumImages retrieves images for an album.
|
||||
input:
|
||||
$ref: '#/components/schemas/AlbumRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
$ref: '#/components/schemas/AlbumImagesResponse'
|
||||
contentType: application/json
|
||||
components:
|
||||
schemas:
|
||||
AlbumImagesResponse:
|
||||
description: AlbumImagesResponse is the response for GetAlbumImages.
|
||||
properties:
|
||||
images:
|
||||
type: array
|
||||
description: Images is the list of album images.
|
||||
items:
|
||||
$ref: '#/components/schemas/ImageInfo'
|
||||
required:
|
||||
- images
|
||||
AlbumInfoResponse:
|
||||
description: AlbumInfoResponse is the response for GetAlbumInfo.
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Name is the album name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the album.
|
||||
description:
|
||||
type: string
|
||||
description: Description is the album description/notes.
|
||||
url:
|
||||
type: string
|
||||
description: URL is the external URL for the album.
|
||||
required:
|
||||
- name
|
||||
- mbid
|
||||
- description
|
||||
- url
|
||||
AlbumRequest:
|
||||
description: AlbumRequest is the common request for album-related functions.
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Name is the album name.
|
||||
artist:
|
||||
type: string
|
||||
description: Artist is the album artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the album (if known).
|
||||
required:
|
||||
- name
|
||||
- artist
|
||||
ArtistBiographyResponse:
|
||||
description: ArtistBiographyResponse is the response for GetArtistBiography.
|
||||
properties:
|
||||
biography:
|
||||
type: string
|
||||
description: Biography is the artist biography text.
|
||||
required:
|
||||
- biography
|
||||
ArtistImagesResponse:
|
||||
description: ArtistImagesResponse is the response for GetArtistImages.
|
||||
properties:
|
||||
images:
|
||||
type: array
|
||||
description: Images is the list of artist images.
|
||||
items:
|
||||
$ref: '#/components/schemas/ImageInfo'
|
||||
required:
|
||||
- images
|
||||
ArtistMBIDRequest:
|
||||
description: ArtistMBIDRequest is the request for GetArtistMBID.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID.
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
ArtistMBIDResponse:
|
||||
description: ArtistMBIDResponse is the response for GetArtistMBID.
|
||||
properties:
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist.
|
||||
required:
|
||||
- mbid
|
||||
ArtistRef:
|
||||
description: ArtistRef is a reference to an artist with name and optional MBID.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID (if known).
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist.
|
||||
required:
|
||||
- name
|
||||
ArtistRequest:
|
||||
description: ArtistRequest is the common request for artist-related functions.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID.
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist (if known).
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
ArtistURLResponse:
|
||||
description: ArtistURLResponse is the response for GetArtistURL.
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
description: URL is the external URL for the artist.
|
||||
required:
|
||||
- url
|
||||
ImageInfo:
|
||||
description: ImageInfo represents an image with URL and size.
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
description: URL is the URL of the image.
|
||||
size:
|
||||
type: integer
|
||||
format: int32
|
||||
description: Size is the size of the image in pixels (width or height).
|
||||
required:
|
||||
- url
|
||||
- size
|
||||
SimilarArtistsRequest:
|
||||
description: SimilarArtistsRequest is the request for GetSimilarArtists.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID.
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist (if known).
|
||||
limit:
|
||||
type: integer
|
||||
format: int32
|
||||
description: Limit is the maximum number of similar artists to return.
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
- limit
|
||||
SimilarArtistsResponse:
|
||||
description: SimilarArtistsResponse is the response for GetSimilarArtists.
|
||||
properties:
|
||||
artists:
|
||||
type: array
|
||||
description: Artists is the list of similar artists.
|
||||
items:
|
||||
$ref: '#/components/schemas/ArtistRef'
|
||||
required:
|
||||
- artists
|
||||
SongRef:
|
||||
description: SongRef is a reference to a song with name and optional MBID.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome mediafile ID (if known).
|
||||
name:
|
||||
type: string
|
||||
description: Name is the song name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the song.
|
||||
required:
|
||||
- name
|
||||
TopSongsRequest:
|
||||
description: TopSongsRequest is the request for GetArtistTopSongs.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID.
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist (if known).
|
||||
count:
|
||||
type: integer
|
||||
format: int32
|
||||
description: Count is the maximum number of top songs to return.
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
- count
|
||||
TopSongsResponse:
|
||||
description: TopSongsResponse is the response for GetArtistTopSongs.
|
||||
properties:
|
||||
songs:
|
||||
type: array
|
||||
description: Songs is the list of top songs.
|
||||
items:
|
||||
$ref: '#/components/schemas/SongRef'
|
||||
required:
|
||||
- songs
|
||||
@@ -0,0 +1,27 @@
|
||||
package capabilities
|
||||
|
||||
// SchedulerCallback provides scheduled task handling.
|
||||
// This capability allows plugins to receive callbacks when their scheduled tasks execute.
|
||||
// Plugins that use the scheduler host service must implement this capability
|
||||
// to handle task execution.
|
||||
//
|
||||
//nd:capability name=scheduler
|
||||
type SchedulerCallback interface {
|
||||
// OnCallback is called when a scheduled task fires.
|
||||
// Errors are logged but do not affect the scheduling system.
|
||||
//nd:export name=nd_scheduler_callback
|
||||
OnCallback(SchedulerCallbackRequest) error
|
||||
}
|
||||
|
||||
// SchedulerCallbackRequest is the request provided when a scheduled task fires.
|
||||
type SchedulerCallbackRequest struct {
|
||||
// ScheduleID is the unique identifier for this scheduled task.
|
||||
// This is either the ID provided when scheduling, or an auto-generated UUID if none was specified.
|
||||
ScheduleID string `json:"scheduleId"`
|
||||
// Payload is the payload data that was provided when the task was scheduled.
|
||||
// Can be used to pass context or parameters to the callback handler.
|
||||
Payload string `json:"payload"`
|
||||
// IsRecurring is true if this is a recurring schedule (created via ScheduleRecurring),
|
||||
// false if it's a one-time schedule (created via ScheduleOneTime).
|
||||
IsRecurring bool `json:"isRecurring"`
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
version: v1-draft
|
||||
exports:
|
||||
nd_scheduler_callback:
|
||||
description: |-
|
||||
OnCallback is called when a scheduled task fires.
|
||||
Errors are logged but do not affect the scheduling system.
|
||||
input:
|
||||
$ref: '#/components/schemas/SchedulerCallbackRequest'
|
||||
contentType: application/json
|
||||
components:
|
||||
schemas:
|
||||
SchedulerCallbackRequest:
|
||||
description: SchedulerCallbackRequest is the request provided when a scheduled task fires.
|
||||
properties:
|
||||
scheduleId:
|
||||
type: string
|
||||
description: |-
|
||||
ScheduleID is the unique identifier for this scheduled task.
|
||||
This is either the ID provided when scheduling, or an auto-generated UUID if none was specified.
|
||||
payload:
|
||||
type: string
|
||||
description: |-
|
||||
Payload is the payload data that was provided when the task was scheduled.
|
||||
Can be used to pass context or parameters to the callback handler.
|
||||
isRecurring:
|
||||
type: boolean
|
||||
description: |-
|
||||
IsRecurring is true if this is a recurring schedule (created via ScheduleRecurring),
|
||||
false if it's a one-time schedule (created via ScheduleOneTime).
|
||||
required:
|
||||
- scheduleId
|
||||
- payload
|
||||
- isRecurring
|
||||
@@ -0,0 +1,106 @@
|
||||
package capabilities
|
||||
|
||||
// Scrobbler provides scrobbling functionality to external services.
|
||||
// This capability allows plugins to submit listening history to services like Last.fm,
|
||||
// ListenBrainz, or custom scrobbling backends.
|
||||
//
|
||||
// All methods are required - plugins implementing this capability must provide
|
||||
// all three functions: IsAuthorized, NowPlaying, and Scrobble.
|
||||
//
|
||||
//nd:capability name=scrobbler required=true
|
||||
type Scrobbler interface {
|
||||
// IsAuthorized checks if a user is authorized to scrobble to this service.
|
||||
//nd:export name=nd_scrobbler_is_authorized
|
||||
IsAuthorized(IsAuthorizedRequest) (bool, error)
|
||||
|
||||
// NowPlaying sends a now playing notification to the scrobbling service.
|
||||
//nd:export name=nd_scrobbler_now_playing
|
||||
NowPlaying(NowPlayingRequest) error
|
||||
|
||||
// Scrobble submits a completed scrobble to the scrobbling service.
|
||||
//nd:export name=nd_scrobbler_scrobble
|
||||
Scrobble(ScrobbleRequest) error
|
||||
}
|
||||
|
||||
// IsAuthorizedRequest is the request for authorization check.
|
||||
type IsAuthorizedRequest struct {
|
||||
// Username is the username of the user.
|
||||
Username string `json:"username"`
|
||||
}
|
||||
|
||||
// ArtistRef is a reference to an artist with name and optional MBID.
|
||||
type ArtistRef struct {
|
||||
// ID is the internal Navidrome artist ID (if known).
|
||||
ID string `json:"id,omitempty"`
|
||||
// Name is the artist name.
|
||||
Name string `json:"name"`
|
||||
// MBID is the MusicBrainz ID for the artist.
|
||||
MBID string `json:"mbid,omitempty"`
|
||||
}
|
||||
|
||||
// TrackInfo contains track metadata for scrobbling.
|
||||
type TrackInfo struct {
|
||||
// ID is the internal Navidrome track ID.
|
||||
ID string `json:"id"`
|
||||
// Title is the track title.
|
||||
Title string `json:"title"`
|
||||
// Album is the album name.
|
||||
Album string `json:"album"`
|
||||
// Artist is the formatted artist name for display (e.g., "Artist1 • Artist2").
|
||||
Artist string `json:"artist"`
|
||||
// AlbumArtist is the formatted album artist name for display.
|
||||
AlbumArtist string `json:"albumArtist"`
|
||||
// Artists is the list of track artists.
|
||||
Artists []ArtistRef `json:"artists"`
|
||||
// AlbumArtists is the list of album artists.
|
||||
AlbumArtists []ArtistRef `json:"albumArtists"`
|
||||
// Duration is the track duration in seconds.
|
||||
Duration float32 `json:"duration"`
|
||||
// TrackNumber is the track number on the album.
|
||||
TrackNumber int32 `json:"trackNumber"`
|
||||
// DiscNumber is the disc number.
|
||||
DiscNumber int32 `json:"discNumber"`
|
||||
// MBZRecordingID is the MusicBrainz recording ID.
|
||||
MBZRecordingID string `json:"mbzRecordingId,omitempty"`
|
||||
// MBZAlbumID is the MusicBrainz album/release ID.
|
||||
MBZAlbumID string `json:"mbzAlbumId,omitempty"`
|
||||
// MBZReleaseGroupID is the MusicBrainz release group ID.
|
||||
MBZReleaseGroupID string `json:"mbzReleaseGroupId,omitempty"`
|
||||
// MBZReleaseTrackID is the MusicBrainz release track ID.
|
||||
MBZReleaseTrackID string `json:"mbzReleaseTrackId,omitempty"`
|
||||
}
|
||||
|
||||
// NowPlayingRequest is the request for now playing notification.
|
||||
type NowPlayingRequest struct {
|
||||
// Username is the username of the user.
|
||||
Username string `json:"username"`
|
||||
// Track is the track currently playing.
|
||||
Track TrackInfo `json:"track"`
|
||||
// Position is the current playback position in seconds.
|
||||
Position int32 `json:"position"`
|
||||
}
|
||||
|
||||
// ScrobbleRequest is the request for submitting a scrobble.
|
||||
type ScrobbleRequest struct {
|
||||
// Username is the username of the user.
|
||||
Username string `json:"username"`
|
||||
// Track is the track that was played.
|
||||
Track TrackInfo `json:"track"`
|
||||
// Timestamp is the Unix timestamp when the track started playing.
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
// ScrobblerError represents an error type for scrobbling operations.
|
||||
type ScrobblerError string
|
||||
|
||||
const (
|
||||
// ScrobblerErrorNotAuthorized indicates the user is not authorized.
|
||||
ScrobblerErrorNotAuthorized ScrobblerError = "scrobbler(not_authorized)"
|
||||
// ScrobblerErrorRetryLater indicates the operation should be retried later.
|
||||
ScrobblerErrorRetryLater ScrobblerError = "scrobbler(retry_later)"
|
||||
// ScrobblerErrorUnrecoverable indicates an unrecoverable error.
|
||||
ScrobblerErrorUnrecoverable ScrobblerError = "scrobbler(unrecoverable)"
|
||||
)
|
||||
|
||||
// Error implements the error interface for ScrobblerError.
|
||||
func (e ScrobblerError) Error() string { return string(e) }
|
||||
@@ -0,0 +1,141 @@
|
||||
version: v1-draft
|
||||
exports:
|
||||
nd_scrobbler_is_authorized:
|
||||
description: IsAuthorized checks if a user is authorized to scrobble to this service.
|
||||
input:
|
||||
$ref: '#/components/schemas/IsAuthorizedRequest'
|
||||
contentType: application/json
|
||||
output:
|
||||
type: boolean
|
||||
contentType: application/json
|
||||
nd_scrobbler_now_playing:
|
||||
description: NowPlaying sends a now playing notification to the scrobbling service.
|
||||
input:
|
||||
$ref: '#/components/schemas/NowPlayingRequest'
|
||||
contentType: application/json
|
||||
nd_scrobbler_scrobble:
|
||||
description: Scrobble submits a completed scrobble to the scrobbling service.
|
||||
input:
|
||||
$ref: '#/components/schemas/ScrobbleRequest'
|
||||
contentType: application/json
|
||||
components:
|
||||
schemas:
|
||||
ArtistRef:
|
||||
description: ArtistRef is a reference to an artist with name and optional MBID.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome artist ID (if known).
|
||||
name:
|
||||
type: string
|
||||
description: Name is the artist name.
|
||||
mbid:
|
||||
type: string
|
||||
description: MBID is the MusicBrainz ID for the artist.
|
||||
required:
|
||||
- name
|
||||
IsAuthorizedRequest:
|
||||
description: IsAuthorizedRequest is the request for authorization check.
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
description: Username is the username of the user.
|
||||
required:
|
||||
- username
|
||||
NowPlayingRequest:
|
||||
description: NowPlayingRequest is the request for now playing notification.
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
description: Username is the username of the user.
|
||||
track:
|
||||
$ref: '#/components/schemas/TrackInfo'
|
||||
description: Track is the track currently playing.
|
||||
position:
|
||||
type: integer
|
||||
format: int32
|
||||
description: Position is the current playback position in seconds.
|
||||
required:
|
||||
- username
|
||||
- track
|
||||
- position
|
||||
ScrobbleRequest:
|
||||
description: ScrobbleRequest is the request for submitting a scrobble.
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
description: Username is the username of the user.
|
||||
track:
|
||||
$ref: '#/components/schemas/TrackInfo'
|
||||
description: Track is the track that was played.
|
||||
timestamp:
|
||||
type: integer
|
||||
format: int64
|
||||
description: Timestamp is the Unix timestamp when the track started playing.
|
||||
required:
|
||||
- username
|
||||
- track
|
||||
- timestamp
|
||||
TrackInfo:
|
||||
description: TrackInfo contains track metadata for scrobbling.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: ID is the internal Navidrome track ID.
|
||||
title:
|
||||
type: string
|
||||
description: Title is the track title.
|
||||
album:
|
||||
type: string
|
||||
description: Album is the album name.
|
||||
artist:
|
||||
type: string
|
||||
description: Artist is the formatted artist name for display (e.g., "Artist1 • Artist2").
|
||||
albumArtist:
|
||||
type: string
|
||||
description: AlbumArtist is the formatted album artist name for display.
|
||||
artists:
|
||||
type: array
|
||||
description: Artists is the list of track artists.
|
||||
items:
|
||||
$ref: '#/components/schemas/ArtistRef'
|
||||
albumArtists:
|
||||
type: array
|
||||
description: AlbumArtists is the list of album artists.
|
||||
items:
|
||||
$ref: '#/components/schemas/ArtistRef'
|
||||
duration:
|
||||
type: number
|
||||
format: float
|
||||
description: Duration is the track duration in seconds.
|
||||
trackNumber:
|
||||
type: integer
|
||||
format: int32
|
||||
description: TrackNumber is the track number on the album.
|
||||
discNumber:
|
||||
type: integer
|
||||
format: int32
|
||||
description: DiscNumber is the disc number.
|
||||
mbzRecordingId:
|
||||
type: string
|
||||
description: MBZRecordingID is the MusicBrainz recording ID.
|
||||
mbzAlbumId:
|
||||
type: string
|
||||
description: MBZAlbumID is the MusicBrainz album/release ID.
|
||||
mbzReleaseGroupId:
|
||||
type: string
|
||||
description: MBZReleaseGroupID is the MusicBrainz release group ID.
|
||||
mbzReleaseTrackId:
|
||||
type: string
|
||||
description: MBZReleaseTrackID is the MusicBrainz release track ID.
|
||||
required:
|
||||
- id
|
||||
- title
|
||||
- album
|
||||
- artist
|
||||
- albumArtist
|
||||
- artists
|
||||
- albumArtists
|
||||
- duration
|
||||
- trackNumber
|
||||
- discNumber
|
||||
@@ -0,0 +1,61 @@
|
||||
package capabilities
|
||||
|
||||
// WebSocketCallback provides WebSocket message handling.
|
||||
// This capability allows plugins to receive callbacks for WebSocket events
|
||||
// such as text messages, binary messages, errors, and connection closures.
|
||||
// Plugins that use the WebSocket host service must implement this capability
|
||||
// to handle incoming events.
|
||||
//
|
||||
//nd:capability name=websocket
|
||||
type WebSocketCallback interface {
|
||||
// OnTextMessage is called when a text message is received on a WebSocket connection.
|
||||
//nd:export name=nd_websocket_on_text_message
|
||||
OnTextMessage(OnTextMessageRequest) error
|
||||
|
||||
// OnBinaryMessage is called when a binary message is received on a WebSocket connection.
|
||||
//nd:export name=nd_websocket_on_binary_message
|
||||
OnBinaryMessage(OnBinaryMessageRequest) error
|
||||
|
||||
// OnError is called when an error occurs on a WebSocket connection.
|
||||
//nd:export name=nd_websocket_on_error
|
||||
OnError(OnErrorRequest) error
|
||||
|
||||
// OnClose is called when a WebSocket connection is closed.
|
||||
//nd:export name=nd_websocket_on_close
|
||||
OnClose(OnCloseRequest) error
|
||||
}
|
||||
|
||||
// OnTextMessageRequest is the request provided when a text message is received.
|
||||
type OnTextMessageRequest struct {
|
||||
// ConnectionID is the unique identifier for the WebSocket connection that received the message.
|
||||
ConnectionID string `json:"connectionId"`
|
||||
// Message is the text message content received from the WebSocket.
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
// OnBinaryMessageRequest is the request provided when a binary message is received.
|
||||
type OnBinaryMessageRequest struct {
|
||||
// ConnectionID is the unique identifier for the WebSocket connection that received the message.
|
||||
ConnectionID string `json:"connectionId"`
|
||||
// Data is the binary data received from the WebSocket, encoded as base64.
|
||||
Data string `json:"data"`
|
||||
}
|
||||
|
||||
// OnErrorRequest is the request provided when an error occurs on a WebSocket connection.
|
||||
type OnErrorRequest struct {
|
||||
// ConnectionID is the unique identifier for the WebSocket connection where the error occurred.
|
||||
ConnectionID string `json:"connectionId"`
|
||||
// Error is the error message describing what went wrong.
|
||||
Error string `json:"error"`
|
||||
}
|
||||
|
||||
// OnCloseRequest is the request provided when a WebSocket connection is closed.
|
||||
type OnCloseRequest struct {
|
||||
// ConnectionID is the unique identifier for the WebSocket connection that was closed.
|
||||
ConnectionID string `json:"connectionId"`
|
||||
// Code is the WebSocket close status code (e.g., 1000 for normal closure,
|
||||
// 1001 for going away, 1006 for abnormal closure).
|
||||
Code int32 `json:"code"`
|
||||
// Reason is the human-readable reason for the connection closure, if provided.
|
||||
Reason string `json:"reason"`
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
version: v1-draft
|
||||
exports:
|
||||
nd_websocket_on_text_message:
|
||||
description: OnTextMessage is called when a text message is received on a WebSocket connection.
|
||||
input:
|
||||
$ref: '#/components/schemas/OnTextMessageRequest'
|
||||
contentType: application/json
|
||||
nd_websocket_on_binary_message:
|
||||
description: OnBinaryMessage is called when a binary message is received on a WebSocket connection.
|
||||
input:
|
||||
$ref: '#/components/schemas/OnBinaryMessageRequest'
|
||||
contentType: application/json
|
||||
nd_websocket_on_error:
|
||||
description: OnError is called when an error occurs on a WebSocket connection.
|
||||
input:
|
||||
$ref: '#/components/schemas/OnErrorRequest'
|
||||
contentType: application/json
|
||||
nd_websocket_on_close:
|
||||
description: OnClose is called when a WebSocket connection is closed.
|
||||
input:
|
||||
$ref: '#/components/schemas/OnCloseRequest'
|
||||
contentType: application/json
|
||||
components:
|
||||
schemas:
|
||||
OnBinaryMessageRequest:
|
||||
description: OnBinaryMessageRequest is the request provided when a binary message is received.
|
||||
properties:
|
||||
connectionId:
|
||||
type: string
|
||||
description: ConnectionID is the unique identifier for the WebSocket connection that received the message.
|
||||
data:
|
||||
type: string
|
||||
description: Data is the binary data received from the WebSocket, encoded as base64.
|
||||
required:
|
||||
- connectionId
|
||||
- data
|
||||
OnCloseRequest:
|
||||
description: OnCloseRequest is the request provided when a WebSocket connection is closed.
|
||||
properties:
|
||||
connectionId:
|
||||
type: string
|
||||
description: ConnectionID is the unique identifier for the WebSocket connection that was closed.
|
||||
code:
|
||||
type: integer
|
||||
format: int32
|
||||
description: |-
|
||||
Code is the WebSocket close status code (e.g., 1000 for normal closure,
|
||||
1001 for going away, 1006 for abnormal closure).
|
||||
reason:
|
||||
type: string
|
||||
description: Reason is the human-readable reason for the connection closure, if provided.
|
||||
required:
|
||||
- connectionId
|
||||
- code
|
||||
- reason
|
||||
OnErrorRequest:
|
||||
description: OnErrorRequest is the request provided when an error occurs on a WebSocket connection.
|
||||
properties:
|
||||
connectionId:
|
||||
type: string
|
||||
description: ConnectionID is the unique identifier for the WebSocket connection where the error occurred.
|
||||
error:
|
||||
type: string
|
||||
description: Error is the error message describing what went wrong.
|
||||
required:
|
||||
- connectionId
|
||||
- error
|
||||
OnTextMessageRequest:
|
||||
description: OnTextMessageRequest is the request provided when a text message is received.
|
||||
properties:
|
||||
connectionId:
|
||||
type: string
|
||||
description: ConnectionID is the unique identifier for the WebSocket connection that received the message.
|
||||
message:
|
||||
type: string
|
||||
description: Message is the text message content received from the WebSocket.
|
||||
required:
|
||||
- connectionId
|
||||
- message
|
||||
Reference in New Issue
Block a user