From 55e7b16ec3953a252cd98fef6922d74cbe29c8bb Mon Sep 17 00:00:00 2001 From: Alexey <247128645+axkurcom@users.noreply.github.com> Date: Wed, 4 Nov 2026 06:47:16 +0300 Subject: [PATCH] Tools: Telemt API: implement all JSON API operations with CLI support --- tools/generate_api_openapi.py | 283 +++++++++++++ tools/telemt_api.py | 637 +++++++++++++++-------------- tools/telemt_api_cli.py | 296 ++++++++++++++ tools/tests/http_fixture.py | 53 +++ tools/tests/test_telemt_api.py | 273 +++++++++++++ tools/tests/test_telemt_api_cli.py | 204 +++++++++ 6 files changed, 1439 insertions(+), 307 deletions(-) create mode 100644 tools/generate_api_openapi.py create mode 100644 tools/telemt_api_cli.py create mode 100644 tools/tests/http_fixture.py create mode 100644 tools/tests/test_telemt_api.py create mode 100644 tools/tests/test_telemt_api_cli.py diff --git a/tools/generate_api_openapi.py b/tools/generate_api_openapi.py new file mode 100644 index 0000000..0912e8c --- /dev/null +++ b/tools/generate_api_openapi.py @@ -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() diff --git a/tools/telemt_api.py b/tools/telemt_api.py index 072ca46..b7d58c5 100644 --- a/tools/telemt_api.py +++ b/tools/telemt_api.py @@ -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 Get single user - create [OPTIONS] Create user - patch [OPTIONS] Partial update user - delete Delete user - secret [--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 ") - _print(api.get_user(args.arg)) - - # -- user write ------------------------------------------------------ - elif cmd == "create": - if not args.arg: - parser.error("create command requires ") - 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 ") - 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 ") - 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 ") - _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()) diff --git a/tools/telemt_api_cli.py b/tools/telemt_api_cli.py new file mode 100644 index 0000000..eee196a --- /dev/null +++ b/tools/telemt_api_cli.py @@ -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 diff --git a/tools/tests/http_fixture.py b/tools/tests/http_fixture.py new file mode 100644 index 0000000..08909fc --- /dev/null +++ b/tools/tests/http_fixture.py @@ -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)) diff --git a/tools/tests/test_telemt_api.py b/tools/tests/test_telemt_api.py new file mode 100644 index 0000000..2c72c6b --- /dev/null +++ b/tools/tests/test_telemt_api.py @@ -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"private-source-excerpt", 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() diff --git a/tools/tests/test_telemt_api_cli.py b/tools/tests/test_telemt_api_cli.py new file mode 100644 index 0000000..dd3ff72 --- /dev/null +++ b/tools/tests/test_telemt_api_cli.py @@ -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()