feat(plugins): add HTTP host service (#5095)

* feat(httpclient): implement HttpClient service for outbound HTTP requests in plugins Signed-off-by: Deluan <deluan@navidrome.org> * feat(httpclient): enhance SSRF protection by validating host requests against private IPs Signed-off-by: Deluan <deluan@navidrome.org> * feat(httpclient): support DELETE requests with body in HttpClient service Signed-off-by: Deluan <deluan@navidrome.org> * feat(httpclient): refactor HTTP client initialization and enhance redirect handling Signed-off-by: Deluan <deluan@navidrome.org> * refactor(http): standardize naming conventions for HTTP types and methods Signed-off-by: Deluan <deluan@navidrome.org> * refactor example plugin to use host.HTTPSend for improved error management Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): fix IPv6 SSRF bypass and wildcard host matching Fix two bugs in the plugin HTTP/WebSocket host validation: 1. extractHostname now strips IPv6 brackets when no port is present (e.g. "[::1]" → "::1"). Previously, net.SplitHostPort failed for bracketed IPv6 without a port, leaving brackets intact. This caused net.ParseIP to return nil, bypassing the private/loopback SSRF guard. 2. matchHostPattern now treats "*" as an allow-all pattern. Previously, a bare "*" only matched via exact equality, so plugins declaring requiredHosts: ["*"] (like webhook-rs) had all requests rejected. --------- Signed-off-by: Deluan <deluan@navidrome.org>
2026-02-24 14:28:36 -05:00
parent 2bb13e5ff1
commit 652c27690b
14 changed files with 1228 additions and 19 deletions
@@ -38,6 +38,7 @@ The following host services are available:
  - Artwork: provides artwork public URL generation capabilities for plugins.
  - Cache: provides in-memory TTL-based caching capabilities for plugins.
  - Config: provides access to plugin configuration values.
+  - HTTP: provides outbound HTTP request capabilities for plugins.
  - KVStore: provides persistent key-value storage for plugins.
  - Library: provides access to music library metadata for plugins.
  - Scheduler: provides task scheduling capabilities for plugins.
