Files
telemt/tools/generate_api_openapi.py
T

313 lines
22 KiB
Python

#!/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),
"source_deny": nullable({"type": "array", "items": {"type": "string", "format": "cidr"}}),
}
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"}}),
"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"},
"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"))
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())
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",
"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)}}}
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()