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

18 KiB

Python Control API client and CLI

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; keep both files together when copying the tool.

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.

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:

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.

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 for limits and source ownership.

The same methods and CLI JSON input accept the five 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.

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.

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.

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 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:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tools/tests -v

These checks need no live proxy, Telegram connection or deployment credentials.