@@ -0,0 +1,87 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the HTTP host service.
+// It is intended for use in Navidrome plugins built with TinyGo.
+//
+//go:build wasip1
+
+package host
+
+import (
+	"encoding/json"
+	"errors"
+
+	"github.com/navidrome/navidrome/plugins/pdk/go/pdk"
+)
+
+// HTTPRequest represents an outbound HTTP request from a plugin.
+type HTTPRequest struct {
+	Method    string            `json:"method"`
+	URL       string            `json:"url"`
+	Headers   map[string]string `json:"headers"`
+	Body      []byte            `json:"body"`
+	TimeoutMs int32             `json:"timeoutMs"`
+}
+
+// HTTPResponse represents the response from an outbound HTTP request.
+type HTTPResponse struct {
+	StatusCode int32             `json:"statusCode"`
+	Headers    map[string]string `json:"headers"`
+	Body       []byte            `json:"body"`
+}
+
+// http_send is the host function provided by Navidrome.
+//
+//go:wasmimport extism:host/user http_send
+func http_send(uint64) uint64
+
+type httpSendRequest struct {
+	Request HTTPRequest `json:"request"`
+}
+
+type httpSendResponse struct {
+	Result *HTTPResponse `json:"result,omitempty"`
+	Error  string        `json:"error,omitempty"`
+}
+
+// HTTPSend calls the http_send host function.
+// Send executes an HTTP request and returns the response.
+//
+// Parameters:
+//   - request: The HTTP request to execute, including method, URL, headers, body, and timeout
+//
+// Returns the HTTP response with status code, headers, and body.
+// Network errors, timeouts, and permission failures are returned as Go errors.
+// Successful HTTP calls (including 4xx/5xx status codes) return a non-nil response with nil error.
+func HTTPSend(request HTTPRequest) (*HTTPResponse, error) {
+	// Marshal request to JSON
+	req := httpSendRequest{
+		Request: request,
+	}
+	reqBytes, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	reqMem := pdk.AllocateBytes(reqBytes)
+	defer reqMem.Free()
+
+	// Call the host function
+	responsePtr := http_send(reqMem.Offset())
+
+	// Read the response from memory
+	responseMem := pdk.FindMemory(responsePtr)
+	responseBytes := responseMem.ReadBytes()
+
+	// Parse the response
+	var response httpSendResponse
+	if err := json.Unmarshal(responseBytes, &response); err != nil {
+		return nil, err
+	}
+
+	// Convert Error field to Go error
+	if response.Error != "" {
+		return nil, errors.New(response.Error)
+	}
+
+	return response.Result, nil
+}
@@ -0,0 +1,55 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains mock implementations for non-WASM builds.
+// These mocks allow IDE support, compilation, and unit testing on non-WASM platforms.
+// Plugin authors can use the exported mock instances to set expectations in tests.
+//
+//go:build !wasip1
+
+package host
+
+import "github.com/stretchr/testify/mock"
+
+// HTTPRequest represents an outbound HTTP request from a plugin.
+type HTTPRequest struct {
+	Method    string            `json:"method"`
+	URL       string            `json:"url"`
+	Headers   map[string]string `json:"headers"`
+	Body      []byte            `json:"body"`
+	TimeoutMs int32             `json:"timeoutMs"`
+}
+
+// HTTPResponse represents the response from an outbound HTTP request.
+type HTTPResponse struct {
+	StatusCode int32             `json:"statusCode"`
+	Headers    map[string]string `json:"headers"`
+	Body       []byte            `json:"body"`
+}
+
+// mockHTTPService is the mock implementation for testing.
+type mockHTTPService struct {
+	mock.Mock
+}
+
+// HTTPMock is the auto-instantiated mock instance for testing.
+// Use this to set expectations: host.HTTPMock.On("MethodName", args...).Return(values...)
+var HTTPMock = &mockHTTPService{}
+
+// Send is the mock method for HTTPSend.
+func (m *mockHTTPService) Send(request HTTPRequest) (*HTTPResponse, error) {
+	args := m.Called(request)
+	return args.Get(0).(*HTTPResponse), args.Error(1)
+}
+
+// HTTPSend delegates to the mock instance.
+// Send executes an HTTP request and returns the response.
+//
+// Parameters:
+//   - request: The HTTP request to execute, including method, URL, headers, body, and timeout
+//
+// Returns the HTTP response with status code, headers, and body.
+// Network errors, timeouts, and permission failures are returned as Go errors.
+// Successful HTTP calls (including 4xx/5xx status codes) return a non-nil response with nil error.
+func HTTPSend(request HTTPRequest) (*HTTPResponse, error) {
+	return HTTPMock.Send(request)
+}
@@ -0,0 +1,59 @@
+# Code generated by ndpgen. DO NOT EDIT.
+#
+# This file contains client wrappers for the HTTP host service.
+# It is intended for use in Navidrome plugins built with extism-py.
+#
+# IMPORTANT: Due to a limitation in extism-py, you cannot import this file directly.
+# The @extism.import_fn decorators are only detected when defined in the plugin's
+# main __init__.py file. Copy the needed functions from this file into your plugin.
+
+from dataclasses import dataclass
+from typing import Any
+
+import extism
+import json
+
+
+class HostFunctionError(Exception):
+    """Raised when a host function returns an error."""
+    pass
+
+
+@extism.import_fn("extism:host/user", "http_send")
+def _http_send(offset: int) -> int:
+    """Raw host function - do not call directly."""
+    ...
+
+
+def http_send(request: Any) -> Any:
+    """Send executes an HTTP request and returns the response.
+
+Parameters:
+  - request: The HTTP request to execute, including method, URL, headers, body, and timeout
+
+Returns the HTTP response with status code, headers, and body.
+Network errors, timeouts, and permission failures are returned as errors.
+Successful HTTP calls (including 4xx/5xx status codes) return a non-nil response with nil error.
+
+    Args:
+        request: Any parameter.
+
+    Returns:
+        Any: The result value.
+
+    Raises:
+        HostFunctionError: If the host function returns an error.
+    """
+    request = {
+        "request": request,
+    }
+    request_bytes = json.dumps(request).encode("utf-8")
+    request_mem = extism.memory.alloc(request_bytes)
+    response_offset = _http_send(request_mem.offset)
+    response_mem = extism.memory.find(response_offset)
+    response = json.loads(extism.memory.string(response_mem))
+
+    if response.get("error"):
+        raise HostFunctionError(response["error"])
+
+    return response.get("result", None)
@@ -35,6 +35,7 @@
 //! - [`artwork`] - provides artwork public URL generation capabilities for plugins.
 //! - [`cache`] - provides in-memory TTL-based caching capabilities for plugins.
 //! - [`config`] - provides access to plugin configuration values.
