Show keyby/indexer in API docs for state

Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com>

Author: timkpaine

csp_gateway/server/gateway/csp/channels.py

@@ -207,6 +207,7 @@ class Channels(BaseModel, metaclass=ChannelsMetaclass):
     _feedbacks: Dict[int, FeedbackOutputDef] = PrivateAttr(default_factory=dict)
 
     _state_requests: Dict[Tuple[str, Optional[Union[str, int]]], Any] = PrivateAttr(default_factory=dict)
+    _state_keybys: Dict[Tuple[str, Optional[Union[str, int]]], Tuple[str, ...]] = PrivateAttr(default_factory=dict)
     _last_requests: Dict[Tuple[str, Optional[Union[str, int]]], Any] = PrivateAttr(default_factory=dict)
     _next_requests: Dict[Tuple[str, Optional[Union[str, int]]], Any] = PrivateAttr(default_factory=dict)
     _send_channels: Dict[Tuple[str, Optional[Union[str, int]]], Any] = PrivateAttr(default_factory=dict)
@@ -732,6 +733,7 @@ def set_state(
 
             # register the trigger
             self._state_requests[state_field, indexer] = trigger
+            self._state_keybys[state_field, indexer] = (keyby,) if isinstance(keyby, str) else tuple(keyby)
         else:
             # TODO
             raise NotImplementedError()

csp_gateway/server/web/app.py

@@ -396,7 +396,25 @@ def add_state_api(self, field: str) -> None:
             model = self._get_field_pydantic_type(name_without_state)
             subroute_key = None
 
-        add_state_routes(api_router=api_router, field=field, model=model, subroute_key=subroute_key)
+        # Look up the keyby/indexer this state was registered with (if any),
+        # so we can surface it in the route's OpenAPI description.
+        keybys = self.gateway.channels._state_keybys
+        keyby = ()
+        indexer = None
+        for (registered_field, registered_indexer), registered_keyby in keybys.items():
+            if registered_field == field:
+                keyby = registered_keyby
+                indexer = registered_indexer
+                break
+
+        add_state_routes(
+            api_router=api_router,
+            field=field,
+            model=model,
+            subroute_key=subroute_key,
+            keyby=keyby,
+            indexer=indexer,
+        )
 
     def add_state_available_channels(self, fields: Optional[Set[str]] = None) -> None:
         api_router = self.get_router("state")

csp_gateway/server/web/routes/state.py

@@ -1,4 +1,5 @@
-from typing import Any, List, Optional, Set, Union, get_origin
+from inspect import cleandoc
+from typing import Any, List, Optional, Set, Tuple, Union, get_origin
 
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
@@ -20,6 +21,8 @@ def add_state_routes(
     field: str = "",
     model: Union[BaseModel, List[BaseModel]] = None,
     subroute_key: Any = None,
+    keyby: Tuple[str, ...] = (),
+    indexer: Optional[Union[str, int]] = None,
 ) -> None:
     if model and get_origin(model) is list:
         list_model = model
@@ -29,6 +32,13 @@ def add_state_routes(
     # Get the fully qualified type name for the description
     fq_type_name = get_fully_qualified_type_name(model)
 
+    keyby_lines = []
+    if keyby:
+        keyby_lines.append("**Keyed by:** ``{}``".format(", ".join(repr(k) for k in keyby)))
+    if indexer is not None:
+        keyby_lines.append("**Indexer:** ``{!r}``".format(indexer))
+    keyby_prefix = ("\n\n".join(keyby_lines) + "\n\n") if keyby_lines else ""
+
     if subroute_key:
         # Prune s_ from start
         name_without_state = field[2:]
@@ -88,6 +98,7 @@ async def get_state(key: str, query: Optional[Query] = query_json(), request: Re
             responses=get_default_responses(),
             response_model=list_model,  # type: ignore[valid-type]
             name="Get State {} by key".format(name_without_state),
+            description=keyby_prefix + cleandoc(get_state.__doc__ or ""),
             openapi_extra={"type_": fq_type_name} if fq_type_name else None,
         )(get_state)
 
@@ -167,6 +178,7 @@ async def get_state(query: Optional[Query] = query_json(), request: Request = No
             responses=get_default_responses(),
             response_model=list_model,  # type: ignore[valid-type]
             name="Get State {}".format(name_without_state),
+            description=keyby_prefix + cleandoc(get_state.__doc__ or ""),
             openapi_extra={"type_": fq_type_name} if fq_type_name else None,
         )(get_state)