Rename and fix code regarding the control and command interfaces

Author: GabyUnalaq

.agents/ARCHITECTURE.md

@@ -1,17 +1,29 @@
 # Architecture (Agent Reference)
 
-Read this before making changes to `ControlInterface`, `Ankaios`, the
-protocol layer, or exception handling.
-
-## Control Interface
-
-The SDK communicates with the Ankaios agent via a Unix socket at
-`/run/ankaios/control_interface` (two FIFOs: `input` and `output`). Messages
-are length-delimited protobuf (`_control_api` wrapping `_ank_base`).
-
-`ControlInterface` runs a background reader thread that deserializes
-incoming messages and dispatches them to `Ankaios` via callbacks. `Ankaios`
-routes responses to the correct caller using a request-ID queue.
+Read this before making changes to `ControlInterfaceConnection`,
+`CommandInterfaceConnection`, `Ankaios`, the protocol layer, or exception
+handling.
+
+## Connections
+
+`Ankaios` talks to Ankaios through one of two interchangeable connections,
+both implementing the `Connection` abstract base class
+(`ankaios_sdk/_components/connection/connection.py`), picked via
+`ConnectionType` at construction time:
+
+- **Control Interface** (`ConnectionType.CONTROL_INTERFACE`, default) — used
+  from inside an Ankaios-managed workload. Communicates via a Unix socket at
+  `/run/ankaios/control_interface` (two FIFOs: `input` and `output`).
+  Messages are length-delimited protobuf (`_control_api` wrapping
+  `_ank_base`). Implemented by `ControlInterfaceConnection`.
+- **Command Interface** (`ConnectionType.COMMAND_INTERFACE`) — used from
+  outside a workload, connecting directly to the Ankaios server over gRPC.
+  Only available if the SDK was installed with the `grpc` extra. Implemented
+  by `CommandInterfaceConnection`.
+
+Both run a background reader thread that deserializes incoming messages and
+dispatches them to `Ankaios` via callbacks. `Ankaios` routes responses to the
+correct caller using a request-ID queue.
 
 `Ankaios` is the primary entry point, typically used as a context manager:
 

AGENTS.md

@@ -24,5 +24,5 @@ Read these only when they apply to the task at hand:
   before making any code or test change: API compatibility, coverage
   philosophy, lint/PEP 8 enforcement, generated proto file handling.
 - [.agents/ARCHITECTURE.md](.agents/ARCHITECTURE.md) — required before
-  touching `ControlInterface`, `Ankaios`, the protocol layer, or exception
-  handling.
+  touching `ControlInterfaceConnection`, `CommandInterfaceConnection`,
+  `Ankaios`, the protocol layer, or exception handling.

DEVELOPMENT.md

@@ -56,8 +56,9 @@ from unittest.mock import patch, PropertyMock
 from ankaios_sdk import Ankaios, ControlInterfaceState
 
 def generate_test_ankaios() -> Ankaios:
-    with patch("ankaios_sdk.ControlInterface.connect"), patch(
-        "ankaios_sdk.ControlInterface.connected", new_callable=PropertyMock
+    with patch("ankaios_sdk.ControlInterfaceConnection.connect"), patch(
+        "ankaios_sdk.ControlInterfaceConnection.connected",
+        new_callable=PropertyMock,
     ) as mock_connected:
         mock_connected.return_value = True
         ankaios = Ankaios()

README.md

@@ -145,7 +145,7 @@ a CI job or a management tool), use a gRPC connection instead:
 from ankaios_sdk import Ankaios, ConnectionType
 
 with Ankaios(
-    connection_type=ConnectionType.GRPC,
+    connection_type=ConnectionType.COMMAND_INTERFACE,
     server_url="http://127.0.0.1:25551",
 ) as ankaios:
     ...

ankaios_sdk/_components/connection/__init__.py

@@ -21,9 +21,9 @@
 
 - Connection component:
     the abstract base class for a connection to Ankaios.
-- ControlInterface component:
+- ControlInterfaceConnection component:
     the control interface (named pipes) implementation of Connection.
