nost-tools 2.0.0__py3-none-any.whl

nost_tools/manager.py

@@ -0,0 +1,472 @@
+"""
+Provides a base manager that coordinates a distributed scenario execution.
+"""
+
+import json
+import logging
+import threading
+import time
+import traceback
+from datetime import datetime, timedelta
+from typing import List
+
+from pydantic import ValidationError
+
+from .application import Application
+from .schemas import (
+    InitCommand,
+    ReadyStatus,
+    StartCommand,
+    StopCommand,
+    TimeStatus,
+    UpdateCommand,
+)
+from .simulator import Mode
+
+logger = logging.getLogger(__name__)
+
+
+class TimeScaleUpdate(object):
+    """
+    Provides a scheduled update to the simulation time scale factor by sending a message at the designated sim_update_time
+    to change the time_scale_factor to the indicated value.
+
+    Attributes:
+        time_scale_factor (float): scenario seconds per wallclock second
+        sim_update_time (:obj:`datetime`): scenario time that the update will occur
+    """
+
+    def __init__(self, time_scale_factor: float, sim_update_time: datetime):
+        """
+        Instantiates a new time scale update.
+
+        Args:
+            time_scale_factor (float): scenario seconds per wallclock second
+            sim_update_time (:obj:`datetime`): scenario time that the update will occur
+        """
+        self.time_scale_factor = time_scale_factor
+        self.sim_update_time = sim_update_time
+
+
+class Manager(Application):
+    """
+    NOS-T Manager Application.
+
+    This object class defines a manager to orchestrate test run executions.
+
+    Attributes:
+        prefix (str): The test run namespace (prefix)
+        simulator (:obj:`Simulator`): Application simulator
+        client (:obj:`Client`): Application MQTT client
+        time_step (:obj:`timedelta`): Scenario time step used in execution
+        time_status_step (:obj:`timedelta`): Scenario duration between time status messages
+        time_status_init (:obj:`datetime`): Scenario time of first time status message
+        app_name (str): Test run application name
+        app_description (str): Test run application description (optional)
+        required_apps_status (dict): Ready status for all required applications
+    """
+
+    def __init__(self):
+        """
+        Initializes a new manager.
+        """
+        # call super class constructor
+        super().__init__("manager")
+        self.required_apps_status = {}
+
+        self.sim_start_time = None
+        self.sim_stop_time = None
+        start_time = None
+        time_step = None
+        time_scale_factor = None
+        time_scale_updates = None
+        time_status_step = None
+        time_status_init = None
+        command_lead = None
+        required_apps = None
+        init_retry_delay_s = None
+        init_max_retry = None
+
+    def establish_exchange(self):
+        """
+        Establishes the exchange for the manager application.
+        """
+        self.channel.exchange_declare(
+            exchange=self.prefix,
+            exchange_type="topic",
+            durable=False,
+            auto_delete=True,
+        )
+
+    def execute_test_plan(
+        self,
+        sim_start_time: datetime = None,
+        sim_stop_time: datetime = None,
+        start_time: datetime = None,
+        time_step: timedelta = timedelta(seconds=1),
+        time_scale_factor: float = 1.0,
+        time_scale_updates: List[TimeScaleUpdate] = [],
+        time_status_step: timedelta = None,
+        time_status_init: datetime = None,
+        command_lead: timedelta = timedelta(seconds=0),
+        required_apps: List[str] = [],
+        init_retry_delay_s: int = 5,
+        init_max_retry: int = 5,
+    ) -> None:
+        """
+        A comprehensive command to start a test run execution.
+
+        Publishes an initialize, start, zero or more updates, and a stop message in one condensed JSON script for testing purposes,
+        or consistent test-case runs.
+
+        Args:
+            sim_start_time (:obj:`datetime`): scenario time at which to start execution
+            sim_stop_time (:obj:`datetime`): scenario time at which to stop execution
+            start_time (:obj:`datetime`): wallclock time at which to start execution (default: now)
+            time_step (:obj:`timedelta`): scenario time step used in execution (default: 1 second)
+            time_scale_factor (float): scenario seconds per wallclock second (default: 1.0)
+            time_scale_updates (list(:obj:`TimeScaleUpdate`)): list of scheduled time scale updates (default: [])
+            time_status_step (:obj:`timedelta`): scenario duration between time status messages
+            time_status_init (:obj:`datetime`): scenario time of first time status message
+            command_lead (:obj:`timedelta`): wallclock lead time between command and action (default: 0 seconds)
+            required_apps (list(str)): list of application names required to continue with the execution
+            init_retry_delay_s (float): number of seconds to wait between initialization commands while waiting for required applications
+            init_max_retry (int): number of initialization commands while waiting for required applications before continuing to execution
+        """
+        if sim_start_time is not None and sim_stop_time is not None:
+            self.sim_start_time = sim_start_time
+            self.sim_stop_time = sim_stop_time
+            self.start_time = start_time
+            self.time_step = time_step
+            self.time_scale_factor = time_scale_factor
+            self.time_scale_updates = time_scale_updates
+            self.time_status_step = time_status_step
+            self.time_status_init = time_status_init
+            self.command_lead = command_lead
+            self.required_apps = required_apps
+            self.init_retry_delay_s = init_retry_delay_s
+            self.init_max_retry = init_max_retry
+        else:
+            if self.config.rc:
+                logger.info("Retrieving execution parameters from YAML file.")
+                parameters = getattr(
+                    self.config.rc.simulation_configuration.execution_parameters,
+                    self.app_name,
+                    None,
+                )
+                self.sim_start_time = parameters.sim_start_time
+                self.sim_stop_time = parameters.sim_stop_time
+                self.start_time = parameters.start_time
+                self.time_step = parameters.time_step
+                self.time_scale_factor = parameters.time_scale_factor
+                self.time_scale_updates = parameters.time_scale_updates
+                self.time_status_step = parameters.time_status_step
+                self.time_status_init = parameters.time_status_init
+                self.command_lead = parameters.command_lead
+                # self.required_apps = (
+                #     self.config.rc.simulation_configuration.execution_parameters.required_apps
+                # )
+                self.required_apps = [
+                    app for app in parameters.required_apps if app != self.app_name
+                ]
+                self.init_retry_delay_s = parameters.init_retry_delay_s
+                self.init_max_retry = parameters.init_max_retry
+            else:
+                raise ValueError(
+                    "No configuration runtime. Please provide simulation start and stop times."
+                )
+        ####
+        self.establish_exchange()
+        # if self.predefined_exchanges_queues:
+        #     self.declare_exchange()
+        #     self.declare_bind_queue()
+        ####
+
+        self.required_apps_status = dict(
+            zip(self.required_apps, [False] * len(self.required_apps))
+        )
+        self.add_message_callback("*", "status.ready", self.on_app_ready_status)
+        self.add_message_callback("*", "status.time", self.on_app_time_status)
+
+        self._create_time_status_publisher(self.time_status_step, self.time_status_init)
+        for i in range(self.init_max_retry):
+            # issue the init command
+            self.init(self.sim_start_time, self.sim_stop_time, self.required_apps)
+            next_try = self.simulator.get_wallclock_time() + timedelta(
+                seconds=self.init_retry_delay_s
+            )
+            # wait until all required apps are ready
+            while (
+                not all([self.required_apps_status[app] for app in self.required_apps])
+                and self.simulator.get_wallclock_time() < next_try
+            ):
+                time.sleep(0.001)
+        # self.remove_message_callback("*", "status.ready")
+        # self.remove_message_callback()
+        # configure start time
+        if self.start_time is None:
+            self.start_time = self.simulator.get_wallclock_time() + self.command_lead
+        # sleep until the start command needs to be issued
+        time.sleep(
+            max(
+                0,
+                (
+                    (self.start_time - self.simulator.get_wallclock_time())
+                    - self.command_lead
+                )
+                / timedelta(seconds=1),
+            )
+        )
+        # issue the start command
+        self.start(
+            self.sim_start_time,
+            self.sim_stop_time,
+            self.start_time,
+            self.time_step,
+            self.time_scale_factor,
+            self.time_status_step,
+            self.time_status_init,
+        )
+        # wait for simulation to start executing
+        while self.simulator.get_mode() != Mode.EXECUTING:
+            time.sleep(0.001)
+        for update in self.time_scale_updates:
+            update_time = self.simulator.get_wallclock_time_at_simulation_time(
+                update.sim_update_time
+            )
+            # sleep until the update command needs to be issued
+            time.sleep(
+                max(
+                    0,
+                    (
+                        (update_time - self.simulator.get_wallclock_time())
+                        - self.command_lead
+                    )
+                    / timedelta(seconds=1),
+                )
+            )
+            # issue the update command
+            self.update(
+                update.time_scale_factor, update.sim_update_time, self.required_apps
+            )
+            # wait until the update command takes effect
+            while self.simulator.get_time_scale_factor() != update.time_scale_factor:
+                time.sleep(self.command_lead / timedelta(seconds=1) / 100)
+        end_time = self.simulator.get_wallclock_time_at_simulation_time(
+            self.simulator.get_end_time()
+        )
+        # sleep until the stop command should be issued
+        time.sleep(
+            max(
+                0,
+                ((end_time - self.simulator.get_wallclock_time()) - self.command_lead)
+                / timedelta(seconds=1),
+            )
+        )
+        # issue the stop command
+        self.stop(self.sim_stop_time)
+
+    def on_app_ready_status(self, ch, method, properties, body) -> None:
+        """
+        Callback to handle a message containing an application ready status.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # split the message topic into components (prefix/app_name/...)
+            topic_parts = method.routing_key.split(".")
+            message = body.decode("utf-8")
+            # check if app_name is monitored in the ready_status dict
+            if len(topic_parts) > 1 and topic_parts[1] in self.required_apps_status:
+                # validate if message is a valid JSON
+                try:
+                    # update the ready status based on the payload value
+                    self.required_apps_status[topic_parts[1]] = (
+                        ReadyStatus.model_validate_json(message).properties.ready
+                    )
+                except json.JSONDecodeError:
+                    logger.error(f"Invalid JSON format: {message}")
+        except ValidationError as e:
+            logger.error(f"Validation error: {e}")
+        except Exception as e:
+            logger.error(
+                f"Exception (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
+
+    def on_app_time_status(self, ch, method, properties, body) -> None:
+        """
+        Callback to handle a message containing an application time status.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # split the message topic into components (prefix/app_name/...)
+            topic_parts = method.routing_key.split(".")
+            message = body.decode("utf-8")
+            # validate if message is a valid JSON
+            try:
+                # parse the message payload properties
+                props = TimeStatus.model_validate_json(message).properties
+                wallclock_delta = self.simulator.get_wallclock_time() - props.time
+                scenario_delta = self.simulator.get_time() - props.sim_time
+                if len(topic_parts) > 1:
+                    logger.info(
+                        f"Application {topic_parts[1]} latency: {scenario_delta} (scenario), {wallclock_delta} (wallclock)"
+                    )
+            except json.JSONDecodeError:
+                logger.error(f"Invalid JSON format: {message}")
+        except ValidationError as e:
+            logger.error(f"Validation error: {e}")
+        except Exception as e:
+            logger.error(
+                f"Exception (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
+
+    def init(
+        self,
+        sim_start_time: datetime,
+        sim_stop_time: datetime,
+        required_apps: List[str] = [],
+    ) -> None:
+        """
+        Publishes an initialize command to initialize a test run execution.
+
+        Args:
+            sim_start_time (:obj:`datetime`): Earliest possible scenario start time
+            sim_stop_time (:obj:`datetime`): Latest possible scenario end time
+            required_apps (list(str)): List of required apps
+        """
+        # publish init command message
+        command = InitCommand.model_validate(
+            {
+                "taskingParameters": {
+                    "simStartTime": sim_start_time,
+                    "simStopTime": sim_stop_time,
+                    "requiredApps": required_apps,
+                }
+            }
+        )
+        logger.info(
+            f"Sending initialize command {command.model_dump_json(by_alias=True)}."
+        )
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="init",
+            payload=command.model_dump_json(by_alias=True),
+        )
+        # logger.info(f"Declared Queues: {self.declared_queues}")
+        # logger.info(f"Declared Exchanges: {self.declared_exchanges}")
+
+    def start(
+        self,
+        sim_start_time: datetime,
+        sim_stop_time: datetime,
+        start_time: datetime = None,
+        time_step: timedelta = timedelta(seconds=1),
+        time_scale_factor: float = 1.0,
+        time_status_step: timedelta = None,
+        time_status_init: datetime = None,
+    ) -> None:
+        """
+
+        Command to start a test run execution by starting the simulator execution with all necessary parameters and publishing
+        a start command, which can be received by the connected applications.
+
+        Args:
+            sim_start_time (:obj:`datetime`): Scenario time at which to start execution
+            sim_stop_time (:obj:`datetime`): Scenario time at which to stop execution
+            start_time (:obj:`datetime`): Wallclock time at which to start execution (default: now)
+            time_step (:obj:`timedelta`): Scenario time step used in execution (default: 1 second)
+            time_scale_factor (float): Scenario seconds per wallclock second (default: 1.0)
+            time_status_step (:obj:`timedelta`): Scenario duration between time status messages
+            time_status_init (:obj:`datetime`): Scenario time of first time status message
+        """
+        if start_time is None:
+            start_time = self.simulator.get_wallclock_time()
+        self.time_status_step = time_status_step
+        self.time_status_init = time_status_init
+        # publish a start command message
+        command = StartCommand.model_validate(
+            {
+                "taskingParameters": {
+                    "startTime": start_time,
+                    "simStartTime": sim_start_time,
+                    "simStopTime": sim_stop_time,
+                    "timeScalingFactor": time_scale_factor,
+                }
+            }
+        )
+        logger.info(f"Sending start command {command.model_dump_json(by_alias=True)}.")
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="start",
+            payload=command.model_dump_json(by_alias=True),
+        )
+        exec_thread = threading.Thread(
+            target=self.simulator.execute,
+            kwargs={
+                "init_time": sim_start_time,
+                "duration": sim_stop_time - sim_start_time,
+                "time_step": time_step,
+                "wallclock_epoch": start_time,
+                "time_scale_factor": time_scale_factor,
+            },
+        )
+        exec_thread.start()
+
+    def stop(self, sim_stop_time: datetime) -> None:
+        """
+        Command to stop a test run execution by updating the execution end time and publishing a stop command.
+
+        Args:
+            sim_stop_time (:obj:`datetime`): Scenario time at which to stop execution.
+        """
+        # publish a stop command message
+        command = StopCommand.model_validate(
+            {"taskingParameters": {"simStopTime": sim_stop_time}}
+        )
+        logger.info(f"Sending stop command {command.model_dump_json(by_alias=True)}.")
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="stop",
+            payload=command.model_dump_json(by_alias=True),
+        )
+        # update the execution end time
+        self.simulator.set_end_time(sim_stop_time)
+
+    def update(self, time_scale_factor: float, sim_update_time: datetime) -> None:
+        """
+        Command to update the time scaling factor for a test run execution by updating the execution time scale factor,
+        and publishing an update command.
+
+        Args:
+            time_scale_factor (float): scenario seconds per wallclock second
+            sim_update_time (:obj:`datetime`): scenario time at which to update
+        """
+        # publish an update command message
+        command = UpdateCommand.model_validate(
+            {
+                "taskingParameters": {
+                    "simUpdateTime": sim_update_time,
+                    "timeScalingFactor": time_scale_factor,
+                }
+            }
+        )
+        logger.info(f"Sending update command {command.model_dump_json(by_alias=True)}.")
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="update",
+            payload=command.model_dump_json(by_alias=True),
+        )
+        # update the execution time scale factor
+        self.simulator.set_time_scale_factor(time_scale_factor, sim_update_time)

