Files
telemt/docs/Architecture/API/PYTHON_CLIENT.md
T
2026-11-10 08:00:49 +03:00

314 lines
18 KiB
Markdown

# Python Control API client and CLI
[tools/telemt_api.py](../../../tools/telemt_api.py) provides a Python 3.10+
standard-library client. No third-party package is required. Import
`TelemtAPI` from `tools.telemt_api` when running from the repository, or add the
`tools` directory to your Python import path and import from `telemt_api`.
The CLI parser lives in
[tools/telemt_api_cli.py](../../../tools/telemt_api_cli.py); keep both files
together when copying the tool.
```bash
python3 tools/telemt_api.py help
python3 tools/telemt_api.py --url http://127.0.0.1:9091 --auth 'Bearer synthetic-demo' capabilities --json-output
python3 tools/telemt_api.py config-state --sections general,access,web --json-output
```
The authorization value is exact, including any `Bearer ` prefix configured by
the operator. Global `--url`, `--auth`, `--timeout`, `--if-match`, and
`--json-output` may appear before or after a command. `--timeout` is the socket
timeout in seconds and defaults to 10; preflight can need a larger value because
its server work budget is 30 seconds. Authentication applies independently to
each request, including polling after a reload.
Default output retains human-readable user/create/delete output and prints
other payloads as JSON followed by revision/status metadata. `--json-output`
prints one JSON object containing `ok`, `data`, `revision`, and `http_status`.
`http_status` belongs to the client wrapper, not the server's JSON envelope.
The state endpoint can have `revision=null` while returning an effective
snapshot and a bounded desired-source error.
## Commands and methods
Existing statistics commands retain their names: `health`, `info`, `status`,
`init`, `limits`, `posture`, `whitelist`, `summary`, `zero`, `upstreams`,
`minimal`, `me-writers`, `dcs`, `me-pool`, `me-quality`, `upstream-quality`,
`nat-stun`, `me-selftest`, `connections`, and `events --limit N`.
| CLI | Python method | Contract |
| --- | --- | --- |
| `ready` | `health_ready()` | `200` ready or `503` readiness data; CLI exits 1 when not ready. |
| `capabilities` | `capabilities()` | Supported routes, feature gates and mutation availability. |
| `schema` | `config_schema()` | Types, defaults, sensitivity, exposure and apply policy. |
| `config` | `get_config()` | Desired editable config, including `web`; administratively sensitive. |
| `config-state [--sections general,web]` | `config_state(["general", "web"])` | Redacted desired/effective state and owner observations. |
| `validate --json FILE` | `validate_config(patch, ...)` | Candidate preparation without persistence/publication. |
| `config-patch --json FILE [--reload instant] [--wait]` | `patch_config(patch, ...)` | Exact sparse patch, optional reload policy, source/runtime preconditions. |
| `reload [--mode instant] [--wait]` | `reload(mode, ...)` | Submit generation reload; default failure policy is server-owned `keep_new`. |
| `reload-status ID` | `reload_status(id)` | Read one retained operation. |
| `reload-wait ID [--expected-revision REV]` | `wait_reload(id, ...)` | Poll to `succeeded`, `failed` or `rolled_back`. |
| `users`, `user NAME` | `list_users()`, `get_user(name)` | User/link responses can carry provisioning secrets. |
| `user-links NAME [--transport web] [--view effective]` | `user_links(name, transport="web", view="effective")` | Credential-bearing exact WEB profiles; `view="desired"` always returns an unusable preview. |
| `create NAME`, `patch NAME`, `delete NAME` | `create_user()`, `patch_user()`, `delete_user()` | Existing convenience methods and command names remain available. |
| `patch NAME --json FILE` or `--clear FIELD` | `patch_user_fields(name, fields)` | Exact omitted/null/value semantics. |
| `secret NAME [--secret HEX]` | `rotate_secret(name, ...)` | Implemented rotation endpoint, not a reserved route. |
| `enable NAME`, `disable NAME` | `enable_user()`, `disable_user()` | User admission controls with optional `If-Match`. |
| `reset-quota NAME` | `reset_user_quota()` | Durable quota reset; preserves the recurring boundary contract. |
| `quota` | `users_quota()` | Desired quota/period and effective recurring schedule/counters. |
| `active-ips` | `users_active_ips()` | Current per-user IP observations. |
| `tls-fingerprints [--limit N]` | `runtime_tls_fingerprints(limit)` | `1..1000`, subject to runtime-edge availability. |
| `web-status` | `web_status()` | Runtime identity, availability and operator lifecycle. |
| `web-sessions [FILTERS]` | `web_sessions(...)` | One bounded page; caller follows `next_cursor`. |
| `web-session REF` | `web_session(ref)` | Live `200` or retained closed `410` tombstone. |
| `web-close --runtime-instance INSTANCE --selector FILE [--wait]` | `web_close_sessions(instance, selector)` | Exact `refs`, nonempty `filter`, or `all` selector. |
| `web-operation ID`, `web-wait ID` | `web_operation(id)`, `wait_web_operation(id)` | Read/poll the process-scoped close operation. |
| `web-debug-clear --runtime-instance INSTANCE` | `web_debug_clear(instance)` | Clears retained debug records. |
| `web-learning-reset --runtime-instance INSTANCE` | `web_learning_reset(instance)` | Resets process-owned carrier learning. |
| `web-pause --runtime-instance INSTANCE` | `web_pause(instance)` | Stops admission of new WEB work. |
| `web-drain --runtime-instance INSTANCE --timeout-secs N [--wait]` | `web_drain(instance, seconds)` | Starts one bounded server drain, returns `202`. |
| `web-drain-wait ID --runtime-instance INSTANCE` | `wait_web_drain(instance, id)` | Polls the same drain through WEB status. |
| `web-resume --runtime-instance INSTANCE` | `web_resume(instance)` | Resumes operator admission subject to other policy gates. |
| `gen-secret` | `TelemtAPI.generate_secret()` | Generates a new 32-hex secret locally. |
The client covers all 54 JSON operations in the operation catalog. Open the
HTML `/web-status` viewer in a browser; it is not decoded as a JSON response.
Feature gates and missing runtime planes still return the server's documented
errors. Discovery availability is a snapshot, not a reservation.
WEB provisioning uses the dedicated user-link endpoint. The client sends
`transport=web` explicitly and defaults to `view=effective`. It preserves the
server's `state`, `usable`, `reason`, runtime identity and link rows; a successful
HTTP response alone does not mean a link is usable. After a rotation, retry a
pending effective response after configuration publication. A desired preview
contains credentials but always has `usable=false`. See the
[WEB user-link contract](API.md#web-user-links).
```bash
python3 tools/telemt_api.py user-links alice --json-output
python3 tools/telemt_api.py user-links alice --view desired --json-output
```
## Sparse values and user updates
`create`/`patch` accept `--secret`, `--ad-tag`, `--max-conns`, `--expires`,
`--quota`, `--max-ips`, `--quota-period daily|weekly|monthly`, `--rate-up`,
`--rate-down`, and mutually exclusive `--enabled`/`--disabled`. Rate units are
bits per second. A zero or false option is transmitted explicitly.
Shared access policy is available through `api.access_policy()` and
`api.patch_access_policy(body, if_match=..., if_runtime_match=...)`, or CLI
`access-policy` / `access-policy-patch --json FILE --if-runtime-match TOKEN`.
JSON null is transmitted unchanged: scalar null restores a default, a null CIDR
entry deletes that rule, and `cidr_rate_limits=null` clears the map. A rate object
replaces both directions, with omitted directions unlimited. Inspect
`desired` / `effective` and the runtime token before relying on publication.
For backward compatibility, `patch_user(..., field=None)` continues to omit that
convenience argument. Use `patch_user_fields` or CLI JSON/`--clear` to transmit
null. The exact method does not alter the supplied dictionary:
```python
from tools.telemt_api import TelemtAPI
api = TelemtAPI("http://127.0.0.1:9091", auth_header="Bearer synthetic-demo")
api.patch_user_fields("alice", {
"quota_period": None,
"rate_limit_up_bps": 0,
"enabled": False,
}, if_match="synthetic-source-revision")
```
For user fields, omission preserves the setting and null removes its override;
`enabled=null` restores the default enabled state. `secret=null` is ignored,
so the CLI excludes `secret` from `--clear`. Removing a quota or recurring period
still follows server validation and durable scheduling rules. `--json` cannot
be combined with field options/`--clear`; conflicting set/clear options fail
before any HTTP request.
```bash
python3 tools/telemt_api.py patch alice --quota 0 --disabled
python3 tools/telemt_api.py patch alice --clear quota_period --clear rate_limit_up_bps
printf '%s\n' '{"quota_period":null,"enabled":false}' | python3 tools/telemt_api.py patch alice --json -
```
Source-deny lists use `source_deny=["192.0.2.0/24", "2001:db8::/32"]`,
`create/patch --source-deny CIDR` (repeatable), or exact PATCH JSON.
`patch alice --clear source_deny` removes the authored row. User deletion retains
that row; `create_user("alice", source_deny=None)` or CLI
`create alice --clear-source-deny` explicitly removes it on recreation. Omitting
the creation argument retains any old rule. The older `patch_user(...,
source_deny=None)` convenience call omits the field; use `patch_user_fields`
for null removal. Empty arrays replace the list with no denied networks.
These changes need explicit generation reload. Inspect
`source_deny_status.runtime_reload_required`, submit `reload` with the returned
revision, and check reload status plus the effective list. Saving alone does not
cancel sessions or change rules in a running generation; a reload already in
progress may have captured an older source revision.
Rotation returns the new raw credential, cancels owners tied to the old
credential identity and relies on asynchronous owner/watcher work for subsequent
publication. `UserInfo.in_runtime` only tests username membership. It does not
prove that a new credential or quota period has reached every consumer. Use
`config_state()` and `users_quota()` to inspect the corresponding evidence.
## Config preparation, ownership and reload
Config objects merge sparsely, arrays replace the complete array, and nested
object null members are ignored by the server. These semantics differ from
user PATCH nulls. In particular, `web.vhosts` is already editable and is replaced
as an array; fetch and retain the complete desired array before changing an entry.
`network.dns_overrides` accepts the same array replacement contract through
`validate_config`/`patch_config` and CLI JSON input. For example,
`{"network":{"dns_overrides":["upstream.example:443:192.0.2.10"]}}` replaces the
list, and `{"network":{"dns_overrides":[]}}` clears it. Other `network` fields
remain rejected. PATCH without a reload query leaves publication to the existing
watcher; it does not wait for the resolver update or move established connections.
See [DNS overrides](API.md#dns-overrides) for limits and source ownership.
The same methods and CLI JSON input accept the five
[API observability settings](API.md#api-observability-settings). For example,
`{"server":{"api":{"runtime_edge_enabled":true,"runtime_edge_cache_ttl_ms":0,"runtime_edge_top_n":20}}}`
enables edge diagnostics with caching disabled after generation activation.
Preview and PATCH the identical body with `reload="instant"`, or `reload="drain"`
and a required `timeout_secs` value, then poll the returned reload ID.
Saving without a reload leaves these settings
pending; the watcher never applies them. `false` and `0` are preserved, while
`null` retains an allowed field's previous value. API security settings and
listener identity remain outside this write surface.
State projections are inspection DTOs and must not be used as PATCH bodies.
`If-Match` fences the recursive desired-source revision. `If-Runtime-Match`
fences the active publication and is accepted by config preflight/PATCH only.
Both quoted and unquoted values are passed through unchanged. A patch must be
owned by one independently writable source; a cross-include edit can fail with
`409 config_patch_not_atomic`. The client preserves the server's error details
and does not split a rejected edit into partial commits.
```python
patch = {"general": {"log_level": "debug"}}
preview = api.validate_config(patch, reload="drain", timeout_secs=30,
failure_policy="rollback")
result = api.patch_config(
patch,
if_match=preview.data["base_revision"],
if_runtime_match=preview.data["runtime"]["runtime_match"],
reload="drain", timeout_secs=30, failure_policy="rollback",
)
accepted = result.data.get("reload")
if accepted:
final = api.wait_reload(accepted["reload_id"],
expected_revision=accepted["config_revision"], timeout=60)
if final.data["state"] != "succeeded":
raise RuntimeError("Reload did not succeed")
```
`restart_required` is the legacy watcher classification;
`runtime_reload_required` describes differences requiring runtime activation;
`process_restart_required` identifies fields retained until process restart.
Do not reduce these flags to one generic restart action. A successful preflight
does not guarantee future binding, unchanged external resources, or consumer
convergence. `published_match` in state describes selected snapshot equality;
`subsystem_convergence` can remain `unknown`.
`--reload drain`/`--mode drain` requires `--timeout-secs 1..3600`; instant forbids
that option. `--failure-policy` is `keep_new` or `rollback`. Config preflight and
PATCH accept those query options; direct reload sends the corresponding JSON
body. Process-only patches can return no reload operation even with `--wait`.
For the CLI examples below, save the sparse config object as `patch.json` and
replace the synthetic preconditions with the tokens returned by preflight.
```bash
python3 tools/telemt_api.py --timeout 35 validate --json patch.json --json-output
python3 tools/telemt_api.py config-patch --json patch.json --if-match synthetic-source-revision --if-runtime-match synthetic-publication-token --reload drain --timeout-secs 30 --failure-policy rollback --wait
python3 tools/telemt_api.py reload --mode instant --wait --wait-timeout 60
```
Polling uses a monotonic budget (`--wait-timeout`, default 60) and a positive
interval (`--poll-interval`, default 0.25). Each request's socket timeout is capped
by the remaining budget; urllib's timeout is a socket wait limit, not a hard
end-to-end deadline against a peer that continuously streams bytes. Polling
only reads status. A timeout raises `TelemtAPIError(code="poll_timeout")` with
`last_response`, and does not cancel or resubmit the server operation. A normal
transport failure remains a transport error and is not retried automatically.
Library waiters return terminal `failed`, `rolled_back`, or `cancelled` data so
callers can inspect it. CLI wait/status commands exit 1 for those terminal
failures, 0 for a successful response/terminal result, and 2 for invalid local
input. Readiness false exits 1; a readable WEB tombstone exits 0. `202` without
`--wait` means the request was accepted, not that the operation completed.
Reload IDs are process-local. `expected_revision` detects a different source
target, but cannot distinguish all ID reuse after process restart with identical
source bytes. WEB identifiers already carry a process reference and are handled
as described below.
## WEB process references and bounded queries
Read `web_status().data["runtime"]["runtime_instance"]` and pass that exact
reference to WEB controls. Copy `session_ref`/`operation_id` unchanged from
server responses. The client never substitutes a fresh runtime reference after
`409 web_runtime_mismatch`; re-evaluate operator intent before submitting work
to a new process.
```python
status = api.web_status()
instance = status.data["runtime"]["runtime_instance"]
page = api.web_sessions(limit=25, user="alice")
refs = [row["session_ref"] for row in page.data["sessions"]]
if refs:
close = api.web_close_sessions(instance, {"kind": "refs", "session_refs": refs})
done = api.wait_web_operation(close.data["operation_id"])
drain = api.web_drain(instance, 30)
drain_id = drain.data["drain"]["operation_id"]
finished = api.wait_web_drain(instance, drain_id, timeout=60)
```
Enumeration defaults to 50 rows and accepts `limit=1..200`. `session_ref` is
mutually exclusive with `cursor`/`limit`. Filters are `ip`, `host`, `user`,
`user_agent_id`, `key_id`, `carrier`, and `state`; the
[API reference](API.md#web-session-enumeration) defines their exact formatting
and length limits. Query values are URL-encoded individually. The client does
not auto-page an unbounded session list. `refs` closes 1..200 unique references;
`filter` requires a non-null filter; `all` remains subject to the server's
issuance-disabled gate.
Every WEB POST sends exactly `Content-Type: application/json`, no query, and a
JSON object with the caller's process reference. The client caps these bodies
at 64 KiB; the configured server body limit can be lower. A close waiter stops
at `completed`, `cancelled`, or `failed`. A drain waiter reads WEB status until
the same drain is `completed` or `cancelled`, preserving `force_closing` as a
pending phase; a changed/missing process or drain fails with
`operation_mismatch`.
## Errors and credential exposure
`TelemtAPIError` exposes `code`, `http_status`, `request_id`, `details`, and an
optional `last_response` for polling diagnostics. JSON success envelopes with
HTTP `503` readiness or `410` tombstone are accepted only by those dedicated
methods. Other error envelopes raise, including feature-gate and stale-process
failures. CLI errors go to stderr with field details and request correlation.
For peers outside the API whitelist, `gray_action="drop"` closes without HTTP,
`"api"` returns structured `403 forbidden`, and `"200"` returns an empty
`200 OK`. An empty/non-JSON body raises `invalid_response`; it is never reported
as a successful mutation. Allowed peers still undergo authentication and
read-only checks.
Config GET, user lists, creation and rotation may reveal credentials or
credential-bearing links. Their library/CLI outputs retain the server contract;
`--json-output` does not redact them. Use the redacted state endpoint for
inspection where appropriate. All credentials and references in this guide
are synthetic examples.
Run the local mock HTTP and CLI contract suite from the repository root:
```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tools/tests -v
```
These checks need no live proxy, Telegram connection or deployment credentials.