Support secrets & signing

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -10,7 +10,9 @@
 
 ## New Features
 
-* `Dispatch.started_at(now: datetime)` was added as alternative to the `started` property for when users want to use the same `now` for multiple calls, ensuring deterministic return values with respect to the same `now`.
+* Support secrets for signing and verifying 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
 

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

@@ -171,12 +171,20 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
     show_envvar=True,
 )
 @click.option(
-    "--key",
+    "--api-key",
     help="API key for authentication",
     envvar="DISPATCH_API_KEY",
     show_envvar=True,
     required=True,
 )
+@click.option(
+    "--sign-secret",
+    help="API signing secret for authentication",
+    envvar="DISPATCH_API_SIGN_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, api_key: str, sign_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: {api_key}", err=True)
+    if sign_secret:
+        click.echo(f"Using API Secret: {sign_secret}", err=True)
 
     ctx.obj["client"] = DispatchApiClient(
         server_url=url,
-        key=key,
+        auth_key=api_key,
+        sign_secret=sign_secret,
         connect=True,
     )
 
     ctx.obj["params"] = {
         "url": url,
-        "key": key,
+        "api_key": api_key,
+        "sign_secret": sign_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, api_key, sign_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"]["api_key"], obj["params"]["sign_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, api_key: str, sign_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))
@@ -614,12 +630,11 @@ async def display_help() -> None:
             break
         else:
             # Split, but keep quoted strings together
-            params = [
-                "--url",
-                url,
-                "--key",
-                key,
-            ] + click.parser.split_arg_string(user_input)
+            params = (
+                ["--url", url, "--api-key", api_key]
+                + (["--sign-secret", sign_secret] if sign_secret else [])
+                + click.parser.split_arg_string(user_input)
+            )
 
             try:
                 await cli.main(args=params, standalone_mode=False)

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],
@@ -138,7 +141,8 @@ async def list(
 
         ```python
         client = DispatchApiClient(
-            key="key",
+            auth_key="key",
+            sign_secret="secret", # Optional so far
             server_url="grpc://dispatch.url.goes.here.example.com"
         )
         async for page in client.list(microgrid_id=MicrogridId(1)):
@@ -199,7 +203,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 +260,6 @@ def _get_stream(
                     AsyncIterator[StreamMicrogridDispatchesResponse],
                     self.stub.StreamMicrogridDispatches(
                         request,
-                        metadata=self._metadata,
                         timeout=self._stream_timeout_seconds,
                     ),
                 ),
@@ -327,7 +330,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 +421,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 +443,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 +462,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