Update API.md

This commit is contained in:
Alexey
2026-11-07 23:05:52 +03:00
parent 982c4e4a34
commit 8fce8fb0df
+56 -9
View File
@@ -542,13 +542,13 @@ original ClientHello.
### `PatchConfigRequest`
A sparse JSON object containing only the top-level config sections to modify. Each key must be one of the editable sections (`general`, `timeouts`, `censorship`, `upstreams`, `dc_overrides`, `web`) or the partially editable objects `server` (only `listeners`) and `network` (only `dns_overrides`; see below). Tables within a section are deep-merged field-by-field into the existing config; arrays and scalar values replace the existing value wholesale. Untouched table bodies and other source files remain byte-identical; touched TOML table bodies are reserialized, except for the DNS value edit described below, so comments and formatting inside a rewritten body can change.
A sparse JSON object containing only the top-level config sections to modify. Each key must be one of the editable sections (`general`, `timeouts`, `censorship`, `upstreams`, `dc_overrides`, `web`) or the partially editable objects `server` (`listeners` and five API observability fields) and `network` (only `dns_overrides`; see below). Tables within a section are deep-merged field-by-field into the existing config; arrays and scalar values replace the existing value wholesale. Untouched table bodies and other source files remain byte-identical; touched TOML table bodies are reserialized, except for the field edits described below, so comments and formatting inside a rewritten body can change.
**Rejected keys:**
- `access` → `400 access_not_editable` (users/secrets are managed via `POST/PATCH /v1/users`).
- An unknown top-level key or a non-null, non-object `server`/`network` value → `400 section_not_editable`.
- `network` with any key other than `dns_overrides`, even when that key is null, → `400 field_not_editable`.
- `server` with any key other than `listeners` (e.g. `port`, `api`, `admin_api`) → `400 field_not_editable`.
- `server` with any key other than `listeners`/`api` (e.g. `port`, `admin_api`), or `server.api` with a key outside its five-field allowlist, even when null, → `400 field_not_editable`.
- An object with no editable keys → `400 bad_request` (empty patch).
- Within otherwise editable sections/fields, unknown nested fields, including fields with null values, → `400 bad_request` with `error.details[].code=unknown_field`, independently of `general.config_strict`. Known fields from an incompatible upstream/decoy variant are rejected with `field_not_applicable`. Open DC/domain maps remain supported; `upstreams[].force_bind` remains an alias of `bindtodevice`.
@@ -562,6 +562,53 @@ Example — replace `[[server.listeners]]` (other `[server]` fields including `[
{"server": {"listeners": [{"ip": "0.0.0.0", "port": 443, "client_mss": "92"}]}}
```
#### API observability settings
`GET /v1/config`, `PATCH /v1/config`, and `POST /v1/config/validate` expose
exactly these nested settings, including their typed defaults in GET:
| Path | Type / bounds | Default |
| --- | --- | --- |
| `server.api.minimal_runtime_enabled` | Boolean | `true` |
| `server.api.minimal_runtime_cache_ttl_ms` | Integer, `0..60000` | `1000` |
| `server.api.runtime_edge_enabled` | Boolean | `false` |
| `server.api.runtime_edge_cache_ttl_ms` | Integer, `0..60000` | `1000` |
| `server.api.runtime_edge_top_n` | Integer, `1..1000` | `10` |
```json
{"server":{"api":{"runtime_edge_enabled":true,"runtime_edge_cache_ttl_ms":0,"runtime_edge_top_n":20}}}
```
Omitted fields and allowed null members retain their values; a server object
without a concrete editable value is rejected. TTL `0` disables cache reuse.
Other API fields, including `auth_header`, `whitelist`, `gray_action`, `read_only`,
`enabled`, `listen`, `request_body_limit_bytes`, and `runtime_edge_events_capacity`,
remain excluded. Forbidden keys are rejected even when null. Authentication and
read-only checks still apply to these mutations.
Each setting edits its exact source owner, using the nearest existing parent
for insertion. API siblings, listener definitions and other source files survive.
Inline, dotted and quoted TOML forms are supported. PATCH uses `server.api` even
when the source retains the legacy `[server.admin_api]` spelling. Ambiguous or
multiple owners return `409 config_patch_not_atomic` without writing.
Saving reports `runtime_reload_required=true` while active values differ; these
settings also retain the legacy `restart_required=true` classification when the
desired source changes, without requiring a process restart. The watcher never
overlays them, including in mixed patches. Use `?reload=instant` or
`?reload=drain&timeout_secs=30`, or submit `POST /v1/system/reload` with the saved revision.
Acceptance is asynchronous: inspect reload status and `GET /v1/config/state` for
activation. The existing API listener and event-ring capacity are retained.
After activation, diagnostic endpoints and capabilities reflect the new flags.
Disabled diagnostics return their existing payload with `reason=feature_disabled`;
enabled ME diagnostics can still report `source_unavailable` when no pool exists.
Cache entries are checked against each request's pinned generation, including
stale edge-cache fallback, so a late old-generation calculation cannot supply a
new-generation response. Requests already in flight may finish using their
original generation. Recompute contention without a matching cache can report
`source_unavailable`.
#### DNS overrides
`network.dns_overrides` is the only editable network field. GET includes the
@@ -633,9 +680,9 @@ Returned by `GET /v1/config` as the envelope `data`. The fields are exactly the
| `dc_overrides` | `object` | Complete normalized DC override map, including the synthesized DC 203 endpoint when it is not authored. |
| `web` | `object` | Complete normalized `[web]` section, including defaults. Each `web.vhosts[]` item preserves either `host` or `hosts` and includes `base_path` (empty string when omitted in TOML); hostname lists remain grouped. The derived runtime-only `web.runtime` field is excluded. |
| `network` | `object` | Only `dns_overrides`, a `string[]` defaulting to `[]`; other network fields are excluded. |
| `server` | `object?` | Partial `[server]` view when editable nested fields are present. Currently only `listeners` may appear; `api`/`admin_api`, `port`, unix sockets, and other bind-identity fields are never returned. |
| `server` | `object` | Partial `[server]` view: `listeners` and the five allowlisted `api` observability settings. API secrets, access controls, `admin_api`, `port`, unix sockets, and other bind-identity fields are never returned. |
The editable typed sections are serialized from the fully defaulted configuration, even when omitted from the source files. Only the editable sections above are returned; `access` (users/secrets) is excluded, and `network` exposes only `dns_overrides`, including its default empty array. Under `server`, only the nested field-level allowlist (`listeners`) is exposed, and an empty listener array is omitted. Changes to `web.allow_wildcard_hosts` and `[web.limits]` remain process-deferred; the patch response reports them in `deferred_process_fields` until restart. Wildcard patterns require the flag to be enabled in the active process; staging the flag does not authorize patterns before restart.
The editable typed sections are serialized from the fully defaulted configuration, even when omitted from the source files. Only the editable sections above are returned; `access` (users/secrets) is excluded, and `network` exposes only `dns_overrides`, including its default empty array. Under `server`, only the nested allowlists (`listeners` and five `api` fields) are exposed, and an empty listener array is omitted. Changes to `web.allow_wildcard_hosts` and `[web.limits]` remain process-deferred; the patch response reports them in `deferred_process_fields` until restart. Wildcard patterns require the flag to be enabled in the active process; staging the flag does not authorize patterns before restart.
### WEB runtime identity and lifecycle
@@ -2219,7 +2266,7 @@ A valid base-path-only change reports `restart_required=false`, `runtime_reload_
| `400` | `bad_request` | Invalid JSON, empty patch, or config validation/deserialization failure. |
| `400` | `access_not_editable` | Patch contains an `access` key. |
| `400` | `section_not_editable` | Patch contains an unknown top-level key or a non-null, non-object partial section. |
| `400` | `field_not_editable` | Patch contains a forbidden nested `server.*` or `network.*` field; only `server.listeners` and `network.dns_overrides` are allowed. |
| `400` | `field_not_editable` | Patch contains a nested field outside `server.listeners`, the five `server.api` observability fields, or `network.dns_overrides`. |
| `401` | `unauthorized` | Missing or invalid `Authorization` header. |
| `403` | `read_only` | API is in read-only mode. |
| `405` | `method_not_allowed` | Method other than `GET` or `PATCH` used on `/v1/config`. |
@@ -2406,13 +2453,13 @@ The current runtime exports these additional bounded-cardinality families. All u
| Bind failure | Failed API bind logs warning and API task exits (no auto-retry loop). |
| ME runtime status endpoints | `/v1/stats/me-writers`, `/v1/stats/dcs`, `/v1/stats/minimal/all` require `[server.api].minimal_runtime_enabled=true`; otherwise they return disabled payload with `reason=feature_disabled`. |
| Upstream runtime endpoint | `/v1/stats/upstreams` always returns `zero`, but runtime fields (`summary`, `upstreams`) require `[server.api].minimal_runtime_enabled=true`. |
| Restart requirements | `server.api` changes are restart-required for predictable behavior. |
| Hot-reload nuance | A pure `server.api`-only config change may not propagate through watcher broadcast; a mixed change (with hot fields) may propagate API flags while still warning that restart is required. |
| Runtime apply path | Successful writes are picked up by existing config watcher/hot-reload path. |
| API observability settings | The five editable `server.api` settings need explicit generation reload. API listener identity and event-ring capacity remain process-owned. |
| Watcher behavior | The watcher retains every `server.api` field, including in mixed changes with watcher-supported settings. |
| Runtime apply path | Saving updates desired state. Watcher-supported fields publish asynchronously; generation-owned fields require explicit reload. |
| Exposure | Built-in TLS/mTLS is not provided. Use loopback bind + reverse proxy if needed. |
| Pagination | User list currently has no pagination/filtering. |
| Serialization side effect | Updated TOML table bodies are re-serialized on write. Endpoints that persist full config can still rewrite broader formatting/comments. |
## Known Limitations (Current Release)
- API runtime controls under `server.api` are documented as restart-required; hot-reload behavior for these fields is not strictly uniform in all change combinations.
- API observability settings require explicit generation reload; saving them alone leaves diagnostics unchanged in the active generation.