nost_tools/observer.py

@@ -0,0 +1,181 @@
+"""
+Provides base classes that implement the observer pattern to loosely couple an observable and observer.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import List, Optional, Union
+
+
+class Observer(ABC):
+    """
+    Abstract base class that can be notified of property changes from an associated :obj:`Observable`.
+    """
+
+    @abstractmethod
+    def on_change(
+        self, source: object, property_name: str, old_value: object, new_value: object
+    ) -> None:
+        """Callback notifying of a change.
+
+        Args:
+            source (object): object that triggered a property change
+            property_name (str): name of the changed property
+            old_value (object): old value of the named property
+            new_value (object): new value of the named property
+        """
+        pass
+
+
+class RecordingObserver(Observer):
+    """
+    Observer that records all changes.
+    """
+
+    def __init__(
+        self,
+        property_filters: Optional[Union[str, List[str]]] = None,
+        timestamped: bool = False,
+    ):
+        """
+        Initializes a new recording obsever.
+
+        Args:
+            properties (Optional[Union[str,List[str]]]): optional list of property names to record
+            timestamped (bool): True, if the changes shall be timestamped
+        """
+        if isinstance(property_filters, str):
+            self.property_filters = [property_filters]
+        else:
+            self.property_filters = property_filters
+        self.changes = []
+        self.timestamped = timestamped
+
+    def on_change(
+        self, source: object, property_name: str, old_value: object, new_value: object
+    ) -> None:
+        """Callback notifying of a change.
+
+        Args:
+            source (object): object that triggered a property change
+            property_name (str): name of the changed property
+            old_value (object): old value of the named property
+            new_value (object): new value of the named property
+        """
+        if self.property_filters is None or property_name in self.property_filters:
+            change = {
+                "source": source,
+                "property_name": property_name,
+                "old_value": old_value,
+                "new_value": new_value,
+            }
+            if self.timestamped:
+                change["time"] = datetime.now(tz=timezone.utc)
+            self.changes.append(change)
+
+
+class Observable(object):
+    """
+    Base class that can register (add/remove) and notify observers of property changes.
+    """
+
+    def __init__(self):
+        """
+        Initializes a new observable.
+        """
+        # list of observers to be notified of events
+        self._observers = []
+
+    def add_observer(self, observer: Observer) -> None:
+        """
+        Adds an observer to this observable.
+
+        Args:
+            observer (:obj:`Observer`): observer to be added
+        """
+        self._observers.append(observer)
+
+    def remove_observer(self, observer: Observer) -> Observer:
+        """
+        Removes an observer from this observable.
+
+        Args:
+            observer (:obj:`Observer`): obsever to be removed
+
+        Returns:
+            :obj:`Observer`: removed observer
+        """
+        return self._observers.remove(observer)
+
+    def notify_observers(
+        self, property_name: str, old_value: object, new_value: object
+    ) -> None:
+        """
+        Notifies observers of a property change.
+
+        Args:
+            property_name (str): name of the changed property
+            old_value (object): old value of the named property
+            new_value (object): new value of the named property
+        """
+        if old_value != new_value:
+            for observer in self._observers:
+                observer.on_change(self, property_name, old_value, new_value)
+
+
+# Add after the existing Observer class
+class MessageObserver(ABC):
+    """
+    Abstract base class for message observers that can receive RabbitMQ messages.
+    """
+
+    @abstractmethod
+    def on_message(self, ch, method, properties, body) -> None:
+        """Callback for when a message is received.
+
+        Args:
+            ch: Channel object
+            method: Method frame
+            properties: Message properties
+            body: Message body
+        """
+        pass
+
+
+class MessageObservable(Observable):
+    """
+    Observable that can notify observers of received messages.
+    """
+
+    def __init__(self):
+        """Initialize message observable"""
+        super().__init__()
+        self._message_observers = []
+
+    def add_message_observer(self, observer: MessageObserver) -> None:
+        """Add a message observer.
+
+        Args:
+            observer (MessageObserver): The observer to add
+        """
+        self._message_observers.append(observer)
+
+    def remove_message_observer(self, observer: MessageObserver) -> None:
+        """Remove a message observer.
+
+        Args:
+            observer (MessageObserver): The observer to remove
+        """
+        self._message_observers.remove(observer)
+
+    def notify_message_observers(self, ch, method, properties, body) -> None:
+        """Notify all message observers about a received message.
+
+        Args:
+            ch: Channel object
+            method: Method frame
+            properties: Message properties
+            body: Message body
+        """
+        for observer in self._message_observers:
+            observer.on_message(ch, method, properties, body)