Files
telemt/tools/telemt_api.py
T

753 lines
33 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""
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
# ---------------------------------------------------------------------------
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 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,
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 byte rates; zero values are transmitted.
enabled:
Optional admission flag; False is transmitted.
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)
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,
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, 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.
"""
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)
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"}
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())