mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
API: expose observability settings and fix cross-generation cache races
This commit is contained in:
@@ -41,6 +41,7 @@ def build_document():
|
||||
"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),
|
||||
"source_deny": nullable({"type": "array", "items": {"type": "string", "format": "cidr"}}),
|
||||
}
|
||||
schemas = {
|
||||
"SuccessEnvelope": object_schema({"ok": {"const": True}, "data": {},
|
||||
@@ -58,7 +59,17 @@ def build_document():
|
||||
**{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"}})})),
|
||||
"server": nullable(object_schema({
|
||||
"listeners": nullable({"type": "array", "items": {"type": "object"}}),
|
||||
"api": nullable(object_schema({
|
||||
"minimal_runtime_enabled": nullable(boolean),
|
||||
"minimal_runtime_cache_ttl_ms": nullable({"type": "integer", "minimum": 0, "maximum": 60000}),
|
||||
"runtime_edge_enabled": nullable(boolean),
|
||||
"runtime_edge_cache_ttl_ms": nullable({"type": "integer", "minimum": 0, "maximum": 60000}),
|
||||
"runtime_edge_top_n": nullable({"type": "integer", "minimum": 1, "maximum": 1000}),
|
||||
})),
|
||||
})),
|
||||
"network": nullable(object_schema({"dns_overrides": nullable({"type": "array", "items": string, "maxItems": 4096})})),
|
||||
}),
|
||||
"ReloadRequest": object_schema({
|
||||
"mode": {"enum": ["instant", "drain"], "default": "instant"},
|
||||
@@ -128,6 +139,23 @@ def build_document():
|
||||
"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"))
|
||||
rates = object_schema({"up_bps": {**count, "maximum": 100000000000},
|
||||
"down_bps": {**count, "maximum": 100000000000}})
|
||||
policy = {"user_max_tcp_conns_global_each": count, "user_max_unique_ips_global_each": count,
|
||||
"user_max_unique_ips_mode": {"enum": ["active_window", "time_window", "combined"]},
|
||||
"user_max_unique_ips_window_secs": {"type": "integer", "minimum": 1},
|
||||
"cidr_rate_limits": {"type": "object", "additionalProperties": rates}}
|
||||
schemas["AccessPolicy"] = object_schema(policy, policy.keys())
|
||||
schemas["AccessPolicyPatch"] = {**object_schema({key: nullable(value) for key, value in policy.items()}),
|
||||
"minProperties": 1, "description": "Omitted fields stay unchanged. Scalar null restores the type default. cidr_rate_limits null clears the map; otherwise keys merge, null entries delete, and non-null entries replace the whole rate pair in bits/second. At least one direction must be positive. One writable source per mutation."}
|
||||
schemas["AccessPolicyPatch"]["properties"]["cidr_rate_limits"] = nullable({"type": "object", "additionalProperties": nullable(rates)})
|
||||
policy_state = {"desired": ref("AccessPolicy"), "effective": ref("AccessPolicy"),
|
||||
"runtime": ref("RuntimeBaseline"), "published_match": boolean,
|
||||
"effective_scope": {"const": "active_config_snapshot"}, "subsystem_convergence": {"const": "unknown"},
|
||||
"apply_mode": {"const": "watcher"}, "changed_paths": strings}
|
||||
schemas["AccessPolicyData"] = object_schema(policy_state, [key for key in policy_state if key != "changed_paths"])
|
||||
schemas["AccessPolicyResponse"] = object_schema({"ok": {"const": True}, "data": ref("AccessPolicyData"),
|
||||
"revision": string}, ("ok", "data", "revision"))
|
||||
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())
|
||||
@@ -231,6 +259,7 @@ def build_document():
|
||||
"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",
|
||||
"access_policy_get": "AccessPolicyResponse", "access_policy_patch": "AccessPolicyResponse",
|
||||
"config_state": "ConfigStateResponse"}.get(operation["id"], "SuccessEnvelope")
|
||||
responses = {str(status): {"description": "Success or documented state payload",
|
||||
"content": {"application/json": {"schema": ref(response_schema)}}}
|
||||
|
||||
+27
-3
@@ -67,6 +67,9 @@ class APIResponse:
|
||||
# Main client
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_UNSET = object()
|
||||
|
||||
|
||||
class TelemtAPI:
|
||||
"""
|
||||
HTTP client for the Telemt Control API.
|
||||
@@ -229,6 +232,17 @@ class TelemtAPI:
|
||||
query = {"sections": ",".join(sections)}
|
||||
return self._get("/v1/config/state", query)
|
||||
|
||||
def access_policy(self) -> APIResponse:
|
||||
"""Desired/published access defaults and CIDR shaping, without credentials."""
|
||||
return self._get("/v1/access/policy")
|
||||
|
||||
def patch_access_policy(self, patch: dict, *, if_match: str | None = None,
|
||||
if_runtime_match: str | None = None) -> APIResponse:
|
||||
"""Preserve explicit null resets and CIDR entry deletion semantics."""
|
||||
_object(patch, "patch")
|
||||
return self._request("PATCH", "/v1/access/policy", patch, if_match,
|
||||
if_runtime_match=if_runtime_match)
|
||||
|
||||
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:
|
||||
@@ -413,6 +427,7 @@ class TelemtAPI:
|
||||
rate_limit_up_bps: int | None = None,
|
||||
rate_limit_down_bps: int | None = None,
|
||||
enabled: bool | None = None,
|
||||
source_deny: list[str] | None | object = _UNSET,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""POST /v1/users — create a new user.
|
||||
@@ -436,9 +451,12 @@ class TelemtAPI:
|
||||
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.
|
||||
Per-user upload/download bit rates; zero values are transmitted.
|
||||
enabled:
|
||||
Optional admission flag; False is transmitted.
|
||||
source_deny:
|
||||
Source CIDRs; omission retains an orphan rule, None removes it.
|
||||
Changes require a generation reload.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision for optimistic concurrency.
|
||||
"""
|
||||
@@ -453,6 +471,8 @@ class TelemtAPI:
|
||||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||||
_opt(body, "enabled", enabled)
|
||||
if source_deny is not _UNSET:
|
||||
body["source_deny"] = source_deny
|
||||
return self._post("/v1/users", body=body, if_match=if_match)
|
||||
|
||||
def patch_user(
|
||||
@@ -469,6 +489,7 @@ class TelemtAPI:
|
||||
rate_limit_up_bps: int | None = None,
|
||||
rate_limit_down_bps: int | None = None,
|
||||
enabled: bool | None = None,
|
||||
source_deny: list[str] | None = None,
|
||||
if_match: str | None = None,
|
||||
) -> APIResponse:
|
||||
"""PATCH /v1/users/{username} — partial update; only provided fields change.
|
||||
@@ -490,8 +511,10 @@ class TelemtAPI:
|
||||
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,
|
||||
Recurring quota, bit rates and admission flag. None omits a field,
|
||||
preserving the legacy helper contract; use patch_user_fields to clear.
|
||||
source_deny:
|
||||
Replace the source CIDR list; use patch_user_fields to send null.
|
||||
if_match:
|
||||
Optional ``If-Match`` revision.
|
||||
"""
|
||||
@@ -506,6 +529,7 @@ class TelemtAPI:
|
||||
_opt(body, "rate_limit_up_bps", rate_limit_up_bps)
|
||||
_opt(body, "rate_limit_down_bps", rate_limit_down_bps)
|
||||
_opt(body, "enabled", enabled)
|
||||
_opt(body, "source_deny", source_deny)
|
||||
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:
|
||||
@@ -665,7 +689,7 @@ class TelemtAPI:
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
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"}
|
||||
"quota_period", "rate_limit_up_bps", "rate_limit_down_bps", "max_unique_ips", "enabled", "source_deny"}
|
||||
|
||||
|
||||
def _safe(value: str) -> str:
|
||||
|
||||
+13
-1
@@ -16,7 +16,7 @@ else:
|
||||
|
||||
READ_COMMANDS = {
|
||||
"health": "health", "ready": "health_ready", "capabilities": "capabilities",
|
||||
"schema": "config_schema", "config": "get_config", "info": "system_info",
|
||||
"access-policy": "access_policy", "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",
|
||||
@@ -85,6 +85,9 @@ def build_parser():
|
||||
_reload_args(sub)
|
||||
if name == "config-patch":
|
||||
_poll_args(sub, optional=True)
|
||||
sub = command("access-policy-patch")
|
||||
sub.add_argument("--json", required=True, metavar="FILE")
|
||||
sub.add_argument("--if-runtime-match")
|
||||
sub = command("reload")
|
||||
_reload_args(sub, submission=True)
|
||||
_poll_args(sub, optional=True)
|
||||
@@ -101,6 +104,12 @@ def build_parser():
|
||||
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 {}))
|
||||
deny = sub.add_mutually_exclusive_group()
|
||||
deny.add_argument("--source-deny", action="append", default=argparse.SUPPRESS, metavar="CIDR",
|
||||
help="Replace the source deny list (repeat for multiple CIDRs); generation reload required")
|
||||
if name == "create":
|
||||
deny.add_argument("--clear-source-deny", dest="source_deny", action="store_const", const=None,
|
||||
default=argparse.SUPPRESS, help="Remove a retained rule when recreating this username")
|
||||
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)
|
||||
@@ -177,6 +186,9 @@ def _dispatch(api, args):
|
||||
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 == "access-policy-patch":
|
||||
return api.patch_access_policy(_json_file(args.json), if_match=revision,
|
||||
if_runtime_match=args.if_runtime_match)
|
||||
if command == "reload":
|
||||
response = api.reload(args.mode, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy, if_match=revision)
|
||||
if args.wait:
|
||||
|
||||
@@ -24,7 +24,7 @@ class ClientTests(unittest.TestCase):
|
||||
|
||||
def test_all_json_operations_match_the_rust_catalog(self):
|
||||
reads = {
|
||||
"health": "health", "health_ready": "health_ready", "capabilities": "capabilities",
|
||||
"access_policy_get": "access_policy", "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",
|
||||
@@ -48,6 +48,7 @@ class ClientTests(unittest.TestCase):
|
||||
"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}}),
|
||||
"access_policy_patch": ("patch_access_policy", ({"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}},), {}, {"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}}),
|
||||
"reload": ("reload", (), {}, {"mode": "instant"}),
|
||||
"reload_status": ("reload_status", (7,), {}, None),
|
||||
"users_create": ("create_user", ("alice",), {}, {"username": "alice"}),
|
||||
@@ -85,7 +86,10 @@ class ClientTests(unittest.TestCase):
|
||||
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": []}
|
||||
body = {"general": {"ad_tag": None, "me_keepalive_enabled": False}, "upstreams": [],
|
||||
"server": {"api": {"minimal_runtime_enabled": False, "minimal_runtime_cache_ttl_ms": 0,
|
||||
"runtime_edge_enabled": True, "runtime_edge_cache_ttl_ms": None,
|
||||
"runtime_edge_top_n": 1}}}
|
||||
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")
|
||||
@@ -117,6 +121,22 @@ class ClientTests(unittest.TestCase):
|
||||
self.api.rotate_secret("alice", secret="0" * 32)
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"secret": "0" * 32})
|
||||
|
||||
def test_source_deny_creation_distinguishes_omitted_null_and_empty(self):
|
||||
for options, expected in [({}, {"username": "alice"}),
|
||||
({"source_deny": None}, {"username": "alice", "source_deny": None}),
|
||||
({"source_deny": []}, {"username": "alice", "source_deny": []}),
|
||||
({"source_deny": ["192.0.2.0/24", "2001:db8::/32"]},
|
||||
{"username": "alice", "source_deny": ["192.0.2.0/24", "2001:db8::/32"]})]:
|
||||
self.peer.reply({})
|
||||
self.api.create_user("alice", **options)
|
||||
self.assertEqual(self.peer.requests[-1]["body"], expected)
|
||||
self.peer.reply({})
|
||||
self.api.patch_user("alice", source_deny=[])
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"source_deny": []})
|
||||
self.peer.reply({})
|
||||
self.api.patch_user_fields("alice", {"source_deny": None})
|
||||
self.assertEqual(self.peer.requests[-1]["body"], {"source_deny": None})
|
||||
|
||||
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"})]:
|
||||
|
||||
@@ -78,6 +78,38 @@ class CLITests(unittest.TestCase):
|
||||
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_access_policy_preserves_null_entries_and_both_fences(self):
|
||||
body = {"user_max_tcp_conns_global_each": None, "cidr_rate_limits": {"192.0.2.0/24": None}}
|
||||
self.peer.reply({})
|
||||
result = self.run_cli(["access-policy-patch", "--json", "-", "--if-match", "source",
|
||||
"--if-runtime-match", "runtime"], json.dumps(body))
|
||||
self.assertEqual(result[0], 0, result[2])
|
||||
request = self.peer.requests[-1]
|
||||
self.assertEqual(request["path"], "/v1/access/policy")
|
||||
self.assertEqual(request["body"], body)
|
||||
self.assertEqual(request["headers"]["if-match"], ["source"])
|
||||
self.assertEqual(request["headers"]["if-runtime-match"], ["runtime"])
|
||||
self.peer.reply({})
|
||||
self.assertEqual(self.run_cli(["access-policy"])[0], 0)
|
||||
self.assertEqual(self.peer.requests[-1]["method"], "GET")
|
||||
|
||||
def test_source_deny_replacement_and_explicit_removal_on_recreation(self):
|
||||
for command in ("create", "patch"):
|
||||
self.peer.reply({})
|
||||
result = self.run_cli([command, "alice", "--source-deny", "192.0.2.0/24",
|
||||
"--source-deny", "2001:db8::/32"])
|
||||
self.assertEqual(result[0], 0, result[2])
|
||||
self.assertEqual(self.peer.requests[-1]["body"]["source_deny"], ["192.0.2.0/24", "2001:db8::/32"])
|
||||
for command, option in [("create", "--clear-source-deny"), ("patch", "--clear")]:
|
||||
self.peer.reply({})
|
||||
result = self.run_cli([command, "alice", option, *(["source_deny"] if command == "patch" else [])])
|
||||
self.assertEqual(result[0], 0, result[2])
|
||||
self.assertIsNone(self.peer.requests[-1]["body"]["source_deny"])
|
||||
count = len(self.peer.requests)
|
||||
self.assertEqual(self.run_cli(["create", "alice", "--source-deny", "192.0.2.0/24", "--clear-source-deny"])[0], 2)
|
||||
self.assertEqual(self.run_cli(["patch", "alice", "--source-deny", "192.0.2.0/24", "--clear", "source_deny"])[0], 2)
|
||||
self.assertEqual(len(self.peer.requests), count)
|
||||
|
||||
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"})
|
||||
|
||||
Reference in New Issue
Block a user