mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
301 lines
18 KiB
Markdown
301 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. |
|
|
| `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 53 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.
|
|
|
|
## 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
|
|
python3 tools/generate_api_openapi.py --check
|
|
```
|
|
|
|
These checks need no live proxy, Telegram connection or deployment credentials.
|