mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
Tools: Telemt API: implement all JSON API operations with CLI support
This commit is contained in:
+330
-307
@@ -1,6 +1,6 @@
|
||||
"""
|
||||
Telemt Control API Python Client
|
||||
Full-coverage client for https://github.com/telemt/telemt
|
||||
Standard-library JSON client and CLI for Telemt's Control API.
|
||||
|
||||
Usage:
|
||||
client = TelemtAPI("http://127.0.0.1:9091", auth_header="your-secret")
|
||||
@@ -13,10 +13,14 @@ Usage:
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import math
|
||||
import secrets
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Dict, List, Optional, Union
|
||||
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
|
||||
|
||||
|
||||
@@ -28,11 +32,14 @@ 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):
|
||||
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}, "
|
||||
@@ -49,9 +56,11 @@ class APIResponse:
|
||||
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}, revision={self.revision!r}, data={self.data!r})"
|
||||
return (f"APIResponse(ok={self.ok}, http_status={self.http_status}, "
|
||||
f"revision={self.revision!r}, data={self.data!r})")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
@@ -78,18 +87,19 @@ class TelemtAPI:
|
||||
self,
|
||||
base_url: str = "http://127.0.0.1:9091",
|
||||
auth_header: str | None = None,
|
||||
timeout: int = 10,
|
||||
timeout: float = 10,
|
||||
) -> None:
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.auth_header = auth_header
|
||||
self.timeout = timeout
|
||||
self.timeout = _positive_seconds(timeout, "timeout")
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Low-level HTTP helpers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _headers(self, extra: dict | None = None) -> dict:
|
||||
h = {"Content-Type": "application/json; charset=utf-8",
|
||||
# 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
|
||||
@@ -104,19 +114,27 @@ class TelemtAPI:
|
||||
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 = "&".join(f"{k}={v}" for k, v in query.items())
|
||||
qs = urlencode(query)
|
||||
url = f"{url}?{qs}"
|
||||
|
||||
raw_body: bytes | None = None
|
||||
if body is not None:
|
||||
raw_body = json.dumps(body).encode()
|
||||
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,
|
||||
@@ -126,42 +144,46 @@ class TelemtAPI:
|
||||
)
|
||||
|
||||
try:
|
||||
with urlopen(req, timeout=self.timeout) as resp:
|
||||
payload = json.loads(resp.read())
|
||||
except HTTPError as exc:
|
||||
raw = exc.read()
|
||||
request_timeout = self.timeout if timeout is None else min(self.timeout, timeout)
|
||||
try:
|
||||
payload = json.loads(raw)
|
||||
except Exception:
|
||||
raise TelemtAPIError(
|
||||
str(exc), http_status=exc.code
|
||||
) from exc
|
||||
err = payload.get("error", {})
|
||||
raise TelemtAPIError(
|
||||
err.get("message", str(exc)),
|
||||
code=err.get("code"),
|
||||
http_status=exc.code,
|
||||
request_id=payload.get("request_id"),
|
||||
) from exc
|
||||
except URLError as exc:
|
||||
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
|
||||
|
||||
if not payload.get("ok"):
|
||||
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) -> APIResponse:
|
||||
return self._request("GET", path, query=query)
|
||||
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:
|
||||
@@ -182,6 +204,72 @@ class TelemtAPI:
|
||||
"""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 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")
|
||||
@@ -278,9 +366,23 @@ class TelemtAPI:
|
||||
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)
|
||||
# ------------------------------------------------------------------
|
||||
@@ -307,6 +409,10 @@ class TelemtAPI:
|
||||
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,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""POST /v1/users — create a new user.
|
||||
@@ -327,6 +433,12 @@ class TelemtAPI:
|
||||
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 byte rates; zero values are transmitted.
|
||||
enabled:
|
||||
Optional admission flag; False is transmitted.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision for optimistic concurrency.
|
||||
"""
|
||||
@@ -337,6 +449,10 @@ class TelemtAPI:
|
||||
_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)
|
||||
return self._post("/v1/users", body=body, if_match=if_match)
|
||||
|
||||
def patch_user(
|
||||
@@ -349,6 +465,10 @@ class TelemtAPI:
|
||||
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,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""PATCH /v1/users/{username} — partial update; only provided fields change.
|
||||
@@ -369,6 +489,9 @@ class TelemtAPI:
|
||||
New quota in bytes.
|
||||
max_unique_ips:
|
||||
New unique IP limit.
|
||||
quota_period, rate_limit_up_bps, rate_limit_down_bps, enabled:
|
||||
Recurring quota, byte rates and admission flag. None omits a field,
|
||||
preserving the legacy helper contract; use patch_user_fields to clear.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision.
|
||||
"""
|
||||
@@ -379,10 +502,31 @@ class TelemtAPI:
|
||||
_opt(body, "expiration_rfc3339", expiration_rfc3339)
|
||||
_opt(body, "data_quota_bytes", data_quota_bytes)
|
||||
_opt(body, "max_unique_ips", max_unique_ips)
|
||||
if not body:
|
||||
raise ValueError("patch_user: at least one field must be provided")
|
||||
return self._patch(f"/v1/users/{_safe(username)}", body=body,
|
||||
if_match=if_match)
|
||||
_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)
|
||||
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,
|
||||
@@ -399,9 +543,6 @@ class TelemtAPI:
|
||||
"""
|
||||
return self._delete(f"/v1/users/{_safe(username)}", if_match=if_match)
|
||||
|
||||
# NOTE: POST /v1/users/{username}/rotate-secret currently returns 404
|
||||
# in the route matcher (documented limitation). The method is provided
|
||||
# for completeness and future compatibility.
|
||||
def rotate_secret(
|
||||
self,
|
||||
username: str,
|
||||
@@ -411,10 +552,8 @@ class TelemtAPI:
|
||||
) -> APIResponse:
|
||||
"""POST /v1/users/{username}/rotate-secret — rotate user secret.
|
||||
|
||||
.. warning::
|
||||
This endpoint currently returns ``404 not_found`` in all released
|
||||
versions (documented route matcher limitation). The method is
|
||||
included for future compatibility.
|
||||
Returns the new credential. Owners of the old identity are cancelled;
|
||||
watcher publication and existing-session retirement remain asynchronous.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
@@ -426,6 +565,91 @@ class TelemtAPI:
|
||||
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
|
||||
# ------------------------------------------------------------------
|
||||
@@ -440,11 +664,15 @@ class TelemtAPI:
|
||||
# Internal helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _safe(username: str) -> str:
|
||||
"""Minimal guard: reject obvious path-injection attempts."""
|
||||
if "/" in username or "\\" in username:
|
||||
raise ValueError(f"Invalid username: {username!r}")
|
||||
return username
|
||||
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"}
|
||||
|
||||
|
||||
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:
|
||||
@@ -453,277 +681,72 @@ def _opt(d: dict, key: str, value: Any) -> None:
|
||||
d[key] = value
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# CLI
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _print(resp: APIResponse) -> None:
|
||||
print(json.dumps(resp.data, indent=2))
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}", flush=True)
|
||||
def _object(value, name):
|
||||
if not isinstance(value, dict):
|
||||
raise ValueError(f"{name} must be a JSON object")
|
||||
return value
|
||||
|
||||
|
||||
def _build_parser():
|
||||
import argparse
|
||||
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}")
|
||||
|
||||
p = argparse.ArgumentParser(
|
||||
prog="telemt_api.py",
|
||||
description="Telemt Control API CLI",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog="""
|
||||
COMMANDS (read)
|
||||
health Liveness check
|
||||
info System info (version, uptime, config hash)
|
||||
status Runtime gates + startup progress
|
||||
init Runtime initialization timeline
|
||||
limits Effective limits (timeouts, upstream, ME)
|
||||
posture Security posture summary
|
||||
whitelist IP whitelist entries
|
||||
summary Stats summary (conns, uptime, users)
|
||||
zero Zero-cost counters (core/upstream/ME/pool/desync)
|
||||
upstreams Upstream health + zero counters
|
||||
minimal ME writers + DC snapshot [minimal_runtime_enabled]
|
||||
me-writers Per-writer ME status [minimal_runtime_enabled]
|
||||
dcs Per-DC coverage [minimal_runtime_enabled]
|
||||
me-pool ME pool generation/writer/refill snapshot
|
||||
me-quality ME KDF, route-drops, per-DC RTT
|
||||
upstream-quality Per-upstream health + latency
|
||||
nat-stun NAT probe state + STUN servers
|
||||
me-selftest KDF/timeskew/IP/PID/BND health
|
||||
connections Live connection totals + top-N [runtime_edge_enabled]
|
||||
events [--limit N] Recent ring-buffer events [runtime_edge_enabled]
|
||||
|
||||
COMMANDS (users)
|
||||
users List all users
|
||||
user <username> Get single user
|
||||
create <username> [OPTIONS] Create user
|
||||
patch <username> [OPTIONS] Partial update user
|
||||
delete <username> Delete user
|
||||
secret <username> [--secret S] Rotate secret (reserved; returns 404 in current release)
|
||||
gen-secret Print a random 32-hex secret and exit
|
||||
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
|
||||
|
||||
USER OPTIONS (for create / patch)
|
||||
--secret S 32 hex chars
|
||||
--ad-tag S 32 hex chars (ad tag)
|
||||
--max-conns N Max concurrent TCP connections
|
||||
--expires DATETIME RFC3339 expiration (e.g. 2026-12-31T23:59:59Z)
|
||||
--quota N Data quota in bytes
|
||||
--max-ips N Max unique source IPs
|
||||
|
||||
EXAMPLES
|
||||
telemt_api.py health
|
||||
telemt_api.py -u http://10.0.0.1:9091 -a mysecret users
|
||||
telemt_api.py create alice --max-conns 5 --quota 10000000000
|
||||
telemt_api.py patch alice --expires 2027-01-01T00:00:00Z
|
||||
telemt_api.py delete alice
|
||||
telemt_api.py events --limit 20
|
||||
""",
|
||||
)
|
||||
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}
|
||||
|
||||
p.add_argument("-u", "--url", default="http://127.0.0.1:9091",
|
||||
metavar="URL", help="API base URL (default: http://127.0.0.1:9091)")
|
||||
p.add_argument("-a", "--auth", default=None, metavar="TOKEN",
|
||||
help="Authorization header value")
|
||||
p.add_argument("-t", "--timeout", type=int, default=10, metavar="SEC",
|
||||
help="Request timeout in seconds (default: 10)")
|
||||
|
||||
p.add_argument("command", nargs="?", default="help",
|
||||
help="Command to run (see COMMANDS below)")
|
||||
p.add_argument("arg", nargs="?", default=None, metavar="USERNAME",
|
||||
help="Username for user commands")
|
||||
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())))
|
||||
|
||||
# user create/patch fields
|
||||
p.add_argument("--secret", default=None)
|
||||
p.add_argument("--ad-tag", dest="ad_tag", default=None)
|
||||
p.add_argument("--max-conns", dest="max_conns", type=int, default=None)
|
||||
p.add_argument("--expires", default=None)
|
||||
p.add_argument("--quota", type=int, default=None)
|
||||
p.add_argument("--max-ips", dest="max_ips", type=int, default=None)
|
||||
|
||||
# events
|
||||
p.add_argument("--limit", type=int, default=None,
|
||||
help="Max events for `events` command")
|
||||
|
||||
# optimistic concurrency
|
||||
p.add_argument("--if-match", dest="if_match", default=None,
|
||||
metavar="REVISION", help="If-Match revision header")
|
||||
|
||||
return p
|
||||
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__":
|
||||
import sys
|
||||
|
||||
parser = _build_parser()
|
||||
args = parser.parse_args()
|
||||
|
||||
cmd = (args.command or "help").lower()
|
||||
|
||||
if cmd in ("help", "--help"):
|
||||
parser.print_help()
|
||||
sys.exit(0)
|
||||
|
||||
if cmd == "gen-secret":
|
||||
print(TelemtAPI.generate_secret())
|
||||
sys.exit(0)
|
||||
|
||||
api = TelemtAPI(args.url, auth_header=args.auth, timeout=args.timeout)
|
||||
|
||||
try:
|
||||
# -- read endpoints --------------------------------------------------
|
||||
if cmd == "health":
|
||||
_print(api.health())
|
||||
|
||||
elif cmd == "info":
|
||||
_print(api.system_info())
|
||||
|
||||
elif cmd == "status":
|
||||
_print(api.runtime_gates())
|
||||
|
||||
elif cmd == "init":
|
||||
_print(api.runtime_initialization())
|
||||
|
||||
elif cmd == "limits":
|
||||
_print(api.limits_effective())
|
||||
|
||||
elif cmd == "posture":
|
||||
_print(api.security_posture())
|
||||
|
||||
elif cmd == "whitelist":
|
||||
_print(api.security_whitelist())
|
||||
|
||||
elif cmd == "summary":
|
||||
_print(api.stats_summary())
|
||||
|
||||
elif cmd == "zero":
|
||||
_print(api.stats_zero_all())
|
||||
|
||||
elif cmd == "upstreams":
|
||||
_print(api.stats_upstreams())
|
||||
|
||||
elif cmd == "minimal":
|
||||
_print(api.stats_minimal_all())
|
||||
|
||||
elif cmd == "me-writers":
|
||||
_print(api.stats_me_writers())
|
||||
|
||||
elif cmd == "dcs":
|
||||
_print(api.stats_dcs())
|
||||
|
||||
elif cmd == "me-pool":
|
||||
_print(api.runtime_me_pool_state())
|
||||
|
||||
elif cmd == "me-quality":
|
||||
_print(api.runtime_me_quality())
|
||||
|
||||
elif cmd == "upstream-quality":
|
||||
_print(api.runtime_upstream_quality())
|
||||
|
||||
elif cmd == "nat-stun":
|
||||
_print(api.runtime_nat_stun())
|
||||
|
||||
elif cmd == "me-selftest":
|
||||
_print(api.runtime_me_selftest())
|
||||
|
||||
elif cmd == "connections":
|
||||
_print(api.runtime_connections_summary())
|
||||
|
||||
elif cmd == "events":
|
||||
_print(api.runtime_events_recent(limit=args.limit))
|
||||
|
||||
# -- user read -------------------------------------------------------
|
||||
elif cmd == "users":
|
||||
resp = api.list_users()
|
||||
users = resp.data or []
|
||||
if not users:
|
||||
print("No users configured.")
|
||||
else:
|
||||
fmt = "{:<24} {:>7} {:>14} {}"
|
||||
print(fmt.format("USERNAME", "CONNS", "OCTETS", "LINKS"))
|
||||
print("-" * 72)
|
||||
for u in users:
|
||||
links = (u.get("links") or {})
|
||||
all_links = (links.get("classic") or []) + \
|
||||
(links.get("secure") or []) + \
|
||||
(links.get("tls") or [])
|
||||
link_str = all_links[0] if all_links else "-"
|
||||
print(fmt.format(
|
||||
u["username"],
|
||||
u.get("current_connections", 0),
|
||||
u.get("total_octets", 0),
|
||||
link_str,
|
||||
))
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "user":
|
||||
if not args.arg:
|
||||
parser.error("user command requires <username>")
|
||||
_print(api.get_user(args.arg))
|
||||
|
||||
# -- user write ------------------------------------------------------
|
||||
elif cmd == "create":
|
||||
if not args.arg:
|
||||
parser.error("create command requires <username>")
|
||||
resp = api.create_user(
|
||||
args.arg,
|
||||
secret=args.secret,
|
||||
user_ad_tag=args.ad_tag,
|
||||
max_tcp_conns=args.max_conns,
|
||||
expiration_rfc3339=args.expires,
|
||||
data_quota_bytes=args.quota,
|
||||
max_unique_ips=args.max_ips,
|
||||
if_match=args.if_match,
|
||||
)
|
||||
d = resp.data or {}
|
||||
print(f"Created: {d.get('user', {}).get('username')}")
|
||||
print(f"Secret: {d.get('secret')}")
|
||||
links = (d.get("user") or {}).get("links") or {}
|
||||
for kind, lst in links.items():
|
||||
for link in (lst or []):
|
||||
print(f"Link ({kind}): {link}")
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "patch":
|
||||
if not args.arg:
|
||||
parser.error("patch command requires <username>")
|
||||
if not any([args.secret, args.ad_tag, args.max_conns,
|
||||
args.expires, args.quota, args.max_ips]):
|
||||
parser.error(
|
||||
"patch requires at least one field (--secret, --max-conns, --expires, --quota, --max-ips, --ad-tag)")
|
||||
_print(api.patch_user(
|
||||
args.arg,
|
||||
secret=args.secret,
|
||||
user_ad_tag=args.ad_tag,
|
||||
max_tcp_conns=args.max_conns,
|
||||
expiration_rfc3339=args.expires,
|
||||
data_quota_bytes=args.quota,
|
||||
max_unique_ips=args.max_ips,
|
||||
if_match=args.if_match,
|
||||
))
|
||||
|
||||
elif cmd == "delete":
|
||||
if not args.arg:
|
||||
parser.error("delete command requires <username>")
|
||||
resp = api.delete_user(args.arg, if_match=args.if_match)
|
||||
print(f"Deleted: {resp.data}")
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "secret":
|
||||
if not args.arg:
|
||||
parser.error("secret command requires <username>")
|
||||
_print(api.rotate_secret(args.arg, secret=args.secret,
|
||||
if_match=args.if_match))
|
||||
|
||||
else:
|
||||
print(f"Unknown command: {cmd!r}\nRun with 'help' to see available commands.",
|
||||
file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
except TelemtAPIError as exc:
|
||||
print(f"API error [{exc.http_status}] {exc.code}: {exc}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
except KeyboardInterrupt:
|
||||
sys.exit(130)
|
||||
raise SystemExit(main())
|
||||
|
||||
Reference in New Issue
Block a user