Make the client accept a server URL to connect to (#49)

This URL is a string with the form
`grpc://hostname[:<port:int=9090>][?ssl=<ssl:bool=false>]`, meaning that
the `port` and `ssl` are optional and default to 9090 and `false`
respectively.

This makes it more convenient to take server URLs from config files and
enviroment variables, but it also means gRPC channels are not exposed
directly to users anymore, so the internal implementation to connect to
the gRPC server can be changed without it being a breaking change (we
could potentially even change the protocol completely to use something
else rather than gRPC).

Author: llucax

RELEASE_NOTES.md

@@ -6,9 +6,10 @@
 
 ## Upgrading
 
-- The client is now using [`grpclib`](https://pypi.org/project/grpclib/) to connect to the server instead of [`grpcio`](https://pypi.org/project/grpcio/). You might need to adapt the way you connect to the server in your code, using `grpcio.client.Channel`.
+- The client now uses a string URL to connect to the server, the `grpc_channel` and `target` arguments are now replaced by `server_url`. The current accepted format is `grpc://hostname[:<port:int=9090>][?ssl=<ssl:bool=false>]`, meaning that the `port` and `ssl` are optional and default to 9090 and `false` respectively. You will have to adapt the way you connect to the server in your code.
+- The client is now using [`grpclib`](https://pypi.org/project/grpclib/) to connect to the server instead of [`grpcio`](https://pypi.org/project/grpcio/). You might need to adapt your code if you are using `grpcio` directly.
 - The client now doesn't raise `grpc.aio.RpcError` exceptions anymore. Instead, it raises `ClientError` exceptions that have the `grpclib.GRPCError` as their `__cause__`. You might need to adapt your error handling code to catch `ClientError` exceptions instead of `grpc.aio.RpcError` exceptions.
-- The client now uses protobuf/grpc bindings generated [betterproto](https://github.com/danielgtaylor/python-betterproto) instead of [grpcio](https://pypi.org/project/grpcio/). If you were using the bindings directly, you might need to do some minor adjustments to your code.
+- The client now uses protobuf/grpc bindings generated [betterproto](https://github.com/danielgtaylor/python-betterproto) ([frequenz-microgrid-betterproto](https://github.com/frequenz-floss/frequenz-microgrid-betterproto-python)) instead of [grpcio](https://pypi.org/project/grpcio/) ([frequenz-api-microgrid](https://github.com/frequenz-floss/frequenz-api-microgrid)). If you were using the bindings directly, you might need to do some minor adjustments to your code.
 
 ## New Features
 

src/frequenz/client/microgrid/_client.py

@@ -12,7 +12,7 @@
 import grpclib.client
 from betterproto.lib.google import protobuf as pb_google
 from frequenz.channels import Receiver
-from frequenz.client.base import retry, streaming
+from frequenz.client.base import channel, retry, streaming
 from frequenz.microgrid.betterproto.frequenz.api import microgrid as pb_microgrid
 from frequenz.microgrid.betterproto.frequenz.api.common import (
     components as pb_components,
@@ -48,33 +48,41 @@
 
 
 class ApiClient:
-    """Microgrid API client implementation using gRPC as the underlying protocol."""
+    """A microgrid API client."""
 
     def __init__(
         self,
-        grpc_channel: grpclib.client.Channel,
-        target: str,
+        server_url: str,
+        *,
         retry_strategy: retry.Strategy | None = None,
     ) -> None:
         """Initialize the class instance.
 
         Args:
-            grpc_channel: asyncio-supporting gRPC channel
-            target: server (host:port) to be used for asyncio-supporting gRPC
-                channel that the client should use to contact the API
+            server_url: The location of the microgrid API server in the form of a URL.
+                The following format is expected:
+                "grpc://hostname{:`port`}{?ssl=`ssl`}",
+                where the `port` should be an int between 0 and 65535 (defaulting to
+                9090) and `ssl` should be a boolean (defaulting to `false`).
+                For example: `grpc://localhost:1090?ssl=true`.
             retry_strategy: The retry strategy to use to reconnect when the connection
                 to the streaming method is lost. By default a linear backoff strategy
                 is used.
         """
-        self.target = target
-        """The location (as "host:port") of the microgrid API gRPC server."""
+        self._server_url = server_url
+        """The location of the microgrid API server as a URL."""
 
-        self.api = pb_microgrid.MicrogridStub(grpc_channel)
+        self.api = pb_microgrid.MicrogridStub(channel.parse_grpc_uri(server_url))
         """The gRPC stub for the microgrid API."""
 
         self._broadcasters: dict[int, streaming.GrpcStreamBroadcaster[Any, Any]] = {}
         self._retry_strategy = retry_strategy
 
+    @property
+    def server_url(self) -> str:
+        """The server location in URL format."""
+        return self._server_url
+
     async def components(self) -> Iterable[Component]:
         """Fetch all the components present in the microgrid.
 
@@ -93,7 +101,7 @@ async def components(self) -> Iterable[Component]:
 
         except grpclib.GRPCError as err:
             raise ClientError(
-                f"Failed to list components. Microgrid API: {self.target}. Err: {err}"
+                f"Failed to list components. Microgrid API: {self._server_url}. Err: {err}"
             ) from err
 
         components_only = filter(
@@ -176,7 +184,7 @@ async def connections(
             )
         except grpclib.GRPCError as err:
             raise ClientError(
-                f"Failed to list connections. Microgrid API: {self.target}. Err: {err}"
+                f"Failed to list connections. Microgrid API: {self._server_url}. Err: {err}"
             ) from err
         # Filter out the components filtered in `components` method.
         # id=0 is an exception indicating grid component.
@@ -388,7 +396,7 @@ async def set_power(self, component_id: int, power_w: float) -> None:
             )
         except grpclib.GRPCError as err:
             raise ClientError(
-                f"Failed to set power. Microgrid API: {self.target}. Err: {err}"
+                f"Failed to set power. Microgrid API: {self._server_url}. Err: {err}"
             ) from err
 
     async def set_bounds(
@@ -410,7 +418,7 @@ async def set_bounds(
             ClientError: If the connection to the Microgrid API cannot be established or
                 when the api call exceeded the timeout.
         """
-        api_details = f"Microgrid API: {self.target}."
+        api_details = f"Microgrid API: {self._server_url}."
         if upper < 0:
             raise ValueError(f"Upper bound {upper} must be greater than or equal to 0.")
         if lower > 0:
@@ -437,6 +445,6 @@ async def set_bounds(
                 err,
             )
             raise ClientError(
-                f"Failed to set inclusion bounds. Microgrid API: {self.target}. "
+                f"Failed to set inclusion bounds. Microgrid API: {self._server_url}. "
                 f"Err: {err}"
             ) from err

tests/test_client.py

@@ -57,11 +57,8 @@
 
 class _TestClient(ApiClient):
     def __init__(self, *, retry_strategy: retry.Strategy | None = None) -> None:
-        mock_channel = mock.MagicMock(name="channel", spec=grpclib.client.Channel)
         mock_stub = mock.MagicMock(name="stub", spec=microgrid.MicrogridStub)
-        target = "mock_host:1234"
-        super().__init__(mock_channel, target, retry_strategy)
-        self.mock_channel = mock_channel
+        super().__init__("grpc://mock_host:1234", retry_strategy=retry_strategy)
         self.mock_stub = mock_stub
         self.api = mock_stub
 
@@ -215,7 +212,8 @@ async def test_components_grpc_error() -> None:
     )
     with pytest.raises(
         ClientError,
-        match="Failed to list components. Microgrid API: mock_host:1234. Err: .*fake grpc error",
+        match="Failed to list components. Microgrid API: grpc://mock_host:1234. "
+        "Err: .*fake grpc error",
     ):
         await client.components()
 
@@ -354,7 +352,8 @@ async def test_connections_grpc_error() -> None:
     )
     with pytest.raises(
         ClientError,
-        match="Failed to list connections. Microgrid API: mock_host:1234. Err: .*fake grpc error",
+        match="Failed to list connections. Microgrid API: grpc://mock_host:1234. "
+        "Err: .*fake grpc error",
     ):
         await client.connections()
 
@@ -569,7 +568,8 @@ async def test_set_power_grpc_error() -> None:
     )
     with pytest.raises(
         ClientError,
-        match="Failed to set power. Microgrid API: mock_host:1234. Err: .*fake grpc error",
+        match="Failed to set power. Microgrid API: grpc://mock_host:1234. "
+        "Err: .*fake grpc error",
     ):
         await client.set_power(component_id=83, power_w=100.0)
 
@@ -634,7 +634,7 @@ async def test_set_bounds_grpc_error() -> None:
     )
     with pytest.raises(
         ClientError,
-        match="Failed to set inclusion bounds. Microgrid API: mock_host:1234. "
+        match="Failed to set inclusion bounds. Microgrid API: grpc://mock_host:1234. "
         "Err: .*fake grpc error",
     ):
         await client.set_bounds(99, 0.0, 100.0)