+//! - [`http`] - provides outbound HTTP request capabilities for plugins.
 //! - [`kvstore`] - provides persistent key-value storage for plugins.
 //! - [`library`] - provides access to music library metadata for plugins.
 //! - [`scheduler`] - provides task scheduling capabilities for plugins.
@@ -63,6 +64,13 @@ pub mod config {
    pub use super::nd_host_config::*;
 }

+#[doc(hidden)]
+mod nd_host_http;
+/// provides outbound HTTP request capabilities for plugins.
+pub mod http {
+    pub use super::nd_host_http::*;
+}
+
 #[doc(hidden)]
 mod nd_host_kvstore;
 /// provides persistent key-value storage for plugins.
@@ -0,0 +1,83 @@
+// Code generated by ndpgen. DO NOT EDIT.
+//
+// This file contains client wrappers for the HTTP host service.
+// It is intended for use in Navidrome plugins built with extism-pdk.
+
+use extism_pdk::*;
+use serde::{Deserialize, Serialize};
+
+/// HTTPRequest represents an outbound HTTP request from a plugin.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HttpRequest {
+    pub method: String,
+    pub url: String,
+    #[serde(default)]
+    pub headers: std::collections::HashMap<String, String>,
+    #[serde(default)]
+    pub body: Vec<u8>,
+    #[serde(default)]
+    pub timeout_ms: i32,
+}
+
+/// HTTPResponse represents the response from an outbound HTTP request.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HttpResponse {
+    pub status_code: i32,
+    #[serde(default)]
+    pub headers: std::collections::HashMap<String, String>,
+    #[serde(default)]
+    pub body: Vec<u8>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct HTTPSendRequest {
+    request: HttpRequest,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct HTTPSendResponse {
+    #[serde(default)]
+    result: Option<HttpResponse>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[host_fn]
+extern "ExtismHost" {
+    fn http_send(input: Json<HTTPSendRequest>) -> Json<HTTPSendResponse>;
+}
+
+/// Send executes an HTTP request and returns the response.
+///
+/// Parameters:
+///   - request: The HTTP request to execute, including method, URL, headers, body, and timeout
+///
+/// Returns the HTTP response with status code, headers, and body.
+/// Network errors, timeouts, and permission failures are returned as errors.
+/// Successful HTTP calls (including 4xx/5xx status codes) return a non-nil response with nil error.
+///
+/// # Arguments
+/// * `request` - HttpRequest parameter.
+///
+/// # Returns
+/// The result value.
+///
+/// # Errors
+/// Returns an error if the host function call fails.
+pub fn send(request: HttpRequest) -> Result<Option<HttpResponse>, Error> {
+    let response = unsafe {
+        http_send(Json(HTTPSendRequest {
+            request: request,
+        }))?
+    };
+
+    if let Some(err) = response.0.error {
+        return Err(Error::msg(err));
+    }
+
+    Ok(response.0.result)
+}