From 4dbd834840010ddd5e1997c986fbbacb79447da3 Mon Sep 17 00:00:00 2001 From: Alexey <247128645+axkurcom@users.noreply.github.com> Date: Thu, 5 Nov 2026 20:02:02 +0300 Subject: [PATCH] Create PYTHON_CLIENT.md --- docs/Architecture/API/PYTHON_CLIENT.md | 266 +++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 docs/Architecture/API/PYTHON_CLIENT.md diff --git a/docs/Architecture/API/PYTHON_CLIENT.md b/docs/Architecture/API/PYTHON_CLIENT.md new file mode 100644 index 0000000..d36926a --- /dev/null +++ b/docs/Architecture/API/PYTHON_CLIENT.md @@ -0,0 +1,266 @@ +# 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 51 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 +bytes per second. A zero or false option is transmitted explicitly. + +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 - +``` + +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. + +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.