Widget Proxy Request Handling#

All widget data fetching goes through a centralized server-side proxy pipeline. Widget components call useWidgetAPI, which serializes request parameters and calls /api/services/proxy. That route resolves the widget definition, validates the endpoint against an allowlist, rewrites the request, and delegates to a proxy handler — most commonly genericProxyHandler or credentialedProxyHandler — which calls httpProxy to make the outbound HTTP/HTTPS request.

Component → useWidgetAPI → /api/services/proxy → proxyHandler → httpProxy → upstream

Request flow in proxy.js#

The handler performs the following steps for every mapped widget:

1. Resolve the mapping — looks up widget.mappings[req.query.endpoint] to get the real endpoint, allowed params, method, body, segments, and optional per-endpoint proxyHandler override 1.
2. Method enforcement — the mapping's method field (defaulting to GET) is written onto req.method; if the incoming request's method doesn't match, a 403 is returned 2.
3. Body forwarding — mapping.body replaces req.body, enabling POST/PUT payloads defined statically in widget.js 3.
4. URL segment substitution — path-level variables (e.g., a node name) are resolved via getSafeSegments, which validates and encodeURIComponent-encodes each segment before substituting into the endpoint string 4.
5. Query parameter serialization — params and optionalParams are merged and appended as a query string (see below).
6. Delegate — calls endpointProxy(req, res, map) (falling back to serviceProxyHandler) with the rewritten request 5.

For widgets using allowedEndpoints (a RegExp) instead of structured mappings, the request is forwarded as-is under GET without any parameter processing 6.

Query parameter handling: params vs optionalParams#

Widget query parameters originate as an object passed to useWidgetAPI; formatProxyUrl JSON-stringifies them into a single query URL parameter sent to the proxy route.

Inside proxy.js, when req.query.query is present, it is parsed and two mapping-declared lists control which keys reach the upstream API 7:

Both lists are then concatenated and passed to URLSearchParams, which appends them to the endpoint URL as a query string.

Example — proxmoxbackupserver nodes/localhost/tasks 8: The mapping declares params: ["errors", "limit", "since"]. The component builds a taskQueryParams object with those keys and passes it to useWidgetAPI 9. The proxy then reliably appends all three to the upstream URL, e.g. ?errors=true&limit=100&since=1700000000.

Example — CoinMarketCap v1/cryptocurrency/quotes/latest: Uses params: ["convert"] (required) alongside optionalParams: ["symbol", "slug"] — symbol and slug are only forwarded when the component actually supplies them.

Proxy handlers#

Both built-in handlers (generic and credentialed) receive the rewritten req and call httpProxy:

• genericProxyHandler: Builds the upstream URL from widgets[type].api + endpoint using formatApiCall. Merges headers from widget-type defaults, per-widget overrides, and req.extraHeaders. Uses widget.method ?? req.method as the HTTP method. Sends req.body or widget.requestBody as the body 10.
• credentialedProxyHandler: Same URL construction, but additionally injects auth headers (Bearer token, Basic auth, API-key headers, etc.) based on widget.type. For example, proxmoxbackupserver gets a PBSAPIToken header 11. Header extras from req.extraHeaders (populated by mapping.headers) are also merged 12.

Both handlers call validateWidgetData on 200 responses before optionally applying the mapping's map() transform 13 14.

httpProxy and transport#

httpProxy selects HTTP or HTTPS based on the URL protocol, attaches a persistent keep-alive agent, and handles gzip/deflate decompression automatically 15. TLS certificate verification is disabled (rejectUnauthorized: false), which is intentional to support self-signed certificates common in self-hosted setups 16. It resolves to [statusCode, contentType, data, responseHeaders].

A separate cachedRequest helper wraps httpProxy with an in-memory cache (default 5-minute TTL) and is used for auxiliary lookups (e.g., icon resolution), not for widget data.

DNS resolution uses a custom lookup function that falls back from dns.lookup to dns.resolve4/dns.resolve6 on ENOTFOUND/EAI_NONAME errors — a fix for Alpine/musl libc environments (e.g., Kubernetes).

Key source files#