Tools: Telemt API: implement all JSON API operations with CLI support

This commit is contained in:
Alexey
2026-11-04 06:47:16 +03:00
parent 996274bed3
commit 55e7b16ec3
6 changed files with 1439 additions and 307 deletions
+283
View File
@@ -0,0 +1,283 @@
#!/usr/bin/env python3
"""Generate/check the versioned Control API route and envelope artifact.
The operation catalog is also consumed by /v1/capabilities. Existing response
payloads remain intentionally unconstrained; API.md defines their detailed DTOs.
"""
import argparse
import json
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
CATALOG = ROOT / "src/api/discovery/operations.json"
OUTPUT = ROOT / "docs/Architecture/API/openapi-v1.json"
def ref(name):
return {"$ref": f"#/components/schemas/{name}"}
def object_schema(properties, required=(), extra=False):
return {"type": "object", "properties": properties,
"required": list(required), "additionalProperties": extra}
def nullable(schema):
return {"anyOf": [schema, {"type": "null"}]}
def build_document():
operations = json.loads(CATALOG.read_text())
string = {"type": "string"}
boolean = {"type": "boolean"}
count = {"type": "integer", "minimum": 0}
secret = {"type": "string", "pattern": "^[0-9A-Fa-f]{32}$"}
username = {"type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$"}
user_properties = {
"secret": nullable(secret), "user_ad_tag": nullable(secret),
"max_tcp_conns": nullable(count),
"expiration_rfc3339": nullable({"type": "string", "format": "date-time"}),
"data_quota_bytes": nullable(count),
"quota_period": nullable({"enum": ["daily", "weekly", "monthly"]}),
"rate_limit_up_bps": nullable(count), "rate_limit_down_bps": nullable(count),
"max_unique_ips": nullable(count), "enabled": nullable(boolean),
}
schemas = {
"SuccessEnvelope": object_schema({"ok": {"const": True}, "data": {},
"revision": string}, ("ok", "data", "revision")),
"ErrorEnvelope": object_schema({
"ok": {"const": False}, "request_id": count,
"error": object_schema({"code": string, "message": string,
"details": {"type": "array", "items": ref("FieldIssue")}}, ("code", "message")),
}, ("ok", "error", "request_id")),
"CreateUserRequest": object_schema({"username": username, **user_properties},
("username",), extra=True),
"PatchUserRequest": object_schema(user_properties, extra=True),
"RotateSecretRequest": object_schema({"secret": nullable(secret)}, extra=True),
"PatchConfigRequest": object_schema({
**{k: nullable({"type": "object"}) for k in
("general", "timeouts", "censorship", "dc_overrides", "web")},
"upstreams": nullable({"type": "array", "items": {"type": "object"}}),
"server": nullable(object_schema({"listeners": nullable({"type": "array", "items": {"type": "object"}})})),
}),
"ReloadRequest": object_schema({
"mode": {"enum": ["instant", "drain"], "default": "instant"},
"timeout_secs": nullable({"type": "integer", "minimum": 1, "maximum": 3600}),
"failure_policy": {"enum": ["keep_new", "rollback"], "default": "keep_new"},
}),
"RuntimeInstanceRequest": object_schema({"runtime_instance": string}, ("runtime_instance",)),
"DrainRequest": object_schema({"runtime_instance": string,
"timeout_secs": {"type": "integer", "minimum": 1, "maximum": 3600}},
("runtime_instance", "timeout_secs")),
"CloseRequest": object_schema({"runtime_instance": string, "selector": {"type": "object"}},
("runtime_instance", "selector")),
}
operation_properties = {
"id": string, "method": {"enum": ["GET", "POST", "PATCH", "DELETE"]},
"path": string, "aliases": {"type": "array", "items": string},
"gate": {"enum": ["always", "minimal", "minimal_me", "middle_proxy", "upstream", "edge", "web_read", "web_control"]},
"success": {"type": "array", "items": {"type": "integer"}},
"credential_bearing": boolean, "body": string, "optional_body": boolean,
"exact_json_content_type": boolean, "if_match": boolean,
"if_runtime_match": boolean, "read_only_operation": boolean,
"supported": boolean, "enabled": boolean, "available": nullable(boolean), "mutable": boolean,
"disabled_reason": string, "unavailable_reason": string, "mutation_blocked_reason": string,
}
schemas["OperationCapability"] = object_schema(operation_properties,
("id", "method", "path", "gate", "success", "credential_bearing", "optional_body",
"exact_json_content_type", "if_match", "if_runtime_match", "read_only_operation",
"supported", "enabled", "available", "mutable"))
schemas["CapabilitiesData"] = object_schema({
"api_version": {"const": "v1"}, "schema_version": {"const": 1}, "software_version": string,
"config_schema": {"const": "/v1/config/schema"}, "openapi_artifact": string,
"read_only": boolean, "availability_scope": string,
"operations": {"type": "array", "items": ref("OperationCapability")},
}, ("api_version", "schema_version", "software_version", "config_schema", "openapi_artifact",
"read_only", "availability_scope", "operations"))
schemas["FieldApi"] = object_schema({
"config_read": boolean, "config_write": boolean,
"read_routes": {"type": "array", "items": string}, "write_routes": {"type": "array", "items": string},
"request_field": string, "non_editable_reason": string, "null_behavior": string,
}, ("config_read", "config_write", "read_routes", "write_routes", "null_behavior"))
schemas["FieldMetadata"] = object_schema({
"path": string, "value": {"type": "object"}, "default": {},
"default_kind": {"enum": ["type_default", "unset", "required", "nested_fields", "map_entry", "redacted"]},
"sensitivity": {"enum": ["public", "deployment", "credential"]}, "description": string,
"aliases": {"type": "array", "items": string}, "unit": string,
"apply": object_schema({"watcher": string, "reload": string, "effect": string},
("watcher", "reload", "effect")),
"dependencies": {"type": "array", "items": string},
"constraints": {"type": "array", "items": string}, "api": ref("FieldApi"),
}, ("path", "value", "default_kind", "sensitivity", "description", "apply", "api"))
schemas["ConfigSchemaData"] = object_schema({
"schema_version": {"const": 1}, "value_schema_dialect": string,
"defaults_scope": string, "validation_scope": string, "path_notation": string,
"config_patch": object_schema({k: string for k in
("objects", "arrays", "object_null_members", "reset", "source_ownership", "if_match")},
("objects", "arrays", "object_null_members", "reset", "source_ownership", "if_match")),
"fields": {"type": "array", "items": ref("FieldMetadata")},
}, ("schema_version", "value_schema_dialect", "defaults_scope", "validation_scope", "path_notation", "config_patch", "fields"))
for name in ("Capabilities", "ConfigSchema"):
schemas[name + "Response"] = object_schema({
"ok": {"const": True}, "data": ref(name + "Data"), "revision": string,
}, ("ok", "data", "revision"))
strings = {"type": "array", "items": string}
schemas["FieldIssue"] = object_schema({"path": string, "code": string, "message": string},
("path", "code", "message"))
schemas["NormalizationEffect"] = object_schema({"path": string,
"code": {"enum": ["normalized", "null_ignored", "alias_canonicalized"]}}, ("path", "code"))
schemas["RuntimeBaseline"] = object_schema({"active_generation": count, "config_epoch": count,
"runtime_match": string}, ("active_generation", "config_epoch", "runtime_match"))
impact = {**{k: strings for k in ("watcher_paths", "generation_paths", "process_restart_paths", "deferred_process_fields")},
**{k: boolean for k in ("restart_required", "runtime_reload_required", "process_restart_required")}}
schemas["ApplyImpact"] = object_schema(impact, impact.keys())
validation = {"valid": {"const": True}, "base_revision": string, "candidate_revision": string,
"runtime": ref("RuntimeBaseline"), "changed_paths": strings,
"normalization_effects": {"type": "array", "items": ref("NormalizationEffect")},
"apply": ref("ApplyImpact"), "source_ownership": {"const": "single_source"},
"touched_sections": strings, "reload": nullable(ref("ReloadRequest")),
"warnings": {"type": "array", "items": ref("FieldIssue")}}
schemas["ConfigValidationData"] = object_schema(validation, validation.keys())
schemas["ConfigValidationResponse"] = object_schema({"ok": {"const": True},
"data": ref("ConfigValidationData"), "revision": string}, ("ok", "data", "revision"))
sections = ["general", "network", "server", "timeouts", "censorship", "upstreams",
"dc_overrides", "web", "access", "logging", "root"]
field_projection = {
"path": {"type": "string", "maxLength": 256}, "value": {}, "redacted": boolean,
"present": boolean, "entries": nullable(count), "differs": nullable(boolean),
"origin": {"enum": ["source", "type_default", "default_or_derived", "inherited",
"runtime_derived", "mixed_unknown", "unknown"]},
"inherited_from": {"const": "network.prefer"},
}
schemas["ConfigFieldProjection"] = object_schema(field_projection,
("path", "redacted", "present", "entries", "differs", "origin"))
projection = {
"fields": {"type": "array", "items": ref("ConfigFieldProjection"), "maxItems": 1024},
"truncated": boolean,
"provenance": {"enum": ["normalized_source", "mixed_publication", "unknown"]},
"source_revision": nullable(string), "source_count": nullable(count),
}
schemas["ConfigProjection"] = object_schema(projection, projection.keys())
comparison = {
"scope": {"const": "selected_sections"},
"status": {"enum": ["unknown", "published_match", "pending_publication", "process_deferred"]},
**{key: {**strings, "maxItems": 512} for key in ("pending_paths", "watcher_pending_paths",
"generation_pending_paths", "process_deferred_paths")},
"deferred_process_fields": strings, "runtime_derived_paths": strings, "truncated": boolean,
}
schemas["ConfigStateComparison"] = object_schema(comparison, comparison.keys())
watcher = {
"sequence": count, "observed_at_epoch_secs": count,
"phase": {"enum": ["initial", "preparing", "unchanged", "retained", "published",
"published_partial", "source_refreshed", "rejected", "publication_failed"]},
"source_revision": nullable(string), "published_config_epoch": nullable(count),
"error_code": nullable(string),
}
schemas["ConfigWatcherObservation"] = object_schema(watcher, watcher.keys())
reload_observation = {
"reload_id": count, "target_generation": count, "source_revision": string,
"phase": {"enum": ["accepted", "preparing", "activating", "draining", "succeeded", "rolled_back", "failed"]},
**{key: nullable(count) for key in ("source_generation", "activated_generation",
"retiring_generation", "retiring_config_epoch")},
"retirement": nullable({"enum": ["retiring", "draining", "retired", "cleanup_timeout"]}),
"error_present": boolean, "warning_count": count,
}
schemas["ConfigReloadObservation"] = object_schema(reload_observation, reload_observation.keys())
state = {
"scope": {"const": "published_configuration_not_subsystem_acknowledgment"},
"sections": {"type": "array", "items": {"enum": sections}, "uniqueItems": True,
"minItems": 1, "maxItems": len(sections)},
"runtime": ref("RuntimeBaseline"), "runtime_sample_current": boolean,
"desired_revision": nullable(string),
"desired_status": {"enum": ["valid", "invalid", "unreadable", "timeout", "busy", "unavailable"]},
"desired_error": nullable(ref("FieldIssue")), "projection_error": nullable(ref("FieldIssue")),
"desired": nullable(ref("ConfigProjection")), "effective": nullable(ref("ConfigProjection")),
"comparison": ref("ConfigStateComparison"),
"watcher": nullable(ref("ConfigWatcherObservation")), "watcher_matches_desired": nullable(boolean),
"reload": nullable(ref("ConfigReloadObservation")), "reload_matches_desired": nullable(boolean),
"reload_observation": {"enum": ["sampled", "busy", "unknown"]},
"subsystem_convergence": {"const": "unknown"},
}
schemas["ConfigStateData"] = object_schema(state, state.keys())
schemas["ConfigStateResponse"] = object_schema({"ok": {"const": True},
"data": ref("ConfigStateData"), "revision": nullable(string)}, ("ok", "data", "revision"))
schemas["PatchConfigRequest"]["description"] = "Sparse merge; object null members are ignored. Unknown nested and inapplicable variant fields are rejected before deserialization. Validate complete candidates on the server. Field metadata: GET /v1/config/schema."
schemas["ReloadRequest"]["description"] = "drain requires timeout_secs; instant forbids a non-null timeout_secs."
paths = {}
for operation in operations:
for path in [operation["path"], *operation.get("aliases", [])]:
alias = path != operation["path"]
parameters = []
for segment in path.split('/'):
if segment.startswith('{'):
parameters.append({"name": segment[1:-1], "in": "path", "required": True,
"schema": {"type": "integer", "minimum": 0} if segment == '{id}' else string})
if operation.get("if_match"):
parameters.append({"name": "If-Match", "in": "header", "required": False,
"schema": string, "description": "Quoted or unquoted source-manifest revision."})
if operation.get("if_runtime_match"):
parameters.append({"name": "If-Runtime-Match", "in": "header", "required": False,
"schema": string, "description": "Optional opaque publication token returned by config/validate or config/state; stale runtime assumptions return 409 runtime_conflict."})
if operation["id"] in ("config_patch", "config_validate"):
parameters.extend({"name": name, "in": "query", "schema": schema} for name, schema in (
("reload", {"enum": ["instant", "drain"]}),
("timeout_secs", {"type": "integer", "minimum": 1, "maximum": 3600}),
("failure_policy", {"enum": ["keep_new", "rollback"]}),
))
if operation["id"] == "config_state":
parameters.append({"name": "sections", "in": "query", "style": "form", "explode": False,
"schema": {"type": "array", "items": {"enum": sections}, "uniqueItems": True,
"minItems": 1, "maxItems": len(sections)},
"description": "Comma-separated sections; omitted selects all. One parameter only, at most 256 query bytes. Snapshots are independently sampled; comparison is not a convergence acknowledgment."})
response_schema = {"capabilities": "CapabilitiesResponse", "config_schema": "ConfigSchemaResponse",
"config_validate": "ConfigValidationResponse",
"config_state": "ConfigStateResponse"}.get(operation["id"], "SuccessEnvelope")
responses = {str(status): {"description": "Success or documented state payload",
"content": {"application/json": {"schema": ref(response_schema)}}}
for status in operation["success"]}
responses["default"] = {"description": "Structured API error; whitelist gray actions may instead drop or return empty HTTP 200.",
"content": {"application/json": {"schema": ref("ErrorEnvelope")}}}
if path == '/web-status':
responses = {"200": {"description": "Authenticated HTML diagnostics", "content": {"text/html": {"schema": string}}},
"default": {"description": "API admission errors are JSON; renderer/query errors may be HTML."}}
entry = {"operationId": operation["id"] + ("_alias" if alias else ""),
"responses": responses, "x-telemt-gate": operation["gate"],
"x-telemt-credential-bearing": operation.get("credential_bearing", False)}
if operation.get("read_only_operation"):
entry["x-telemt-read-only-operation"] = True
entry["description"] = "Authenticated preflight permitted under read_only. Reads DNS/static assets without persistence, publication, reload reservation or listener binding. Two concurrent preparations, 30 second deadline; cancelled workers retain their slot until exit. Apply classifications describe a publication baseline, not subsystem convergence or guaranteed startup."
for status, description in {"409": "Source, runtime or source-ownership conflict.",
"429": "Both preparation slots are occupied.",
"504": "Preparation exceeded 30 seconds."}.items():
responses[status] = {"description": description, "content": {"application/json": {"schema": ref("ErrorEnvelope")}}}
if parameters:entry['parameters'] = parameters
if operation.get('body'):
entry['requestBody'] = {"required": not operation.get('optional_body', False),
"content": {"application/json": {"schema": ref(operation['body'])}}}
entry['x-telemt-exact-json-content-type'] = operation.get('exact_json_content_type', False)
paths.setdefault(path, {})[operation['method'].lower()] = entry
return {"openapi": "3.1.0", "info": {"title": "Telemt Control API", "version": "v1-discovery-1",
"description": "Generated by tools/generate_api_openapi.py. Routes and envelopes are checked against the runtime catalog. Legacy data payload details, query filters and cross-field constraints remain in API.md. Discovery is administrative, not an observer authorization role."},
"security": [{}, {"AuthorizationHeader": []}],
"paths": paths, "components": {"securitySchemes": {"AuthorizationHeader": {
"type": "apiKey", "in": "header", "name": "Authorization",
"description": "Exact configured header value, required only when header authentication is enabled; direct-peer whitelist applies independently."}},
"schemas": schemas}}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--check", action="store_true")
args = parser.parse_args()
rendered = json.dumps(build_document(), indent=2, ensure_ascii=False) + "\n"
if args.check:
if not OUTPUT.is_file() or OUTPUT.read_text() != rendered:
parser.exit(1, f"Outdated artifact: run {Path(__file__).name}\n")
print("OpenAPI artifact matches the operation catalog")
else:
OUTPUT.write_text(rendered)
print(OUTPUT.relative_to(ROOT))
if __name__ == "__main__":
main()
+330 -307
View File
@@ -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())
+296
View File
@@ -0,0 +1,296 @@
"""Argument parsing and output for the standard-library Control API client."""
from __future__ import annotations
import argparse
import json
import sys
from dataclasses import asdict
from pathlib import Path
if __package__:
from .telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS, _positive_seconds
else:
from telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS, _positive_seconds
READ_COMMANDS = {
"health": "health", "ready": "health_ready", "capabilities": "capabilities",
"schema": "config_schema", "config": "get_config", "info": "system_info",
"status": "runtime_gates", "init": "runtime_initialization", "limits": "limits_effective",
"posture": "security_posture", "whitelist": "security_whitelist", "summary": "stats_summary",
"zero": "stats_zero_all", "upstreams": "stats_upstreams", "minimal": "stats_minimal_all",
"me-writers": "stats_me_writers", "dcs": "stats_dcs", "me-pool": "runtime_me_pool_state",
"me-quality": "runtime_me_quality", "upstream-quality": "runtime_upstream_quality",
"nat-stun": "runtime_nat_stun", "me-selftest": "runtime_me_selftest",
"connections": "runtime_connections_summary", "users": "list_users",
"quota": "users_quota", "active-ips": "users_active_ips", "web-status": "web_status",
}
USER_OPTIONS = {
"--secret": ("secret", str), "--ad-tag": ("user_ad_tag", str),
"--max-conns": ("max_tcp_conns", int), "--expires": ("expiration_rfc3339", str),
"--quota": ("data_quota_bytes", int), "--max-ips": ("max_unique_ips", int),
"--quota-period": ("quota_period", str), "--rate-up": ("rate_limit_up_bps", int),
"--rate-down": ("rate_limit_down_bps", int),
}
def _seconds(value):
try:
return _positive_seconds(float(value), "timeout/interval")
except ValueError as error:
raise argparse.ArgumentTypeError(str(error)) from error
def _poll_args(parser, optional=False):
if optional:
parser.add_argument("--wait", action="store_true", help="Poll this accepted operation to a terminal state")
parser.add_argument("--wait-timeout", type=_seconds, default=60, help="Polling budget in seconds (default: 60)")
parser.add_argument("--poll-interval", type=_seconds, default=0.25)
def _reload_args(parser, submission=False):
parser.add_argument("--mode" if submission else "--reload", choices=("instant", "drain"),
default="instant" if submission else None)
parser.add_argument("--timeout-secs", type=int, help="Server drain deadline, 1..3600; forbidden for instant")
parser.add_argument("--failure-policy", choices=("keep_new", "rollback"))
def build_parser():
# SUPPRESS lets common options appear before or after a command without a
# subparser default overwriting a value already supplied to the root parser.
common = argparse.ArgumentParser(add_help=False, argument_default=argparse.SUPPRESS)
common.add_argument("-u", "--url", help="API base URL (default: http://127.0.0.1:9091)")
common.add_argument("-a", "--auth", help="Exact Authorization header value")
common.add_argument("-t", "--timeout", type=_seconds, help="Socket timeout in seconds (default: 10)")
common.add_argument("--if-match", help="Optional source revision for mutations/preflight")
common.add_argument("--json-output", action="store_true", help="Print one JSON envelope including http_status")
parser = argparse.ArgumentParser(prog="telemt_api.py", parents=[common],
description="Telemt Control API CLI. JSON input uses a file or '-' for stdin.",
epilog="Config/user outputs may contain credentials. See docs/Architecture/API/PYTHON_CLIENT.md.")
commands = parser.add_subparsers(dest="command")
def command(name, **options):
return commands.add_parser(name, parents=[common], **options)
command("help", help="Show available commands")
command("gen-secret", help="Generate a new 32-hex secret locally")
for name, method in READ_COMMANDS.items():
command(name, help=method.replace("_", " "))
for name in ("events", "tls-fingerprints"):
command(name).add_argument("--limit", type=int)
command("config-state").add_argument("--sections", help="Comma-separated section names; omission selects all")
for name in ("config-patch", "validate"):
sub = command(name)
sub.add_argument("--json", required=True, metavar="FILE", help="Sparse config object; '-' reads stdin")
sub.add_argument("--if-runtime-match", help="Publication token from state or preflight")
_reload_args(sub)
if name == "config-patch":
_poll_args(sub, optional=True)
sub = command("reload")
_reload_args(sub, submission=True)
_poll_args(sub, optional=True)
for name in ("reload-status", "reload-wait"):
sub = command(name)
sub.add_argument("reload_id", type=int)
if name == "reload-wait":
_poll_args(sub)
sub.add_argument("--expected-revision", help="Accepted operation's config_revision")
for name in ("user", "create", "patch", "delete", "secret", "enable", "disable", "reset-quota"):
sub = command(name)
sub.add_argument("username")
if name in ("create", "patch"):
for option, (field, kind) in USER_OPTIONS.items():
sub.add_argument(option, dest=field, type=kind, default=argparse.SUPPRESS,
**({"choices": ("daily", "weekly", "monthly")} if field == "quota_period" else {}))
enabled = sub.add_mutually_exclusive_group()
enabled.add_argument("--enabled", dest="enabled", action="store_const", const=True, default=argparse.SUPPRESS)
enabled.add_argument("--disabled", dest="enabled", action="store_const", const=False, default=argparse.SUPPRESS)
if name == "patch":
sub.add_argument("--json", metavar="FILE", help="Exact sparse object; cannot be combined with field options")
sub.add_argument("--clear", action="append", choices=sorted(USER_FIELDS - {"secret"}), default=[],
help="Send JSON null for one field (repeatable)")
if name == "secret":
sub.add_argument("--secret", help="32 hex characters; omission asks the server to generate a secret")
sub = command("web-sessions")
sub.add_argument("--limit", type=int)
for name in ("cursor", "session-ref", "ip", "host", "user", "user-agent-id", "key-id", "carrier", "state"):
sub.add_argument("--" + name)
command("web-session").add_argument("session_ref")
for name in ("web-operation", "web-wait", "web-drain-wait"):
sub = command(name)
sub.add_argument("operation_id")
if name != "web-operation":
_poll_args(sub)
if name == "web-drain-wait":
sub.add_argument("--runtime-instance", required=True)
for name in ("web-close", "web-debug-clear", "web-learning-reset", "web-pause", "web-drain", "web-resume"):
sub = command(name)
sub.add_argument("--runtime-instance", required=True, help="Exact process reference copied from WEB status")
if name == "web-close":
sub.add_argument("--selector", required=True, metavar="FILE", help="refs/filter/all selector JSON, or '-' for stdin")
_poll_args(sub, optional=True)
if name == "web-drain":
sub.add_argument("--timeout-secs", required=True, type=int)
_poll_args(sub, optional=True)
return parser
def _json_file(path):
data = json.loads(sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8"))
if not isinstance(data, dict):
raise ValueError("JSON input must be an object")
return data
def _response_field(response, *keys):
value = response.data
for key in keys:
if not isinstance(value, dict) or key not in value:
raise TelemtAPIError("Missing operation metadata", code="invalid_response", last_response=response)
value = value[key]
return value
def _wait_reload(api, response, accepted, options):
if not isinstance(accepted, dict) or not isinstance(accepted.get("config_revision"), str) or isinstance(accepted.get("reload_id"), bool) or not isinstance(accepted.get("reload_id"), int):
raise TelemtAPIError("Invalid accepted reload metadata", code="invalid_response", last_response=response)
return api.wait_reload(accepted["reload_id"], expected_revision=accepted["config_revision"], **options)
def _dispatch(api, args):
command = args.command
revision = getattr(args, "if_match", None)
wait_options = {"timeout": getattr(args, "wait_timeout", 60), "poll_interval": getattr(args, "poll_interval", 0.25)}
if command in READ_COMMANDS:
return getattr(api, READ_COMMANDS[command])()
if command in ("events", "tls-fingerprints"):
method = api.runtime_events_recent if command == "events" else api.runtime_tls_fingerprints
return method(args.limit)
if command == "config-state":
return api.config_state(args.sections.split(",") if args.sections is not None else None)
if command in ("config-patch", "validate"):
method = api.patch_config if command == "config-patch" else api.validate_config
response = method(_json_file(args.json), if_match=revision, if_runtime_match=args.if_runtime_match,
reload=args.reload, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy)
accepted = response.data.get("reload") if isinstance(response.data, dict) else None
if getattr(args, "wait", False) and accepted:
return _wait_reload(api, response, accepted, wait_options)
if getattr(args, "wait", False) and response.http_status == 202:
raise TelemtAPIError("Accepted config patch lacks reload metadata", code="invalid_response", last_response=response)
return response
if command == "reload":
response = api.reload(args.mode, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy, if_match=revision)
if args.wait:
return _wait_reload(api, response, response.data, wait_options)
return response
if command == "reload-status":
return api.reload_status(args.reload_id)
if command == "reload-wait":
return api.wait_reload(args.reload_id, expected_revision=args.expected_revision, **wait_options)
if command == "user":
return api.get_user(args.username)
if command in ("create", "patch"):
fields = {key: value for key, value in vars(args).items() if key in USER_FIELDS}
if command == "create":
return api.create_user(args.username, if_match=revision, **fields)
if args.json:
if fields or args.clear:
raise ValueError("--json cannot be combined with user field options or --clear")
fields = _json_file(args.json)
else:
for name in args.clear:
if name in fields:
raise ValueError("A field cannot be set and cleared together or cleared twice")
fields[name] = None
return api.patch_user_fields(args.username, fields, if_match=revision)
if command in ("delete", "enable", "disable", "reset-quota", "secret"):
method = {"delete": api.delete_user, "enable": api.enable_user, "disable": api.disable_user,
"reset-quota": api.reset_user_quota, "secret": api.rotate_secret}[command]
return method(args.username, if_match=revision, **({"secret": args.secret} if command == "secret" else {}))
if command == "web-sessions":
return api.web_sessions(**{key: getattr(args, key) for key in
("limit", "cursor", "session_ref", "ip", "host", "user", "user_agent_id", "key_id", "carrier", "state")})
if command == "web-session":
return api.web_session(args.session_ref)
if command == "web-operation":
return api.web_operation(args.operation_id)
if command == "web-wait":
return api.wait_web_operation(args.operation_id, **wait_options)
if command == "web-drain-wait":
return api.wait_web_drain(args.runtime_instance, args.operation_id, **wait_options)
if command == "web-close":
response = api.web_close_sessions(args.runtime_instance, _json_file(args.selector))
return api.wait_web_operation(_response_field(response, "operation_id"), **wait_options) if args.wait else response
if command == "web-drain":
response = api.web_drain(args.runtime_instance, args.timeout_secs)
return api.wait_web_drain(args.runtime_instance, _response_field(response, "drain", "operation_id"), **wait_options) if args.wait else response
method = {"web-debug-clear": api.web_debug_clear, "web-learning-reset": api.web_learning_reset,
"web-pause": api.web_pause, "web-resume": api.web_resume}[command]
return method(args.runtime_instance)
def _display(response, args):
if getattr(args, "json_output", False):
print(json.dumps(asdict(response), indent=2))
return
data = response.data
if args.command == "users":
if not data:
print("No users configured.")
else:
fmt = "{:<24} {:>7} {:>14} {}"
print(fmt.format("USERNAME", "CONNS", "OCTETS", "LINKS"))
print("-" * 72)
for user in data:
links = user.get("links") or {}
all_links = sum((links.get(kind) or [] for kind in ("classic", "secure", "tls")), [])
print(fmt.format(user["username"], user.get("current_connections", 0), user.get("total_octets", 0), all_links[0] if all_links else "-"))
elif args.command == "create":
print(f"Created: {data.get('user', {}).get('username')}")
print(f"Secret: {data.get('secret')}")
for kind, links in ((data.get("user") or {}).get("links") or {}).items():
for link in links or []:
print(f"Link ({kind}): {link}")
elif args.command == "delete":
print(f"Deleted: {data}")
else:
print(json.dumps(data, indent=2))
if response.revision is not None:
print(f"# revision: {response.revision}")
if response.http_status != 200:
print(f"# HTTP: {response.http_status}")
def main(argv=None):
parser = build_parser()
args = parser.parse_args(argv)
if args.command in (None, "help"):
parser.print_help()
return 0
if args.command == "gen-secret":
print(TelemtAPI.generate_secret())
return 0
try:
api = TelemtAPI(getattr(args, "url", "http://127.0.0.1:9091"),
auth_header=getattr(args, "auth", None), timeout=getattr(args, "timeout", 10))
response = _dispatch(api, args)
_display(response, args)
if args.command == "ready":
return 0 if response.http_status == 200 and _response_field(response, "ready") is True else 1
data = response.data if isinstance(response.data, dict) else {}
if data.get("state") in ("failed", "rolled_back", "cancelled"):
return 1
if args.command in ("web-drain", "web-drain-wait") and getattr(args, "wait", args.command == "web-drain-wait"):
drain = (data.get("operator_lifecycle") or {}).get("drain") or {}
return 1 if drain.get("state") == "cancelled" else 0
return 0
except TelemtAPIError as error:
request = f" (request_id={error.request_id})" if error.request_id is not None else ""
print(f"API error [{error.http_status}] {error.code}: {error}{request}", file=sys.stderr)
if error.details:
print(json.dumps(error.details), file=sys.stderr)
return 1
except (ValueError, OSError) as error:
print(f"Input error: {error}", file=sys.stderr)
return 2
except KeyboardInterrupt:
return 130
+53
View File
@@ -0,0 +1,53 @@
"""Local scripted HTTP peer for wire-contract tests; no live Telemt is required."""
import json
import threading
from collections import deque
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class MockAPI:
def __init__(self):
self.requests = []
self.responses = deque()
fixture = self
class Handler(BaseHTTPRequestHandler):
def handle_request(self):
raw = self.rfile.read(int(self.headers.get("Content-Length", "0")))
fixture.requests.append({"method": self.command, "path": self.path,
"headers": {key.lower(): self.headers.get_all(key) for key in self.headers},
"body": json.loads(raw) if raw else None, "raw": raw})
if fixture.responses:
status, body, media_type = fixture.responses.popleft()
else:
status, body, media_type = 500, b'{"ok":false,"error":{"code":"unscripted","message":"Unexpected request"}}', "application/json"
self.send_response(status)
self.send_header("Content-Type", media_type)
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
do_GET = do_POST = do_PATCH = do_DELETE = handle_request
def log_message(self, *_args):
pass
self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
self.url = f"http://127.0.0.1:{self.server.server_port}"
self.thread = threading.Thread(target=self.server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True)
def __enter__(self):
self.thread.start()
return self
def __exit__(self, *_args):
self.server.shutdown()
self.server.server_close()
self.thread.join()
def reply(self, data=None, status=200, revision="source-revision"):
self.raw(json.dumps({"ok": True, "data": data, "revision": revision}).encode(), status)
def raw(self, body, status=200, media_type="application/json"):
self.responses.append((status, body, media_type))
+273
View File
@@ -0,0 +1,273 @@
import json
import re
import unittest
from http.client import RemoteDisconnected
from pathlib import Path
from urllib.error import URLError
from urllib.parse import parse_qs, urlsplit
from unittest.mock import patch
from tools.telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS
from http_fixture import MockAPI
INSTANCE = "0123456789abcdef0123456789abcdef"
SESSION = f"ws1.{INSTANCE}.0000000000000001"
OPERATION = f"wo1.{INSTANCE}.0000000000000001"
class ClientTests(unittest.TestCase):
def setUp(self):
self.peer = MockAPI().__enter__()
self.addCleanup(self.peer.__exit__, None, None, None)
self.api = TelemtAPI(self.peer.url, auth_header="Bearer synthetic-test", timeout=2)
def test_all_json_operations_match_the_rust_catalog(self):
reads = {
"health": "health", "health_ready": "health_ready", "capabilities": "capabilities",
"config_schema": "config_schema", "system_info": "system_info", "runtime_gates": "runtime_gates",
"runtime_initialization": "runtime_initialization", "limits_effective": "limits_effective",
"security_posture": "security_posture", "security_whitelist": "security_whitelist",
"stats_summary": "stats_summary", "stats_zero_all": "stats_zero_all", "stats_upstreams": "stats_upstreams",
"stats_minimal_all": "stats_minimal_all", "stats_me_writers": "stats_me_writers", "stats_dcs": "stats_dcs",
"runtime_me_pool_state": "runtime_me_pool_state", "runtime_me_quality": "runtime_me_quality",
"runtime_upstream_quality": "runtime_upstream_quality", "runtime_nat_stun": "runtime_nat_stun",
"runtime_me_selftest": "runtime_me_selftest", "runtime_connections_summary": "runtime_connections_summary",
"runtime_events_recent": "runtime_events_recent", "runtime_tls_fingerprints": "runtime_tls_fingerprints",
"web_status": "web_status", "web_sessions": "web_sessions", "users_active_ips": "users_active_ips",
"users_quota": "users_quota", "config_get": "get_config", "config_state": "config_state", "users_list": "list_users",
}
calls = {key: (method, (), {}, None) for key, method in reads.items()}
calls.update({
"web_session": ("web_session", (SESSION,), {}, None),
"web_sessions_close": ("web_close_sessions", (INSTANCE, {"kind": "refs", "session_refs": [SESSION]}), {}, {"runtime_instance": INSTANCE, "selector": {"kind": "refs", "session_refs": [SESSION]}}),
"web_operation": ("web_operation", (OPERATION,), {}, None),
**{key: (method, (INSTANCE,), {}, {"runtime_instance": INSTANCE}) for key, method in
[("web_debug_clear", "web_debug_clear"), ("web_learning_reset", "web_learning_reset"),
("web_pause", "web_pause"), ("web_resume", "web_resume")]},
"web_drain": ("web_drain", (INSTANCE, 30), {}, {"runtime_instance": INSTANCE, "timeout_secs": 30}),
"config_validate": ("validate_config", ({"general": {"log_level": "debug"}},), {}, {"general": {"log_level": "debug"}}),
"config_patch": ("patch_config", ({"web": {"enabled": False}},), {}, {"web": {"enabled": False}}),
"reload": ("reload", (), {}, {"mode": "instant"}),
"reload_status": ("reload_status", (7,), {}, None),
"users_create": ("create_user", ("alice",), {}, {"username": "alice"}),
"users_get": ("get_user", ("alice",), {}, None),
"users_patch": ("patch_user", ("alice",), {"enabled": False}, {"enabled": False}),
"users_delete": ("delete_user", ("alice",), {}, None),
"users_rotate_secret": ("rotate_secret", ("alice",), {}, None),
"users_enable": ("enable_user", ("alice",), {}, None),
"users_disable": ("disable_user", ("alice",), {}, None),
"users_reset_quota": ("reset_user_quota", ("alice",), {}, None),
})
root = Path(__file__).resolve().parents[2]
catalog = json.loads((root / "src/api/discovery/operations.json").read_text())
self.assertEqual(set(calls), {row["id"] for row in catalog} - {"web_status_html"})
for operation in catalog:
if operation["id"] == "web_status_html":
continue # The HTML viewer is opened in a browser, not decoded as JSON.
with self.subTest(operation=operation["id"]):
method, args, options, body = calls[operation["id"]]
status = operation["success"][0]
self.peer.reply({"fixture": operation["id"]}, status)
response = getattr(self.api, method)(*args, **options)
request = self.peer.requests[-1]
self.assertEqual(request["method"], operation["method"])
self.assertEqual(request["path"], operation["path"].format(username="alice", id=7, session_ref=SESSION, operation_id=OPERATION))
self.assertEqual(request["body"], body)
self.assertEqual(request["headers"]["authorization"], ["Bearer synthetic-test"])
self.assertEqual(request["headers"]["content-type"], ["application/json"])
self.assertEqual(response.http_status, status)
self.assertEqual(response.revision, "source-revision")
def test_exact_user_fields_match_the_versioned_request_contract(self):
root = Path(__file__).resolve().parents[2]
artifact = json.loads((root / "docs/Architecture/API/openapi-v1.json").read_text())
self.assertEqual(USER_FIELDS, set(artifact["components"]["schemas"]["PatchUserRequest"]["properties"]))
def test_config_sparse_body_queries_and_both_preconditions_are_unchanged(self):
body = {"general": {"ad_tag": None, "me_keepalive_enabled": False}, "upstreams": []}
for method in (self.api.validate_config, self.api.patch_config):
self.peer.reply({"reload": {"reload_id": 7}}, 202 if method == self.api.patch_config else 200)
method(body, if_match='"source"', if_runtime_match='"process:1:2"', reload="drain", timeout_secs=30, failure_policy="rollback")
request = self.peer.requests[-1]
self.assertEqual(request["body"], body)
self.assertEqual(parse_qs(urlsplit(request["path"]).query), {"reload": ["drain"], "timeout_secs": ["30"], "failure_policy": ["rollback"]})
self.assertEqual(request["headers"]["if-match"], ['"source"'])
self.assertEqual(request["headers"]["if-runtime-match"], ['"process:1:2"'])
def test_null_false_zero_and_legacy_none_omission(self):
self.peer.reply({})
fields = {"data_quota_bytes": None, "quota_period": None, "rate_limit_up_bps": 0, "enabled": False}
self.api.patch_user_fields("alice", fields, if_match="rev")
self.assertEqual(self.peer.requests[-1]["body"], fields)
self.peer.reply({})
self.api.patch_user("alice", max_tcp_conns=None, data_quota_bytes=0, enabled=False, rate_limit_down_bps=0)
self.assertEqual(self.peer.requests[-1]["body"], {"data_quota_bytes": 0, "enabled": False, "rate_limit_down_bps": 0})
self.peer.reply({})
self.api.create_user("alice", enabled=False, quota_period="weekly", rate_limit_up_bps=0, rate_limit_down_bps=12)
self.assertEqual(self.peer.requests[-1]["body"], {"username": "alice", "enabled": False, "quota_period": "weekly", "rate_limit_up_bps": 0, "rate_limit_down_bps": 12})
def test_rotation_controls_preserve_revision_and_real_http_status(self):
for method in (self.api.enable_user, self.api.disable_user, self.api.reset_user_quota, self.api.delete_user, self.api.rotate_secret):
self.peer.reply({"in_runtime": False}, 202)
response = method("alice", if_match="source-rev")
self.assertEqual(response.http_status, 202)
self.assertEqual(self.peer.requests[-1]["headers"]["if-match"], ["source-rev"])
self.peer.reply({"secret": "0" * 32})
self.api.rotate_secret("alice", secret="0" * 32)
self.assertEqual(self.peer.requests[-1]["body"], {"secret": "0" * 32})
def test_ready_503_and_web_410_are_data_only_on_the_documented_routes(self):
for status, method, args, data in [(503, self.api.health_ready, (), {"ready": False}),
(410, self.api.web_session, (SESSION,), {"state": "closed", "reason": "timeout"})]:
self.peer.reply(data, status)
response = method(*args)
self.assertEqual(response.data, data)
self.assertEqual(response.http_status, status)
self.peer.reply(data, status)
with self.assertRaises(TelemtAPIError):
self.api.health()
self.peer.raw(b'{"ok":false,"error":{"code":"web_snapshot_busy","message":"busy"}}', 503)
with self.assertRaises(TelemtAPIError) as raised:
self.api.health_ready()
self.assertEqual(raised.exception.code, "web_snapshot_busy")
def test_error_envelope_retains_details_and_request_id(self):
details = [{"path": "web.debug", "code": "effective_config_invalid", "message": "retained capacity"}]
self.peer.raw(json.dumps({"ok": False, "error": {"code": "bad_request", "message": "invalid", "details": details}, "request_id": 42}).encode(), 400)
with self.assertRaises(TelemtAPIError) as raised:
self.api.validate_config({})
error = raised.exception
self.assertEqual((error.http_status, error.code, error.request_id, error.details), (400, "bad_request", 42, details))
self.assertEqual(len(self.peer.requests), 1)
def test_gray_and_malformed_responses_are_structured_errors_without_raw_contents(self):
for raw in (b"", b"<html>private-source-excerpt</html>", b"[]", b'{"ok":"true"}', b'{"ok":true}'):
self.peer.raw(raw)
with self.assertRaises(TelemtAPIError) as raised:
self.api.health()
self.assertEqual(raised.exception.code, "invalid_response")
self.assertEqual(raised.exception.http_status, 200)
self.assertNotIn("private-source-excerpt", str(raised.exception))
def test_transport_failure_never_resubmits_a_mutation(self):
for failure in (URLError("unreachable"), TimeoutError("socket timed out"),
RemoteDisconnected("connection closed after submission")):
with self.subTest(failure=type(failure).__name__), patch("tools.telemt_api.urlopen", side_effect=failure) as request:
with self.assertRaises(TelemtAPIError) as raised:
self.api.reload()
self.assertIs(raised.exception.__cause__, failure)
self.assertEqual(request.call_count, 1)
self.assertEqual(request.call_args.args[0].get_method(), "POST")
self.assertEqual(self.peer.requests, [])
def test_documented_python_examples_run_against_the_http_contract(self):
root = Path(__file__).resolve().parents[2]
guide = (root / "docs/Architecture/API/PYTHON_CLIENT.md").read_text()
examples = re.findall(r"^```python\n(.*?)^```", guide, re.M | re.S)
self.assertEqual(len(examples), 3)
self.peer.reply({"username": "alice"})
self.peer.reply({"base_revision": "source", "runtime": {"runtime_match": "publication"}})
self.peer.reply({"reload": {"reload_id": 7, "config_revision": "target"}}, 202)
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "succeeded"})
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}})
self.peer.reply({"sessions": [{"session_ref": SESSION}]})
self.peer.reply({"operation_id": OPERATION}, 202)
self.peer.reply({"operation_id": OPERATION, "state": "completed"})
self.peer.reply({"drain": {"operation_id": "wd1.synthetic"}}, 202)
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}, "operator_lifecycle": {
"drain": {"operation_id": "wd1.synthetic", "state": "completed"}}})
namespace = {}
with patch("tools.telemt_api.TelemtAPI", return_value=self.api):
for example in examples:
exec(compile(example, "PYTHON_CLIENT.md", "exec"), namespace)
self.assertEqual(len(self.peer.requests), 10)
self.assertEqual(len(self.peer.responses), 0)
self.assertEqual(self.peer.requests[0]["body"]["quota_period"], None)
self.assertEqual(self.peer.requests[2]["headers"]["if-runtime-match"], ["publication"])
self.assertEqual(self.peer.requests[6]["body"]["runtime_instance"], INSTANCE)
self.assertEqual(self.peer.requests[6]["body"]["selector"]["session_refs"], [SESSION])
def test_query_and_path_values_cannot_inject_parameters(self):
self.peer.reply({})
self.api.web_sessions(user="alice&limit=200", host="a+b.example", ip="::1", cursor=SESSION, limit=1)
self.assertEqual(parse_qs(urlsplit(self.peer.requests[-1]["path"]).query),
{"user": ["alice&limit=200"], "host": ["a+b.example"], "ip": ["::1"], "cursor": [SESSION], "limit": ["1"]})
self.peer.reply({})
self.api.get_user("alice?admin=true#fragment")
self.assertEqual(self.peer.requests[-1]["path"], "/v1/users/alice%3Fadmin%3Dtrue%23fragment")
def test_state_scopes_nullable_revision_and_unknown_convergence_are_preserved(self):
data = {"desired_status": "unreadable", "subsystem_convergence": "unknown", "effective": {"fields": []}}
self.peer.reply(data, revision=None)
response = self.api.config_state(["web", "access"])
self.assertIsNone(response.revision)
self.assertEqual(response.data, data)
self.assertEqual(parse_qs(urlsplit(self.peer.requests[-1]["path"]).query), {"sections": ["web,access"]})
def test_invalid_bounds_and_combinations_send_nothing(self):
cases = [lambda: self.api.reload("instant", timeout_secs=1), lambda: self.api.reload("drain"),
lambda: self.api.reload("drain", timeout_secs=3601), lambda: self.api.reload(failure_policy="retry"),
lambda: self.api.patch_config({}, timeout_secs=2), lambda: self.api.patch_config([]),
lambda: self.api.web_sessions(limit=201), lambda: self.api.web_sessions(session_ref=SESSION, limit=1),
lambda: self.api.runtime_tls_fingerprints(0), lambda: self.api.runtime_events_recent(True),
lambda: self.api.web_drain(INSTANCE, 0), lambda: self.api.web_close_sessions(INSTANCE, {"kind": "filter"}),
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "refs", "session_refs": [SESSION] * 2}),
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "all", "user": "alice"}),
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "filter", "host": "x" * 70000}),
lambda: self.api.config_state([]), lambda: self.api.config_state(["web", "web"]),
lambda: self.api.get_user("../alice"), lambda: self.api.patch_user_fields("alice", {"typo": 1})]
for call in cases:
with self.subTest(call=call), self.assertRaises(ValueError):
call()
self.assertEqual(self.peer.requests, [])
def test_polling_reaches_every_reload_and_web_terminal_state_without_mutation(self):
for terminal in ("succeeded", "failed", "rolled_back"):
for phase in ("accepted", "preparing", "activating", "draining", terminal):
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": phase})
response = self.api.wait_reload(7, expected_revision="target", poll_interval=0.001)
self.assertEqual(response.data["state"], terminal)
for terminal in ("completed", "cancelled", "failed"):
for phase in ("queued", "running", terminal):
self.peer.reply({"operation_id": OPERATION, "state": phase})
response = self.api.wait_web_operation(OPERATION, poll_interval=0.001)
self.assertEqual(response.data["state"], terminal)
self.assertTrue(all(request["method"] == "GET" for request in self.peer.requests))
def test_drain_polling_preserves_process_and_operation_identity(self):
for phase in ("draining", "force_closing", "completed"):
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}, "operator_lifecycle": {"drain": {"operation_id": "wd1.synthetic", "state": phase}}})
response = self.api.wait_web_drain(INSTANCE, "wd1.synthetic", poll_interval=0.001)
self.assertEqual(response.data["operator_lifecycle"]["drain"]["state"], "completed")
self.peer.reply({"runtime": {"runtime_instance": "f" * 32}, "operator_lifecycle": {"drain": {"operation_id": "wd1.synthetic", "state": "completed"}}})
with self.assertRaises(TelemtAPIError) as raised:
self.api.wait_web_drain(INSTANCE, "wd1.synthetic")
self.assertEqual(raised.exception.code, "operation_mismatch")
def test_polling_rejects_reused_reload_ids_and_unknown_or_malformed_status(self):
for data, code in [({"reload_id": 7, "config_revision": "different", "state": "succeeded"}, "operation_mismatch"),
({"reload_id": 7, "config_revision": "target", "state": "invented"}, "invalid_response"),
(None, "invalid_response")]:
self.peer.reply(data)
with self.assertRaises(TelemtAPIError) as raised:
self.api.wait_reload(7, expected_revision="target")
self.assertEqual(raised.exception.code, code)
def test_poll_budget_caps_each_request_and_keeps_last_response(self):
clock = [0.0]
def sleep(seconds):
clock[0] += seconds
for _ in range(2):
self.peer.reply({"reload_id": 7, "state": "preparing"})
with patch("tools.telemt_api.time.monotonic", side_effect=lambda: clock[0]), patch("tools.telemt_api.time.sleep", side_effect=sleep), patch("tools.telemt_api.urlopen", wraps=__import__("urllib.request", fromlist=["urlopen"]).urlopen) as request:
with self.assertRaises(TelemtAPIError) as raised:
self.api.wait_reload(7, timeout=0.5, poll_interval=0.3)
self.assertEqual(raised.exception.code, "poll_timeout")
self.assertEqual(raised.exception.last_response.data["state"], "preparing")
self.assertEqual([call.kwargs["timeout"] for call in request.call_args_list], [0.5, 0.2])
self.assertEqual(len(self.peer.requests), 2)
if __name__ == "__main__":
unittest.main()
+204
View File
@@ -0,0 +1,204 @@
import contextlib
import io
import json
import os
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch
from urllib.parse import parse_qs, urlsplit
from tools.telemt_api_cli import main
from http_fixture import MockAPI
INSTANCE = "0123456789abcdef0123456789abcdef"
SESSION = f"ws1.{INSTANCE}.0000000000000001"
OPERATION = f"wo1.{INSTANCE}.0000000000000001"
class CLITests(unittest.TestCase):
def setUp(self):
self.peer = MockAPI().__enter__()
self.addCleanup(self.peer.__exit__, None, None, None)
self.directory = tempfile.TemporaryDirectory()
self.addCleanup(self.directory.cleanup)
def run_cli(self, arguments, stdin=""):
output, errors = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors), patch("sys.stdin", io.StringIO(stdin)):
try:
code = main(["--url", self.peer.url, "--auth", "Bearer synthetic-test", "--json-output", *arguments])
except SystemExit as error:
code = error.code
return code, output.getvalue(), errors.getvalue()
def json_file(self, value):
path = Path(self.directory.name) / "request.json"
path.write_text(json.dumps(value))
return str(path)
def test_user_patch_sends_explicit_zero_false_and_null(self):
self.peer.reply({"username": "alice", "enabled": False}, 202)
result = self.run_cli(["patch", "alice", "--quota", "0", "--disabled", "--clear", "quota_period",
"--rate-up", "0", "--rate-down", "10", "--if-match", "source"])
self.assertEqual(result[0], 0, result[2])
self.assertEqual(json.loads(result[1])["http_status"], 202)
self.assertEqual(self.peer.requests[-1]["body"], {"data_quota_bytes": 0, "enabled": False, "quota_period": None,
"rate_limit_up_bps": 0, "rate_limit_down_bps": 10})
self.assertEqual(self.peer.requests[-1]["headers"]["if-match"], ["source"])
def test_patch_exact_json_from_stdin_and_ambiguous_inputs_are_rejected(self):
body = {"expiration_rfc3339": None, "enabled": False}
self.peer.reply({})
self.assertEqual(self.run_cli(["patch", "alice", "--json", "-"], json.dumps(body))[0], 0)
self.assertEqual(self.peer.requests[-1]["body"], body)
for arguments in (["patch", "alice", "--json", "-", "--quota", "1"],
["patch", "alice", "--quota", "0", "--clear", "data_quota_bytes"],
["patch", "alice", "--clear", "quota_period", "--clear", "quota_period"],
["patch", "alice"], ["config-patch", "--json", "-"],
["web-close", "--selector", "-"], ["reload", "--wait", "--wait-timeout", "0"]):
with self.subTest(arguments=arguments):
self.assertEqual(self.run_cli(arguments, "[]")[0], 2)
self.assertEqual(len(self.peer.requests), 1)
def test_config_validation_and_commit_preserve_headers_and_policy(self):
body = {"general": {"me_keepalive_enabled": False}, "web": {"vhosts": []}}
path = self.json_file(body)
for command in ("validate", "config-patch"):
self.peer.reply({"valid": True, "reload": None})
result = self.run_cli([command, "--json", path, "--if-match", '"rev"', "--if-runtime-match", "opaque",
"--reload", "drain", "--timeout-secs", "12", "--failure-policy", "rollback"])
self.assertEqual(result[0], 0, result[2])
request = self.peer.requests[-1]
self.assertEqual(request["body"], body)
self.assertEqual(request["headers"]["if-match"], ['"rev"'])
self.assertEqual(request["headers"]["if-runtime-match"], ["opaque"])
self.assertEqual(parse_qs(urlsplit(request["path"]).query), {"reload": ["drain"], "timeout_secs": ["12"], "failure_policy": ["rollback"]})
def test_reload_waits_for_terminal_state_and_reports_failure(self):
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "accepted"}, 202)
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "draining"})
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "rolled_back", "error": "synthetic failure"})
result = self.run_cli(["reload", "--mode", "drain", "--timeout-secs", "10", "--failure-policy", "rollback", "--wait", "--poll-interval", "0.001"])
self.assertEqual(result[0], 1, result[2])
self.assertEqual(json.loads(result[1])["data"]["state"], "rolled_back")
self.assertEqual([request["method"] for request in self.peer.requests], ["POST", "GET", "GET"])
self.assertEqual(self.peer.requests[0]["body"], {"mode": "drain", "timeout_secs": 10, "failure_policy": "rollback"})
def test_config_wait_only_polls_an_operation_actually_accepted(self):
self.peer.reply({"reload": {"reload_id": 9, "config_revision": "target"}}, 202)
self.peer.reply({"reload_id": 9, "config_revision": "target", "state": "succeeded"})
result = self.run_cli(["config-patch", "--json", "-", "--reload", "instant", "--wait"], '{}')
self.assertEqual(result[0], 0, result[2])
self.assertEqual([request["path"] for request in self.peer.requests], ["/v1/config?reload=instant", "/v1/system/reload/9"])
self.peer.reply({"process_restart_required": True})
self.assertEqual(self.run_cli(["config-patch", "--json", "-", "--wait"], '{}')[0], 0)
self.assertEqual(len(self.peer.requests), 3)
def test_web_controls_use_exact_media_type_and_caller_process_reference(self):
cases = [("web-debug-clear", [], "/debug/clear"), ("web-learning-reset", [], "/carrier-learning/reset"),
("web-pause", [], "/lifecycle/pause"), ("web-resume", [], "/lifecycle/resume"),
("web-drain", ["--timeout-secs", "30"], "/lifecycle/drain"),
("web-close", ["--selector", "-"], "/sessions/close")]
for command, options, suffix in cases:
self.peer.reply({"state": "accepted"}, 202 if command in ("web-drain", "web-close") else 200)
result = self.run_cli([command, "--runtime-instance", INSTANCE, *options], '{"kind":"refs","session_refs":["' + SESSION + '"]}')
self.assertEqual(result[0], 0, result[2])
request = self.peer.requests[-1]
self.assertEqual(request["headers"]["content-type"], ["application/json"])
self.assertEqual(request["path"], "/v1/runtime/web" + suffix)
self.assertEqual(request["body"]["runtime_instance"], INSTANCE)
def test_web_close_wait_and_cancelled_drain_wait(self):
self.peer.reply({"operation_id": OPERATION, "state": "queued"}, 202)
self.peer.reply({"operation_id": OPERATION, "state": "completed"})
result = self.run_cli(["web-close", "--runtime-instance", INSTANCE, "--selector", "-", "--wait"], '{"kind":"all"}')
self.assertEqual(result[0], 0, result[2])
self.assertEqual(self.peer.requests[-1]["path"], "/v1/runtime/web/operations/" + OPERATION)
self.peer.reply({"drain": {"operation_id": "wd1.synthetic", "state": "draining"}}, 202)
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}, "operator_lifecycle": {"drain": {"operation_id": "wd1.synthetic", "state": "cancelled"}}})
result = self.run_cli(["web-drain", "--runtime-instance", INSTANCE, "--timeout-secs", "10", "--wait"])
self.assertEqual(result[0], 1, result[2])
self.assertEqual(self.peer.requests[-1]["path"], "/v1/runtime/web/status")
def test_readiness_503_is_failure_but_retained_tombstone_is_readable(self):
self.peer.reply({"ready": False, "reason": "admission_closed"}, 503)
code, output, errors = self.run_cli(["ready"])
self.assertEqual(code, 1, errors)
self.assertEqual(json.loads(output)["http_status"], 503)
self.peer.reply({"state": "closed", "reason": "timeout"}, 410)
code, output, errors = self.run_cli(["web-session", SESSION])
self.assertEqual(code, 0, errors)
self.assertEqual(json.loads(output)["http_status"], 410)
def test_error_details_are_visible_and_transport_does_not_retry_mutations(self):
self.peer.raw(b'{"ok":false,"error":{"code":"runtime_conflict","message":"stale","details":[{"path":"$","code":"runtime_conflict","message":"retry preview"}]},"request_id":9}', 409)
code, output, errors = self.run_cli(["config-patch", "--json", "-"], '{}')
self.assertEqual(code, 1)
self.assertEqual(output, "")
self.assertIn("runtime_conflict", errors)
self.assertIn("retry preview", errors)
self.assertIn("request_id=9", errors)
self.assertEqual(len(self.peer.requests), 1)
def test_missing_accepted_metadata_does_not_trigger_a_new_mutation(self):
for args, stdin in [(["reload", "--wait"], ""),
(["config-patch", "--json", "-", "--wait"], '{}'),
(["web-close", "--runtime-instance", INSTANCE, "--selector", "-", "--wait"], '{"kind":"all"}'),
(["web-drain", "--runtime-instance", INSTANCE, "--timeout-secs", "10", "--wait"], "")]:
self.peer.reply({}, 202)
code, _, errors = self.run_cli(args, stdin)
self.assertEqual(code, 1, errors)
self.assertIn("invalid_response", errors)
self.assertEqual(len(self.peer.requests), 4)
def test_new_read_commands_send_their_documented_query_scope(self):
for args, path, query in [(["capabilities"], "/v1/capabilities", {}),
(["schema"], "/v1/config/schema", {}),
(["config"], "/v1/config", {}),
(["config-state", "--sections", "web,access"], "/v1/config/state", {"sections": ["web,access"]}),
(["quota"], "/v1/stats/users/quota", {}),
(["active-ips"], "/v1/stats/users/active-ips", {}),
(["tls-fingerprints", "--limit", "1"], "/v1/runtime/tls-fingerprints", {"limit": ["1"]}),
(["web-sessions", "--limit", "1", "--user", "a&b"], "/v1/runtime/web/sessions", {"limit": ["1"], "user": ["a&b"]}),
(["web-operation", OPERATION], "/v1/runtime/web/operations/" + OPERATION, {}),
(["reload-status", "7"], "/v1/system/reload/7", {})]:
self.peer.reply({})
result = self.run_cli(args)
self.assertEqual(result[0], 0, result[2])
request = self.peer.requests[-1]
self.assertEqual(request["method"], "GET")
self.assertEqual(urlsplit(request["path"]).path, path)
self.assertEqual(parse_qs(urlsplit(request["path"]).query), query)
def test_global_options_work_on_either_side_of_the_command(self):
self.peer.reply({"status": "ok"})
self.assertEqual(self.run_cli(["health", "--url", self.peer.url, "--auth", "Bearer later", "--timeout", "0.5"])[0], 0)
self.assertEqual(self.peer.requests[-1]["headers"]["authorization"], ["Bearer later"])
self.peer.reply({"status": "ok"})
self.assertEqual(self.run_cli(["health"])[0], 0)
self.assertEqual(self.peer.requests[-1]["headers"]["authorization"], ["Bearer synthetic-test"])
def test_old_command_names_and_actual_script_and_module_entrypoints(self):
for invocation in ([sys.executable, "tools/telemt_api.py"], [sys.executable, "-m", "tools.telemt_api"]):
self.peer.reply({"status": "ok"})
result = subprocess.run([*invocation, "health", "--url", self.peer.url, "--json-output"],
capture_output=True, text=True, timeout=5,
cwd=Path(__file__).resolve().parents[2], env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"})
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(json.loads(result.stdout)["data"], {"status": "ok"})
for command, options, expected in [("create", ["alice", "--quota-period", "daily", "--disabled"], "/v1/users"),
("secret", ["alice"], "/v1/users/alice/rotate-secret"),
("enable", ["alice"], "/v1/users/alice/enable"),
("disable", ["alice"], "/v1/users/alice/disable"),
("reset-quota", ["alice"], "/v1/users/alice/reset-quota")]:
self.peer.reply({"user": {"username": "alice"}})
self.assertEqual(self.run_cli([command, *options])[0], 0)
self.assertEqual(self.peer.requests[-1]["path"], expected)
if __name__ == "__main__":
unittest.main()