navidrome/plugins/cmd/ndpgen

ndpgen

Navidrome Plugin Development Kit (PDK) code generator. It reads Go interface definitions with special annotations and generates client wrappers for WASM plugins.

This tool is the unified code generator that replaces hostgen and will eventually handle both host function wrappers and capability wrappers.

Usage

ndpgen -input <dir> -output <dir> [-package <name>] [-v] [-dry-run] [-host-only] [-go] [-python] [-rust]

Flags

Flag	Description	Default
-input	Directory containing Go source files with annotated interfaces	Required
-output	Directory where generated files will be written	Same as input
-package	Package name for generated files	Inferred from output
-v	Verbose output	false
-dry-run	Parse and validate without writing files	false
-host-only	Generate only host function wrappers (capability support TBD)	true
-go	Generate Go client wrappers	true*
-python	Generate Python client wrappers	false
-rust	Generate Rust client wrappers	false

* -go is enabled by default when neither -python nor -rust is specified. Use combinations like -go -python -rust to generate multiple languages.

Example

go run ./plugins/cmd/ndpgen \
  -input ./plugins/host \
  -output ./plugins/pdk/go/host

Annotations

//nd:hostservice

Marks an interface as a host service that will have wrappers generated.

//nd:hostservice name=<ServiceName> permission=<permission>
type MyService interface { ... }

Parameter	Description	Required
name	Service name used in generated type names and function prefixes	Yes
permission	Permission required by plugins to use this service	Yes

//nd:hostfunc

Marks a method within a host service interface for export to plugins.

//nd:hostfunc [name=<export_name>]
MethodName(ctx context.Context, ...) (result Type, err error)

Parameter	Description	Required
name	Custom export name (default: <servicename>_<methodname> in lowercase)	No

Input Format

Host service interfaces must follow these conventions:

1. First parameter must be context.Context - Required for all methods
2. Last return value should be error - For proper error handling
3. Annotations must be on consecutive lines - No blank comment lines between doc and annotation

Example Interface

package host

import "context"

// SubsonicAPIService provides access to Navidrome's Subsonic API.
// This documentation becomes part of the generated code.
//nd:hostservice name=SubsonicAPI permission=subsonicapi
type SubsonicAPIService interface {
    // Call executes a Subsonic API request and returns the response.
    //nd:hostfunc
    Call(ctx context.Context, uri string) (response string, err error)
}

Generated Output

Go Client Library (Go/TinyGo WASM)

Generated files are named nd_host_<servicename>.go (lowercase) and placed directly in the output directory. The output directory becomes a complete Go module (github.com/navidrome/navidrome/plugins/pdk/go/host) with package name ndpdk, intended for import by Navidrome plugins built with TinyGo.

The generator creates:

• nd_host_<servicename>.go - Client wrapper code (WASM build)
• nd_host_<servicename>_stub.go - Stub code for non-WASM platforms
• doc.go - Package documentation listing all available services
• go.mod - Go module file with required dependencies

Each service file includes:

• // Code generated by ndpgen. DO NOT EDIT. header
• Required imports (encoding/json, errors, github.com/extism/go-pdk)
• //go:wasmimport declarations for each host function
• Response struct types and any struct definitions from the service
• Wrapper functions that handle memory allocation and JSON parsing

Python Client Library

When using -python, Python client files are generated in a python/ subdirectory.

Rust Client Library

When using -rust, Rust client files are generated in a rust/ subdirectory.

Supported Types

ndpgen supports these Go types in method signatures:

Type	JSON Representation
string, int, bool, etc.	Native JSON types
[]T (slices)	JSON arrays
map[K]V (maps)	JSON objects
*T (pointers)	Nullable fields
interface{} / any	Converts to any
Custom structs	JSON objects (must be JSON-serializable)

Multiple Return Values

Methods can return multiple values (plus error):

//nd:hostfunc
Search(ctx context.Context, query string) (results []string, total int, hasMore bool, err error)

Generates:

type ServiceSearchResponse struct {
    Results []string `json:"results,omitempty"`
    Total   int      `json:"total,omitempty"`
    HasMore bool     `json:"hasMore,omitempty"`
    Error   string   `json:"error,omitempty"`
}

Migration from hostgen

The ndpgen tool replaces hostgen for plugin development. Key differences:

1. Output structure: Files go directly in the output directory (not a go/ subdirectory)
2. Package name: Generated code uses ndpdk instead of ndhost
3. Module path: Uses github.com/navidrome/navidrome/plugins/pdk/go/host instead of github.com/navidrome/navidrome/plugins/host/go
4. Focus: ndpgen generates only client-side code (plugin SDK), not host-side code

Running Tests

go test ./plugins/cmd/ndpgen/...