Add a stateful Proxmox API console and broad handler coverage beyond the

initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
2026-07-16 01:08:01 +03:00
parent 003ee5d634
commit 777926487b
189 changed files with 241501 additions and 944 deletions
@@ -0,0 +1,109 @@
+"""OpenAPI tag resolution for contract-driven routes."""
+
+from __future__ import annotations
+
+_NODE_SECTION_LABELS: dict[str, str] = {
+    "qemu": "QEMU",
+    "lxc": "LXC",
+    "ceph": "Ceph",
+    "storage": "Storage",
+    "sdn": "SDN",
+    "firewall": "Firewall",
+    "apt": "APT",
+    "certificates": "Certificates",
+    "scan": "Scan",
+    "network": "Network",
+    "services": "Services",
+    "capabilities": "Capabilities",
+    "hardware": "Hardware",
+    "replication": "Replication",
+    "tasks": "Tasks",
+    "subscription": "Subscription",
+    "vzdump": "Backup",
+    "disks": "Disks",
+    "config": "Config",
+    "dns": "DNS",
+    "hosts": "Hosts",
+    "status": "Status",
+    "time": "Time",
+    "aplinfo": "Appliance",
+}
+
+_CLUSTER_SECTION_LABELS: dict[str, str] = {
+    "sdn": "SDN",
+    "firewall": "Firewall",
+    "notifications": "Notifications",
+    "ha": "HA",
+    "mapping": "Mapping",
+    "acme": "ACME",
+    "config": "Config",
+    "ceph": "Ceph",
+    "jobs": "Jobs",
+    "metrics": "Metrics",
+    "qemu": "QEMU",
+    "backup": "Backup",
+    "bulk-action": "Bulk Action",
+    "replication": "Replication",
+    "backup-info": "Backup Info",
+    "options": "Options",
+    "log": "Log",
+    "nextid": "Next ID",
+    "resources": "Resources",
+    "status": "Status",
+    "tasks": "Tasks",
+}
+
+
+def contract_openapi_tag(path: str) -> str:
+    """Map a semantic contract path to a Swagger UI category."""
+
+    parts = [part for part in path.strip("/").split("/") if part]
+    if not parts or parts == ["version"]:
+        return "Core"
+    root = parts[0]
+    if root == "access":
+        return "Access"
+    if root == "nodes":
+        if len(parts) >= 3 and parts[1] == "{node}":
+            section = parts[2]
+            label = _NODE_SECTION_LABELS.get(section, section.replace("-", " ").title())
+            return f"Nodes · {label}"
+        return "Nodes"
+    if root == "cluster":
+        if len(parts) >= 2:
+            section = parts[1]
+            label = _CLUSTER_SECTION_LABELS.get(section, section.replace("-", " ").title())
+            return f"Cluster · {label}"
+        return "Cluster"
+    if root == "storage":
+        return "Storage"
+    if root == "pools":
+        return "Pools"
+    return root.replace("-", " ").title()
+
+
+def contract_openapi_tags(path: str, renderer: str) -> list[str]:
+    """Return OpenAPI tags for a contract route, including the API renderer."""
+
+    renderer_label = "API2 JSON" if renderer == "json" else "API2 ExtJS"
+    return [contract_openapi_tag(path), renderer_label]
+
+
+def openapi_tag_metadata() -> list[dict[str, str]]:
+    """Descriptions shown in Swagger UI for each tag group."""
+
+    descriptions: dict[str, str] = {
+        "Core": "Version and global simulator metadata.",
+        "Access": "Authentication, users, groups, roles, ACLs, and API tokens.",
+        "Nodes": "Node inventory and node-level endpoints without a resource section.",
+        "Storage": "Cluster-wide and node storage definitions and content.",
+        "Pools": "Resource pools and membership.",
+        "API2 JSON": "Proxmox `/api2/json` renderer routes.",
+        "API2 ExtJS": "Proxmox `/api2/extjs` renderer routes.",
+        "Simulator": "Health checks, compatibility reports, and the web console.",
+    }
+    for label in _NODE_SECTION_LABELS.values():
+        descriptions.setdefault(f"Nodes · {label}", f"Node-level {label} API.")
+    for label in _CLUSTER_SECTION_LABELS.values():
+        descriptions.setdefault(f"Cluster · {label}", f"Cluster-level {label} API.")
+    return [{"name": name, "description": text} for name, text in sorted(descriptions.items())]