Support secrets & signing

Signed-off-by: Mathias L. Baumann <mathias.baumann@frequenz.com>

Author: Marenz

RELEASE_NOTES.md

@@ -10,7 +10,9 @@
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* Support secrets for signing and veryfying messages.
+  * Use the new env variable `DISPATCH_API_SECRET` to set the secret key.
+  * Use the new `sign_secret` parameter in the `DispatchClient` constructor to set the secret key.
 
 ## Bug Fixes
 

mkdocs.yml

@@ -103,14 +103,15 @@ plugins:
             paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
-            merge_init_into_class: false
+            merge_init_into_class: true
             separate_signature: true
             show_category_heading: true
             show_root_heading: true
             show_root_members_full_path: true
             show_signature_annotations: true
             show_source: true
             signature_crossrefs: true
+            members_order: source
           import:
             - https://docs.python.org/3/objects.inv
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv

pyproject.toml

@@ -38,7 +38,7 @@ requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
   "frequenz-api-dispatch == 1.0.0-rc2",
-  "frequenz-client-base >= 0.8.0, < 0.12.0",
+  "frequenz-client-base >= 0.11.0, < 0.12.0",
   "frequenz-client-common >= 0.3.2,  < 0.4.0",
   "frequenz-core >= 1.0.2, < 2.0.0",
   "grpcio >= 1.70.0, < 2",

src/frequenz/client/dispatch/__main__.py

@@ -177,6 +177,14 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
     show_envvar=True,
     required=True,
 )
+@click.option(
+    "--secret",
+    help="API signing secret for authentication",
+    envvar="DISPATCH_API_SECRET",
+    show_envvar=True,
+    required=False,
+    default=None,
+)
 @click.option(
     "--raw",
     is_flag=True,
@@ -185,29 +193,36 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
     default=False,
 )
 @click.pass_context
-async def cli(ctx: click.Context, url: str, key: str, raw: bool) -> None:
+async def cli(
+    ctx: click.Context, url: str, key: str, secret: str | None, raw: bool
+) -> None:
     """Dispatch Service CLI."""
     if ctx.obj is None:
         ctx.obj = {}
 
     click.echo(f"Using API URL: {url}", err=True)
+    click.echo(f"Using API Key: {key}", err=True)
+    if secret:
+        click.echo(f"Using API Secret: {secret}", err=True)
 
     ctx.obj["client"] = DispatchApiClient(
         server_url=url,
-        key=key,
+        auth_key=key,
+        sign_secret=secret,
         connect=True,
     )
 
     ctx.obj["params"] = {
         "url": url,
         "key": key,
+        "secret": secret,
     }
 
     ctx.obj["raw"] = raw
 
     # Check if a subcommand was given
     if ctx.invoked_subcommand is None:
-        await interactive_mode(url, key)
+        await interactive_mode(url, key, secret)
 
 
 @cli.command("list")
@@ -533,8 +548,9 @@ async def repl(
     obj: dict[str, Any],
 ) -> None:
     """Start an interactive interface."""
-    click.echo(f"Parameters: {obj}")
-    await interactive_mode(obj["params"]["url"], obj["params"]["key"])
+    await interactive_mode(
+        obj["params"]["url"], obj["params"]["key"], obj["params"]["secret"]
+    )
 
 
 @cli.command()
@@ -574,7 +590,7 @@ async def delete(
         raise click.ClickException("Some deletions failed.")
 
 
-async def interactive_mode(url: str, key: str) -> None:
+async def interactive_mode(url: str, key: str, secret: str | None) -> None:
     """Interactive mode for the CLI."""
     hist_file = os.path.expanduser("~/.dispatch_cli_history.txt")
     session: PromptSession[str] = PromptSession(history=FileHistory(filename=hist_file))
@@ -619,6 +635,8 @@ async def display_help() -> None:
                 url,
                 "--key",
                 key,
+                "--secret",
+                secret if secret else "",
             ] + click.parser.split_arg_string(user_input)
 
             try:

