chore(plugins): document requiredHosts rules and deprecate pdk.NewHTTPRequest (#6129)

* 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.

plugins/cmd/ndpgen/internal/generator_test.go

@@ -1790,6 +1790,33 @@ var _ = Describe("Rust Generation", func() {
 				Expect(codeStr).NotTo(ContainSubstring("return args.Get(0).(*HTTPRequest)"))
 			})
 		})
+
+		Describe("Deprecated PDK functions", func() {
+			symbols := &PDKSymbols{
+				Functions: []PDKFunc{
+					{
+						Name:       "NewHTTPRequest",
+						Doc:        "NewHTTPRequest returns a new `HTTPRequest`.",
+						Params:     []PDKParam{{Name: "method", Type: "HTTPMethod"}, {Name: "url", Type: "string"}},
+						Returns:    []PDKReturn{{Type: "*HTTPRequest"}},
+						Deprecated: "Use host.HTTPSend instead.",
+					},
+				},
+			}
+
+			DescribeTable("emits a Deprecated paragraph after the doc line",
+				func(generate func(*PDKSymbols) ([]byte, error)) {
+					code, err := generate(symbols)
+					Expect(err).NotTo(HaveOccurred())
+					_, err = format.Source(code)
+					Expect(err).NotTo(HaveOccurred())
+					Expect(string(code)).To(ContainSubstring(
+						"// NewHTTPRequest NewHTTPRequest returns a new `HTTPRequest`.\n//\n// Deprecated: Use host.HTTPSend instead.\nfunc NewHTTPRequest("))
+				},
+				Entry("WASM wrapper", GeneratePDKGo),
+				Entry("native stub", GeneratePDKGoStub),
+			)
+		})
 	})
 })
 

plugins/cmd/ndpgen/internal/pdk_parser.go

@@ -50,6 +50,12 @@ type PDKFunc struct {
 	Params     []PDKParam
 	Returns    []PDKReturn
 	IsVariadic bool
+	Deprecated string // Rendered as a "Deprecated:" paragraph when set
+}
+
+// deprecatedPDKFuncs marks extism functions that do not work inside Navidrome, with what to use instead.
+var deprecatedPDKFuncs = map[string]string{
+	"NewHTTPRequest": "Navidrome does not enable extism's http_request host function, so every request sent this way fails. Use host.HTTPSend instead.",
 }
 
 // PDKParam represents a function parameter.
@@ -156,6 +162,7 @@ func ParseExtismPDK() (*PDKSymbols, error) {
 						t.Methods = append(t.Methods, fn)
 					}
 				} else {
+					fn.Deprecated = deprecatedPDKFuncs[fn.Name]
 					symbols.Functions = append(symbols.Functions, fn)
 				}
 			}

plugins/cmd/ndpgen/internal/templates/client.rs.tmpl

@@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize};
 {{if .Doc}}
 {{rustDocComment .Doc}}
 {{else}}
-{{end}}#[derive(Debug, Clone, Serialize, Deserialize)]
+{{end}}#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct {{.Name}} {
 {{- range .Fields}}

plugins/cmd/ndpgen/internal/templates/pdk.go.tmpl

@@ -40,6 +40,10 @@ const (
 {{- if .Doc}}
 // {{.Name}} {{firstSentence .Doc}}
 {{- end}}
+{{- if .Deprecated}}
+//
+// Deprecated: {{.Deprecated}}
+{{- end}}
 func {{.Name}}({{paramList .Params}}){{returnList .Returns}} {
 {{- if .Returns}}
 	return extism.{{.Name}}({{argList .Params}})

plugins/cmd/ndpgen/internal/templates/pdk_stub.go.tmpl

@@ -31,6 +31,10 @@ func ResetMock() {
 {{- if .Doc}}
 // {{.Name}} {{firstSentence .Doc}}
 {{- end}}
+{{- if .Deprecated}}
+//
+// Deprecated: {{.Deprecated}}
+{{- end}}
 func {{.Name}}({{paramList .Params}}){{returnList .Returns}} {
 {{- if .Returns}}
 	args := PDKMock.Called({{argList .Params}})

plugins/cmd/ndpgen/testdata/comprehensive_client_expected.rs

@@ -29,14 +29,14 @@ mod base64_bytes {
     }
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User2 {
     pub id: String,
     pub name: String,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Filter2 {
     pub active: bool,

plugins/cmd/ndpgen/testdata/list_client_expected.rs

@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Filter {
     pub active: bool,

plugins/cmd/ndpgen/testdata/search_client_expected.rs

@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Result {
     pub id: String,

plugins/cmd/ndpgen/testdata/store_client_expected.rs

@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Item {
     pub id: String,

plugins/cmd/ndpgen/testdata/users_client_expected.rs

@@ -6,7 +6,7 @@
 use extism_pdk::*;
 use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct User {
     pub id: String,