Use a server URL to connect to the microgrid API

Instead of using host and port, we now use 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`.

This also removes the default host and port, as normally users always
want to override it.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -12,6 +12,15 @@
 
 - The `microgrid.*_pool` methods would only accept keyword arguments from now on.
 
+- The `microgrid.initialize()` method now takes a `server_url` instead of a `host` and `port`.
+
+   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` or `grpc://localhost:1090?ssl=true`.
+
+   The default was also removed, so you always need to specify the server URL.
+
+   This applies to the `ConnectionManager` as well, which also now doesn't expose the `host` and `port` attributes, only the `server_url`. If you need to extract the host or port from the `server_url`, you can use the standard Python `urllib.parse.urlparse()` function.
+
+
 ## New Features
 
 - Calls to `microgrid.*_pool` methods now accept an optional `in_shifting_group` parameter.  Power requests sent to `*_pool` instances that have the `in_shifting_group` flag set, will get resolved separately, and their target power will be added to the target power calculated from regular actors, if any, which would, in effect, shift the zero for the regular actors by the target power from the shifting group.

benchmarks/power_distribution/power_distributor.py

@@ -140,7 +140,8 @@ async def run() -> None:
     # pylint: disable=protected-access
 
     await microgrid.initialize(
-        HOST, PORT, ResamplerConfig(resampling_period=timedelta(seconds=1.0))
+        "grpc://microgrid.sandbox.api.frequenz.io:62060",
+        ResamplerConfig(resampling_period=timedelta(seconds=1.0)),
     )
 
     all_batteries: set[Component] = connection_manager.get().component_graph.components(

docs/tutorials/getting_started.md

@@ -44,13 +44,11 @@ microgrid.
 ```python
 async def run() -> None:
     # This points to the default Frequenz microgrid sandbox
-    microgrid_host = "microgrid.sandbox.api.frequenz.io"
-    microgrid_port = 62060
+    server_url = "grpc://microgrid.sandbox.api.frequenz.io:62060",
 
     # Initialize the microgrid
     await microgrid.initialize(
-        microgrid_host,
-        microgrid_port,
+        server_url,
         ResamplerConfig(resampling_period=timedelta(seconds=1)),
     )
 
@@ -106,13 +104,11 @@ from frequenz.sdk.actor import ResamplerConfig
 
 async def run() -> None:
     # This points to the default Frequenz microgrid sandbox
-    microgrid_host = "microgrid.sandbox.api.frequenz.io"
-    microgrid_port = 62060
+    server_url = "grpc://microgrid.sandbox.api.frequenz.io:62060",
 
     # Initialize the microgrid
     await microgrid.initialize(
-        microgrid_host,
-        microgrid_port,
+        server_url,
         ResamplerConfig(resampling_period=timedelta(seconds=1)),
     )
 

examples/battery_pool.py

@@ -23,8 +23,7 @@ async def main() -> None:
         level=logging.DEBUG, format="%(asctime)s %(name)s %(levelname)s:%(message)s"
     )
     await microgrid.initialize(
-        host=HOST,
-        port=PORT,
+        "grpc://microgrid.sandbox.api.frequenz.io:62060",
         resampler_config=ResamplerConfig(resampling_period=timedelta(seconds=1.0)),
     )
 

src/frequenz/sdk/microgrid/__init__.py

@@ -239,15 +239,18 @@
 )
 
 
-async def initialize(host: str, port: int, resampler_config: ResamplerConfig) -> None:
+async def initialize(server_url: str, resampler_config: ResamplerConfig) -> None:
     """Initialize the microgrid connection manager and the data pipeline.
 
     Args:
-        host: Host to connect to, to reach the microgrid API.
-        port: port to connect to.
+        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`.
         resampler_config: Configuration for the resampling actor.
     """
-    await connection_manager.initialize(host, port)
+    await connection_manager.initialize(server_url)
     await _data_pipeline.initialize(resampler_config)
 
 

src/frequenz/sdk/microgrid/connection_manager.py

@@ -11,49 +11,33 @@
 import logging
 from abc import ABC, abstractmethod
 
-import grpc.aio as grpcaio
 from frequenz.client.microgrid import ApiClient, Location, Metadata
 
 from .component_graph import ComponentGraph, _MicrogridComponentGraph
 
-# Not public default host and port
-_DEFAULT_MICROGRID_HOST = "[::1]"
-_DEFAULT_MICROGRID_PORT = 443
-
 _logger = logging.getLogger(__name__)
 
 
 class ConnectionManager(ABC):
     """Creates and stores core features."""
 
-    def __init__(self, host: str, port: int) -> None:
+    def __init__(self, server_url: str) -> None:
         """Create object instance.
 
         Args:
-            host: server host
-            port: server port
+            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`.
         """
         super().__init__()
-        self._host: str = host
-        self._port: int = port
+        self._server_url = server_url
 
     @property
-    def host(self) -> str:
-        """Get host of the currently connected server.
-
-        Returns:
-            host
-        """
-        return self._host
-
-    @property
-    def port(self) -> int:
-        """Get port of the currently connected server.
-
-        Returns:
-            port
-        """
-        return self._port
+    def server_url(self) -> str:
+        """The location of the microgrid API server in the form of a URL."""
+        return self._server_url
 
     @property
     @abstractmethod
@@ -91,9 +75,8 @@ def location(self) -> Location | None:
             the location of the microgrid if available, None otherwise.
         """
 
-    async def _update_api(self, host: str, port: int) -> None:
-        self._host = host
-        self._port = port
+    async def _update_api(self, server_url: str) -> None:
+        self._server_url = server_url
 
     @abstractmethod
     async def _initialize(self) -> None:
@@ -103,19 +86,18 @@ async def _initialize(self) -> None:
 class _InsecureConnectionManager(ConnectionManager):
     """Microgrid Api with insecure channel implementation."""
 
-    def __init__(
-        self, host: str = _DEFAULT_MICROGRID_HOST, port: int = _DEFAULT_MICROGRID_PORT
-    ) -> None:
+    def __init__(self, server_url: str) -> None:
         """Create and stores core features.
 
         Args:
-            host: host. Defaults to _DEFAULT_MICROGRID_HOST.
-            port: port. Defaults to _DEFAULT_MICROGRID_PORT.
+            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`.
         """
-        super().__init__(host, port)
-        target = f"{host}:{port}"
-        grpc_channel = grpcaio.insecure_channel(target)
-        self._api = ApiClient(grpc_channel, target)
+        super().__init__(server_url)
+        self._api = ApiClient(server_url)
         # To create graph from the api we need await.
         # So create empty graph here, and update it in `run` method.
         self._graph = _MicrogridComponentGraph()
@@ -159,18 +141,20 @@ def component_graph(self) -> ComponentGraph:
         """
         return self._graph
 
-    async def _update_api(self, host: str, port: int) -> None:
+    async def _update_api(self, server_url: str) -> None:
         """Update api with new host and port.
 
         Args:
-            host: new host
-            port: new port
+            server_url: The new 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`.
         """
-        await super()._update_api(host, port)  # pylint: disable=protected-access
+        await super()._update_api(server_url)  # pylint: disable=protected-access
 
-        target = f"{host}:{port}"
-        grpc_channel = grpcaio.insecure_channel(target)
-        self._api = ApiClient(grpc_channel, target)
+        self._api = ApiClient(server_url)
         self._metadata = await self._api.metadata()
         await self._graph.refresh_from_api(self._api)
 
@@ -183,12 +167,15 @@ async def _initialize(self) -> None:
 """The ConnectionManager singleton instance."""
 
 
-async def initialize(host: str, port: int) -> None:
+async def initialize(server_url: str) -> None:
     """Initialize the MicrogridApi. This function should be called only once.
 
     Args:
-        host: Microgrid host
-        port: Microgrid port
+        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`.
 
     Raises:
         AssertionError: If method was called more then once.
@@ -200,9 +187,9 @@ async def initialize(host: str, port: int) -> None:
     if _CONNECTION_MANAGER is not None:
         raise AssertionError("MicrogridApi was already initialized.")
 
-    _logger.info("Connecting to microgrid at %s:%s", host, port)
+    _logger.info("Connecting to microgrid at %s", server_url)
 
-    microgrid_api = _InsecureConnectionManager(host, port)
+    microgrid_api = _InsecureConnectionManager(server_url)
     await microgrid_api._initialize()  # pylint: disable=protected-access
 
     # Check again that _MICROGRID_API is None in case somebody had the great idea of

src/frequenz/sdk/timeseries/_voltage_streamer.py

@@ -39,8 +39,7 @@ class VoltageStreamer:
         from frequenz.sdk.timeseries import ResamplerConfig
 
         await microgrid.initialize(
-            "127.0.0.1",
-            50051,
+            "grpc://127.0.0.1:50051",
             ResamplerConfig(resampling_period=timedelta(seconds=1))
         )
 

src/frequenz/sdk/timeseries/consumer.py

@@ -38,8 +38,7 @@ class Consumer:
         from frequenz.sdk.timeseries import ResamplerConfig
 
         await microgrid.initialize(
-            "127.0.0.1",
-            50051,
+            "grpc://127.0.0.1:50051",
             ResamplerConfig(resampling_period=timedelta(seconds=1.0))
         )
 

src/frequenz/sdk/timeseries/grid.py

@@ -51,8 +51,7 @@ class Grid:
         from frequenz.sdk.timeseries import ResamplerConfig
 
         await microgrid.initialize(
-            "127.0.0.1",
-            50051,
+            "grpc://127.0.0.1:50051",
             ResamplerConfig(resampling_period=timedelta(seconds=1))
         )
 

src/frequenz/sdk/timeseries/logical_meter/_logical_meter.py

@@ -36,8 +36,7 @@ class LogicalMeter:
         from frequenz.sdk.timeseries import ResamplerConfig
 
         await microgrid.initialize(
-            "127.0.0.1",
-            50051,
+            "grpc://127.0.0.1:50051",
             ResamplerConfig(resampling_period=timedelta(seconds=1))
         )