mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
777 lines
34 KiB
Python
777 lines
34 KiB
Python
"""
|
||
Telemt Control API Python Client
|
||
Standard-library JSON client and CLI for Telemt's Control API.
|
||
|
||
Usage:
|
||
client = TelemtAPI("http://127.0.0.1:9091", auth_header="your-secret")
|
||
client.health()
|
||
client.create_user("alice", max_tcp_conns=10)
|
||
client.patch_user("alice", data_quota_bytes=1_000_000_000)
|
||
client.delete_user("alice")
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
import math
|
||
import secrets
|
||
import time
|
||
from dataclasses import dataclass
|
||
from http.client import HTTPException
|
||
from typing import Any, Dict
|
||
from urllib.error import HTTPError, URLError
|
||
from urllib.parse import quote, urlencode
|
||
from urllib.request import Request, urlopen
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# Exceptions
|
||
# ---------------------------------------------------------------------------
|
||
|
||
class TelemtAPIError(Exception):
|
||
"""Raised when the API returns an error envelope or a transport error."""
|
||
|
||
def __init__(self, message: str, code: str | None = None,
|
||
http_status: int | None = None, request_id: int | None = None,
|
||
details: list | None = None, last_response: APIResponse | None = None):
|
||
super().__init__(message)
|
||
self.code = code
|
||
self.http_status = http_status
|
||
self.request_id = request_id
|
||
self.details = details or []
|
||
self.last_response = last_response
|
||
|
||
def __repr__(self) -> str:
|
||
return (f"TelemtAPIError(message={str(self)!r}, code={self.code!r}, "
|
||
f"http_status={self.http_status}, request_id={self.request_id})")
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# Response wrapper
|
||
# ---------------------------------------------------------------------------
|
||
|
||
@dataclass
|
||
class APIResponse:
|
||
"""Wraps a successful API response envelope."""
|
||
ok: bool
|
||
data: Any
|
||
revision: str | None = None
|
||
http_status: int = 200
|
||
|
||
def __repr__(self) -> str: # pragma: no cover
|
||
return (f"APIResponse(ok={self.ok}, http_status={self.http_status}, "
|
||
f"revision={self.revision!r}, data={self.data!r})")
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# Main client
|
||
# ---------------------------------------------------------------------------
|
||
|
||
_UNSET = object()
|
||
|
||
|
||
class TelemtAPI:
|
||
"""
|
||
HTTP client for the Telemt Control API.
|
||
|
||
Parameters
|
||
----------
|
||
base_url:
|
||
Scheme + host + port, e.g. ``"http://127.0.0.1:9091"``.
|
||
Trailing slash is stripped automatically.
|
||
auth_header:
|
||
Exact value for the ``Authorization`` header.
|
||
Leave *None* when ``auth_header`` is not configured server-side.
|
||
timeout:
|
||
Socket timeout in seconds for every request (default 10).
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
base_url: str = "http://127.0.0.1:9091",
|
||
auth_header: str | None = None,
|
||
timeout: float = 10,
|
||
) -> None:
|
||
self.base_url = base_url.rstrip("/")
|
||
self.auth_header = auth_header
|
||
self.timeout = _positive_seconds(timeout, "timeout")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Low-level HTTP helpers
|
||
# ------------------------------------------------------------------
|
||
|
||
def _headers(self, extra: dict | None = None) -> dict:
|
||
# WEB controls require this exact media type without charset parameters.
|
||
h = {"Content-Type": "application/json",
|
||
"Accept": "application/json"}
|
||
if self.auth_header:
|
||
h["Authorization"] = self.auth_header
|
||
if extra:
|
||
h.update(extra)
|
||
return h
|
||
|
||
def _request(
|
||
self,
|
||
method: str,
|
||
path: str,
|
||
body: dict | None = None,
|
||
if_match: str | None = None,
|
||
query: dict | None = None,
|
||
*,
|
||
if_runtime_match: str | None = None,
|
||
success_statuses: tuple[int, ...] = (),
|
||
timeout: float | None = None,
|
||
) -> APIResponse:
|
||
url = self.base_url + path
|
||
if query:
|
||
qs = urlencode(query)
|
||
url = f"{url}?{qs}"
|
||
|
||
raw_body: bytes | None = None
|
||
if body is not None:
|
||
raw_body = json.dumps(body, allow_nan=False).encode("utf-8")
|
||
if method == "POST" and path.startswith("/v1/runtime/web/") and len(raw_body) > 65536:
|
||
raise ValueError("WEB control JSON exceeds 65536 bytes")
|
||
|
||
extra_headers: dict = {}
|
||
if if_match is not None:
|
||
extra_headers["If-Match"] = if_match
|
||
if if_runtime_match is not None:
|
||
extra_headers["If-Runtime-Match"] = if_runtime_match
|
||
|
||
req = Request(
|
||
url,
|
||
data=raw_body,
|
||
headers=self._headers(extra_headers),
|
||
method=method,
|
||
)
|
||
|
||
try:
|
||
request_timeout = self.timeout if timeout is None else min(self.timeout, timeout)
|
||
try:
|
||
response = urlopen(req, timeout=request_timeout)
|
||
except HTTPError as error:
|
||
response = error
|
||
with response:
|
||
status, raw = response.status, response.read()
|
||
except (URLError, OSError, HTTPException) as exc:
|
||
raise TelemtAPIError(str(exc)) from exc
|
||
|
||
try:
|
||
payload = json.loads(raw)
|
||
except (ValueError, UnicodeError) as exc:
|
||
raise TelemtAPIError("Expected a JSON API envelope (empty gray_action responses are not success)",
|
||
code="invalid_response", http_status=status) from exc
|
||
if not isinstance(payload, dict) or not isinstance(payload.get("ok"), bool):
|
||
raise TelemtAPIError("Invalid API envelope", code="invalid_response", http_status=status)
|
||
if not payload["ok"]:
|
||
err = payload.get("error", {})
|
||
if not isinstance(err, dict):
|
||
err = {}
|
||
raise TelemtAPIError(
|
||
err.get("message", "unknown error"),
|
||
code=err.get("code"),
|
||
http_status=status,
|
||
request_id=payload.get("request_id"),
|
||
details=err.get("details"),
|
||
)
|
||
if not (200 <= status < 300 or status in success_statuses) or "data" not in payload:
|
||
raise TelemtAPIError("Unexpected API success response", code="invalid_response", http_status=status)
|
||
|
||
return APIResponse(
|
||
ok=True,
|
||
data=payload.get("data"),
|
||
revision=payload.get("revision"),
|
||
http_status=status,
|
||
)
|
||
|
||
def _get(self, path: str, query: dict | None = None, **options) -> APIResponse:
|
||
return self._request("GET", path, query=query, **options)
|
||
|
||
def _post(self, path: str, body: dict | None = None,
|
||
if_match: str | None = None) -> APIResponse:
|
||
return self._request("POST", path, body=body, if_match=if_match)
|
||
|
||
def _patch(self, path: str, body: dict,
|
||
if_match: str | None = None) -> APIResponse:
|
||
return self._request("PATCH", path, body=body, if_match=if_match)
|
||
|
||
def _delete(self, path: str, if_match: str | None = None) -> APIResponse:
|
||
return self._request("DELETE", path, if_match=if_match)
|
||
|
||
# ------------------------------------------------------------------
|
||
# Health & system
|
||
# ------------------------------------------------------------------
|
||
|
||
def health(self) -> APIResponse:
|
||
"""GET /v1/health — liveness probe."""
|
||
return self._get("/v1/health")
|
||
|
||
def health_ready(self) -> APIResponse:
|
||
"""Return readiness data for both 200 and a documented 503 ok=true response."""
|
||
return self._get("/v1/health/ready", success_statuses=(503,))
|
||
|
||
def capabilities(self) -> APIResponse:
|
||
return self._get("/v1/capabilities")
|
||
|
||
def config_schema(self) -> APIResponse:
|
||
return self._get("/v1/config/schema")
|
||
|
||
def get_config(self) -> APIResponse:
|
||
"""Desired editable configuration; the legacy response can contain credentials."""
|
||
return self._get("/v1/config")
|
||
|
||
def config_state(self, sections: list[str] | None = None) -> APIResponse:
|
||
"""Redacted publication state, including partial results and nullable revision."""
|
||
query = None
|
||
if sections is not None:
|
||
allowed = {"general", "network", "server", "timeouts", "censorship", "upstreams",
|
||
"dc_overrides", "web", "access", "logging", "root"}
|
||
if isinstance(sections, str) or not sections or len(set(sections)) != len(sections) or not set(sections) <= allowed:
|
||
raise ValueError("sections must contain unique known section names")
|
||
query = {"sections": ",".join(sections)}
|
||
return self._get("/v1/config/state", query)
|
||
|
||
def access_policy(self) -> APIResponse:
|
||
"""Desired/published access defaults and CIDR shaping, without credentials."""
|
||
return self._get("/v1/access/policy")
|
||
|
||
def patch_access_policy(self, patch: dict, *, if_match: str | None = None,
|
||
if_runtime_match: str | None = None) -> APIResponse:
|
||
"""Preserve explicit null resets and CIDR entry deletion semantics."""
|
||
_object(patch, "patch")
|
||
return self._request("PATCH", "/v1/access/policy", patch, if_match,
|
||
if_runtime_match=if_runtime_match)
|
||
|
||
def patch_config(self, patch: dict, *, if_match: str | None = None,
|
||
if_runtime_match: str | None = None, reload: str | None = None,
|
||
timeout_secs: int | None = None, failure_policy: str | None = None) -> APIResponse:
|
||
"""Send a sparse patch unchanged; nested nulls keep the server's merge semantics."""
|
||
_object(patch, "patch")
|
||
return self._request("PATCH", "/v1/config", patch, if_match,
|
||
_reload_query(reload, timeout_secs, failure_policy),
|
||
if_runtime_match=if_runtime_match)
|
||
|
||
def validate_config(self, patch: dict, *, if_match: str | None = None,
|
||
if_runtime_match: str | None = None, reload: str | None = None,
|
||
timeout_secs: int | None = None, failure_policy: str | None = None) -> APIResponse:
|
||
"""Prepare a candidate without committing; accepts the same inputs as PATCH."""
|
||
_object(patch, "patch")
|
||
return self._request("POST", "/v1/config/validate", patch, if_match,
|
||
_reload_query(reload, timeout_secs, failure_policy),
|
||
if_runtime_match=if_runtime_match)
|
||
|
||
def reload(self, mode: str = "instant", *, timeout_secs: int | None = None,
|
||
failure_policy: str | None = None, if_match: str | None = None) -> APIResponse:
|
||
body = _reload_query(mode, timeout_secs, failure_policy)
|
||
body["mode"] = body.pop("reload")
|
||
return self._post("/v1/system/reload", body, if_match)
|
||
|
||
def reload_status(self, reload_id: int) -> APIResponse:
|
||
_bounded(reload_id, 0, 2**64 - 1, "reload_id")
|
||
return self._get(f"/v1/system/reload/{reload_id}")
|
||
|
||
def wait_reload(self, reload_id: int, *, timeout: float = 60, poll_interval: float = 0.25,
|
||
expected_revision: str | None = None) -> APIResponse:
|
||
"""Poll an accepted ID; failed/rolled_back are returned as terminal data."""
|
||
_bounded(reload_id, 0, 2**64 - 1, "reload_id")
|
||
def state(response):
|
||
data = _object(response.data, "reload status")
|
||
if data.get("reload_id") != reload_id or (expected_revision is not None and data.get("config_revision") != expected_revision):
|
||
raise TelemtAPIError("Reload identity changed while polling", code="operation_mismatch", last_response=response)
|
||
return data.get("state")
|
||
return _poll(lambda remaining: self._get(f"/v1/system/reload/{reload_id}", timeout=remaining),
|
||
state, {"succeeded", "failed", "rolled_back"},
|
||
{"accepted", "preparing", "activating", "draining"}, timeout, poll_interval)
|
||
|
||
def system_info(self) -> APIResponse:
|
||
"""GET /v1/system/info — binary version, uptime, config hash."""
|
||
return self._get("/v1/system/info")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Runtime gates & initialization
|
||
# ------------------------------------------------------------------
|
||
|
||
def runtime_gates(self) -> APIResponse:
|
||
"""GET /v1/runtime/gates — admission gates and startup progress."""
|
||
return self._get("/v1/runtime/gates")
|
||
|
||
def runtime_initialization(self) -> APIResponse:
|
||
"""GET /v1/runtime/initialization — detailed startup timeline."""
|
||
return self._get("/v1/runtime/initialization")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Limits & security
|
||
# ------------------------------------------------------------------
|
||
|
||
def limits_effective(self) -> APIResponse:
|
||
"""GET /v1/limits/effective — effective timeout/upstream/ME limits."""
|
||
return self._get("/v1/limits/effective")
|
||
|
||
def security_posture(self) -> APIResponse:
|
||
"""GET /v1/security/posture — API auth, telemetry, log-level summary."""
|
||
return self._get("/v1/security/posture")
|
||
|
||
def security_whitelist(self) -> APIResponse:
|
||
"""GET /v1/security/whitelist — current IP whitelist CIDRs."""
|
||
return self._get("/v1/security/whitelist")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Stats
|
||
# ------------------------------------------------------------------
|
||
|
||
def stats_summary(self) -> APIResponse:
|
||
"""GET /v1/stats/summary — uptime, connection totals, user count."""
|
||
return self._get("/v1/stats/summary")
|
||
|
||
def stats_zero_all(self) -> APIResponse:
|
||
"""GET /v1/stats/zero/all — zero-cost counters (core, upstream, ME, pool, desync)."""
|
||
return self._get("/v1/stats/zero/all")
|
||
|
||
def stats_upstreams(self) -> APIResponse:
|
||
"""GET /v1/stats/upstreams — upstream health + zero counters."""
|
||
return self._get("/v1/stats/upstreams")
|
||
|
||
def stats_minimal_all(self) -> APIResponse:
|
||
"""GET /v1/stats/minimal/all — ME writers + DC snapshot (requires minimal_runtime_enabled)."""
|
||
return self._get("/v1/stats/minimal/all")
|
||
|
||
def stats_me_writers(self) -> APIResponse:
|
||
"""GET /v1/stats/me-writers — per-writer ME status (requires minimal_runtime_enabled)."""
|
||
return self._get("/v1/stats/me-writers")
|
||
|
||
def stats_dcs(self) -> APIResponse:
|
||
"""GET /v1/stats/dcs — per-DC coverage and writer counts (requires minimal_runtime_enabled)."""
|
||
return self._get("/v1/stats/dcs")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Runtime deep-dive
|
||
# ------------------------------------------------------------------
|
||
|
||
def runtime_me_pool_state(self) -> APIResponse:
|
||
"""GET /v1/runtime/me_pool_state — ME pool generation/writer/refill snapshot."""
|
||
return self._get("/v1/runtime/me_pool_state")
|
||
|
||
def runtime_me_quality(self) -> APIResponse:
|
||
"""GET /v1/runtime/me_quality — ME KDF, route-drop, and per-DC RTT counters."""
|
||
return self._get("/v1/runtime/me_quality")
|
||
|
||
def runtime_upstream_quality(self) -> APIResponse:
|
||
"""GET /v1/runtime/upstream_quality — per-upstream health, latency, DC preferences."""
|
||
return self._get("/v1/runtime/upstream_quality")
|
||
|
||
def runtime_nat_stun(self) -> APIResponse:
|
||
"""GET /v1/runtime/nat_stun — NAT probe state, STUN servers, reflected IPs."""
|
||
return self._get("/v1/runtime/nat_stun")
|
||
|
||
def runtime_me_selftest(self) -> APIResponse:
|
||
"""GET /v1/runtime/me-selftest — KDF/timeskew/IP/PID/BND health state."""
|
||
return self._get("/v1/runtime/me-selftest")
|
||
|
||
def runtime_connections_summary(self) -> APIResponse:
|
||
"""GET /v1/runtime/connections/summary — live connection totals + top-N users (requires runtime_edge_enabled)."""
|
||
return self._get("/v1/runtime/connections/summary")
|
||
|
||
def runtime_events_recent(self, limit: int | None = None) -> APIResponse:
|
||
"""GET /v1/runtime/events/recent — recent ring-buffer events (requires runtime_edge_enabled).
|
||
|
||
Parameters
|
||
----------
|
||
limit:
|
||
Optional cap on returned events (1–1000, server default 50).
|
||
"""
|
||
if limit is not None:
|
||
_bounded(limit, 1, 1000, "limit")
|
||
query = {"limit": str(limit)} if limit is not None else None
|
||
return self._get("/v1/runtime/events/recent", query=query)
|
||
|
||
def runtime_tls_fingerprints(self, limit: int | None = None) -> APIResponse:
|
||
if limit is not None:
|
||
_bounded(limit, 1, 1000, "limit")
|
||
return self._get("/v1/runtime/tls-fingerprints", {"limit": limit} if limit is not None else None)
|
||
|
||
def users_quota(self) -> APIResponse:
|
||
"""Desired quota/period and effective recurring quota schedule are distinct."""
|
||
return self._get("/v1/stats/users/quota")
|
||
|
||
def users_active_ips(self) -> APIResponse:
|
||
return self._get("/v1/stats/users/active-ips")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Users (read)
|
||
# ------------------------------------------------------------------
|
||
|
||
def list_users(self) -> APIResponse:
|
||
"""GET /v1/users — list all users with connection/traffic info."""
|
||
return self._get("/v1/users")
|
||
|
||
def get_user(self, username: str) -> APIResponse:
|
||
"""GET /v1/users/{username} — single user info."""
|
||
return self._get(f"/v1/users/{_safe(username)}")
|
||
|
||
# ------------------------------------------------------------------
|
||
# Users (write)
|
||
# ------------------------------------------------------------------
|
||
|
||
def create_user(
|
||
self,
|
||
username: str,
|
||
*,
|
||
secret: str | None = None,
|
||
user_ad_tag: str | None = None,
|
||
max_tcp_conns: int | None = None,
|
||
expiration_rfc3339: str | None = None,
|
||
data_quota_bytes: int | None = None,
|
||
max_unique_ips: int | None = None,
|
||
quota_period: str | None = None,
|
||
rate_limit_up_bps: int | None = None,
|
||
rate_limit_down_bps: int | None = None,
|
||
enabled: bool | None = None,
|
||
source_deny: list[str] | None | object = _UNSET,
|
||
if_match: str | None = None,
|
||
) -> APIResponse:
|
||
"""POST /v1/users — create a new user.
|
||
|
||
Parameters
|
||
----------
|
||
username:
|
||
``[A-Za-z0-9_.-]``, length 1–64.
|
||
secret:
|
||
Exactly 32 hex chars. Auto-generated if omitted.
|
||
user_ad_tag:
|
||
Exactly 32 hex chars.
|
||
max_tcp_conns:
|
||
Per-user concurrent TCP limit.
|
||
expiration_rfc3339:
|
||
RFC3339 expiration timestamp, e.g. ``"2025-12-31T23:59:59Z"``.
|
||
data_quota_bytes:
|
||
Per-user traffic quota in bytes.
|
||
max_unique_ips:
|
||
Per-user unique source IP limit.
|
||
quota_period:
|
||
Optional UTC recurring period: daily, weekly or monthly.
|
||
rate_limit_up_bps, rate_limit_down_bps:
|
||
Per-user upload/download bit rates; zero values are transmitted.
|
||
enabled:
|
||
Optional admission flag; False is transmitted.
|
||
source_deny:
|
||
Source CIDRs; omission retains an orphan rule, None removes it.
|
||
Changes require a generation reload.
|
||
if_match:
|
||
Optional ``If-Match`` revision for optimistic concurrency.
|
||
"""
|
||
body: Dict[str, Any] = {"username": username}
|
||
_opt(body, "secret", secret)
|
||
_opt(body, "user_ad_tag", user_ad_tag)
|
||
_opt(body, "max_tcp_conns", max_tcp_conns)
|
||
_opt(body, "expiration_rfc3339", expiration_rfc3339)
|
||
_opt(body, "data_quota_bytes", data_quota_bytes)
|
||
_opt(body, "max_unique_ips", max_unique_ips)
|
||
_opt(body, "quota_period", quota_period)
|
||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||
_opt(body, "enabled", enabled)
|
||
if source_deny is not _UNSET:
|
||
body["source_deny"] = source_deny
|
||
return self._post("/v1/users", body=body, if_match=if_match)
|
||
|
||
def patch_user(
|
||
self,
|
||
username: str,
|
||
*,
|
||
secret: str | None = None,
|
||
user_ad_tag: str | None = None,
|
||
max_tcp_conns: int | None = None,
|
||
expiration_rfc3339: str | None = None,
|
||
data_quota_bytes: int | None = None,
|
||
max_unique_ips: int | None = None,
|
||
quota_period: str | None = None,
|
||
rate_limit_up_bps: int | None = None,
|
||
rate_limit_down_bps: int | None = None,
|
||
enabled: bool | None = None,
|
||
source_deny: list[str] | None = None,
|
||
if_match: str | None = None,
|
||
) -> APIResponse:
|
||
"""PATCH /v1/users/{username} — partial update; only provided fields change.
|
||
|
||
Parameters
|
||
----------
|
||
username:
|
||
Existing username to update.
|
||
secret:
|
||
New secret (32 hex chars).
|
||
user_ad_tag:
|
||
New ad tag (32 hex chars).
|
||
max_tcp_conns:
|
||
New TCP concurrency limit.
|
||
expiration_rfc3339:
|
||
New expiration timestamp.
|
||
data_quota_bytes:
|
||
New quota in bytes.
|
||
max_unique_ips:
|
||
New unique IP limit.
|
||
quota_period, rate_limit_up_bps, rate_limit_down_bps, enabled:
|
||
Recurring quota, bit rates and admission flag. None omits a field,
|
||
preserving the legacy helper contract; use patch_user_fields to clear.
|
||
source_deny:
|
||
Replace the source CIDR list; use patch_user_fields to send null.
|
||
if_match:
|
||
Optional ``If-Match`` revision.
|
||
"""
|
||
body: Dict[str, Any] = {}
|
||
_opt(body, "secret", secret)
|
||
_opt(body, "user_ad_tag", user_ad_tag)
|
||
_opt(body, "max_tcp_conns", max_tcp_conns)
|
||
_opt(body, "expiration_rfc3339", expiration_rfc3339)
|
||
_opt(body, "data_quota_bytes", data_quota_bytes)
|
||
_opt(body, "max_unique_ips", max_unique_ips)
|
||
_opt(body, "quota_period", quota_period)
|
||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||
_opt(body, "enabled", enabled)
|
||
_opt(body, "source_deny", source_deny)
|
||
return self.patch_user_fields(username, body, if_match=if_match)
|
||
|
||
def patch_user_fields(self, username: str, fields: dict, *, if_match: str | None = None) -> APIResponse:
|
||
"""Exact sparse PATCH: omission preserves a field; explicit None sends JSON null.
|
||
|
||
The older patch_user convenience method still omits None-valued arguments.
|
||
Server-specific null semantics apply, including secret:null being ignored.
|
||
"""
|
||
_object(fields, "fields")
|
||
if not fields or not fields.keys() <= USER_FIELDS:
|
||
raise ValueError("patch_user_fields requires at least one known user field")
|
||
return self._patch(f"/v1/users/{_safe(username)}", fields, if_match)
|
||
|
||
def enable_user(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||
return self._post(f"/v1/users/{_safe(username)}/enable", if_match=if_match)
|
||
|
||
def disable_user(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||
return self._post(f"/v1/users/{_safe(username)}/disable", if_match=if_match)
|
||
|
||
def reset_user_quota(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||
return self._post(f"/v1/users/{_safe(username)}/reset-quota", if_match=if_match)
|
||
|
||
def delete_user(
|
||
self,
|
||
username: str,
|
||
*,
|
||
if_match: str | None = None,
|
||
) -> APIResponse:
|
||
"""DELETE /v1/users/{username} — remove user; blocks deletion of last user.
|
||
|
||
Parameters
|
||
----------
|
||
if_match:
|
||
Optional ``If-Match`` revision for optimistic concurrency.
|
||
"""
|
||
return self._delete(f"/v1/users/{_safe(username)}", if_match=if_match)
|
||
|
||
def rotate_secret(
|
||
self,
|
||
username: str,
|
||
*,
|
||
secret: str | None = None,
|
||
if_match: str | None = None,
|
||
) -> APIResponse:
|
||
"""POST /v1/users/{username}/rotate-secret — rotate user secret.
|
||
|
||
Returns the new credential. Owners of the old identity are cancelled;
|
||
watcher publication and existing-session retirement remain asynchronous.
|
||
|
||
Parameters
|
||
----------
|
||
secret:
|
||
New secret (32 hex chars). Auto-generated if omitted.
|
||
"""
|
||
body: Dict[str, Any] = {}
|
||
_opt(body, "secret", secret)
|
||
return self._post(f"/v1/users/{_safe(username)}/rotate-secret",
|
||
body=body or None, if_match=if_match)
|
||
|
||
# ------------------------------------------------------------------
|
||
# WEB runtime: opaque references are always supplied by the caller.
|
||
# ------------------------------------------------------------------
|
||
|
||
def web_status(self) -> APIResponse:
|
||
return self._get("/v1/runtime/web/status")
|
||
|
||
def web_sessions(self, *, limit: int | None = None, cursor: str | None = None,
|
||
session_ref: str | None = None, ip: str | None = None,
|
||
host: str | None = None, user: str | None = None,
|
||
user_agent_id: str | None = None, key_id: str | None = None,
|
||
carrier: str | None = None, state: str | None = None) -> APIResponse:
|
||
if limit is not None:
|
||
_bounded(limit, 1, 200, "limit")
|
||
if session_ref is not None and (cursor is not None or limit is not None):
|
||
raise ValueError("session_ref cannot be combined with cursor or limit")
|
||
query = {key: value for key, value in dict(limit=limit, cursor=cursor, session_ref=session_ref,
|
||
ip=ip, host=host, user=user, user_agent_id=user_agent_id, key_id=key_id,
|
||
carrier=carrier, state=state).items() if value is not None}
|
||
return self._get("/v1/runtime/web/sessions", query)
|
||
|
||
def web_session(self, session_ref: str) -> APIResponse:
|
||
"""A 410 ok=true tombstone is data, with http_status retained."""
|
||
return self._get(f"/v1/runtime/web/sessions/{_safe(session_ref)}", success_statuses=(410,))
|
||
|
||
def web_close_sessions(self, runtime_instance: str, selector: dict) -> APIResponse:
|
||
_object(selector, "selector")
|
||
kind = selector.get("kind")
|
||
if kind == "refs":
|
||
refs = selector.get("session_refs")
|
||
if not isinstance(refs, list) or not all(isinstance(ref, str) for ref in refs) or not 1 <= len(refs) <= 200 or len(set(refs)) != len(refs) or set(selector) != {"kind", "session_refs"}:
|
||
raise ValueError("refs selector requires 1..200 unique session references")
|
||
elif kind == "all":
|
||
if set(selector) != {"kind"}:
|
||
raise ValueError("all selector accepts only kind")
|
||
elif kind == "filter":
|
||
allowed = {"kind", "session_ref", "ip", "host", "user", "user_agent_id", "key_id", "carrier", "state"}
|
||
if not selector.keys() <= allowed or not any(value is not None for key, value in selector.items() if key != "kind"):
|
||
raise ValueError("filter selector requires at least one known non-null filter")
|
||
else:
|
||
raise ValueError("selector.kind must be refs, filter or all")
|
||
return self._post("/v1/runtime/web/sessions/close", {"runtime_instance": runtime_instance, "selector": selector})
|
||
|
||
def web_operation(self, operation_id: str) -> APIResponse:
|
||
return self._get(f"/v1/runtime/web/operations/{_safe(operation_id)}")
|
||
|
||
def wait_web_operation(self, operation_id: str, *, timeout: float = 60, poll_interval: float = 0.25) -> APIResponse:
|
||
path = f"/v1/runtime/web/operations/{_safe(operation_id)}"
|
||
def state(response):
|
||
data = _object(response.data, "WEB operation")
|
||
if data.get("operation_id") != operation_id:
|
||
raise TelemtAPIError("WEB operation identity changed", code="operation_mismatch", last_response=response)
|
||
return data.get("state")
|
||
return _poll(lambda remaining: self._get(path, timeout=remaining), state,
|
||
{"completed", "cancelled", "failed"}, {"queued", "running"}, timeout, poll_interval)
|
||
|
||
def web_debug_clear(self, runtime_instance: str) -> APIResponse:
|
||
return self._post("/v1/runtime/web/debug/clear", {"runtime_instance": runtime_instance})
|
||
|
||
def web_learning_reset(self, runtime_instance: str) -> APIResponse:
|
||
return self._post("/v1/runtime/web/carrier-learning/reset", {"runtime_instance": runtime_instance})
|
||
|
||
def web_pause(self, runtime_instance: str) -> APIResponse:
|
||
return self._post("/v1/runtime/web/lifecycle/pause", {"runtime_instance": runtime_instance})
|
||
|
||
def web_drain(self, runtime_instance: str, timeout_secs: int) -> APIResponse:
|
||
_bounded(timeout_secs, 1, 3600, "timeout_secs")
|
||
return self._post("/v1/runtime/web/lifecycle/drain", {"runtime_instance": runtime_instance, "timeout_secs": timeout_secs})
|
||
|
||
def web_resume(self, runtime_instance: str) -> APIResponse:
|
||
return self._post("/v1/runtime/web/lifecycle/resume", {"runtime_instance": runtime_instance})
|
||
|
||
def wait_web_drain(self, runtime_instance: str, operation_id: str, *,
|
||
timeout: float = 60, poll_interval: float = 0.25) -> APIResponse:
|
||
"""Poll the same drain through WEB status; never substitute a new process or drain."""
|
||
def state(response):
|
||
data = _object(response.data, "WEB status")
|
||
runtime = data.get("runtime") or {}
|
||
drain = (data.get("operator_lifecycle") or {}).get("drain") or {}
|
||
if runtime.get("runtime_instance") != runtime_instance or drain.get("operation_id") != operation_id:
|
||
raise TelemtAPIError("WEB process or drain identity changed", code="operation_mismatch", last_response=response)
|
||
return drain.get("state")
|
||
return _poll(lambda remaining: self._get("/v1/runtime/web/status", timeout=remaining), state,
|
||
{"completed", "cancelled"}, {"draining", "force_closing"}, timeout, poll_interval)
|
||
|
||
# ------------------------------------------------------------------
|
||
# Convenience helpers
|
||
# ------------------------------------------------------------------
|
||
|
||
@staticmethod
|
||
def generate_secret() -> str:
|
||
"""Generate a random 32-character hex secret suitable for user creation."""
|
||
return secrets.token_hex(16) # 16 bytes → 32 hex chars
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# Internal helpers
|
||
# ---------------------------------------------------------------------------
|
||
|
||
USER_FIELDS = {"secret", "user_ad_tag", "max_tcp_conns", "expiration_rfc3339", "data_quota_bytes",
|
||
"quota_period", "rate_limit_up_bps", "rate_limit_down_bps", "max_unique_ips", "enabled", "source_deny"}
|
||
|
||
|
||
def _safe(value: str) -> str:
|
||
"""Keep one opaque path segment from becoming a path, query or fragment."""
|
||
if not isinstance(value, str) or not value or value in (".", "..") or "/" in value or "\\" in value:
|
||
raise ValueError("Expected one nonempty path segment")
|
||
return quote(value, safe="")
|
||
|
||
|
||
def _opt(d: dict, key: str, value: Any) -> None:
|
||
"""Add key to dict only when value is not None."""
|
||
if value is not None:
|
||
d[key] = value
|
||
|
||
|
||
def _object(value, name):
|
||
if not isinstance(value, dict):
|
||
raise ValueError(f"{name} must be a JSON object")
|
||
return value
|
||
|
||
|
||
def _bounded(value, minimum, maximum, name):
|
||
if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
|
||
raise ValueError(f"{name} must be within {minimum}..{maximum}")
|
||
|
||
|
||
def _positive_seconds(value, name):
|
||
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
|
||
raise ValueError(f"{name} must be a finite positive number of seconds")
|
||
return value
|
||
|
||
|
||
def _reload_query(mode, timeout_secs, failure_policy):
|
||
if mode is None:
|
||
if timeout_secs is not None or failure_policy is not None:
|
||
raise ValueError("timeout_secs and failure_policy require reload mode")
|
||
return None
|
||
if mode not in ("instant", "drain"):
|
||
raise ValueError("reload mode must be instant or drain")
|
||
if mode == "drain":
|
||
_bounded(timeout_secs, 1, 3600, "timeout_secs")
|
||
elif timeout_secs is not None:
|
||
raise ValueError("instant reload forbids timeout_secs")
|
||
if failure_policy is not None and failure_policy not in ("keep_new", "rollback"):
|
||
raise ValueError("failure_policy must be keep_new or rollback")
|
||
return {key: value for key, value in dict(reload=mode, timeout_secs=timeout_secs,
|
||
failure_policy=failure_policy).items() if value is not None}
|
||
|
||
|
||
def _poll(fetch, state, terminal, pending, timeout, interval):
|
||
deadline = time.monotonic() + _positive_seconds(timeout, "poll timeout")
|
||
_positive_seconds(interval, "poll interval")
|
||
last = None
|
||
while True:
|
||
remaining = deadline - time.monotonic()
|
||
if remaining <= 0:
|
||
raise TelemtAPIError("Polling budget expired; the server operation was not cancelled",
|
||
code="poll_timeout", last_response=last)
|
||
last = fetch(remaining)
|
||
if time.monotonic() >= deadline:
|
||
raise TelemtAPIError("Polling budget expired; the server operation was not cancelled",
|
||
code="poll_timeout", last_response=last)
|
||
try:
|
||
phase = state(last)
|
||
known = phase in terminal or phase in pending
|
||
except (ValueError, TypeError, AttributeError) as error:
|
||
raise TelemtAPIError("Invalid operation response", code="invalid_response", last_response=last) from error
|
||
if phase in terminal:
|
||
return last
|
||
if not known:
|
||
raise TelemtAPIError("Unknown operation phase", code="invalid_response", last_response=last)
|
||
time.sleep(min(interval, max(0, deadline - time.monotonic())))
|
||
|
||
|
||
def main(argv=None):
|
||
if __package__:
|
||
from .telemt_api_cli import main as cli_main
|
||
else:
|
||
from telemt_api_cli import main as cli_main
|
||
return cli_main(argv)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|