-- GrpcConnection component:
+- CommandInterfaceConnection component:
     the command interface (gRPC server interface) implementation of
     Connection. Only available if the 'grpc' extra is installed.
 """
@@ -32,10 +32,10 @@
 from .control_interface import *
 
 try:
-    from .grpc_interface import *
+    from .command_interface import *
 except ImportError:
-    # The 'grpc' extra is not installed; GrpcConnection stays unavailable,
-    # but the rest of the SDK must still work.
+    # The 'grpc' extra is not installed; CommandInterfaceConnection
+    # stays unavailable, but the rest of the SDK must still work.
     pass
 
 __all__ = [name for name in globals() if not name.startswith("_")]

…_components/connection/grpc_interface.py …mponents/connection/command_interface.pyankaios_sdk/_components/connection/grpc_interface.py renamed to ankaios_sdk/_components/connection/command_interface.py ankaios_sdk/_components/connection/grpc_interface.py renamed to ankaios_sdk/_components/connection/command_interface.py

@@ -13,29 +13,29 @@
 # SPDX-License-Identifier: Apache-2.0
 
 """
-This script defines the GrpcConnection class, implementing the
+This script defines the CommandInterfaceConnection class, implementing the
 Connection abstraction over a direct gRPC connection to the Ankaios
 server, used to connect to Ankaios from outside a workload.
 
 Classes
 -------
 
-- :class:`GrpcConnection`:
+- :class:`CommandInterfaceConnection`:
     Handles the interaction with Ankaios over gRPC.
 
 Enums
 -----
 
-- :class:`GrpcConnectionState`:
+- :class:`CommandInterfaceState`:
     Represents the state of the gRPC connection.
 
 Usage
 -----
 
-- Create a GrpcConnection instance, connect and disconnect.
+- Create a CommandInterfaceConnection instance, connect and disconnect.
     .. code-block:: python
 
