Source code for ankaios_sdk._components.connection.control_interface

# Copyright (c) 2024 Elektrobit Automotive GmbH
#
# This program and the accompanying materials are made available under the
# terms of the Apache License, Version 2.0 which is available at
# https://www.apache.org/licenses/LICENSE-2.0.
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
#
# SPDX-License-Identifier: Apache-2.0

"""
This script defines the ControlInterfaceConnection class that handles
the writing and reading of data to and from the Ankaios control
interface.

Classes
-------

- :class:`ControlInterfaceConnection`:
    Handles the interaction with the Ankaios control interface.

Enums
-----

- :class:`ControlInterfaceState`:
    Represents the state of the control interface connection.

Usage
-----

- Create a ControlInterfaceConnection instance, connect and disconnect.
    .. code-block:: python

        ci = ControlInterfaceConnection(<callbacks from Ankaios>)
        ci.connect()
        ...
        ci.disconnect()
"""


__all__ = ["ControlInterfaceConnection", "ControlInterfaceState"]


import os
import select
import threading
from typing import Callable
from enum import Enum
from google.protobuf.internal.encoder import _VarintBytes
from google.protobuf.internal.decoder import _DecodeVarint

from ..._protos import _control_api
from ..request import Request
from ..response import Response, ResponseException, ResponseType
from ...exceptions import ConnectionException, ConnectionClosedException
from ...utils import DEFAULT_CONTROL_INTERFACE_PATH, ANKAIOS_VERSION
from .connection import Connection


