nost-tools 2.0.0__py3-none-any.whl

nost_tools/application_utils.py

@@ -0,0 +1,262 @@
+"""
+Provides utility classes to help applications interact with the broker.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+import yaml
+from dotenv import dotenv_values
+from pydantic import ValidationError
+
+from .observer import Observer
+from .publisher import ScenarioTimeIntervalPublisher
+from .schemas import Config, ModeStatus, TimeStatus
+from .simulator import Mode, Simulator
+
+if TYPE_CHECKING:
+    from .application import Application
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionConfig(object):
+    """Connection configuration.
+
+    The configuration settings to establish a connection to the broker, including authentication for the
+    user and identification of the server.
+
+    Attributes:
+        username (str): client username, provided by NOS-T operator
+        password (str): client password, provided by NOS-T operator
+        host (str): broker hostname
+        rabbitmq_port (int): RabbitMQ broker port number
+        keycloak_port (int): Keycloak IAM port number
+        keycloak_realm (str): Keycloak realm name
+        client_id (str): Keycloak client ID
+        client_secret_key (str): Keycloak client secret key
+        virtual_host (str): RabbitMQ virtual host
+        is_tls (bool): True, if the connection uses Transport Layer Security (TLS)
+        env_file (str): Path to the .env file
+        yaml_file (str): Path to the YAML configuration file
+    """
+
+    def __init__(
+        self,
+        username: str = None,
+        password: str = None,
+        host: str = None,
+        rabbitmq_port: int = None,
+        keycloak_port: int = None,
+        keycloak_realm: str = None,
+        client_id: str = None,
+        client_secret_key: str = None,
+        virtual_host: str = None,
+        is_tls: bool = True,
+        env_file: str = None,
+        yaml_file: str = None,
+    ):
+        """
+        Initializes a new connection configuration.
+
+        Args:
+            username (str): client username, provided by NOS-T operator
+            password (str): client password, provided by NOS-T operator
+            host (str): broker hostname
+            rabbitmq_port (int): RabbitMQ broker port number
+            keycloak_port (int): Keycloak IAM port number
+            keycloak_realm (str): Keycloak realm name
+            client_id (str): Keycloak client ID
+            client_secret_key (str): Keycloak client secret key
+            virtual_host (str): RabbitMQ virtual host
+            is_tls (bool): True, if the connection uses TLS
+            env_file (str): Path to the .env file
+            yaml_file (str): Path to the YAML configuration file
+        """
+        self.yaml_config = None  # Initialize the attribute to store YAML data
+        self.yaml_mode = (
+            False  # Initialize the attribute to store the mode of operation
+        )
+
+        if env_file and yaml_file:
+            logger.info(f"Loading configuration from {env_file} and {yaml_file}.")
+            self.load_config_from_files(env_file, yaml_file)
+            self.yaml_mode = True
+        else:
+            logger.info("Loading configuration from arguments.")
+            self.username = username
+            self.password = password
+            self.host = host
+            self.rabbitmq_port = rabbitmq_port
+            self.keycloak_port = keycloak_port
+            self.keycloak_realm = keycloak_realm
+            self.client_id = client_id
+            self.client_secret_key = client_secret_key
+            self.virtual_host = virtual_host
+            self.is_tls = is_tls
+
+    def load_config_from_files(self, env_file: str, yaml_file: str):
+        """
+        Loads configuration from .env and YAML files.
+
+        Args:
+            env_file (str): Path to the .env file
+            yaml_file (str): Path to the YAML configuration file
+        """
+        # Load .env file
+        credentials = dotenv_values(env_file)
+        self.username = credentials["USERNAME"]
+        self.password = credentials["PASSWORD"]
+        self.client_id = credentials["CLIENT_ID"]
+        self.client_secret_key = credentials["CLIENT_SECRET_KEY"]
+
+        # Load YAML file
+        with open(yaml_file, "r") as file:
+            yaml_data = yaml.safe_load(file)
+
+        try:
+            config = Config(**yaml_data)
+            self.yaml_config = yaml_data
+        except ValidationError as e:
+            raise ValueError(f"Invalid configuration: {e}")
+
+        self.host = config.servers.rabbitmq.host
+        self.rabbitmq_port = config.servers.rabbitmq.port
+        self.keycloak_port = config.servers.keycloak.port
+        self.keycloak_realm = config.servers.keycloak.realm
+        self.virtual_host = config.servers.rabbitmq.virtual_host
+        self.is_tls = config.servers.rabbitmq.tls and config.servers.keycloak.tls
+
+        if not self.is_tls:
+            raise ValueError("TLS must be enabled for both RabbitMQ and Keycloak.")
+
+
+class ShutDownObserver(Observer):
+    """
+    Observer that shuts down an application after scenario termination.
+
+    Attributes:
+        app (:obj:`Application`): application to be shut down after termination
+    """
+
+    def __init__(self, app: "Application"):
+        """
+        Initializes a new shut down observer.
+
+        Args:
+            app (:obj:`Application`): application to be shut down after termination
+        """
+        self.app = app
+
+    def on_change(
+        self, source: object, property_name: str, old_value: object, new_value: object
+    ) -> None:
+        """
+        Shuts down the application in response to a transition to the TERMINATED mode.
+
+        Args:
+            source (object): object that triggered a property change
+            property_name (str): name of the changed property
+            old_value (obj): old value of the named property
+            new_value (obj): new value of the named property
+        """
+        if property_name == Simulator.PROPERTY_MODE and new_value == Mode.TERMINATED:
+            self.app.shut_down()
+
+
+class TimeStatusPublisher(ScenarioTimeIntervalPublisher):
+    """
+    Publishes time status messages for an application at a regular interval.
+
+    Attributes:
+        app (:obj:`Application`): application to publish time status messages
+    """
+
+    def publish_message(self) -> None:
+        """
+        Publishes a time status message.
+        """
+        status = TimeStatus.model_validate(
+            {
+                "name": self.app.app_name,
+                "description": self.app.app_description,
+                "properties": {
+                    "simTime": self.app.simulator.get_time(),
+                    "time": self.app.simulator.get_wallclock_time(),
+                },
+            }
+        )
+        logger.info(
+            f"Sending time status {status.model_dump_json(by_alias=True,exclude_none=True)}."
+        )
+
+        self.app.send_message(
+            app_name=self.app.app_name,
+            app_topics="status.time",
+            payload=status.model_dump_json(by_alias=True, exclude_none=True),
+        )
+
+
+class ModeStatusObserver(Observer):
+    """
+    Observer that publishes mode status messages for an application.
+
+    Attributes:
+        app (:obj:`Application`): application to publish mode status messages
+    """
+
+    def __init__(self, app: "Application"):
+        """
+        Initializes a new mode status observer.
+        """
+        self.app = app
+
+    def stop_application(self):
+        """
+        Stops the application by closing the channel and connection if they are open.
+        """
+        if self.app.channel.is_open:
+            self.app.channel.close()
+            logger.info(f"Channel closed for application {self.app.app_name}.")
+
+        if self.app.connection.is_open:
+            self.app.connection.close()
+            logger.info(f"Connection closed for application {self.app.app_name}.")
+
+        logger.info(f'Application "{self.app.app_name}" successfully stopped.')
+
+    def on_change(
+        self, source: object, property_name: str, old_value: object, new_value: object
+    ) -> None:
+        """
+        Publishes a mode status message in response to a mode transition.
+
+        Args:
+            source (object): observable that triggered the change
+            property_name (str): name of the changed property
+            old_value (obj): old value of the named property
+            new_value (obj): new value of the named property
+        """
+        if property_name == Simulator.PROPERTY_MODE:
+            status = ModeStatus.model_validate(
+                {
+                    "name": self.app.app_name,
+                    "description": self.app.app_description,
+                    "properties": {"mode": self.app.simulator.get_mode()},
+                }
+            )
+            logger.info(
+                f"Sending mode status {status.model_dump_json(by_alias=True, exclude_none=True)}."
+            )
+
+            # Ensure self.prefix is a string
+            if not isinstance(self.app.prefix, str):
+                raise ValueError(f"Exchange ({self.app.prefix}) must be a string")
+
+            # Declare the topic exchange
+            if self.app.channel.is_open and self.app.connection.is_open:
+                self.app.send_message(
+                    app_name=self.app.app_name,
+                    app_topics="status.mode",
+                    payload=status.model_dump_json(by_alias=True, exclude_none=True),
+                )

nost_tools/configuration.py

@@ -0,0 +1,304 @@
+"""
+Configuration Settings.
+"""
+
+import logging
+import os
+
+import yaml
+from dotenv import find_dotenv, load_dotenv
+from pydantic import ValidationError
+
+from .errors import ConfigAssertionError, ConfigurationError, EnvironmentVariableError
+from .schemas import (
+    ChannelConfig,
+    Config,
+    Credentials,
+    ExchangeConfig,
+    ExecConfig,
+    KeycloakConfig,
+    RabbitMQConfig,
+    RuntimeConfig,
+    ServersConfig,
+    SimulationConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+class ConnectionConfig:
+    """Connection configuration.
+
+    The configuration settings to establish a connection to the broker, including authentication for the
+    user and identification of the server.
+
+    Attributes:
+        username (str): client username, provided by NOS-T operator
+        password (str): client password, provided by NOS-T operator
+        host (str): broker hostname
+        rabbitmq_port (int): RabbitMQ broker port number
+        keycloak_port (int): Keycloak IAM port number
+        keycloak_realm (str): Keycloak realm name
+        client_id (str): Keycloak client ID
+        client_secret_key (str): Keycloak client secret key
+        virtual_host (str): RabbitMQ virtual host
+        is_tls (bool): True, if the connection uses Transport Layer Security (TLS)
+        yaml_file (str): Path to the YAML configuration file
+    """
+
+    def __init__(
+        self,
+        username: str = None,
+        password: str = None,
+        rabbitmq_host: str = None,
+        rabbitmq_port: int = None,
+        keycloak_host: str = None,
+        keycloak_port: int = None,
+        keycloak_realm: str = None,
+        client_id: str = None,
+        client_secret_key: str = None,
+        virtual_host: str = None,
+        is_tls: bool = True,
+        yaml_file: str = None,
+    ):
+        """
+        Initializes a new connection configuration.
+
+        Args:
+            username (str): client username, provided by NOS-T operator
+            password (str): client password, provided by NOS-T operator
+            host (str): broker hostname
+            rabbitmq_port (int): RabbitMQ broker port number
+            keycloak_port (int): Keycloak IAM port number
+            keycloak_realm (str): Keycloak realm name
+            client_id (str): Keycloak client ID
+            client_secret_key (str): Keycloak client secret key
+            virtual_host (str): RabbitMQ virtual host
+            is_tls (bool): True, if the connection uses TLS
+            yaml_file (str): Path to the YAML configuration file
+        """
+        self.username = username
+        self.password = password
+        self.rabbitmq_host = rabbitmq_host
+        self.keycloak_host = keycloak_host
+        self.rabbitmq_port = rabbitmq_port
+        self.keycloak_port = keycloak_port
+        self.keycloak_realm = keycloak_realm
+        self.client_id = client_id
+        self.client_secret_key = client_secret_key
+        self.virtual_host = virtual_host
+        self.is_tls = is_tls
+
+        self.yaml_config = None
+        self.predefined_exchanges_queues = False
+        self.yaml_file = yaml_file
+        self.unique_exchanges = {}
+        self.channel_configs = []
+
+        self.create_connection_config()
+
+    def get_exchanges(self):
+        """
+        Get exchanges from the YAML configuration file.
+        """
+        for app, app_channels in self.yaml_config.channels.items():
+            for channel, details in app_channels.items():
+                bindings = details.get("bindings", {}).get("amqp", {})
+                exchange = bindings.get("exchange", {})
+                exchange_name = exchange.get("name")
+                if exchange_name:
+                    exchange_config = ExchangeConfig(
+                        name=exchange_name,
+                        type=exchange.get("type", "topic"),
+                        durable=exchange.get("durable", True),
+                        auto_delete=exchange.get("autoDelete", False),
+                        vhost=exchange.get("vhost", "/"),
+                    )
+                    if exchange_name in self.unique_exchanges:
+                        if (
+                            self.unique_exchanges[exchange_name]
+                            != exchange_config.model_dump()
+                        ):
+                            raise ValueError(
+                                f"Conflicting configurations for exchange '{exchange_name}': {self.unique_exchanges[exchange_name]} vs {exchange_config.model_dump()}"
+                            )
+                    else:
+                        self.unique_exchanges[exchange_name] = (
+                            exchange_config.model_dump()
+                        )
+
+    def get_channels(self):
+        """
+        Get channels from the YAML configuration file.
+        """
+        for app, app_channels in self.yaml_config.channels.items():
+            for channel, details in app_channels.items():
+                bindings = details.get("bindings", {}).get("amqp", {})
+                exchange = bindings.get("exchange", {})
+                exchange_name = exchange.get("name")
+                address = details.get("address")
+                if address and bindings:
+                    channel_config = ChannelConfig(
+                        app=app,
+                        address=address,
+                        exchange=exchange_name or "default_exchange",
+                        durable=exchange.get("durable", True),
+                        auto_delete=exchange.get("autoDelete", False),
+                        vhost=exchange.get("vhost", "/"),
+                    )
+                    self.channel_configs.append(channel_config.model_dump())
+
+    def get_exchanges_channels(self):
+        """
+        Get exchanges and channels from the YAML configuration file.
+        """
+
+        self.get_exchanges(), self.get_channels()
+        if self.unique_exchanges and self.channel_configs:
+            self.predefined_exchanges_queues = True
+        self.simulation_config = SimulationConfig(
+            exchanges=self.unique_exchanges,
+            queues=self.channel_configs,
+            execution_parameters=self.yaml_config.execution,
+            predefined_exchanges_queues=self.predefined_exchanges_queues,
+        )
+
+    def load_environment_variables(self):
+        """
+        Loads an environment (.env) file and returns the parsed data.
+        """
+        dotenv_path = find_dotenv(usecwd=True)
+        if dotenv_path:
+            logger.info(f"Checking for credentials in the .env file: {dotenv_path}.")
+            load_dotenv(dotenv_path, override=True)
+        else:
+            logger.warning(
+                "Checking for credentials in the system environment variables."
+            )
+        if self.server_config.servers.rabbitmq.keycloak_authentication:
+            required_fields = [
+                "USERNAME",
+                "PASSWORD",
+                "CLIENT_ID",
+                "CLIENT_SECRET_KEY",
+            ]
+        else:
+            required_fields = ["USERNAME", "PASSWORD"]
+
+        env_data = {field: os.getenv(field) for field in required_fields}
+
+        missing_fields = [field for field, value in env_data.items() if value is None]
+        if missing_fields:
+            raise EnvironmentVariableError(
+                f"Missing required fields in .env file: {', '.join(missing_fields)}"
+            )
+
+        try:
+            if self.server_config.servers.rabbitmq.keycloak_authentication:
+                self.credentials_config = Credentials(
+                    username=env_data["USERNAME"],
+                    password=env_data["PASSWORD"],
+                    client_id=env_data["CLIENT_ID"],
+                    client_secret_key=env_data["CLIENT_SECRET_KEY"],
+                )
+            else:
+                self.credentials_config = Credentials(
+                    username=env_data["USERNAME"],
+                    password=env_data["PASSWORD"],
+                )
+        except ValidationError as err:
+            raise EnvironmentVariableError(f"Invalid environment variables: {err}")
+
+    def load_yaml_config_file(self):
+        """
+        Loads a YAML configuration file and returns the parsed data.
+        """
+        if not os.path.exists(self.yaml_file):
+            raise ConfigurationError("Couldn't load config file (not found)")
+
+        with open(self.yaml_file, "r", encoding="utf-8") as f:
+            try:
+                yaml_data = yaml.safe_load(f)  # Store the parsed YAML data
+            except yaml.YAMLError as err:
+                raise ConfigurationError(f"Invalid YAML configuration: {err}")
+
+        try:
+            self.yaml_config = Config(**yaml_data)
+        except ValidationError as err:
+            raise ConfigurationError(f"Invalid configuration: {err}")
+
+    def create_connection_config(self):
+        """
+        Creates a connection configuration.
+        """
+        if self.yaml_file:
+            try:
+                self.load_yaml_config_file()
+            except ConfigurationError as e:
+                raise ValueError(f"Configuration error: {e}")
+
+            try:
+                assert all(
+                    item in self.yaml_config.execution.required_apps
+                    for item in self.yaml_config.channels.keys()
+                ), "Application names do not match the channels defined in the configuration file."
+            except ConfigAssertionError as e:
+                raise ValueError(f"Assertion error: {e}")
+        else:
+            try:
+                self.yaml_config = Config(
+                    servers=ServersConfig(
+                        rabbitmq=RabbitMQConfig(
+                            host=self.rabbitmq_host,
+                            port=self.rabbitmq_port,
+                            virtual_host=self.virtual_host,
+                            tls=self.is_tls,
+                        ),
+                        keycloak=KeycloakConfig(
+                            host=self.keycloak_host,
+                            port=self.keycloak_port,
+                            realm=self.keycloak_realm,
+                            tls=self.is_tls,
+                        ),
+                    ),
+                    channels={},
+                    execution=ExecConfig(),
+                )
+            except:
+                self.yaml_config = Config(
+                    servers=ServersConfig(
+                        rabbitmq=RabbitMQConfig(), keycloak=KeycloakConfig()
+                    ),
+                    channels={},
+                    execution=ExecConfig(),
+                )
+
+        self.get_exchanges_channels()
+
+        server_config = self.yaml_config.copy()
+        if hasattr(server_config, "channels"):
+            del server_config.channels
+        if hasattr(server_config, "execution"):
+            del server_config.execution
+        self.server_config = server_config
+
+        if (
+            self.username is not None
+            and self.password is not None
+            and self.client_id is not None
+            and self.client_secret_key is not None
+        ):
+            logger.info("Using provided credentials.")
+            self.credentials_config = Credentials(
+                username=self.username,
+                password=self.password,
+                client_id=self.client_id,
+                client_secret_key=self.client_secret_key,
+            )
+        else:
+            self.load_environment_variables()
+
+        self.rc = RuntimeConfig(
+            credentials=self.credentials_config,
+            server_configuration=server_config,
+            simulation_configuration=self.simulation_config,
+        )

nost_tools/entity.py

@@ -0,0 +1,73 @@
+"""
+Provides a base class to maintain state variables during scenario execution.
+"""
+
+import logging
+from datetime import datetime, timedelta
+
+from .observer import Observable
+
+logger = logging.getLogger(__name__)
+
+
+class Entity(Observable):
+    """
+    A base entity that maintains its own clock (time) during scenario execution.
+
+    Notifies observers of changes to one observable property
+     * `time`: current scenario time
+
+    Attributes:
+        name (str): The entity name (optional)
+    """
+
+    PROPERTY_TIME = "time"
+
+    def __init__(self, name: str = None):
+        """
+        Initializes a new entity.
+
+        Args:
+            name (str): name of the entity (default: None)
+        """
+        super().__init__()
+        self.name = name
+        self._init_time = self._time = self._next_time = None
+
+    def initialize(self, init_time: datetime) -> None:
+        """
+        Initializes the entity at a designated initial scenario time.
+
+        Args:
+            init_time (:obj:`datetime`): initial scenario time
+        """
+        self._init_time = self._time = self._next_time = init_time
+
+    def tick(self, time_step: timedelta) -> None:
+        """
+        Computes the next state transition following an elapsed scenario duration (time step).
+
+        Args:
+            time_step (:obj:`timedelta`): elapsed scenario duration
+        """
+        self._next_time = self._time + time_step
+
+    def tock(self) -> None:
+        """
+        Commits the state transition pre-computed in `tick` and notifies observers of changes.
+        """
+        # update the time
+        if self._time != self._next_time:
+            prev_time = self._time
+            self._time = self._next_time
+            logger.debug(f"Entity {self.name} updated time to {self._time}.")
+            self.notify_observers(self.PROPERTY_TIME, prev_time, self._time)
+
+    def get_time(self) -> datetime:
+        """
+        Retrieves the current scenario time.
+
+        Returns:
+            :obj:`datetime`: current scenario time
+        """
+        return self._time

nost_tools/errors.py

@@ -0,0 +1,14 @@
+"""
+Provides object models for common data structures.
+"""
+
+class ConfigurationError(Exception):
+    """Configuration error"""
+
+
+class EnvironmentVariableError(Exception):
+    """Environment variable error"""
+
+
+class ConfigAssertionError(Exception):  # Renamed to avoid shadowing built-in
+    """Assertion error for configuration validation"""