-        conn = GrpcConnection(
+        conn = CommandInterfaceConnection(
             "http://127.0.0.1:25551", <callbacks from Ankaios>
         )
         conn.connect()
@@ -44,7 +44,7 @@
 """
 
 
-__all__ = ["GrpcConnection", "GrpcConnectionState"]
+__all__ = ["CommandInterfaceConnection", "CommandInterfaceState"]
 
 
 import queue
@@ -64,7 +64,7 @@
 from .connection import Connection
 
 
-class GrpcConnectionState(Enum):
+class CommandInterfaceState(Enum):
     """The state of the gRPC connection."""
 
     INITIALIZED = 1
@@ -87,11 +87,11 @@ def __str__(self) -> str:
 
 
 # pylint: disable=too-many-instance-attributes
-class GrpcConnection(Connection):
+class CommandInterfaceConnection(Connection):
     """
-    This class handles the interaction with an Ankaios server over a
-    direct gRPC connection, playing the commander role via the
-    CommandConnection service.
+    This class handles the interaction with an Ankaios server over the
+    command interface: a direct gRPC connection to the server,
+    playing the commander role via the CommandConnection service.
 
     The initial :func:`connect` attempt is never retried. Once a
     connection has been established, losing it is treated as
@@ -119,8 +119,8 @@ def __init__(
         key_pem: Optional[str] = None,
     ) -> None:
         """
-        Initialize the GrpcConnection object. This is used to
-        interact with an Ankaios server directly over gRPC.
+        Initialize the CommandInterfaceConnection object. This is used to
+        interact with an Ankaios server directly over the command interface.
 
         If none of ca_pem, crt_pem and key_pem are provided, the
         connection is a plaintext (insecure) one. If all three are
@@ -170,31 +170,31 @@ def __init__(
         self._key_pem = key_pem
 
         # The state of the connection must not be changed directly.
-        self._state_value = GrpcConnectionState.TERMINATED
+        self._state_value = CommandInterfaceState.TERMINATED
         self._state_lock = threading.Lock()
         self._channel: Optional[grpc.Channel] = None
         self._call = None
         self._write_queue: "queue.Queue" = queue.Queue()
         self._reader_thread: Optional[threading.Thread] = None
 
     @property
-    def _state(self) -> GrpcConnectionState:
+    def _state(self) -> CommandInterfaceState:
         """
         Get the current state of the connection.
 
         :returns: The current state.
-        :rtype: GrpcConnectionState
+        :rtype: CommandInterfaceState
         """
         with self._state_lock:
             return self._state_value
 
     @_state.setter
-    def _state(self, value: GrpcConnectionState) -> None:
+    def _state(self, value: CommandInterfaceState) -> None:
         """
         Set the current state of the connection.
 
         :param value: The new state to set.
-        :type value: GrpcConnectionState
+        :type value: CommandInterfaceState
         """
         with self._state_lock:
             self._state_value = value
@@ -207,7 +207,7 @@ def connected(self) -> bool:
         :returns: True if connected, False otherwise.
         :rtype: bool
         """
-        return self._state == GrpcConnectionState.CONNECTED
+        return self._state == CommandInterfaceState.CONNECTED
 
     def connect(self) -> None:
         """
@@ -221,35 +221,35 @@ def connect(self) -> None:
             the connection could not be established.
         """
         if self._state in (
-            GrpcConnectionState.INITIALIZED,
-            GrpcConnectionState.CONNECTED,
-            GrpcConnectionState.RECONNECTING,
+            CommandInterfaceState.INITIALIZED,
+            CommandInterfaceState.CONNECTED,
+            CommandInterfaceState.RECONNECTING,
         ):
             raise ConnectionException("Already connected.")
 
         # Only change the state once past the point where connecting
         # can still fail, so a failed attempt leaves the connection
         # exactly as it was and free to retry via a plain connect().
         call = self._open_stream()
-        self._state = GrpcConnectionState.INITIALIZED
+        self._state = CommandInterfaceState.INITIALIZED
 
         self._reader_thread = threading.Thread(
             target=self._read_from_grpc, args=(call,), daemon=True
         )
         self._reader_thread.start()
-        self._state = GrpcConnectionState.CONNECTED
+        self._state = CommandInterfaceState.CONNECTED
         self._logger.debug("Connected to the Ankaios server over gRPC.")
 
     def disconnect(self) -> None:
         """
         Disconnect from the gRPC connection.
         """
-        if self._state == GrpcConnectionState.TERMINATED:
+        if self._state == CommandInterfaceState.TERMINATED:
             self._logger.debug("Already disconnected.")
             return
 
         self._logger.debug("Disconnecting..")
-        self._state = GrpcConnectionState.TERMINATED
+        self._state = CommandInterfaceState.TERMINATED
         if self._call is not None:
             self._call.cancel()
         if self._reader_thread is not None:
@@ -271,7 +271,7 @@ def write_request(self, request: Request) -> None:
 
         :raises ConnectionException: If not connected.
         """
-        if self._state != GrpcConnectionState.CONNECTED:
+        if self._state != CommandInterfaceState.CONNECTED:
             self._logger.error(
                 "Could not write to the gRPC connection, not connected."
             )
@@ -384,7 +384,7 @@ def _read_from_grpc(self, call) -> None:
                 for from_server in call:
                     self._handle_from_server(from_server)
             except grpc.RpcError as e:
-                if self._state == GrpcConnectionState.TERMINATED:
+                if self._state == CommandInterfaceState.TERMINATED:
                     # disconnect() already cancelled the call itself;
                     # this is the expected, self-inflicted result.
                     self._logger.debug(
@@ -397,10 +397,10 @@ def _read_from_grpc(self, call) -> None:
                         e,
                     )
 
-            if self._state == GrpcConnectionState.TERMINATED:
+            if self._state == CommandInterfaceState.TERMINATED:
                 return
 
-            self._state = GrpcConnectionState.RECONNECTING
+            self._state = CommandInterfaceState.RECONNECTING
             self._logger.warning(
                 "Lost connection to the Ankaios server, attempting to "
                 "reconnect every %ss..",
@@ -421,14 +421,14 @@ def _reconnect(self):
         """
         while True:
             time.sleep(self.RECONNECT_INTERVAL)
-            if self._state == GrpcConnectionState.TERMINATED:
+            if self._state == CommandInterfaceState.TERMINATED:
                 return None
             try:
                 call = self._open_stream()
             except ConnectionException as e:
                 self._logger.debug("Reconnect attempt failed: '%s'", e)
                 continue
-            self._state = GrpcConnectionState.CONNECTED
+            self._state = CommandInterfaceState.CONNECTED
             self._logger.info("Reconnected to the Ankaios server.")
             return call
 

ankaios_sdk/_components/connection/connection.py

@@ -49,8 +49,8 @@ class ConnectionType(Enum):
 
     CONTROL_INTERFACE = 1
     "(int): Connect via the control interface (named pipes)."
-    GRPC = 2
-    "(int): Connect directly to the Ankaios server over gRPC."
+    COMMAND_INTERFACE = 2
+    "(int): Connect via the command interface (direct gRPC)."
 
     def __str__(self) -> str:
         """