Merge pull request 'openapi: add strict top-level checking' (#4280) from api-cleanup into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4280

pkgs/clan-cli/clan_lib/api/directory.py

@@ -69,7 +69,7 @@ def blk_from_dict(data: dict) -> BlkInfo:
 
 
 @API.register
-def list_block_devices() -> Blockdevices:
+def list_system_storage_devices() -> Blockdevices:
     """
     List local block devices by running `lsblk`.
 

pkgs/clan-cli/clan_lib/api/mdns_discovery.py

@@ -88,7 +88,7 @@ def parse_avahi_output(output: str) -> DNSInfo:
 
 
 @API.register
-def list_mdns_services() -> DNSInfo:
+def list_system_services_mdns() -> DNSInfo:
     """List mDNS/DNS-SD services on the local network.
     Returns:
         DNSInfo: A dictionary containing discovered mDNS/DNS-SD services.
@@ -111,7 +111,7 @@ def list_mdns_services() -> DNSInfo:
 
 
 def mdns_command(args: argparse.Namespace) -> None:
-    dns_info = list_mdns_services()
+    dns_info = list_system_services_mdns()
     for name, info in dns_info.services.items():
         print(f"Hostname: {name} - ip: {info.ip}")
 

pkgs/clan-cli/clan_lib/api/tasks.py

@@ -33,7 +33,7 @@ def delete_task(task_id: str) -> None:
 
 
 @API.register
-def run_blocking_task(somearg: str) -> str:
+def run_task_blocking(somearg: str) -> str:
     """A long blocking task that simulates a long-running operation."""
     time.sleep(1)
     ctx = get_async_ctx()

pkgs/clan-cli/openapi.py

@@ -29,6 +29,25 @@ COMMON_VERBS = {
 }
 
 
+# !!! IMPORTANT !!!
+# AVOID ADDING RESOUCRCES IN THIS LIST
+# Think twice before adding a new resource.
+# If you need a new resource, consider if it can be a sub-resource of an existing
+# resource instead.
+# If you need a new top-level resource, create an issue to discuss it first.
+TOP_LEVEL_RESOURCES = {
+    "clan",  # clan management
+    "machine",  # machine management
+    "task",  # task management
+    "file",  # file operations
+    "secret",  # sops & key operations
+    "log",  # log operations
+    "generator",  # vars generators operations
+    "module",  # module (clan.service) management
+    "system",  # system operations
+}
+
+
 def is_verb(word: str) -> bool:
     return word in COMMON_VERBS
 
@@ -60,12 +79,19 @@ def normalize_op_name(op_name: str) -> list[str]:
 
 def check_operation_name(op_name: str, normalized: list[str]) -> list[str]:
     verb = normalized[0]
-    _nouns = normalized[1:]
+    nouns = normalized[1:]
     warnings = []
     if not is_verb(verb):
         warnings.append(
             f"""Verb '{verb}' of API operation {op_name} is not allowed.
 Use one of: {", ".join(COMMON_VERBS)}
+"""
+        )
+    top_level_noun = nouns[0] if nouns else None
+    if top_level_noun is None or top_level_noun.lower() not in TOP_LEVEL_RESOURCES:
+        warnings.append(
+            f"""Top-level resource '{top_level_noun}' of API operation {op_name} is not allowed.
+Use one of: {", ".join(TOP_LEVEL_RESOURCES)}
 """
         )
     return warnings