mirror of
https://github.com/navidrome/navidrome.git
synced 2026-10-08 02:17:25 +02:00
1072e9f7eb* fix(plugins): align the Python HTTP example with the repo's host-call pattern
Bind http_send with raw memory offsets like nowplaying-py does, drop
guards for fields the host always sends, and document how plugins
without a PDK call host services and which built-in HTTP APIs are
disabled.
* docs(plugins): document the private-address rules for HTTP requiredHosts
Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can.
* docs(plugins): document the private-address rules for requiredHosts
Explain in the README and manifest schema that named hosts can't reach
private addresses while IP/CIDR entries and a bare "*" can, for both
HTTP and WebSocket. Inline the single-use HTTP isHostAllowed wrapper.
* feat(plugins): derive Default for Rust host service structs
The ndpgen client.rs template now adds Default to the derive list of host
service structs, as the capability and shared types templates already do.
Plugin authors can now set only the fields they need, for example
HTTPRequest { method, url, ..Default::default() }. The webhook-rs and
discord-rich-presence-rs examples use this form now. The golden files and
the generated nd-pdk-host crate are updated to match.
* feat(plugins): deprecate pdk.NewHTTPRequest in the Go PDK
Navidrome no longer enables extism's http_request host function, so a
request built with pdk.NewHTTPRequest always fails. ndpgen now reads a small
deprecation table and writes a Deprecated: paragraph for the listed extism
functions, in both the WASM wrapper and the native stub. Linters and IDEs
now point plugin authors to host.HTTPSend. The PDK example tests used to
teach NewHTTPRequest. They now use host.HTTPSend and host.HTTPMock.
* docs(plugins): correct requiredHosts rules for websocket and private addresses
Two statements in the plugin docs did not match the code.
The WebSocket section claimed requiredHosts behaves like HTTP. It does not:
host_httpclient.go only consults the allowlist when the list is non-empty and
otherwise falls back to allowing public addresses, while host_websocket.go
always calls isHostInAllowlist, so an absent list blocks every connection.
The HTTP section claimed a named host can never reach a private address.
checkPrivateDial scans the whole requiredHosts list, so a named host does
reach a private address when the same list also holds a covering IP or CIDR.
Reworded both, plus the matching requiredHosts descriptions in
manifest-schema.json, and regenerated manifest_gen.go.
277 lines
8.5 KiB
JSON
277 lines
8.5 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://navidrome.org/schemas/Manifest.json",
|
|
"title": "Manifest",
|
|
"description": "Plugin manifest for Navidrome plugins",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": ["name", "author", "version"],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "The display name of the plugin",
|
|
"minLength": 1
|
|
},
|
|
"author": {
|
|
"type": "string",
|
|
"description": "The author of the plugin",
|
|
"minLength": 1
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"description": "The version of the plugin (semver recommended)",
|
|
"minLength": 1
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "A brief description of what the plugin does"
|
|
},
|
|
"website": {
|
|
"type": "string",
|
|
"description": "URL to the plugin's website or repository",
|
|
"format": "uri"
|
|
},
|
|
"permissions": {
|
|
"$ref": "#/$defs/Permissions"
|
|
},
|
|
"config": {
|
|
"$ref": "#/$defs/ConfigDefinition"
|
|
}
|
|
},
|
|
"$defs": {
|
|
"ConfigDefinition": {
|
|
"type": "object",
|
|
"description": "Configuration schema for the plugin using JSON Schema (draft-07) and optional JSONForms UI Schema",
|
|
"additionalProperties": false,
|
|
"required": ["schema"],
|
|
"properties": {
|
|
"schema": {
|
|
"type": "object",
|
|
"description": "JSON Schema (draft-07) defining the plugin's configuration options"
|
|
},
|
|
"uiSchema": {
|
|
"type": "object",
|
|
"description": "Optional JSONForms UI Schema for customizing form layout"
|
|
}
|
|
}
|
|
},
|
|
"Permissions": {
|
|
"type": "object",
|
|
"description": "Permissions required by the plugin",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"http": {
|
|
"$ref": "#/$defs/HTTPPermission"
|
|
},
|
|
"subsonicapi": {
|
|
"$ref": "#/$defs/SubsonicAPIPermission"
|
|
},
|
|
"scheduler": {
|
|
"$ref": "#/$defs/SchedulerPermission"
|
|
},
|
|
"websocket": {
|
|
"$ref": "#/$defs/WebSocketPermission"
|
|
},
|
|
"artwork": {
|
|
"$ref": "#/$defs/ArtworkPermission"
|
|
},
|
|
"cache": {
|
|
"$ref": "#/$defs/CachePermission"
|
|
},
|
|
"library": {
|
|
"$ref": "#/$defs/LibraryPermission"
|
|
},
|
|
"kvstore": {
|
|
"$ref": "#/$defs/KVStorePermission"
|
|
},
|
|
"users": {
|
|
"$ref": "#/$defs/UsersPermission"
|
|
},
|
|
"taskqueue": {
|
|
"$ref": "#/$defs/TaskQueuePermission"
|
|
},
|
|
"matcher": {
|
|
"$ref": "#/$defs/MatcherPermission"
|
|
},
|
|
"storage": {
|
|
"$ref": "#/$defs/StoragePermission"
|
|
},
|
|
"scrobbleRetriever": {
|
|
"$ref": "#/$defs/ScrobbleRetrieverPermission"
|
|
}
|
|
}
|
|
},
|
|
"ArtworkPermission": {
|
|
"type": "object",
|
|
"description": "Artwork service permissions for generating artwork URLs",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why artwork access is needed"
|
|
}
|
|
}
|
|
},
|
|
"CachePermission": {
|
|
"type": "object",
|
|
"description": "Cache service permissions for storing and retrieving data",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why cache access is needed"
|
|
}
|
|
}
|
|
},
|
|
"HTTPPermission": {
|
|
"type": "object",
|
|
"description": "HTTP access permissions for a plugin",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why HTTP access is needed"
|
|
},
|
|
"requiredHosts": {
|
|
"type": "array",
|
|
"description": "List of required host patterns for HTTP requests (e.g., 'api.example.com', '*.musicbrainz.org'). A named host alone can't reach a private address; also list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"SubsonicAPIPermission": {
|
|
"type": "object",
|
|
"description": "SubsonicAPI service permissions. Requires 'users' permission to be declared.",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why SubsonicAPI access is needed"
|
|
}
|
|
}
|
|
},
|
|
"SchedulerPermission": {
|
|
"type": "object",
|
|
"description": "Scheduler service permissions for scheduling tasks",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why scheduler access is needed"
|
|
}
|
|
}
|
|
},
|
|
"WebSocketPermission": {
|
|
"type": "object",
|
|
"description": "WebSocket service permissions for establishing WebSocket connections",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why WebSocket access is needed"
|
|
},
|
|
"requiredHosts": {
|
|
"type": "array",
|
|
"description": "List of required host patterns for WebSocket connections (e.g., 'api.example.com', '*.musicbrainz.org'). Required: with no entries every connection is blocked. A named host alone can't reach a private address; also list an IP, a CIDR (e.g., '10.0.0.0/8') or '*' for that",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"LibraryPermission": {
|
|
"type": "object",
|
|
"description": "Library service permissions for accessing library metadata and optionally filesystem",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why library access is needed"
|
|
},
|
|
"filesystem": {
|
|
"type": "boolean",
|
|
"description": "Whether the plugin requires read-only filesystem access to library directories",
|
|
"default": false
|
|
}
|
|
}
|
|
},
|
|
"KVStorePermission": {
|
|
"type": "object",
|
|
"description": "Key-value store permissions for persistent plugin storage",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why key-value store access is needed"
|
|
},
|
|
"maxSize": {
|
|
"type": "string",
|
|
"description": "Maximum storage size (e.g., '1MB', '500KB'). Default: 1MB"
|
|
}
|
|
}
|
|
},
|
|
"TaskQueuePermission": {
|
|
"type": "object",
|
|
"description": "Task queue permissions for background task processing",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why task queue access is needed"
|
|
},
|
|
"maxConcurrency": {
|
|
"type": "integer",
|
|
"description": "Maximum total concurrent workers across all queues. Default: 1",
|
|
"minimum": 1,
|
|
"default": 1
|
|
}
|
|
}
|
|
},
|
|
"UsersPermission": {
|
|
"type": "object",
|
|
"description": "Users service permissions for accessing user information",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why users access is needed"
|
|
}
|
|
}
|
|
},
|
|
"MatcherPermission": {
|
|
"type": "object",
|
|
"description": "Matcher service permissions for resolving external songs to local library tracks",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why matcher access is needed"
|
|
}
|
|
}
|
|
},
|
|
"StoragePermission": {
|
|
"type": "object",
|
|
"description": "Storage permissions for enabling persistent read-write storage exclusively for the plugin",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why storage access is needed"
|
|
}
|
|
}
|
|
},
|
|
"ScrobbleRetrieverPermission": {
|
|
"type": "object",
|
|
"description": "Scrobble retriever permissions for retrieving scrobbles from users",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Explanation for why scrobble retriever access is needed"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|