API: expose observability settings and fix cross-generation cache races

This commit is contained in:
Alexey
2026-11-07 08:05:22 +03:00
parent b1502b629b
commit 982c4e4a34
19 changed files with 1024 additions and 52 deletions
+30 -1
View File
@@ -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
View File
@@ -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
View File
@@ -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:
+22 -2
View File
@@ -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"})]:
+32
View File
@@ -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"})