src/frequenz/client/dispatch/_client.py

@@ -60,7 +60,8 @@ def __init__(
         self,
         *,
         server_url: str,
-        key: str,
+        auth_key: str,
+        sign_secret: str | None = None,
         connect: bool = True,
         call_timeout: timedelta = timedelta(seconds=60),
         stream_timeout: timedelta = timedelta(minutes=5),
@@ -69,7 +70,8 @@ def __init__(
 
         Args:
             server_url: The URL of the server to connect to.
-            key: API key to use for authentication.
+            auth_key: API key to use for authentication.
+            sign_secret: Optional secret for signing requests.
             connect: Whether to connect to the service immediately.
             call_timeout: Timeout for gRPC calls, default is 60 seconds.
             stream_timeout: Timeout for gRPC streams, default is 5 minutes.
@@ -82,8 +84,9 @@ def __init__(
                 port=DEFAULT_DISPATCH_PORT,
                 ssl=SslOptions(enabled=True),
             ),
+            auth_key=auth_key,
+            sign_secret=sign_secret,
         )
-        self._metadata = (("key", key),)
         self._streams: dict[
             MicrogridId,
             GrpcStreamBroadcaster[StreamMicrogridDispatchesResponse, DispatchEvent],
@@ -199,7 +202,7 @@ def to_interval(
             response = await cast(
                 Awaitable[ListMicrogridDispatchesResponse],
                 self.stub.ListMicrogridDispatches(
-                    request, metadata=self._metadata, timeout=self._call_timeout_seconds
+                    request, timeout=self._call_timeout_seconds
                 ),
             )
 
@@ -256,7 +259,6 @@ def _get_stream(
                     AsyncIterator[StreamMicrogridDispatchesResponse],
                     self.stub.StreamMicrogridDispatches(
                         request,
-                        metadata=self._metadata,
                         timeout=self._stream_timeout_seconds,
                     ),
                 ),
@@ -327,7 +329,6 @@ async def create(  # pylint: disable=too-many-positional-arguments
             Awaitable[CreateMicrogridDispatchResponse],
             self.stub.CreateMicrogridDispatch(
                 request.to_protobuf(),
-                metadata=self._metadata,
                 timeout=self._call_timeout_seconds,
             ),
         )
@@ -419,9 +420,7 @@ async def update(
 
         response = await cast(
             Awaitable[UpdateMicrogridDispatchResponse],
-            self.stub.UpdateMicrogridDispatch(
-                msg, metadata=self._metadata, timeout=self._call_timeout_seconds
-            ),
+            self.stub.UpdateMicrogridDispatch(msg, timeout=self._call_timeout_seconds),
         )
 
         return Dispatch.from_protobuf(response.dispatch)
@@ -443,9 +442,7 @@ async def get(
         )
         response = await cast(
             Awaitable[GetMicrogridDispatchResponse],
-            self.stub.GetMicrogridDispatch(
-                request, metadata=self._metadata, timeout=self._call_timeout_seconds
-            ),
+            self.stub.GetMicrogridDispatch(request, timeout=self._call_timeout_seconds),
         )
         return Dispatch.from_protobuf(response.dispatch)
 
@@ -464,6 +461,6 @@ async def delete(
         await cast(
             Awaitable[None],
             self.stub.DeleteMicrogridDispatch(
-                request, metadata=self._metadata, timeout=self._call_timeout_seconds
+                request, timeout=self._call_timeout_seconds
             ),
         )

src/frequenz/client/dispatch/test/client.py

@@ -24,7 +24,7 @@ def __init__(
         self,
     ) -> None:
         """Initialize the mock client."""
-        super().__init__(server_url="mock", key=ALL_KEY, connect=False)
+        super().__init__(server_url="mock", auth_key=ALL_KEY, connect=False)
         self._stuba: FakeService = FakeService()
 
     @property