[docs] class ControlInterfaceState(Enum): """The state of the control interface connection.""" INITIALIZED = 1 "(int): Connection initialized state." CONNECTED = 2 "(int): Connection established state." TERMINATED = 3 "(int): Connection stopped state." AGENT_DISCONNECTED = 4 "(int): Agent disconnected state." CONNECTION_CLOSED = 5 "(int): Connection closed state."
[docs] def __str__(self) -> str: """ Returns the string representation of the state. :returns: The state as a string. :rtype: str """ return self.name
# pylint: disable=too-many-instance-attributes
[docs] class ControlInterfaceConnection(Connection): """ This class handles the interaction with the Ankaios control interface. It provides methods to send and receive data to and from the control interface pipes. """ ANKAIOS_CONTROL_INTERFACE_BASE_PATH = DEFAULT_CONTROL_INTERFACE_PATH "(str): The base path for the Ankaios control interface." AGENT_RECONNECT_INTERVAL_SEC = 1 "(int): Seconds to wait between hello retries while the agent is gone." _ACTIVE_STATES = ( ControlInterfaceState.INITIALIZED, ControlInterfaceState.CONNECTED, ControlInterfaceState.AGENT_DISCONNECTED, ) "(tuple): The states in which a reader thread is running."
[docs] def __init__( self, add_response_callback: Callable, add_log_callback: Callable, add_event_callback: Callable, ) -> None: """ Initialize the ControlInterfaceConnection object. This is used to interact with the control interface. :param add_response_callback: The callback function to add a response to the Ankaios class. :type add_response_callback: Callable :param add_log_callback: The callback function to add a log to the Ankaios class. :type add_log_callback: Callable :param add_event_callback: The callback function to add an event to the Ankaios class. :type add_event_callback: Callable """ super().__init__( add_response_callback, add_log_callback, add_event_callback ) # The state of the control interface must not be changed directly. # Use the _set_state method instead. self._state = ControlInterfaceState.TERMINATED # Guards _state, _output_file and _read_thread. Never held across # a fifo write or a thread join. self._lock = threading.Lock() # Held across every framed write and around closing the output # file, so a write can never be split by another writer or have # its file closed underneath it. Never taken while holding _lock. self._write_lock = threading.Lock() self._output_file = None self._read_thread = None self._disconnect_event = threading.Event()
@property def connected(self) -> bool: """ Check if the control interface is connected. :returns: True if connected, False otherwise. :rtype: bool """ return self._state == ControlInterfaceState.CONNECTED
[docs] def connect(self) -> None: """ Connect to the control interface by starting to read from the input fifo and opening the output fifo. :raises ConnectionException: If an error occurred. """ with self._lock: if self._state in self._ACTIVE_STATES: raise ConnectionException("Already connected.") # Only one reader thread may ever run: a previous one that did # not stop in time would otherwise read the same fifo and tear # down this connection's resources when it finally exits. if self._read_thread is not None and self._read_thread.is_alive(): raise ConnectionException( "Previous connection is still shutting down." ) if not os.path.exists( f"{self.ANKAIOS_CONTROL_INTERFACE_BASE_PATH}/input" ): raise ConnectionException( "Control interface input fifo does not exist." ) if not os.path.exists( f"{self.ANKAIOS_CONTROL_INTERFACE_BASE_PATH}/output" ): raise ConnectionException( "Control interface output fifo does not exist." ) # pylint: disable=consider-using-with try: self._output_file = open( f"{self.ANKAIOS_CONTROL_INTERFACE_BASE_PATH}/output", "ab", ) except Exception as e: self._logger.error( "Error while opening output fifo: %s", e ) raise ConnectionException( "Error while opening output fifo." ) from e # A previous disconnect leaves the event set; clear it so the # new reader thread is not stopped immediately. self._disconnect_event.clear() # Set before the reader starts, so a reader that fails right # away cannot have its TERMINATED overwritten. self._set_state(ControlInterfaceState.INITIALIZED) self._read_thread = threading.Thread( target=self._read_from_control_interface, daemon=True ) self._read_thread.start() # Sent without holding the lock: the hello write can block on # the fifo and must not hold off a concurrent disconnect(). self._send_initial_hello()
[docs] def disconnect(self) -> None: """ Disconnect from the control interface. """ with self._lock: if self._state not in self._ACTIVE_STATES: self._logger.debug("Already disconnected.") return self._logger.debug("Disconnecting..") self._disconnect_event.set() output_file = self._detach_resources() # Kept even if it does not stop in time, so connect() can # refuse to start a second reader while it is still alive. read_thread = self._read_thread # The resources are detached, so the slow teardown runs unlocked. if read_thread is not None: read_thread.join(timeout=2) if read_thread.is_alive(): self._logger.error("Read thread did not stop.") self._close_output_file(output_file)
def _cleanup(self) -> None: """ Clean up the resources. Called by the reader thread when it stops; a no-op if disconnect() already cleaned up. """ with self._lock: output_file = self._detach_resources() self._close_output_file(output_file) self._logger.debug("Cleanup happened") def _detach_resources(self): """ Marks the connection as terminated and detaches the output file from it. The caller must hold the lock. :returns: The detached output file (or None if already detached), to be closed once the lock is released. """ self._set_state(ControlInterfaceState.TERMINATED) output_file, self._output_file = self._output_file, None return output_file def _close_output_file(self, output_file) -> None: """ Closes a detached output file, waiting for any write in progress on it to finish first. :param output_file: The output file to close, or None. """ if output_file is None: return with self._write_lock: output_file.close() def _change_state_from_reader( self, state: ControlInterfaceState, info: str = None ) -> None: """ Change the state of the control interface on behalf of the reader thread, unless a disconnect was requested, so the reader cannot overwrite the TERMINATED state set by disconnect(). :param state: The new state. :type state: ControlInterfaceState :param info: Additional information about the state change. :type info: str """ with self._lock: if not self._disconnect_event.is_set(): self._set_state(state, info) def _set_state( self, state: ControlInterfaceState, info: str = None ) -> None: """ Change the state of the control interface. The caller must hold the lock. :param state: The new state. :type state: ControlInterfaceState :param info: Additional information about the state change. :type info: str """ if state == self._state: self._logger.debug("State is already %s.", state) return if self._state == ControlInterfaceState.CONNECTION_CLOSED: self._logger.debug("State CONNECTION_CLOSED is unrecoverable.") return self._state = state if info is None: self._logger.debug("State changed to %s.", state) else: self._logger.debug("State changed to %s: %s", state, info) # pylint: disable=too-many-statements, too-many-branches def _read_from_control_interface(self) -> None: """ Reads from the control interface input fifo. This is meant to be run in a separate thread. The responses are then sent to the Ankaios class to be handled. The input fifo is opened and closed by this thread alone. :raises ConnectionException: If an error occurs while reading the fifo. """ # The pragma: no cover is used on small checks that are not expected # to fail. This method is difficult to test and testing each check # would be redundant. # pylint: disable=invalid-name MOST_SIGNIFICANT_BIT_MASK = 0b10000000 # pylint: disable=consider-using-with try: # Unbuffered, so select() sees every byte not yet read: a # buffered reader could hold a whole message in its own buffer # while select() reports the fifo as empty. input_file = open( f"{self.ANKAIOS_CONTROL_INTERFACE_BASE_PATH}/input", "rb", buffering=0, ) except Exception as e: self._logger.error("Error while opening input fifo: %s", e) # Runs on the reader thread itself, so it must tear down # directly instead of calling disconnect() (which would join # the current thread). self._disconnect_event.set() self._cleanup() raise ConnectionException( "Error while opening input fifo." ) from e os.set_blocking(input_file.fileno(), False) try: self._logger.debug("Started reading from the input pipe.") while not self._disconnect_event.is_set(): # The loop continues when data is available or when the # timeout of 1 second is reached. ready, _, _ = select.select([input_file], [], [], 1) if not ready: # pragma: no cover continue # Buffer for reading in the byte size of the proto msg varint_buffer = bytearray() while True: # Consume byte for byte next_byte = input_file.read(1) if not next_byte: # pragma: no cover break varint_buffer += next_byte # Check if we reached the last byte if next_byte[0] & MOST_SIGNIFICANT_BIT_MASK == 0: break if not varint_buffer: self._change_state_from_reader( ControlInterfaceState.AGENT_DISCONNECTED ) self._logger.warning( "Nothing to read from the input fifo pipe." ) self._agent_gone_routine() continue # Decode the varint and receive the proto msg length msg_len, _ = _DecodeVarint(varint_buffer, 0) msg_buf = self._read_exactly(input_file, msg_len) if len(msg_buf) < msg_len: self._logger.error( "Incomplete message read from the input fifo." ) continue try: response = self._decode_response(msg_buf) except ResponseException as e: # pragma: no cover self._logger.error("Error while reading: %s", e) continue # Handle the response self._handle_response(response) except Exception as e: # pylint: disable=broad-exception-caught self._logger.error("Error while reading fifo file: %s", e) finally: input_file.close() self._cleanup() def _read_exactly(self, input_file, size: int) -> bytes: """ Reads size bytes from the non-blocking input fifo, waiting for the rest to arrive if needed: a fifo only delivers a write in one piece up to PIPE_BUF bytes, so a large message can arrive in several chunks. :param input_file: The unbuffered, non-blocking input fifo. :param size: The number of bytes to read. :type size: int :returns: The bytes read; fewer than size if the agent closed the fifo or a disconnect was requested meanwhile. :rtype: bytes """ buffer = bytearray() while len(buffer) < size and not self._disconnect_event.is_set(): chunk = input_file.read(size - len(buffer)) if chunk is None: # The rest has not arrived yet. select.select([input_file], [], [], 1) continue if not chunk: # End of file: the agent closed the fifo. break buffer += chunk return bytes(buffer) @staticmethod def _decode_response(message_buffer: bytes) -> Response: """ Decodes a message read from the control interface's own envelope (a length-delimited `_control_api.FromAnkaios` message) into a Response, owning the control-interface- specific envelope unwrapping so that Response itself only needs to know about the shared ank_base.Response payload. :param message_buffer: The received message buffer. :type message_buffer: bytes :returns: The decoded Response object. :rtype: Response :raises ResponseException: If there is an error parsing the message buffer, or if it contains none of the expected variants. """ from_ankaios = _control_api.FromAnkaios() try: from_ankaios.ParseFromString(message_buffer) except Exception as e: raise ResponseException(f"Parsing error: '{e}'") from e if from_ankaios.HasField("response"): return Response._from_ank_base_response(from_ankaios.response) if from_ankaios.HasField("controlInterfaceAccepted"): return Response._control_interface_accepted() if from_ankaios.HasField("connectionClosed"): return Response._connection_closed( from_ankaios.connectionClosed.reason ) raise ResponseException( # pragma: no cover "Invalid response type." ) def _handle_response(self, response: Response) -> None: """ Handle the response received from the control interface. :param response: The response object to handle. :type response: Response :raises ConnectionException: If the response is not in a valid state. :raises ConnectionClosedException: If the connection is closed. """ # Handle the initialized state if self._state == ControlInterfaceState.INITIALIZED: if ( response.content_type == ResponseType.CONTROL_INTERFACE_ACCEPTED ): self._logger.debug( "Received control interface accepted response." ) self._change_state_from_reader( ControlInterfaceState.CONNECTED ) elif response.content_type == ResponseType.CONNECTION_CLOSED: self._add_response_callback(response) self._change_state_from_reader( ControlInterfaceState.CONNECTION_CLOSED, response.content, ) raise ConnectionClosedException(response.content) else: self._logger.error( "Received response %s, but expected " "CONTROL_INTERFACE_ACCEPTED. Ignoring..", response.content_type, ) # Handle the connected state elif self._state == ControlInterfaceState.CONNECTED: if self._dispatch_response(response): return # Check if the response is connection closed in order to # terminate the thread. if response.content_type == ResponseType.CONNECTION_CLOSED: self._change_state_from_reader( ControlInterfaceState.CONNECTION_CLOSED, response.content, ) raise ConnectionClosedException(response.content) if ( response.content_type == ResponseType.CONTROL_INTERFACE_ACCEPTED ): self._logger.warning( "Received unexpected " "control interface accepted response." ) else: self._logger.warning( "Received response %s, but not in a valid state. " "Ignoring..", response.content_type, ) def _agent_gone_routine(self) -> None: """ Method will be called when the agent is gone. It will attempt to write the hello message to the agent until the agent is connected or a disconnect is requested. """ while ( not self._disconnect_event.is_set() and self._state == ControlInterfaceState.AGENT_DISCONNECTED ): try: self._send_initial_hello() except BrokenPipeError as _: self._logger.warning("Waiting for the agent..") # Wait on the event so a disconnect wakes us immediately. self._disconnect_event.wait( self.AGENT_RECONNECT_INTERVAL_SEC ) else: self._change_state_from_reader( ControlInterfaceState.INITIALIZED ) break def _write_to_pipe(self, to_ankaios: _control_api.ToAnkaios) -> None: """ Writes the ToAnkaios proto message to the control interface output fifo. :param to_ankaios: The ToAnkaios proto message. :type to_ankaios: _control_api.ToAnkaios :raises ConnectionException: If the output pipe is None, or was closed by a disconnect before the write. """ output_file = self._output_file if output_file is None: self._logger.error( "Could not write to pipe, output file handler is None." ) raise ConnectionException( "Could not write to pipe, output file handler is None." ) # Held across the whole write so the length prefix and the payload # cannot be split by another writer, and so the file cannot be # closed mid-write. with self._write_lock: try: # Adds the byte length of the proto msg output_file.write(_VarintBytes(to_ankaios.ByteSize())) # Adds the proto msg itself output_file.write(to_ankaios.SerializeToString()) output_file.flush() except ValueError as e: # A disconnect closed the file after we took it. raise ConnectionException( "Could not write to pipe, output file closed." ) from e
[docs] def write_request(self, request: Request) -> None: """ Writes the request into the control interface output fifo. :param request: The request object to be written. :type request: Request :raises ConnectionException: If not connected. :raises ConnectionClosedException: If the connection is closed. """ state = self._state if state == ControlInterfaceState.CONNECTION_CLOSED: raise ConnectionClosedException( "Could not write to pipe, connection closed." ) if state != ControlInterfaceState.CONNECTED: raise ConnectionException( "Could not write to pipe, not connected." ) request_to_ankaios = _control_api.ToAnkaios( request=request._to_proto() ) self._write_to_pipe(request_to_ankaios)
def _send_initial_hello(self) -> None: """ Send an initial hello message with the version to the control interface. :raises ConnectionException: If not connected. """ initial_hello = _control_api.ToAnkaios( hello=_control_api.Hello(protocolVersion=str(ANKAIOS_VERSION)) ) self._write_to_pipe(initial_hello) self._logger.debug( "Sent initial hello message with the version %s", ANKAIOS_VERSION )