68 lines
4.1 KiB
Plaintext
68 lines
4.1 KiB
Plaintext
# Configure requests and security
|
|
|
|
Most widgets use a single source named `default`; the manifest must contain it. Extra keyed sources are available for widgets
|
|
that combine APIs. Source IDs are case-insensitively unique. Base URLs must use HTTP(S), contain no embedded credentials,
|
|
query string, or fragment, and sources can be `public`, `private`, or `loopback`. Authentication is `none`, `bearer`,
|
|
`basic`, an API-key header, or an API-key query parameter. Credentials belong to the widget but remain outside its manifest.
|
|
Source origins are fixed by the definition and source-setup flow; widget options and invocation parameters cannot redirect a
|
|
request to a different origin.
|
|
|
|
## Named requests
|
|
|
|
Requests are keyed by ID. `source`, `kind`, `method`, `trigger`, `auth`, and `permission` have sensible defaults, so a load query can be as small as:
|
|
|
|
```json
|
|
{ "status": { "path": "/api/status" } }
|
|
```
|
|
|
|
The request `path` is appended to the source `baseUrl`, including a base path such as `/api/v2`.
|
|
|
|
GET, POST, PUT, and PATCH work for queries and actions. DELETE is restricted to actions so it can never run while a
|
|
board loads. Kind controls the remaining behavior: load queries run automatically, manual queries run through
|
|
`SubFetch`, and actions run only from `ActionButton` or `ToggleSwitch`.
|
|
|
|
Bind values directly where they are used:
|
|
|
|
```json
|
|
{
|
|
"containers": {
|
|
"path": "/api/endpoints/{option:endpointId}/docker/containers/json",
|
|
"query": { "all": { "$option": "showAll" } }
|
|
},
|
|
"restart": {
|
|
"kind": "action",
|
|
"method": "POST",
|
|
"path": "/api/endpoints/{option:endpointId}/docker/containers/{param:id}/restart",
|
|
"invalidates": ["containers"]
|
|
}
|
|
}
|
|
```
|
|
|
|
`{option:name}` and `$option` read saved widget options. `{param:name}` and `$param` read invocation-time `params`. Load queries cannot use invocation parameters. Homarr infers the exact parameter names and primitive values from these references, rejecting missing or extra invocation params at the request boundary.
|
|
|
|
Path placeholders and query values must resolve to text, numbers, or booleans. `$option` and `$param` references may appear
|
|
recursively in JSON bodies; invocation parameters remain primitive, and load queries cannot use `$param`. JSON bodies can
|
|
also use structured `json` and `multiSelect` option values, for example `{ "entity_ids": { "$option": "entities" } }`.
|
|
|
|
## Protection
|
|
|
|
Every request uses Homarr's existing server executor: same-origin source enforcement, network scope, DNS and redirect validation, SSRF protection, board permissions, rate and request limits, body and response limits, timeouts, and encrypted credential injection. Static headers cannot override credentials, cookies, routing, proxy, forwarding, or hop-by-hop headers.
|
|
|
|
The executor caps request bodies at 10 KiB and response bodies at 1 MiB. Parsed JSON is limited to depth 32 and 50,000 nodes;
|
|
each network hop has a ten-second timeout, queries follow at most three same-origin redirects, actions do not follow redirects,
|
|
and the total request deadline is 45 seconds.
|
|
|
|
The limiter allows four concurrent requests per user/item and eight per definition. Per minute, a user/item can make up to 60
|
|
queries, 10 actions, or 3 DELETE actions; a definition can receive up to 240, 40, or 12 of those request categories.
|
|
|
|
Queries default to view permission and actions to modify. DELETE always requires full permission and confirmation. Actions are never cached, retried, or run on load.
|
|
|
|
Management and runtime are intentionally separate. A Homarr administrator with board-modify permission places and
|
|
configures the widget. After placement, query and action authorization follows the request's board permission. Public
|
|
boards may execute queries for anonymous viewers, but mutations stay authenticated. This includes shared-cache
|
|
invalidation: `RefreshButton` is disabled only without an active item or preview session, or in edit mode, while ordinary
|
|
scheduled query rendering remains available to anonymous viewers.
|
|
|
|
Responses use bounded, versioned shared-Redis cache keys. Action invalidation advances the shared version so every
|
|
Homarr replica stops serving the previous response without scanning or deleting a key prefix.
|