mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
Tools: Telemt API: implement all JSON API operations with CLI support
This commit is contained in:
@@ -0,0 +1,283 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate/check the versioned Control API route and envelope artifact.
|
||||
|
||||
The operation catalog is also consumed by /v1/capabilities. Existing response
|
||||
payloads remain intentionally unconstrained; API.md defines their detailed DTOs.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
CATALOG = ROOT / "src/api/discovery/operations.json"
|
||||
OUTPUT = ROOT / "docs/Architecture/API/openapi-v1.json"
|
||||
|
||||
|
||||
def ref(name):
|
||||
return {"$ref": f"#/components/schemas/{name}"}
|
||||
|
||||
|
||||
def object_schema(properties, required=(), extra=False):
|
||||
return {"type": "object", "properties": properties,
|
||||
"required": list(required), "additionalProperties": extra}
|
||||
|
||||
|
||||
def nullable(schema):
|
||||
return {"anyOf": [schema, {"type": "null"}]}
|
||||
|
||||
|
||||
def build_document():
|
||||
operations = json.loads(CATALOG.read_text())
|
||||
string = {"type": "string"}
|
||||
boolean = {"type": "boolean"}
|
||||
count = {"type": "integer", "minimum": 0}
|
||||
secret = {"type": "string", "pattern": "^[0-9A-Fa-f]{32}$"}
|
||||
username = {"type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$"}
|
||||
user_properties = {
|
||||
"secret": nullable(secret), "user_ad_tag": nullable(secret),
|
||||
"max_tcp_conns": nullable(count),
|
||||
"expiration_rfc3339": nullable({"type": "string", "format": "date-time"}),
|
||||
"data_quota_bytes": nullable(count),
|
||||
"quota_period": nullable({"enum": ["daily", "weekly", "monthly"]}),
|
||||
"rate_limit_up_bps": nullable(count), "rate_limit_down_bps": nullable(count),
|
||||
"max_unique_ips": nullable(count), "enabled": nullable(boolean),
|
||||
}
|
||||
schemas = {
|
||||
"SuccessEnvelope": object_schema({"ok": {"const": True}, "data": {},
|
||||
"revision": string}, ("ok", "data", "revision")),
|
||||
"ErrorEnvelope": object_schema({
|
||||
"ok": {"const": False}, "request_id": count,
|
||||
"error": object_schema({"code": string, "message": string,
|
||||
"details": {"type": "array", "items": ref("FieldIssue")}}, ("code", "message")),
|
||||
}, ("ok", "error", "request_id")),
|
||||
"CreateUserRequest": object_schema({"username": username, **user_properties},
|
||||
("username",), extra=True),
|
||||
"PatchUserRequest": object_schema(user_properties, extra=True),
|
||||
"RotateSecretRequest": object_schema({"secret": nullable(secret)}, extra=True),
|
||||
"PatchConfigRequest": object_schema({
|
||||
**{k: nullable({"type": "object"}) for k in
|
||||
("general", "timeouts", "censorship", "dc_overrides", "web")},
|
||||
"upstreams": nullable({"type": "array", "items": {"type": "object"}}),
|
||||
"server": nullable(object_schema({"listeners": nullable({"type": "array", "items": {"type": "object"}})})),
|
||||
}),
|
||||
"ReloadRequest": object_schema({
|
||||
"mode": {"enum": ["instant", "drain"], "default": "instant"},
|
||||
"timeout_secs": nullable({"type": "integer", "minimum": 1, "maximum": 3600}),
|
||||
"failure_policy": {"enum": ["keep_new", "rollback"], "default": "keep_new"},
|
||||
}),
|
||||
"RuntimeInstanceRequest": object_schema({"runtime_instance": string}, ("runtime_instance",)),
|
||||
"DrainRequest": object_schema({"runtime_instance": string,
|
||||
"timeout_secs": {"type": "integer", "minimum": 1, "maximum": 3600}},
|
||||
("runtime_instance", "timeout_secs")),
|
||||
"CloseRequest": object_schema({"runtime_instance": string, "selector": {"type": "object"}},
|
||||
("runtime_instance", "selector")),
|
||||
}
|
||||
operation_properties = {
|
||||
"id": string, "method": {"enum": ["GET", "POST", "PATCH", "DELETE"]},
|
||||
"path": string, "aliases": {"type": "array", "items": string},
|
||||
"gate": {"enum": ["always", "minimal", "minimal_me", "middle_proxy", "upstream", "edge", "web_read", "web_control"]},
|
||||
"success": {"type": "array", "items": {"type": "integer"}},
|
||||
"credential_bearing": boolean, "body": string, "optional_body": boolean,
|
||||
"exact_json_content_type": boolean, "if_match": boolean,
|
||||
"if_runtime_match": boolean, "read_only_operation": boolean,
|
||||
"supported": boolean, "enabled": boolean, "available": nullable(boolean), "mutable": boolean,
|
||||
"disabled_reason": string, "unavailable_reason": string, "mutation_blocked_reason": string,
|
||||
}
|
||||
schemas["OperationCapability"] = object_schema(operation_properties,
|
||||
("id", "method", "path", "gate", "success", "credential_bearing", "optional_body",
|
||||
"exact_json_content_type", "if_match", "if_runtime_match", "read_only_operation",
|
||||
"supported", "enabled", "available", "mutable"))
|
||||
schemas["CapabilitiesData"] = object_schema({
|
||||
"api_version": {"const": "v1"}, "schema_version": {"const": 1}, "software_version": string,
|
||||
"config_schema": {"const": "/v1/config/schema"}, "openapi_artifact": string,
|
||||
"read_only": boolean, "availability_scope": string,
|
||||
"operations": {"type": "array", "items": ref("OperationCapability")},
|
||||
}, ("api_version", "schema_version", "software_version", "config_schema", "openapi_artifact",
|
||||
"read_only", "availability_scope", "operations"))
|
||||
schemas["FieldApi"] = object_schema({
|
||||
"config_read": boolean, "config_write": boolean,
|
||||
"read_routes": {"type": "array", "items": string}, "write_routes": {"type": "array", "items": string},
|
||||
"request_field": string, "non_editable_reason": string, "null_behavior": string,
|
||||
}, ("config_read", "config_write", "read_routes", "write_routes", "null_behavior"))
|
||||
schemas["FieldMetadata"] = object_schema({
|
||||
"path": string, "value": {"type": "object"}, "default": {},
|
||||
"default_kind": {"enum": ["type_default", "unset", "required", "nested_fields", "map_entry", "redacted"]},
|
||||
"sensitivity": {"enum": ["public", "deployment", "credential"]}, "description": string,
|
||||
"aliases": {"type": "array", "items": string}, "unit": string,
|
||||
"apply": object_schema({"watcher": string, "reload": string, "effect": string},
|
||||
("watcher", "reload", "effect")),
|
||||
"dependencies": {"type": "array", "items": string},
|
||||
"constraints": {"type": "array", "items": string}, "api": ref("FieldApi"),
|
||||
}, ("path", "value", "default_kind", "sensitivity", "description", "apply", "api"))
|
||||
schemas["ConfigSchemaData"] = object_schema({
|
||||
"schema_version": {"const": 1}, "value_schema_dialect": string,
|
||||
"defaults_scope": string, "validation_scope": string, "path_notation": string,
|
||||
"config_patch": object_schema({k: string for k in
|
||||
("objects", "arrays", "object_null_members", "reset", "source_ownership", "if_match")},
|
||||
("objects", "arrays", "object_null_members", "reset", "source_ownership", "if_match")),
|
||||
"fields": {"type": "array", "items": ref("FieldMetadata")},
|
||||
}, ("schema_version", "value_schema_dialect", "defaults_scope", "validation_scope", "path_notation", "config_patch", "fields"))
|
||||
for name in ("Capabilities", "ConfigSchema"):
|
||||
schemas[name + "Response"] = object_schema({
|
||||
"ok": {"const": True}, "data": ref(name + "Data"), "revision": string,
|
||||
}, ("ok", "data", "revision"))
|
||||
strings = {"type": "array", "items": string}
|
||||
schemas["FieldIssue"] = object_schema({"path": string, "code": string, "message": string},
|
||||
("path", "code", "message"))
|
||||
schemas["NormalizationEffect"] = object_schema({"path": string,
|
||||
"code": {"enum": ["normalized", "null_ignored", "alias_canonicalized"]}}, ("path", "code"))
|
||||
schemas["RuntimeBaseline"] = object_schema({"active_generation": count, "config_epoch": count,
|
||||
"runtime_match": string}, ("active_generation", "config_epoch", "runtime_match"))
|
||||
impact = {**{k: strings for k in ("watcher_paths", "generation_paths", "process_restart_paths", "deferred_process_fields")},
|
||||
**{k: boolean for k in ("restart_required", "runtime_reload_required", "process_restart_required")}}
|
||||
schemas["ApplyImpact"] = object_schema(impact, impact.keys())
|
||||
validation = {"valid": {"const": True}, "base_revision": string, "candidate_revision": string,
|
||||
"runtime": ref("RuntimeBaseline"), "changed_paths": strings,
|
||||
"normalization_effects": {"type": "array", "items": ref("NormalizationEffect")},
|
||||
"apply": ref("ApplyImpact"), "source_ownership": {"const": "single_source"},
|
||||
"touched_sections": strings, "reload": nullable(ref("ReloadRequest")),
|
||||
"warnings": {"type": "array", "items": ref("FieldIssue")}}
|
||||
schemas["ConfigValidationData"] = object_schema(validation, validation.keys())
|
||||
schemas["ConfigValidationResponse"] = object_schema({"ok": {"const": True},
|
||||
"data": ref("ConfigValidationData"), "revision": string}, ("ok", "data", "revision"))
|
||||
sections = ["general", "network", "server", "timeouts", "censorship", "upstreams",
|
||||
"dc_overrides", "web", "access", "logging", "root"]
|
||||
field_projection = {
|
||||
"path": {"type": "string", "maxLength": 256}, "value": {}, "redacted": boolean,
|
||||
"present": boolean, "entries": nullable(count), "differs": nullable(boolean),
|
||||
"origin": {"enum": ["source", "type_default", "default_or_derived", "inherited",
|
||||
"runtime_derived", "mixed_unknown", "unknown"]},
|
||||
"inherited_from": {"const": "network.prefer"},
|
||||
}
|
||||
schemas["ConfigFieldProjection"] = object_schema(field_projection,
|
||||
("path", "redacted", "present", "entries", "differs", "origin"))
|
||||
projection = {
|
||||
"fields": {"type": "array", "items": ref("ConfigFieldProjection"), "maxItems": 1024},
|
||||
"truncated": boolean,
|
||||
"provenance": {"enum": ["normalized_source", "mixed_publication", "unknown"]},
|
||||
"source_revision": nullable(string), "source_count": nullable(count),
|
||||
}
|
||||
schemas["ConfigProjection"] = object_schema(projection, projection.keys())
|
||||
comparison = {
|
||||
"scope": {"const": "selected_sections"},
|
||||
"status": {"enum": ["unknown", "published_match", "pending_publication", "process_deferred"]},
|
||||
**{key: {**strings, "maxItems": 512} for key in ("pending_paths", "watcher_pending_paths",
|
||||
"generation_pending_paths", "process_deferred_paths")},
|
||||
"deferred_process_fields": strings, "runtime_derived_paths": strings, "truncated": boolean,
|
||||
}
|
||||
schemas["ConfigStateComparison"] = object_schema(comparison, comparison.keys())
|
||||
watcher = {
|
||||
"sequence": count, "observed_at_epoch_secs": count,
|
||||
"phase": {"enum": ["initial", "preparing", "unchanged", "retained", "published",
|
||||
"published_partial", "source_refreshed", "rejected", "publication_failed"]},
|
||||
"source_revision": nullable(string), "published_config_epoch": nullable(count),
|
||||
"error_code": nullable(string),
|
||||
}
|
||||
schemas["ConfigWatcherObservation"] = object_schema(watcher, watcher.keys())
|
||||
reload_observation = {
|
||||
"reload_id": count, "target_generation": count, "source_revision": string,
|
||||
"phase": {"enum": ["accepted", "preparing", "activating", "draining", "succeeded", "rolled_back", "failed"]},
|
||||
**{key: nullable(count) for key in ("source_generation", "activated_generation",
|
||||
"retiring_generation", "retiring_config_epoch")},
|
||||
"retirement": nullable({"enum": ["retiring", "draining", "retired", "cleanup_timeout"]}),
|
||||
"error_present": boolean, "warning_count": count,
|
||||
}
|
||||
schemas["ConfigReloadObservation"] = object_schema(reload_observation, reload_observation.keys())
|
||||
state = {
|
||||
"scope": {"const": "published_configuration_not_subsystem_acknowledgment"},
|
||||
"sections": {"type": "array", "items": {"enum": sections}, "uniqueItems": True,
|
||||
"minItems": 1, "maxItems": len(sections)},
|
||||
"runtime": ref("RuntimeBaseline"), "runtime_sample_current": boolean,
|
||||
"desired_revision": nullable(string),
|
||||
"desired_status": {"enum": ["valid", "invalid", "unreadable", "timeout", "busy", "unavailable"]},
|
||||
"desired_error": nullable(ref("FieldIssue")), "projection_error": nullable(ref("FieldIssue")),
|
||||
"desired": nullable(ref("ConfigProjection")), "effective": nullable(ref("ConfigProjection")),
|
||||
"comparison": ref("ConfigStateComparison"),
|
||||
"watcher": nullable(ref("ConfigWatcherObservation")), "watcher_matches_desired": nullable(boolean),
|
||||
"reload": nullable(ref("ConfigReloadObservation")), "reload_matches_desired": nullable(boolean),
|
||||
"reload_observation": {"enum": ["sampled", "busy", "unknown"]},
|
||||
"subsystem_convergence": {"const": "unknown"},
|
||||
}
|
||||
schemas["ConfigStateData"] = object_schema(state, state.keys())
|
||||
schemas["ConfigStateResponse"] = object_schema({"ok": {"const": True},
|
||||
"data": ref("ConfigStateData"), "revision": nullable(string)}, ("ok", "data", "revision"))
|
||||
schemas["PatchConfigRequest"]["description"] = "Sparse merge; object null members are ignored. Unknown nested and inapplicable variant fields are rejected before deserialization. Validate complete candidates on the server. Field metadata: GET /v1/config/schema."
|
||||
schemas["ReloadRequest"]["description"] = "drain requires timeout_secs; instant forbids a non-null timeout_secs."
|
||||
paths = {}
|
||||
for operation in operations:
|
||||
for path in [operation["path"], *operation.get("aliases", [])]:
|
||||
alias = path != operation["path"]
|
||||
parameters = []
|
||||
for segment in path.split('/'):
|
||||
if segment.startswith('{'):
|
||||
parameters.append({"name": segment[1:-1], "in": "path", "required": True,
|
||||
"schema": {"type": "integer", "minimum": 0} if segment == '{id}' else string})
|
||||
if operation.get("if_match"):
|
||||
parameters.append({"name": "If-Match", "in": "header", "required": False,
|
||||
"schema": string, "description": "Quoted or unquoted source-manifest revision."})
|
||||
if operation.get("if_runtime_match"):
|
||||
parameters.append({"name": "If-Runtime-Match", "in": "header", "required": False,
|
||||
"schema": string, "description": "Optional opaque publication token returned by config/validate or config/state; stale runtime assumptions return 409 runtime_conflict."})
|
||||
if operation["id"] in ("config_patch", "config_validate"):
|
||||
parameters.extend({"name": name, "in": "query", "schema": schema} for name, schema in (
|
||||
("reload", {"enum": ["instant", "drain"]}),
|
||||
("timeout_secs", {"type": "integer", "minimum": 1, "maximum": 3600}),
|
||||
("failure_policy", {"enum": ["keep_new", "rollback"]}),
|
||||
))
|
||||
if operation["id"] == "config_state":
|
||||
parameters.append({"name": "sections", "in": "query", "style": "form", "explode": False,
|
||||
"schema": {"type": "array", "items": {"enum": sections}, "uniqueItems": True,
|
||||
"minItems": 1, "maxItems": len(sections)},
|
||||
"description": "Comma-separated sections; omitted selects all. One parameter only, at most 256 query bytes. Snapshots are independently sampled; comparison is not a convergence acknowledgment."})
|
||||
response_schema = {"capabilities": "CapabilitiesResponse", "config_schema": "ConfigSchemaResponse",
|
||||
"config_validate": "ConfigValidationResponse",
|
||||
"config_state": "ConfigStateResponse"}.get(operation["id"], "SuccessEnvelope")
|
||||
responses = {str(status): {"description": "Success or documented state payload",
|
||||
"content": {"application/json": {"schema": ref(response_schema)}}}
|
||||
for status in operation["success"]}
|
||||
responses["default"] = {"description": "Structured API error; whitelist gray actions may instead drop or return empty HTTP 200.",
|
||||
"content": {"application/json": {"schema": ref("ErrorEnvelope")}}}
|
||||
if path == '/web-status':
|
||||
responses = {"200": {"description": "Authenticated HTML diagnostics", "content": {"text/html": {"schema": string}}},
|
||||
"default": {"description": "API admission errors are JSON; renderer/query errors may be HTML."}}
|
||||
entry = {"operationId": operation["id"] + ("_alias" if alias else ""),
|
||||
"responses": responses, "x-telemt-gate": operation["gate"],
|
||||
"x-telemt-credential-bearing": operation.get("credential_bearing", False)}
|
||||
if operation.get("read_only_operation"):
|
||||
entry["x-telemt-read-only-operation"] = True
|
||||
entry["description"] = "Authenticated preflight permitted under read_only. Reads DNS/static assets without persistence, publication, reload reservation or listener binding. Two concurrent preparations, 30 second deadline; cancelled workers retain their slot until exit. Apply classifications describe a publication baseline, not subsystem convergence or guaranteed startup."
|
||||
for status, description in {"409": "Source, runtime or source-ownership conflict.",
|
||||
"429": "Both preparation slots are occupied.",
|
||||
"504": "Preparation exceeded 30 seconds."}.items():
|
||||
responses[status] = {"description": description, "content": {"application/json": {"schema": ref("ErrorEnvelope")}}}
|
||||
if parameters:entry['parameters'] = parameters
|
||||
if operation.get('body'):
|
||||
entry['requestBody'] = {"required": not operation.get('optional_body', False),
|
||||
"content": {"application/json": {"schema": ref(operation['body'])}}}
|
||||
entry['x-telemt-exact-json-content-type'] = operation.get('exact_json_content_type', False)
|
||||
paths.setdefault(path, {})[operation['method'].lower()] = entry
|
||||
return {"openapi": "3.1.0", "info": {"title": "Telemt Control API", "version": "v1-discovery-1",
|
||||
"description": "Generated by tools/generate_api_openapi.py. Routes and envelopes are checked against the runtime catalog. Legacy data payload details, query filters and cross-field constraints remain in API.md. Discovery is administrative, not an observer authorization role."},
|
||||
"security": [{}, {"AuthorizationHeader": []}],
|
||||
"paths": paths, "components": {"securitySchemes": {"AuthorizationHeader": {
|
||||
"type": "apiKey", "in": "header", "name": "Authorization",
|
||||
"description": "Exact configured header value, required only when header authentication is enabled; direct-peer whitelist applies independently."}},
|
||||
"schemas": schemas}}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--check", action="store_true")
|
||||
args = parser.parse_args()
|
||||
rendered = json.dumps(build_document(), indent=2, ensure_ascii=False) + "\n"
|
||||
if args.check:
|
||||
if not OUTPUT.is_file() or OUTPUT.read_text() != rendered:
|
||||
parser.exit(1, f"Outdated artifact: run {Path(__file__).name}\n")
|
||||
print("OpenAPI artifact matches the operation catalog")
|
||||
else:
|
||||
OUTPUT.write_text(rendered)
|
||||
print(OUTPUT.relative_to(ROOT))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+330
-307
@@ -1,6 +1,6 @@
|
||||
"""
|
||||
Telemt Control API Python Client
|
||||
Full-coverage client for https://github.com/telemt/telemt
|
||||
Standard-library JSON client and CLI for Telemt's Control API.
|
||||
|
||||
Usage:
|
||||
client = TelemtAPI("http://127.0.0.1:9091", auth_header="your-secret")
|
||||
@@ -13,10 +13,14 @@ Usage:
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import math
|
||||
import secrets
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Dict, List, Optional, Union
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from http.client import HTTPException
|
||||
from typing import Any, Dict
|
||||
from urllib.error import HTTPError, URLError
|
||||
from urllib.parse import quote, urlencode
|
||||
from urllib.request import Request, urlopen
|
||||
|
||||
|
||||
@@ -28,11 +32,14 @@ class TelemtAPIError(Exception):
|
||||
"""Raised when the API returns an error envelope or a transport error."""
|
||||
|
||||
def __init__(self, message: str, code: str | None = None,
|
||||
http_status: int | None = None, request_id: int | None = None):
|
||||
http_status: int | None = None, request_id: int | None = None,
|
||||
details: list | None = None, last_response: APIResponse | None = None):
|
||||
super().__init__(message)
|
||||
self.code = code
|
||||
self.http_status = http_status
|
||||
self.request_id = request_id
|
||||
self.details = details or []
|
||||
self.last_response = last_response
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return (f"TelemtAPIError(message={str(self)!r}, code={self.code!r}, "
|
||||
@@ -49,9 +56,11 @@ class APIResponse:
|
||||
ok: bool
|
||||
data: Any
|
||||
revision: str | None = None
|
||||
http_status: int = 200
|
||||
|
||||
def __repr__(self) -> str: # pragma: no cover
|
||||
return f"APIResponse(ok={self.ok}, revision={self.revision!r}, data={self.data!r})"
|
||||
return (f"APIResponse(ok={self.ok}, http_status={self.http_status}, "
|
||||
f"revision={self.revision!r}, data={self.data!r})")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
@@ -78,18 +87,19 @@ class TelemtAPI:
|
||||
self,
|
||||
base_url: str = "http://127.0.0.1:9091",
|
||||
auth_header: str | None = None,
|
||||
timeout: int = 10,
|
||||
timeout: float = 10,
|
||||
) -> None:
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.auth_header = auth_header
|
||||
self.timeout = timeout
|
||||
self.timeout = _positive_seconds(timeout, "timeout")
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Low-level HTTP helpers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _headers(self, extra: dict | None = None) -> dict:
|
||||
h = {"Content-Type": "application/json; charset=utf-8",
|
||||
# WEB controls require this exact media type without charset parameters.
|
||||
h = {"Content-Type": "application/json",
|
||||
"Accept": "application/json"}
|
||||
if self.auth_header:
|
||||
h["Authorization"] = self.auth_header
|
||||
@@ -104,19 +114,27 @@ class TelemtAPI:
|
||||
body: dict | None = None,
|
||||
if_match: str | None = None,
|
||||
query: dict | None = None,
|
||||
*,
|
||||
if_runtime_match: str | None = None,
|
||||
success_statuses: tuple[int, ...] = (),
|
||||
timeout: float | None = None,
|
||||
) -> APIResponse:
|
||||
url = self.base_url + path
|
||||
if query:
|
||||
qs = "&".join(f"{k}={v}" for k, v in query.items())
|
||||
qs = urlencode(query)
|
||||
url = f"{url}?{qs}"
|
||||
|
||||
raw_body: bytes | None = None
|
||||
if body is not None:
|
||||
raw_body = json.dumps(body).encode()
|
||||
raw_body = json.dumps(body, allow_nan=False).encode("utf-8")
|
||||
if method == "POST" and path.startswith("/v1/runtime/web/") and len(raw_body) > 65536:
|
||||
raise ValueError("WEB control JSON exceeds 65536 bytes")
|
||||
|
||||
extra_headers: dict = {}
|
||||
if if_match is not None:
|
||||
extra_headers["If-Match"] = if_match
|
||||
if if_runtime_match is not None:
|
||||
extra_headers["If-Runtime-Match"] = if_runtime_match
|
||||
|
||||
req = Request(
|
||||
url,
|
||||
@@ -126,42 +144,46 @@ class TelemtAPI:
|
||||
)
|
||||
|
||||
try:
|
||||
with urlopen(req, timeout=self.timeout) as resp:
|
||||
payload = json.loads(resp.read())
|
||||
except HTTPError as exc:
|
||||
raw = exc.read()
|
||||
request_timeout = self.timeout if timeout is None else min(self.timeout, timeout)
|
||||
try:
|
||||
payload = json.loads(raw)
|
||||
except Exception:
|
||||
raise TelemtAPIError(
|
||||
str(exc), http_status=exc.code
|
||||
) from exc
|
||||
err = payload.get("error", {})
|
||||
raise TelemtAPIError(
|
||||
err.get("message", str(exc)),
|
||||
code=err.get("code"),
|
||||
http_status=exc.code,
|
||||
request_id=payload.get("request_id"),
|
||||
) from exc
|
||||
except URLError as exc:
|
||||
response = urlopen(req, timeout=request_timeout)
|
||||
except HTTPError as error:
|
||||
response = error
|
||||
with response:
|
||||
status, raw = response.status, response.read()
|
||||
except (URLError, OSError, HTTPException) as exc:
|
||||
raise TelemtAPIError(str(exc)) from exc
|
||||
|
||||
if not payload.get("ok"):
|
||||
try:
|
||||
payload = json.loads(raw)
|
||||
except (ValueError, UnicodeError) as exc:
|
||||
raise TelemtAPIError("Expected a JSON API envelope (empty gray_action responses are not success)",
|
||||
code="invalid_response", http_status=status) from exc
|
||||
if not isinstance(payload, dict) or not isinstance(payload.get("ok"), bool):
|
||||
raise TelemtAPIError("Invalid API envelope", code="invalid_response", http_status=status)
|
||||
if not payload["ok"]:
|
||||
err = payload.get("error", {})
|
||||
if not isinstance(err, dict):
|
||||
err = {}
|
||||
raise TelemtAPIError(
|
||||
err.get("message", "unknown error"),
|
||||
code=err.get("code"),
|
||||
http_status=status,
|
||||
request_id=payload.get("request_id"),
|
||||
details=err.get("details"),
|
||||
)
|
||||
if not (200 <= status < 300 or status in success_statuses) or "data" not in payload:
|
||||
raise TelemtAPIError("Unexpected API success response", code="invalid_response", http_status=status)
|
||||
|
||||
return APIResponse(
|
||||
ok=True,
|
||||
data=payload.get("data"),
|
||||
revision=payload.get("revision"),
|
||||
http_status=status,
|
||||
)
|
||||
|
||||
def _get(self, path: str, query: dict | None = None) -> APIResponse:
|
||||
return self._request("GET", path, query=query)
|
||||
def _get(self, path: str, query: dict | None = None, **options) -> APIResponse:
|
||||
return self._request("GET", path, query=query, **options)
|
||||
|
||||
def _post(self, path: str, body: dict | None = None,
|
||||
if_match: str | None = None) -> APIResponse:
|
||||
@@ -182,6 +204,72 @@ class TelemtAPI:
|
||||
"""GET /v1/health — liveness probe."""
|
||||
return self._get("/v1/health")
|
||||
|
||||
def health_ready(self) -> APIResponse:
|
||||
"""Return readiness data for both 200 and a documented 503 ok=true response."""
|
||||
return self._get("/v1/health/ready", success_statuses=(503,))
|
||||
|
||||
def capabilities(self) -> APIResponse:
|
||||
return self._get("/v1/capabilities")
|
||||
|
||||
def config_schema(self) -> APIResponse:
|
||||
return self._get("/v1/config/schema")
|
||||
|
||||
def get_config(self) -> APIResponse:
|
||||
"""Desired editable configuration; the legacy response can contain credentials."""
|
||||
return self._get("/v1/config")
|
||||
|
||||
def config_state(self, sections: list[str] | None = None) -> APIResponse:
|
||||
"""Redacted publication state, including partial results and nullable revision."""
|
||||
query = None
|
||||
if sections is not None:
|
||||
allowed = {"general", "network", "server", "timeouts", "censorship", "upstreams",
|
||||
"dc_overrides", "web", "access", "logging", "root"}
|
||||
if isinstance(sections, str) or not sections or len(set(sections)) != len(sections) or not set(sections) <= allowed:
|
||||
raise ValueError("sections must contain unique known section names")
|
||||
query = {"sections": ",".join(sections)}
|
||||
return self._get("/v1/config/state", query)
|
||||
|
||||
def patch_config(self, patch: dict, *, if_match: str | None = None,
|
||||
if_runtime_match: str | None = None, reload: str | None = None,
|
||||
timeout_secs: int | None = None, failure_policy: str | None = None) -> APIResponse:
|
||||
"""Send a sparse patch unchanged; nested nulls keep the server's merge semantics."""
|
||||
_object(patch, "patch")
|
||||
return self._request("PATCH", "/v1/config", patch, if_match,
|
||||
_reload_query(reload, timeout_secs, failure_policy),
|
||||
if_runtime_match=if_runtime_match)
|
||||
|
||||
def validate_config(self, patch: dict, *, if_match: str | None = None,
|
||||
if_runtime_match: str | None = None, reload: str | None = None,
|
||||
timeout_secs: int | None = None, failure_policy: str | None = None) -> APIResponse:
|
||||
"""Prepare a candidate without committing; accepts the same inputs as PATCH."""
|
||||
_object(patch, "patch")
|
||||
return self._request("POST", "/v1/config/validate", patch, if_match,
|
||||
_reload_query(reload, timeout_secs, failure_policy),
|
||||
if_runtime_match=if_runtime_match)
|
||||
|
||||
def reload(self, mode: str = "instant", *, timeout_secs: int | None = None,
|
||||
failure_policy: str | None = None, if_match: str | None = None) -> APIResponse:
|
||||
body = _reload_query(mode, timeout_secs, failure_policy)
|
||||
body["mode"] = body.pop("reload")
|
||||
return self._post("/v1/system/reload", body, if_match)
|
||||
|
||||
def reload_status(self, reload_id: int) -> APIResponse:
|
||||
_bounded(reload_id, 0, 2**64 - 1, "reload_id")
|
||||
return self._get(f"/v1/system/reload/{reload_id}")
|
||||
|
||||
def wait_reload(self, reload_id: int, *, timeout: float = 60, poll_interval: float = 0.25,
|
||||
expected_revision: str | None = None) -> APIResponse:
|
||||
"""Poll an accepted ID; failed/rolled_back are returned as terminal data."""
|
||||
_bounded(reload_id, 0, 2**64 - 1, "reload_id")
|
||||
def state(response):
|
||||
data = _object(response.data, "reload status")
|
||||
if data.get("reload_id") != reload_id or (expected_revision is not None and data.get("config_revision") != expected_revision):
|
||||
raise TelemtAPIError("Reload identity changed while polling", code="operation_mismatch", last_response=response)
|
||||
return data.get("state")
|
||||
return _poll(lambda remaining: self._get(f"/v1/system/reload/{reload_id}", timeout=remaining),
|
||||
state, {"succeeded", "failed", "rolled_back"},
|
||||
{"accepted", "preparing", "activating", "draining"}, timeout, poll_interval)
|
||||
|
||||
def system_info(self) -> APIResponse:
|
||||
"""GET /v1/system/info — binary version, uptime, config hash."""
|
||||
return self._get("/v1/system/info")
|
||||
@@ -278,9 +366,23 @@ class TelemtAPI:
|
||||
limit:
|
||||
Optional cap on returned events (1–1000, server default 50).
|
||||
"""
|
||||
if limit is not None:
|
||||
_bounded(limit, 1, 1000, "limit")
|
||||
query = {"limit": str(limit)} if limit is not None else None
|
||||
return self._get("/v1/runtime/events/recent", query=query)
|
||||
|
||||
def runtime_tls_fingerprints(self, limit: int | None = None) -> APIResponse:
|
||||
if limit is not None:
|
||||
_bounded(limit, 1, 1000, "limit")
|
||||
return self._get("/v1/runtime/tls-fingerprints", {"limit": limit} if limit is not None else None)
|
||||
|
||||
def users_quota(self) -> APIResponse:
|
||||
"""Desired quota/period and effective recurring quota schedule are distinct."""
|
||||
return self._get("/v1/stats/users/quota")
|
||||
|
||||
def users_active_ips(self) -> APIResponse:
|
||||
return self._get("/v1/stats/users/active-ips")
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Users (read)
|
||||
# ------------------------------------------------------------------
|
||||
@@ -307,6 +409,10 @@ class TelemtAPI:
|
||||
expiration_rfc3339: str | None = None,
|
||||
data_quota_bytes: int | None = None,
|
||||
max_unique_ips: int | None = None,
|
||||
quota_period: str | None = None,
|
||||
rate_limit_up_bps: int | None = None,
|
||||
rate_limit_down_bps: int | None = None,
|
||||
enabled: bool | None = None,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""POST /v1/users — create a new user.
|
||||
@@ -327,6 +433,12 @@ class TelemtAPI:
|
||||
Per-user traffic quota in bytes.
|
||||
max_unique_ips:
|
||||
Per-user unique source IP limit.
|
||||
quota_period:
|
||||
Optional UTC recurring period: daily, weekly or monthly.
|
||||
rate_limit_up_bps, rate_limit_down_bps:
|
||||
Per-user upload/download byte rates; zero values are transmitted.
|
||||
enabled:
|
||||
Optional admission flag; False is transmitted.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision for optimistic concurrency.
|
||||
"""
|
||||
@@ -337,6 +449,10 @@ class TelemtAPI:
|
||||
_opt(body, "expiration_rfc3339", expiration_rfc3339)
|
||||
_opt(body, "data_quota_bytes", data_quota_bytes)
|
||||
_opt(body, "max_unique_ips", max_unique_ips)
|
||||
_opt(body, "quota_period", quota_period)
|
||||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||||
_opt(body, "enabled", enabled)
|
||||
return self._post("/v1/users", body=body, if_match=if_match)
|
||||
|
||||
def patch_user(
|
||||
@@ -349,6 +465,10 @@ class TelemtAPI:
|
||||
expiration_rfc3339: str | None = None,
|
||||
data_quota_bytes: int | None = None,
|
||||
max_unique_ips: int | None = None,
|
||||
quota_period: str | None = None,
|
||||
rate_limit_up_bps: int | None = None,
|
||||
rate_limit_down_bps: int | None = None,
|
||||
enabled: bool | None = None,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""PATCH /v1/users/{username} — partial update; only provided fields change.
|
||||
@@ -369,6 +489,9 @@ class TelemtAPI:
|
||||
New quota in bytes.
|
||||
max_unique_ips:
|
||||
New unique IP limit.
|
||||
quota_period, rate_limit_up_bps, rate_limit_down_bps, enabled:
|
||||
Recurring quota, byte rates and admission flag. None omits a field,
|
||||
preserving the legacy helper contract; use patch_user_fields to clear.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision.
|
||||
"""
|
||||
@@ -379,10 +502,31 @@ class TelemtAPI:
|
||||
_opt(body, "expiration_rfc3339", expiration_rfc3339)
|
||||
_opt(body, "data_quota_bytes", data_quota_bytes)
|
||||
_opt(body, "max_unique_ips", max_unique_ips)
|
||||
if not body:
|
||||
raise ValueError("patch_user: at least one field must be provided")
|
||||
return self._patch(f"/v1/users/{_safe(username)}", body=body,
|
||||
if_match=if_match)
|
||||
_opt(body, "quota_period", quota_period)
|
||||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||||
_opt(body, "enabled", enabled)
|
||||
return self.patch_user_fields(username, body, if_match=if_match)
|
||||
|
||||
def patch_user_fields(self, username: str, fields: dict, *, if_match: str | None = None) -> APIResponse:
|
||||
"""Exact sparse PATCH: omission preserves a field; explicit None sends JSON null.
|
||||
|
||||
The older patch_user convenience method still omits None-valued arguments.
|
||||
Server-specific null semantics apply, including secret:null being ignored.
|
||||
"""
|
||||
_object(fields, "fields")
|
||||
if not fields or not fields.keys() <= USER_FIELDS:
|
||||
raise ValueError("patch_user_fields requires at least one known user field")
|
||||
return self._patch(f"/v1/users/{_safe(username)}", fields, if_match)
|
||||
|
||||
def enable_user(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||||
return self._post(f"/v1/users/{_safe(username)}/enable", if_match=if_match)
|
||||
|
||||
def disable_user(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||||
return self._post(f"/v1/users/{_safe(username)}/disable", if_match=if_match)
|
||||
|
||||
def reset_user_quota(self, username: str, *, if_match: str | None = None) -> APIResponse:
|
||||
return self._post(f"/v1/users/{_safe(username)}/reset-quota", if_match=if_match)
|
||||
|
||||
def delete_user(
|
||||
self,
|
||||
@@ -399,9 +543,6 @@ class TelemtAPI:
|
||||
"""
|
||||
return self._delete(f"/v1/users/{_safe(username)}", if_match=if_match)
|
||||
|
||||
# NOTE: POST /v1/users/{username}/rotate-secret currently returns 404
|
||||
# in the route matcher (documented limitation). The method is provided
|
||||
# for completeness and future compatibility.
|
||||
def rotate_secret(
|
||||
self,
|
||||
username: str,
|
||||
@@ -411,10 +552,8 @@ class TelemtAPI:
|
||||
) -> APIResponse:
|
||||
"""POST /v1/users/{username}/rotate-secret — rotate user secret.
|
||||
|
||||
.. warning::
|
||||
This endpoint currently returns ``404 not_found`` in all released
|
||||
versions (documented route matcher limitation). The method is
|
||||
included for future compatibility.
|
||||
Returns the new credential. Owners of the old identity are cancelled;
|
||||
watcher publication and existing-session retirement remain asynchronous.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
@@ -426,6 +565,91 @@ class TelemtAPI:
|
||||
return self._post(f"/v1/users/{_safe(username)}/rotate-secret",
|
||||
body=body or None, if_match=if_match)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# WEB runtime: opaque references are always supplied by the caller.
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def web_status(self) -> APIResponse:
|
||||
return self._get("/v1/runtime/web/status")
|
||||
|
||||
def web_sessions(self, *, limit: int | None = None, cursor: str | None = None,
|
||||
session_ref: str | None = None, ip: str | None = None,
|
||||
host: str | None = None, user: str | None = None,
|
||||
user_agent_id: str | None = None, key_id: str | None = None,
|
||||
carrier: str | None = None, state: str | None = None) -> APIResponse:
|
||||
if limit is not None:
|
||||
_bounded(limit, 1, 200, "limit")
|
||||
if session_ref is not None and (cursor is not None or limit is not None):
|
||||
raise ValueError("session_ref cannot be combined with cursor or limit")
|
||||
query = {key: value for key, value in dict(limit=limit, cursor=cursor, session_ref=session_ref,
|
||||
ip=ip, host=host, user=user, user_agent_id=user_agent_id, key_id=key_id,
|
||||
carrier=carrier, state=state).items() if value is not None}
|
||||
return self._get("/v1/runtime/web/sessions", query)
|
||||
|
||||
def web_session(self, session_ref: str) -> APIResponse:
|
||||
"""A 410 ok=true tombstone is data, with http_status retained."""
|
||||
return self._get(f"/v1/runtime/web/sessions/{_safe(session_ref)}", success_statuses=(410,))
|
||||
|
||||
def web_close_sessions(self, runtime_instance: str, selector: dict) -> APIResponse:
|
||||
_object(selector, "selector")
|
||||
kind = selector.get("kind")
|
||||
if kind == "refs":
|
||||
refs = selector.get("session_refs")
|
||||
if not isinstance(refs, list) or not all(isinstance(ref, str) for ref in refs) or not 1 <= len(refs) <= 200 or len(set(refs)) != len(refs) or set(selector) != {"kind", "session_refs"}:
|
||||
raise ValueError("refs selector requires 1..200 unique session references")
|
||||
elif kind == "all":
|
||||
if set(selector) != {"kind"}:
|
||||
raise ValueError("all selector accepts only kind")
|
||||
elif kind == "filter":
|
||||
allowed = {"kind", "session_ref", "ip", "host", "user", "user_agent_id", "key_id", "carrier", "state"}
|
||||
if not selector.keys() <= allowed or not any(value is not None for key, value in selector.items() if key != "kind"):
|
||||
raise ValueError("filter selector requires at least one known non-null filter")
|
||||
else:
|
||||
raise ValueError("selector.kind must be refs, filter or all")
|
||||
return self._post("/v1/runtime/web/sessions/close", {"runtime_instance": runtime_instance, "selector": selector})
|
||||
|
||||
def web_operation(self, operation_id: str) -> APIResponse:
|
||||
return self._get(f"/v1/runtime/web/operations/{_safe(operation_id)}")
|
||||
|
||||
def wait_web_operation(self, operation_id: str, *, timeout: float = 60, poll_interval: float = 0.25) -> APIResponse:
|
||||
path = f"/v1/runtime/web/operations/{_safe(operation_id)}"
|
||||
def state(response):
|
||||
data = _object(response.data, "WEB operation")
|
||||
if data.get("operation_id") != operation_id:
|
||||
raise TelemtAPIError("WEB operation identity changed", code="operation_mismatch", last_response=response)
|
||||
return data.get("state")
|
||||
return _poll(lambda remaining: self._get(path, timeout=remaining), state,
|
||||
{"completed", "cancelled", "failed"}, {"queued", "running"}, timeout, poll_interval)
|
||||
|
||||
def web_debug_clear(self, runtime_instance: str) -> APIResponse:
|
||||
return self._post("/v1/runtime/web/debug/clear", {"runtime_instance": runtime_instance})
|
||||
|
||||
def web_learning_reset(self, runtime_instance: str) -> APIResponse:
|
||||
return self._post("/v1/runtime/web/carrier-learning/reset", {"runtime_instance": runtime_instance})
|
||||
|
||||
def web_pause(self, runtime_instance: str) -> APIResponse:
|
||||
return self._post("/v1/runtime/web/lifecycle/pause", {"runtime_instance": runtime_instance})
|
||||
|
||||
def web_drain(self, runtime_instance: str, timeout_secs: int) -> APIResponse:
|
||||
_bounded(timeout_secs, 1, 3600, "timeout_secs")
|
||||
return self._post("/v1/runtime/web/lifecycle/drain", {"runtime_instance": runtime_instance, "timeout_secs": timeout_secs})
|
||||
|
||||
def web_resume(self, runtime_instance: str) -> APIResponse:
|
||||
return self._post("/v1/runtime/web/lifecycle/resume", {"runtime_instance": runtime_instance})
|
||||
|
||||
def wait_web_drain(self, runtime_instance: str, operation_id: str, *,
|
||||
timeout: float = 60, poll_interval: float = 0.25) -> APIResponse:
|
||||
"""Poll the same drain through WEB status; never substitute a new process or drain."""
|
||||
def state(response):
|
||||
data = _object(response.data, "WEB status")
|
||||
runtime = data.get("runtime") or {}
|
||||
drain = (data.get("operator_lifecycle") or {}).get("drain") or {}
|
||||
if runtime.get("runtime_instance") != runtime_instance or drain.get("operation_id") != operation_id:
|
||||
raise TelemtAPIError("WEB process or drain identity changed", code="operation_mismatch", last_response=response)
|
||||
return drain.get("state")
|
||||
return _poll(lambda remaining: self._get("/v1/runtime/web/status", timeout=remaining), state,
|
||||
{"completed", "cancelled"}, {"draining", "force_closing"}, timeout, poll_interval)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Convenience helpers
|
||||
# ------------------------------------------------------------------
|
||||
@@ -440,11 +664,15 @@ class TelemtAPI:
|
||||
# Internal helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _safe(username: str) -> str:
|
||||
"""Minimal guard: reject obvious path-injection attempts."""
|
||||
if "/" in username or "\\" in username:
|
||||
raise ValueError(f"Invalid username: {username!r}")
|
||||
return username
|
||||
USER_FIELDS = {"secret", "user_ad_tag", "max_tcp_conns", "expiration_rfc3339", "data_quota_bytes",
|
||||
"quota_period", "rate_limit_up_bps", "rate_limit_down_bps", "max_unique_ips", "enabled"}
|
||||
|
||||
|
||||
def _safe(value: str) -> str:
|
||||
"""Keep one opaque path segment from becoming a path, query or fragment."""
|
||||
if not isinstance(value, str) or not value or value in (".", "..") or "/" in value or "\\" in value:
|
||||
raise ValueError("Expected one nonempty path segment")
|
||||
return quote(value, safe="")
|
||||
|
||||
|
||||
def _opt(d: dict, key: str, value: Any) -> None:
|
||||
@@ -453,277 +681,72 @@ def _opt(d: dict, key: str, value: Any) -> None:
|
||||
d[key] = value
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# CLI
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _print(resp: APIResponse) -> None:
|
||||
print(json.dumps(resp.data, indent=2))
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}", flush=True)
|
||||
def _object(value, name):
|
||||
if not isinstance(value, dict):
|
||||
raise ValueError(f"{name} must be a JSON object")
|
||||
return value
|
||||
|
||||
|
||||
def _build_parser():
|
||||
import argparse
|
||||
def _bounded(value, minimum, maximum, name):
|
||||
if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
|
||||
raise ValueError(f"{name} must be within {minimum}..{maximum}")
|
||||
|
||||
p = argparse.ArgumentParser(
|
||||
prog="telemt_api.py",
|
||||
description="Telemt Control API CLI",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog="""
|
||||
COMMANDS (read)
|
||||
health Liveness check
|
||||
info System info (version, uptime, config hash)
|
||||
status Runtime gates + startup progress
|
||||
init Runtime initialization timeline
|
||||
limits Effective limits (timeouts, upstream, ME)
|
||||
posture Security posture summary
|
||||
whitelist IP whitelist entries
|
||||
summary Stats summary (conns, uptime, users)
|
||||
zero Zero-cost counters (core/upstream/ME/pool/desync)
|
||||
upstreams Upstream health + zero counters
|
||||
minimal ME writers + DC snapshot [minimal_runtime_enabled]
|
||||
me-writers Per-writer ME status [minimal_runtime_enabled]
|
||||
dcs Per-DC coverage [minimal_runtime_enabled]
|
||||
me-pool ME pool generation/writer/refill snapshot
|
||||
me-quality ME KDF, route-drops, per-DC RTT
|
||||
upstream-quality Per-upstream health + latency
|
||||
nat-stun NAT probe state + STUN servers
|
||||
me-selftest KDF/timeskew/IP/PID/BND health
|
||||
connections Live connection totals + top-N [runtime_edge_enabled]
|
||||
events [--limit N] Recent ring-buffer events [runtime_edge_enabled]
|
||||
|
||||
COMMANDS (users)
|
||||
users List all users
|
||||
user <username> Get single user
|
||||
create <username> [OPTIONS] Create user
|
||||
patch <username> [OPTIONS] Partial update user
|
||||
delete <username> Delete user
|
||||
secret <username> [--secret S] Rotate secret (reserved; returns 404 in current release)
|
||||
gen-secret Print a random 32-hex secret and exit
|
||||
def _positive_seconds(value, name):
|
||||
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
|
||||
raise ValueError(f"{name} must be a finite positive number of seconds")
|
||||
return value
|
||||
|
||||
USER OPTIONS (for create / patch)
|
||||
--secret S 32 hex chars
|
||||
--ad-tag S 32 hex chars (ad tag)
|
||||
--max-conns N Max concurrent TCP connections
|
||||
--expires DATETIME RFC3339 expiration (e.g. 2026-12-31T23:59:59Z)
|
||||
--quota N Data quota in bytes
|
||||
--max-ips N Max unique source IPs
|
||||
|
||||
EXAMPLES
|
||||
telemt_api.py health
|
||||
telemt_api.py -u http://10.0.0.1:9091 -a mysecret users
|
||||
telemt_api.py create alice --max-conns 5 --quota 10000000000
|
||||
telemt_api.py patch alice --expires 2027-01-01T00:00:00Z
|
||||
telemt_api.py delete alice
|
||||
telemt_api.py events --limit 20
|
||||
""",
|
||||
)
|
||||
def _reload_query(mode, timeout_secs, failure_policy):
|
||||
if mode is None:
|
||||
if timeout_secs is not None or failure_policy is not None:
|
||||
raise ValueError("timeout_secs and failure_policy require reload mode")
|
||||
return None
|
||||
if mode not in ("instant", "drain"):
|
||||
raise ValueError("reload mode must be instant or drain")
|
||||
if mode == "drain":
|
||||
_bounded(timeout_secs, 1, 3600, "timeout_secs")
|
||||
elif timeout_secs is not None:
|
||||
raise ValueError("instant reload forbids timeout_secs")
|
||||
if failure_policy is not None and failure_policy not in ("keep_new", "rollback"):
|
||||
raise ValueError("failure_policy must be keep_new or rollback")
|
||||
return {key: value for key, value in dict(reload=mode, timeout_secs=timeout_secs,
|
||||
failure_policy=failure_policy).items() if value is not None}
|
||||
|
||||
p.add_argument("-u", "--url", default="http://127.0.0.1:9091",
|
||||
metavar="URL", help="API base URL (default: http://127.0.0.1:9091)")
|
||||
p.add_argument("-a", "--auth", default=None, metavar="TOKEN",
|
||||
help="Authorization header value")
|
||||
p.add_argument("-t", "--timeout", type=int, default=10, metavar="SEC",
|
||||
help="Request timeout in seconds (default: 10)")
|
||||
|
||||
p.add_argument("command", nargs="?", default="help",
|
||||
help="Command to run (see COMMANDS below)")
|
||||
p.add_argument("arg", nargs="?", default=None, metavar="USERNAME",
|
||||
help="Username for user commands")
|
||||
def _poll(fetch, state, terminal, pending, timeout, interval):
|
||||
deadline = time.monotonic() + _positive_seconds(timeout, "poll timeout")
|
||||
_positive_seconds(interval, "poll interval")
|
||||
last = None
|
||||
while True:
|
||||
remaining = deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
raise TelemtAPIError("Polling budget expired; the server operation was not cancelled",
|
||||
code="poll_timeout", last_response=last)
|
||||
last = fetch(remaining)
|
||||
if time.monotonic() >= deadline:
|
||||
raise TelemtAPIError("Polling budget expired; the server operation was not cancelled",
|
||||
code="poll_timeout", last_response=last)
|
||||
try:
|
||||
phase = state(last)
|
||||
known = phase in terminal or phase in pending
|
||||
except (ValueError, TypeError, AttributeError) as error:
|
||||
raise TelemtAPIError("Invalid operation response", code="invalid_response", last_response=last) from error
|
||||
if phase in terminal:
|
||||
return last
|
||||
if not known:
|
||||
raise TelemtAPIError("Unknown operation phase", code="invalid_response", last_response=last)
|
||||
time.sleep(min(interval, max(0, deadline - time.monotonic())))
|
||||
|
||||
# user create/patch fields
|
||||
p.add_argument("--secret", default=None)
|
||||
p.add_argument("--ad-tag", dest="ad_tag", default=None)
|
||||
p.add_argument("--max-conns", dest="max_conns", type=int, default=None)
|
||||
p.add_argument("--expires", default=None)
|
||||
p.add_argument("--quota", type=int, default=None)
|
||||
p.add_argument("--max-ips", dest="max_ips", type=int, default=None)
|
||||
|
||||
# events
|
||||
p.add_argument("--limit", type=int, default=None,
|
||||
help="Max events for `events` command")
|
||||
|
||||
# optimistic concurrency
|
||||
p.add_argument("--if-match", dest="if_match", default=None,
|
||||
metavar="REVISION", help="If-Match revision header")
|
||||
|
||||
return p
|
||||
def main(argv=None):
|
||||
if __package__:
|
||||
from .telemt_api_cli import main as cli_main
|
||||
else:
|
||||
from telemt_api_cli import main as cli_main
|
||||
return cli_main(argv)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
import sys
|
||||
|
||||
parser = _build_parser()
|
||||
args = parser.parse_args()
|
||||
|
||||
cmd = (args.command or "help").lower()
|
||||
|
||||
if cmd in ("help", "--help"):
|
||||
parser.print_help()
|
||||
sys.exit(0)
|
||||
|
||||
if cmd == "gen-secret":
|
||||
print(TelemtAPI.generate_secret())
|
||||
sys.exit(0)
|
||||
|
||||
api = TelemtAPI(args.url, auth_header=args.auth, timeout=args.timeout)
|
||||
|
||||
try:
|
||||
# -- read endpoints --------------------------------------------------
|
||||
if cmd == "health":
|
||||
_print(api.health())
|
||||
|
||||
elif cmd == "info":
|
||||
_print(api.system_info())
|
||||
|
||||
elif cmd == "status":
|
||||
_print(api.runtime_gates())
|
||||
|
||||
elif cmd == "init":
|
||||
_print(api.runtime_initialization())
|
||||
|
||||
elif cmd == "limits":
|
||||
_print(api.limits_effective())
|
||||
|
||||
elif cmd == "posture":
|
||||
_print(api.security_posture())
|
||||
|
||||
elif cmd == "whitelist":
|
||||
_print(api.security_whitelist())
|
||||
|
||||
elif cmd == "summary":
|
||||
_print(api.stats_summary())
|
||||
|
||||
elif cmd == "zero":
|
||||
_print(api.stats_zero_all())
|
||||
|
||||
elif cmd == "upstreams":
|
||||
_print(api.stats_upstreams())
|
||||
|
||||
elif cmd == "minimal":
|
||||
_print(api.stats_minimal_all())
|
||||
|
||||
elif cmd == "me-writers":
|
||||
_print(api.stats_me_writers())
|
||||
|
||||
elif cmd == "dcs":
|
||||
_print(api.stats_dcs())
|
||||
|
||||
elif cmd == "me-pool":
|
||||
_print(api.runtime_me_pool_state())
|
||||
|
||||
elif cmd == "me-quality":
|
||||
_print(api.runtime_me_quality())
|
||||
|
||||
elif cmd == "upstream-quality":
|
||||
_print(api.runtime_upstream_quality())
|
||||
|
||||
elif cmd == "nat-stun":
|
||||
_print(api.runtime_nat_stun())
|
||||
|
||||
elif cmd == "me-selftest":
|
||||
_print(api.runtime_me_selftest())
|
||||
|
||||
elif cmd == "connections":
|
||||
_print(api.runtime_connections_summary())
|
||||
|
||||
elif cmd == "events":
|
||||
_print(api.runtime_events_recent(limit=args.limit))
|
||||
|
||||
# -- user read -------------------------------------------------------
|
||||
elif cmd == "users":
|
||||
resp = api.list_users()
|
||||
users = resp.data or []
|
||||
if not users:
|
||||
print("No users configured.")
|
||||
else:
|
||||
fmt = "{:<24} {:>7} {:>14} {}"
|
||||
print(fmt.format("USERNAME", "CONNS", "OCTETS", "LINKS"))
|
||||
print("-" * 72)
|
||||
for u in users:
|
||||
links = (u.get("links") or {})
|
||||
all_links = (links.get("classic") or []) + \
|
||||
(links.get("secure") or []) + \
|
||||
(links.get("tls") or [])
|
||||
link_str = all_links[0] if all_links else "-"
|
||||
print(fmt.format(
|
||||
u["username"],
|
||||
u.get("current_connections", 0),
|
||||
u.get("total_octets", 0),
|
||||
link_str,
|
||||
))
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "user":
|
||||
if not args.arg:
|
||||
parser.error("user command requires <username>")
|
||||
_print(api.get_user(args.arg))
|
||||
|
||||
# -- user write ------------------------------------------------------
|
||||
elif cmd == "create":
|
||||
if not args.arg:
|
||||
parser.error("create command requires <username>")
|
||||
resp = api.create_user(
|
||||
args.arg,
|
||||
secret=args.secret,
|
||||
user_ad_tag=args.ad_tag,
|
||||
max_tcp_conns=args.max_conns,
|
||||
expiration_rfc3339=args.expires,
|
||||
data_quota_bytes=args.quota,
|
||||
max_unique_ips=args.max_ips,
|
||||
if_match=args.if_match,
|
||||
)
|
||||
d = resp.data or {}
|
||||
print(f"Created: {d.get('user', {}).get('username')}")
|
||||
print(f"Secret: {d.get('secret')}")
|
||||
links = (d.get("user") or {}).get("links") or {}
|
||||
for kind, lst in links.items():
|
||||
for link in (lst or []):
|
||||
print(f"Link ({kind}): {link}")
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "patch":
|
||||
if not args.arg:
|
||||
parser.error("patch command requires <username>")
|
||||
if not any([args.secret, args.ad_tag, args.max_conns,
|
||||
args.expires, args.quota, args.max_ips]):
|
||||
parser.error(
|
||||
"patch requires at least one field (--secret, --max-conns, --expires, --quota, --max-ips, --ad-tag)")
|
||||
_print(api.patch_user(
|
||||
args.arg,
|
||||
secret=args.secret,
|
||||
user_ad_tag=args.ad_tag,
|
||||
max_tcp_conns=args.max_conns,
|
||||
expiration_rfc3339=args.expires,
|
||||
data_quota_bytes=args.quota,
|
||||
max_unique_ips=args.max_ips,
|
||||
if_match=args.if_match,
|
||||
))
|
||||
|
||||
elif cmd == "delete":
|
||||
if not args.arg:
|
||||
parser.error("delete command requires <username>")
|
||||
resp = api.delete_user(args.arg, if_match=args.if_match)
|
||||
print(f"Deleted: {resp.data}")
|
||||
if resp.revision:
|
||||
print(f"# revision: {resp.revision}")
|
||||
|
||||
elif cmd == "secret":
|
||||
if not args.arg:
|
||||
parser.error("secret command requires <username>")
|
||||
_print(api.rotate_secret(args.arg, secret=args.secret,
|
||||
if_match=args.if_match))
|
||||
|
||||
else:
|
||||
print(f"Unknown command: {cmd!r}\nRun with 'help' to see available commands.",
|
||||
file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
except TelemtAPIError as exc:
|
||||
print(f"API error [{exc.http_status}] {exc.code}: {exc}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
except KeyboardInterrupt:
|
||||
sys.exit(130)
|
||||
raise SystemExit(main())
|
||||
|
||||
@@ -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
|
||||
@@ -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))
|
||||
@@ -0,0 +1,273 @@
|
||||
import json
|
||||
import re
|
||||
import unittest
|
||||
from http.client import RemoteDisconnected
|
||||
from pathlib import Path
|
||||
from urllib.error import URLError
|
||||
from urllib.parse import parse_qs, urlsplit
|
||||
from unittest.mock import patch
|
||||
|
||||
from tools.telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS
|
||||
from http_fixture import MockAPI
|
||||
|
||||
|
||||
INSTANCE = "0123456789abcdef0123456789abcdef"
|
||||
SESSION = f"ws1.{INSTANCE}.0000000000000001"
|
||||
OPERATION = f"wo1.{INSTANCE}.0000000000000001"
|
||||
|
||||
|
||||
class ClientTests(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.peer = MockAPI().__enter__()
|
||||
self.addCleanup(self.peer.__exit__, None, None, None)
|
||||
self.api = TelemtAPI(self.peer.url, auth_header="Bearer synthetic-test", timeout=2)
|
||||
|
||||
def test_all_json_operations_match_the_rust_catalog(self):
|
||||
reads = {
|
||||
"health": "health", "health_ready": "health_ready", "capabilities": "capabilities",
|
||||
"config_schema": "config_schema", "system_info": "system_info", "runtime_gates": "runtime_gates",
|
||||
"runtime_initialization": "runtime_initialization", "limits_effective": "limits_effective",
|
||||
"security_posture": "security_posture", "security_whitelist": "security_whitelist",
|
||||
"stats_summary": "stats_summary", "stats_zero_all": "stats_zero_all", "stats_upstreams": "stats_upstreams",
|
||||
"stats_minimal_all": "stats_minimal_all", "stats_me_writers": "stats_me_writers", "stats_dcs": "stats_dcs",
|
||||
"runtime_me_pool_state": "runtime_me_pool_state", "runtime_me_quality": "runtime_me_quality",
|
||||
"runtime_upstream_quality": "runtime_upstream_quality", "runtime_nat_stun": "runtime_nat_stun",
|
||||
"runtime_me_selftest": "runtime_me_selftest", "runtime_connections_summary": "runtime_connections_summary",
|
||||
"runtime_events_recent": "runtime_events_recent", "runtime_tls_fingerprints": "runtime_tls_fingerprints",
|
||||
"web_status": "web_status", "web_sessions": "web_sessions", "users_active_ips": "users_active_ips",
|
||||
"users_quota": "users_quota", "config_get": "get_config", "config_state": "config_state", "users_list": "list_users",
|
||||
}
|
||||
calls = {key: (method, (), {}, None) for key, method in reads.items()}
|
||||
calls.update({
|
||||
"web_session": ("web_session", (SESSION,), {}, None),
|
||||
"web_sessions_close": ("web_close_sessions", (INSTANCE, {"kind": "refs", "session_refs": [SESSION]}), {}, {"runtime_instance": INSTANCE, "selector": {"kind": "refs", "session_refs": [SESSION]}}),
|
||||
"web_operation": ("web_operation", (OPERATION,), {}, None),
|
||||
**{key: (method, (INSTANCE,), {}, {"runtime_instance": INSTANCE}) for key, method in
|
||||
[("web_debug_clear", "web_debug_clear"), ("web_learning_reset", "web_learning_reset"),
|
||||
("web_pause", "web_pause"), ("web_resume", "web_resume")]},
|
||||
"web_drain": ("web_drain", (INSTANCE, 30), {}, {"runtime_instance": INSTANCE, "timeout_secs": 30}),
|
||||
"config_validate": ("validate_config", ({"general": {"log_level": "debug"}},), {}, {"general": {"log_level": "debug"}}),
|
||||
"config_patch": ("patch_config", ({"web": {"enabled": False}},), {}, {"web": {"enabled": False}}),
|
||||
"reload": ("reload", (), {}, {"mode": "instant"}),
|
||||
"reload_status": ("reload_status", (7,), {}, None),
|
||||
"users_create": ("create_user", ("alice",), {}, {"username": "alice"}),
|
||||
"users_get": ("get_user", ("alice",), {}, None),
|
||||
"users_patch": ("patch_user", ("alice",), {"enabled": False}, {"enabled": False}),
|
||||
"users_delete": ("delete_user", ("alice",), {}, None),
|
||||
"users_rotate_secret": ("rotate_secret", ("alice",), {}, None),
|
||||
"users_enable": ("enable_user", ("alice",), {}, None),
|
||||
"users_disable": ("disable_user", ("alice",), {}, None),
|
||||
"users_reset_quota": ("reset_user_quota", ("alice",), {}, None),
|
||||
})
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
catalog = json.loads((root / "src/api/discovery/operations.json").read_text())
|
||||
self.assertEqual(set(calls), {row["id"] for row in catalog} - {"web_status_html"})
|
||||
for operation in catalog:
|
||||
if operation["id"] == "web_status_html":
|
||||
continue # The HTML viewer is opened in a browser, not decoded as JSON.
|
||||
with self.subTest(operation=operation["id"]):
|
||||
method, args, options, body = calls[operation["id"]]
|
||||
status = operation["success"][0]
|
||||
self.peer.reply({"fixture": operation["id"]}, status)
|
||||
response = getattr(self.api, method)(*args, **options)
|
||||
request = self.peer.requests[-1]
|
||||
self.assertEqual(request["method"], operation["method"])
|
||||
self.assertEqual(request["path"], operation["path"].format(username="alice", id=7, session_ref=SESSION, operation_id=OPERATION))
|
||||
self.assertEqual(request["body"], body)
|
||||
self.assertEqual(request["headers"]["authorization"], ["Bearer synthetic-test"])
|
||||
self.assertEqual(request["headers"]["content-type"], ["application/json"])
|
||||
self.assertEqual(response.http_status, status)
|
||||
self.assertEqual(response.revision, "source-revision")
|
||||
|
||||
def test_exact_user_fields_match_the_versioned_request_contract(self):
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
artifact = json.loads((root / "docs/Architecture/API/openapi-v1.json").read_text())
|
||||
self.assertEqual(USER_FIELDS, set(artifact["components"]["schemas"]["PatchUserRequest"]["properties"]))
|
||||
|
||||
def test_config_sparse_body_queries_and_both_preconditions_are_unchanged(self):
|
||||
body = {"general": {"ad_tag": None, "me_keepalive_enabled": False}, "upstreams": []}
|
||||
for method in (self.api.validate_config, self.api.patch_config):
|
||||
self.peer.reply({"reload": {"reload_id": 7}}, 202 if method == self.api.patch_config else 200)
|
||||
method(body, if_match='"source"', if_runtime_match='"process:1:2"', reload="drain", timeout_secs=30, failure_policy="rollback")
|
||||
request = self.peer.requests[-1]
|
||||
self.assertEqual(request["body"], body)
|
||||
self.assertEqual(parse_qs(urlsplit(request["path"]).query), {"reload": ["drain"], "timeout_secs": ["30"], "failure_policy": ["rollback"]})
|
||||
self.assertEqual(request["headers"]["if-match"], ['"source"'])
|
||||
self.assertEqual(request["headers"]["if-runtime-match"], ['"process:1:2"'])
|
||||
|
||||
def test_null_false_zero_and_legacy_none_omission(self):
|
||||
self.peer.reply({})
|
||||
fields = {"data_quota_bytes": None, "quota_period": None, "rate_limit_up_bps": 0, "enabled": False}
|
||||
self.api.patch_user_fields("alice", fields, if_match="rev")
|
||||
self.assertEqual(self.peer.requests[-1]["body"], fields)
|
||||
self.peer.reply({})
|
||||
self.api.patch_user("alice", max_tcp_conns=None, data_quota_bytes=0, enabled=False, rate_limit_down_bps=0)
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"data_quota_bytes": 0, "enabled": False, "rate_limit_down_bps": 0})
|
||||
self.peer.reply({})
|
||||
self.api.create_user("alice", enabled=False, quota_period="weekly", rate_limit_up_bps=0, rate_limit_down_bps=12)
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"username": "alice", "enabled": False, "quota_period": "weekly", "rate_limit_up_bps": 0, "rate_limit_down_bps": 12})
|
||||
|
||||
def test_rotation_controls_preserve_revision_and_real_http_status(self):
|
||||
for method in (self.api.enable_user, self.api.disable_user, self.api.reset_user_quota, self.api.delete_user, self.api.rotate_secret):
|
||||
self.peer.reply({"in_runtime": False}, 202)
|
||||
response = method("alice", if_match="source-rev")
|
||||
self.assertEqual(response.http_status, 202)
|
||||
self.assertEqual(self.peer.requests[-1]["headers"]["if-match"], ["source-rev"])
|
||||
self.peer.reply({"secret": "0" * 32})
|
||||
self.api.rotate_secret("alice", secret="0" * 32)
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"secret": "0" * 32})
|
||||
|
||||
def test_ready_503_and_web_410_are_data_only_on_the_documented_routes(self):
|
||||
for status, method, args, data in [(503, self.api.health_ready, (), {"ready": False}),
|
||||
(410, self.api.web_session, (SESSION,), {"state": "closed", "reason": "timeout"})]:
|
||||
self.peer.reply(data, status)
|
||||
response = method(*args)
|
||||
self.assertEqual(response.data, data)
|
||||
self.assertEqual(response.http_status, status)
|
||||
self.peer.reply(data, status)
|
||||
with self.assertRaises(TelemtAPIError):
|
||||
self.api.health()
|
||||
self.peer.raw(b'{"ok":false,"error":{"code":"web_snapshot_busy","message":"busy"}}', 503)
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.health_ready()
|
||||
self.assertEqual(raised.exception.code, "web_snapshot_busy")
|
||||
|
||||
def test_error_envelope_retains_details_and_request_id(self):
|
||||
details = [{"path": "web.debug", "code": "effective_config_invalid", "message": "retained capacity"}]
|
||||
self.peer.raw(json.dumps({"ok": False, "error": {"code": "bad_request", "message": "invalid", "details": details}, "request_id": 42}).encode(), 400)
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.validate_config({})
|
||||
error = raised.exception
|
||||
self.assertEqual((error.http_status, error.code, error.request_id, error.details), (400, "bad_request", 42, details))
|
||||
self.assertEqual(len(self.peer.requests), 1)
|
||||
|
||||
def test_gray_and_malformed_responses_are_structured_errors_without_raw_contents(self):
|
||||
for raw in (b"", b"<html>private-source-excerpt</html>", b"[]", b'{"ok":"true"}', b'{"ok":true}'):
|
||||
self.peer.raw(raw)
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.health()
|
||||
self.assertEqual(raised.exception.code, "invalid_response")
|
||||
self.assertEqual(raised.exception.http_status, 200)
|
||||
self.assertNotIn("private-source-excerpt", str(raised.exception))
|
||||
|
||||
def test_transport_failure_never_resubmits_a_mutation(self):
|
||||
for failure in (URLError("unreachable"), TimeoutError("socket timed out"),
|
||||
RemoteDisconnected("connection closed after submission")):
|
||||
with self.subTest(failure=type(failure).__name__), patch("tools.telemt_api.urlopen", side_effect=failure) as request:
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.reload()
|
||||
self.assertIs(raised.exception.__cause__, failure)
|
||||
self.assertEqual(request.call_count, 1)
|
||||
self.assertEqual(request.call_args.args[0].get_method(), "POST")
|
||||
self.assertEqual(self.peer.requests, [])
|
||||
|
||||
def test_documented_python_examples_run_against_the_http_contract(self):
|
||||
root = Path(__file__).resolve().parents[2]
|
||||
guide = (root / "docs/Architecture/API/PYTHON_CLIENT.md").read_text()
|
||||
examples = re.findall(r"^```python\n(.*?)^```", guide, re.M | re.S)
|
||||
self.assertEqual(len(examples), 3)
|
||||
self.peer.reply({"username": "alice"})
|
||||
self.peer.reply({"base_revision": "source", "runtime": {"runtime_match": "publication"}})
|
||||
self.peer.reply({"reload": {"reload_id": 7, "config_revision": "target"}}, 202)
|
||||
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": "succeeded"})
|
||||
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}})
|
||||
self.peer.reply({"sessions": [{"session_ref": SESSION}]})
|
||||
self.peer.reply({"operation_id": OPERATION}, 202)
|
||||
self.peer.reply({"operation_id": OPERATION, "state": "completed"})
|
||||
self.peer.reply({"drain": {"operation_id": "wd1.synthetic"}}, 202)
|
||||
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}, "operator_lifecycle": {
|
||||
"drain": {"operation_id": "wd1.synthetic", "state": "completed"}}})
|
||||
namespace = {}
|
||||
with patch("tools.telemt_api.TelemtAPI", return_value=self.api):
|
||||
for example in examples:
|
||||
exec(compile(example, "PYTHON_CLIENT.md", "exec"), namespace)
|
||||
self.assertEqual(len(self.peer.requests), 10)
|
||||
self.assertEqual(len(self.peer.responses), 0)
|
||||
self.assertEqual(self.peer.requests[0]["body"]["quota_period"], None)
|
||||
self.assertEqual(self.peer.requests[2]["headers"]["if-runtime-match"], ["publication"])
|
||||
self.assertEqual(self.peer.requests[6]["body"]["runtime_instance"], INSTANCE)
|
||||
self.assertEqual(self.peer.requests[6]["body"]["selector"]["session_refs"], [SESSION])
|
||||
|
||||
def test_query_and_path_values_cannot_inject_parameters(self):
|
||||
self.peer.reply({})
|
||||
self.api.web_sessions(user="alice&limit=200", host="a+b.example", ip="::1", cursor=SESSION, limit=1)
|
||||
self.assertEqual(parse_qs(urlsplit(self.peer.requests[-1]["path"]).query),
|
||||
{"user": ["alice&limit=200"], "host": ["a+b.example"], "ip": ["::1"], "cursor": [SESSION], "limit": ["1"]})
|
||||
self.peer.reply({})
|
||||
self.api.get_user("alice?admin=true#fragment")
|
||||
self.assertEqual(self.peer.requests[-1]["path"], "/v1/users/alice%3Fadmin%3Dtrue%23fragment")
|
||||
|
||||
def test_state_scopes_nullable_revision_and_unknown_convergence_are_preserved(self):
|
||||
data = {"desired_status": "unreadable", "subsystem_convergence": "unknown", "effective": {"fields": []}}
|
||||
self.peer.reply(data, revision=None)
|
||||
response = self.api.config_state(["web", "access"])
|
||||
self.assertIsNone(response.revision)
|
||||
self.assertEqual(response.data, data)
|
||||
self.assertEqual(parse_qs(urlsplit(self.peer.requests[-1]["path"]).query), {"sections": ["web,access"]})
|
||||
|
||||
def test_invalid_bounds_and_combinations_send_nothing(self):
|
||||
cases = [lambda: self.api.reload("instant", timeout_secs=1), lambda: self.api.reload("drain"),
|
||||
lambda: self.api.reload("drain", timeout_secs=3601), lambda: self.api.reload(failure_policy="retry"),
|
||||
lambda: self.api.patch_config({}, timeout_secs=2), lambda: self.api.patch_config([]),
|
||||
lambda: self.api.web_sessions(limit=201), lambda: self.api.web_sessions(session_ref=SESSION, limit=1),
|
||||
lambda: self.api.runtime_tls_fingerprints(0), lambda: self.api.runtime_events_recent(True),
|
||||
lambda: self.api.web_drain(INSTANCE, 0), lambda: self.api.web_close_sessions(INSTANCE, {"kind": "filter"}),
|
||||
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "refs", "session_refs": [SESSION] * 2}),
|
||||
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "all", "user": "alice"}),
|
||||
lambda: self.api.web_close_sessions(INSTANCE, {"kind": "filter", "host": "x" * 70000}),
|
||||
lambda: self.api.config_state([]), lambda: self.api.config_state(["web", "web"]),
|
||||
lambda: self.api.get_user("../alice"), lambda: self.api.patch_user_fields("alice", {"typo": 1})]
|
||||
for call in cases:
|
||||
with self.subTest(call=call), self.assertRaises(ValueError):
|
||||
call()
|
||||
self.assertEqual(self.peer.requests, [])
|
||||
|
||||
def test_polling_reaches_every_reload_and_web_terminal_state_without_mutation(self):
|
||||
for terminal in ("succeeded", "failed", "rolled_back"):
|
||||
for phase in ("accepted", "preparing", "activating", "draining", terminal):
|
||||
self.peer.reply({"reload_id": 7, "config_revision": "target", "state": phase})
|
||||
response = self.api.wait_reload(7, expected_revision="target", poll_interval=0.001)
|
||||
self.assertEqual(response.data["state"], terminal)
|
||||
for terminal in ("completed", "cancelled", "failed"):
|
||||
for phase in ("queued", "running", terminal):
|
||||
self.peer.reply({"operation_id": OPERATION, "state": phase})
|
||||
response = self.api.wait_web_operation(OPERATION, poll_interval=0.001)
|
||||
self.assertEqual(response.data["state"], terminal)
|
||||
self.assertTrue(all(request["method"] == "GET" for request in self.peer.requests))
|
||||
|
||||
def test_drain_polling_preserves_process_and_operation_identity(self):
|
||||
for phase in ("draining", "force_closing", "completed"):
|
||||
self.peer.reply({"runtime": {"runtime_instance": INSTANCE}, "operator_lifecycle": {"drain": {"operation_id": "wd1.synthetic", "state": phase}}})
|
||||
response = self.api.wait_web_drain(INSTANCE, "wd1.synthetic", poll_interval=0.001)
|
||||
self.assertEqual(response.data["operator_lifecycle"]["drain"]["state"], "completed")
|
||||
self.peer.reply({"runtime": {"runtime_instance": "f" * 32}, "operator_lifecycle": {"drain": {"operation_id": "wd1.synthetic", "state": "completed"}}})
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.wait_web_drain(INSTANCE, "wd1.synthetic")
|
||||
self.assertEqual(raised.exception.code, "operation_mismatch")
|
||||
|
||||
def test_polling_rejects_reused_reload_ids_and_unknown_or_malformed_status(self):
|
||||
for data, code in [({"reload_id": 7, "config_revision": "different", "state": "succeeded"}, "operation_mismatch"),
|
||||
({"reload_id": 7, "config_revision": "target", "state": "invented"}, "invalid_response"),
|
||||
(None, "invalid_response")]:
|
||||
self.peer.reply(data)
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.wait_reload(7, expected_revision="target")
|
||||
self.assertEqual(raised.exception.code, code)
|
||||
|
||||
def test_poll_budget_caps_each_request_and_keeps_last_response(self):
|
||||
clock = [0.0]
|
||||
def sleep(seconds):
|
||||
clock[0] += seconds
|
||||
for _ in range(2):
|
||||
self.peer.reply({"reload_id": 7, "state": "preparing"})
|
||||
with patch("tools.telemt_api.time.monotonic", side_effect=lambda: clock[0]), patch("tools.telemt_api.time.sleep", side_effect=sleep), patch("tools.telemt_api.urlopen", wraps=__import__("urllib.request", fromlist=["urlopen"]).urlopen) as request:
|
||||
with self.assertRaises(TelemtAPIError) as raised:
|
||||
self.api.wait_reload(7, timeout=0.5, poll_interval=0.3)
|
||||
self.assertEqual(raised.exception.code, "poll_timeout")
|
||||
self.assertEqual(raised.exception.last_response.data["state"], "preparing")
|
||||
self.assertEqual([call.kwargs["timeout"] for call in request.call_args_list], [0.5, 0.2])
|
||||
self.assertEqual(len(self.peer.requests), 2)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user