cgse 0.14.0__tar.gz → 0.15.0__tar.gz

{cgse-0.14.0 → cgse-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse
-Version: 0.14.0
+Version: 0.15.0
 Summary: Generic Common-EGSE: Commanding and monitoring lab equipment
 Author: IvS KU Leuven
 Maintainer-email: Rik Huygen <rik.huygen@kuleuven.be>, Sara Regibo <sara.regibo@kuleuven.be>

cgse-0.15.0/docs/libs/cgse-core/notifyhub.md

@@ -0,0 +1,168 @@
+# The Notification Hub
+
+## Overview
+
+The Notification Hub serves as a centralized event distribution system for the core services and control servers. 
+Instead of having services directly subscribe to each other, all services publish their events to the hub, which 
+then redistributes them to interested subscribers via ZeroMQ PUB-SUB sockets.
+
+## Benefits
+
+- **Decoupling**: Services don't need to know about each other directly
+- **Scalability**: Easy to add new subscribers without modifying existing services
+- **Reliability**: Single point of event distribution with consistent delivery
+- **Simplicity**: One subscription endpoint for all system events
+
+# Socket Endpoints
+
+The Notification Hub exposes three ZeroMQ sockets:
+
+| Purpose            |    Pattern     |  Your Socket  | Endpoint                    |
+|--------------------|:--------------:|:-------------:|-----------------------------|
+| Event Publishing   |   PUSH-PULL    |     PUSH      | tcp://notification-hub:4245 |
+| Event Subscription |    PUB-SUB     |      SUB      | tcp://notification-hub:4246 |
+| Health Checks      | ROUTER-DEALER  |    DEALER     | tcp://notification-hub:4247 |
+
+Note: port numbers can be changed in the local settings YAML file.
+
+## Events
+
+```python
+from egse.notifyhub.event import NotificationEvent
+
+event = NotificationEvent(
+    event_type="new_setup",
+    source_service="cm_cs",
+    data={"setup_id": "0001234"},
+)
+```
+A `NotificationEvent` also has a `timestamp` and a `correlation_id` 
+associated. These fields are automatically filled on creation of the event 
+and must not be provided. An event can be converted into a plain dictionary 
+with the `.as_dict()` method.
+
+```
+>>> print(event.as_dict())
+{
+  'event_type': 'new_setup', 
+  'source_service': 'cm_cs', 
+  'data': {'setup_id': '0001234'}, 
+  'timestamp': 1756709627.25942, 
+  'correlation_id': '23b44f16-34f9-498a-85f7-5c57658ea363'
+}
+```
+
+## Publishing Events
+
+Any core service, control server, or script can publish events to the notification hub using the EventPublisher class. For convenience, EventPublisher supports usage as a context manager, making it easy to send single events.
+
+=== "Synchronous"
+
+    ```python
+    from egse.notifyhub.services import EventPublisher
+    
+    with EventPublisher() as publisher:
+        publisher.publish(event)
+    ```
+
+=== "Asynchronous"
+
+    ```python
+    from egse.notifyhub.services import AsyncEventPublisher
+    
+    async with AsyncEventPublisher() as publisher:
+        await publisher.publish(event)
+    ```
+
+
+## Subscribing to Events
+
+Listen to events from the notification hub with the EventSubscriber class. 
+The usage for this class is quite different for synchronous and asynchronous 
+contexts. 
+
+=== "Synchronous"
+
+    In a synchronous context, you will need to add code to poll the socket 
+    and handle the event inside your own event loop. The subscriber socket 
+    can be retrieved with the `subscriber.socket` property, you can then add 
+    the socket to a Poller object.
+
+    ```python
+    from egse.notifyhub.services import EventSubscriber
+    
+    def load_setup(event_data: dict):
+        ...
+
+    subscriber = EventSubscriber(["new_setup"])
+    subscriber.register_handler("new_setup", load_setup)
+    subscriber.connect()
+    
+    while True:
+
+        ...
+
+        if subscriber.poll():
+            subscriber.handle_event()
+        
+    subscriber.disconnect()
+    ```
+
+=== "Asynchronous"
+
+    ```python
+    from egse.notifyhub.services import AsyncEventSubscriber
+
+    async def load_setup(event_data: dict):
+        ...
+
+    subscriber = AsyncEventSubscriber(["new_setup"])
+    subscriber.register_handler("new_setup", load_setup)
+    await subscriber.connect()
+
+    event_listener = asyncio.create_task(subscriber.start_listening())
+
+    ...
+
+    subscriber.disconnect()
+    await event_listener  # add a wait_for with a timeout if needed
+    ```
+
+## Health Checks
+
+The Notification Hub provides a health check interface to monitor the status and availability of the hub. This allows services and scripts to verify connectivity and basic hub functionality.
+To perform a health check, use the NotificationHubClient class. The client 
+connects to the hub's ROUTER-DEALER socket and sends a health check request. 
+If the hub is available, it responds True. In case of an error or when the 
+hub is not available, False is returned.
+
+=== "Synchronous"
+
+    ```python
+    from egse.notifyhub.client import NotificationHubClient
+    
+    with NotificationHubClient() as client:
+        if not client.health_check():
+            ... # notification hub not available
+    ```
+
+=== "Asynchronous"
+
+    ```python
+    from egse.notifyhub.client import AsyncNotificationHubClient
+    
+    with AsyncNotificationHubClient() as client:
+        if not await client.health_check():
+            ... # notification hub not available
+    ```
+
+The health check has a default timeout of 5 seconds. If this is too long for 
+your needs, provide a `request_timeout` argument as a float in seconds to 
+the `NotificationHubClient` call. 
+
+
+## Monitoring
+
+Every 30s, the hub provides basic connection and event statistics to the log.
+
+TODO: this should also go on the PUB channel as a StatsEvent.

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-common/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cgse-common"
-version = "0.14.0"
+version = "0.15.0"
 description = "Software framework to support hardware testing"
 authors = [
     {name = "IvS KU Leuven"}

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-common/src/egse/log.py

@@ -13,34 +13,70 @@ Environment variables that affect logging:
 
 __all__ = [
     "LOG_FORMAT_FULL",
+    "LOG_FORMAT_CLEAN",
+    "LOG_FORMAT_STYLE",
+    "LOG_DATE_FORMAT_FULL",
+    "LOG_DATE_FORMAT_CLEAN",
     "logger",
     "root_logger",
     "egse_logger",
+    "get_log_level_from_env",
+    "PackageFilter",
 ]
 
 import logging
 import os
 import textwrap
+from pathlib import Path
 
 import rich
 
+# The format for the log messages.
+# The log record attributes are listed: https://docs.python.org/3.12/library/logging.html#logrecord-attributes
+
 LOG_FORMAT_STYLE = "{"
 LOG_FORMAT_FULL = (
     "{asctime:19s}.{msecs:03.0f} : {processName:20s} : {levelname:8s} : {name:^25s} : {lineno:6d} : {filename:20s} : {"
     "message}"
 )
-LOG_FORMAT_CLEAN = "{asctime} [{levelname:>8s}] {message} ({filename}:{lineno:d})"
+LOG_FORMAT_CLEAN = (
+    "{asctime} [{levelname:>8s}] {message} ({processName}[{process}]:{package_name}:{filename}:{lineno:d})"
+)
 
 LOG_DATE_FORMAT_FULL = "%Y-%m-%d %H:%M:%S"
 LOG_DATE_FORMAT_CLEAN = "%Y-%m-%d %H:%M:%S"
 
 
-class EGSEFilter(logging.Filter):
+class PackageFilter(logging.Filter):
+    """Adds 'package_name' to the log record.
+
+    When this filter is added to a handler of a logger, the formatter of that
+    logger can use the 'package_name' attribute.
+
+    When the package name can not be determined, is will contain 'n/a'.
+
+    NOTE: this filer assumes the root package is 'egse'.
+    """
+
     def filter(self, record):
-        return record.name.startswith("egse")
+        if hasattr(record, "pathname"):
+            parts = Path(record.pathname).parent.parts
+            try:
+                egse_index = parts.index("egse")
+                package_name = ".".join(parts[egse_index:])
+            except ValueError:
+                package_name = "n/a"
+
+            record.package_name = package_name
+        else:
+            record.package_name = "n/a"
 
+        return True
 
-egse_filter = EGSEFilter()
+
+class EGSEFilter(logging.Filter):
+    def filter(self, record):
+        return record.name.startswith("egse")
 
 
 class NonEGSEFilter(logging.Filter):
@@ -48,9 +84,6 @@ class NonEGSEFilter(logging.Filter):
         return not record.name.startswith("egse")
 
 
-root_filter = NonEGSEFilter()
-
-
 def get_log_level_from_env(env_var: str = "LOG_LEVEL", default: int = logging.INFO):
     """Read the log level from an environment variable."""
     log_level_str = os.getenv(env_var, default)
@@ -89,21 +122,19 @@ else:
     egse_formatter = logging.Formatter(fmt=LOG_FORMAT_CLEAN, datefmt=LOG_DATE_FORMAT_CLEAN, style=LOG_FORMAT_STYLE)
 
 egse_handler.setFormatter(egse_formatter)
-egse_handler.addFilter(egse_filter)
+egse_handler.addFilter(EGSEFilter())
+egse_handler.addFilter(PackageFilter())
 
 root_logger.addHandler(egse_handler)
 
 for handler in root_logger.handlers:
     if handler != egse_handler:  # Don't filter our new handler
-        handler.addFilter(root_filter)
+        handler.addFilter(NonEGSEFilter())
+        handler.addFilter(PackageFilter())
 
 logger = egse_logger
 
 if __name__ == "__main__":
-    logging.basicConfig(
-        level=get_log_level_from_env(), format=LOG_FORMAT_CLEAN, datefmt=LOG_DATE_FORMAT_CLEAN, style="{"
-    )
-
     root_logger = logging.getLogger()
 
     rich.print(

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-coordinates/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cgse-coordinates"
-version = "0.14.0"
+version = "0.15.0"
 description = "Reference Frames and Coordinate Transofrmations for CGSE"
 authors = [
     {name = "IvS KU Leuven"}

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cgse-core"
-version = "0.14.0"
+version = "0.15.0"
 description = "Core services for the CGSE framework"
 authors = [
     {name = "IvS KU Leuven"}
@@ -49,6 +49,7 @@ log = 'cgse_core.services:log_cs'
 cm = 'cgse_core.services:cm_cs'
 sm = 'cgse_core.services:sm_cs'
 pm = 'cgse_core.services:pm_cs'
+notify = 'cgse_core.services:notifyhub'
 
 [project.entry-points."cgse.explore"]
 explore = "cgse_core.cgse_explore"
@@ -73,8 +74,8 @@ filterwarnings = [
     "ignore::DeprecationWarning"
 ]
 log_cli = true
-log_cli_level = "INFO"
-log_cli_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
+log_cli_level = "DEBUG"
+#log_cli_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
 log_cli_date_format = "%Y-%m-%d %H:%M:%S"
 
 [tool.coverage.run]

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/cgse_core/_start.py

@@ -73,3 +73,17 @@ def start_pm_cs():
         stdin=subprocess.DEVNULL,
         close_fds=True,
     )
+
+
+def start_notifyhub():
+    rich.print("Starting the notification hub core service...")
+
+    out = open(Path("~/.notifyhub.start.out").expanduser(), "w")
+
+    subprocess.Popen(
+        [sys.executable, "-m", "egse.notifyhub.server", "start"],
+        stdout=out,
+        stderr=out,
+        stdin=subprocess.DEVNULL,
+        close_fds=True,
+    )

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/cgse_core/_stop.py

@@ -103,3 +103,23 @@ def stop_pm_cs():
             waiting_for(lambda: not is_process_running(["procman_cs", "start"]), timeout=5.0)
     except TimeoutError:
         logger.warning("pm_cs should not be running anymore...")
+
+
+def stop_notifyhub():
+    rich.print("Terminating the notification hub core service...")
+
+    out = open(Path("~/.notifyhub.stop.out").expanduser(), "w")
+
+    subprocess.Popen(
+        [sys.executable, "-m", "egse.notifyhub.server", "stop"],
+        stdout=out,
+        stderr=out,
+        stdin=subprocess.DEVNULL,
+        close_fds=True,
+    )
+
+    try:
+        with Timer("notifyhub stop timer", log_level=logging.DEBUG):
+            waiting_for(lambda: not is_process_running(["egse.notifyhub.server", "start"]), timeout=5.0)
+    except TimeoutError:
+        logger.warning("notifyhub should not be running anymore...")

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/cgse_core/cgse_explore.py

@@ -12,7 +12,7 @@ def show_processes():
     """Returns of list of ProcessInfo data classes for matching processes from this package."""
 
     def filter_procs(pi: ProcessInfo):
-        pattern = r"(log|confman|storage|procman)_cs|registry\.server"
+        pattern = r"(log|confman|storage|procman)_cs|registry\.server|notifyhub\.server"
 
         return re.search(pattern, pi.command)
 

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/cgse_core/services.py

@@ -12,6 +12,7 @@ from egse.signal import create_signal_command_file
 from egse.system import TyperAsyncCommand
 from ._start import start_cm_cs
 from ._start import start_log_cs
+from ._start import start_notifyhub
 from ._start import start_pm_cs
 from ._start import start_rm_cs
 from ._start import start_sm_cs
@@ -23,6 +24,7 @@ from ._status import status_rm_cs
 from ._status import status_sm_cs
 from ._stop import stop_cm_cs
 from ._stop import stop_log_cs
+from ._stop import stop_notifyhub
 from ._stop import stop_pm_cs
 from ._stop import stop_rm_cs
 from ._stop import stop_sm_cs
@@ -41,6 +43,7 @@ def start_core_services(log_level: str = "WARNING"):
 
     start_rm_cs(log_level)
     start_log_cs()
+    start_notifyhub()
     start_sm_cs()
     start_cm_cs()
     start_pm_cs()
@@ -55,9 +58,12 @@ def stop_core_services():
     stop_pm_cs()
     stop_cm_cs()
     stop_sm_cs()
+    stop_notifyhub()
+
     # We need the logger for logging the termination process for other services, so leave it running for a while
     time.sleep(1.0)
     stop_log_cs()
+
     # We need the registry server to stop other core services, so leave it running for a while
     time.sleep(1.0)
     stop_rm_cs()
@@ -274,3 +280,21 @@ def pm_cs_reregister(force: bool = False):
         app_name,
         {"action": "reregister", "params": {"force": force}},
     )
+
+
+notifyhub = typer.Typer(
+    name="notifyhub",
+    help="handle notification hub: start, stop, status, re-register",
+)
+
+
+@notifyhub.command(name="start")
+def notifyhub_start():
+    """Start the Process Manager."""
+    start_notifyhub()
+
+
+@notifyhub.command(name="stop")
+def notifyhub_stop():
+    """Stop the Process Manager."""
+    stop_notifyhub()

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/cgse_core/settings.yaml

@@ -3,9 +3,13 @@ PACKAGES:
 
 Logging Control Server:                          # LOG_CS
 
-    SERVICE_TYPE:                LOGGER
+    SERVICE_TYPE:                LOG_CS
     MAX_NR_LOG_FILES:                20          # The maximum number of log files that will be maintained in a roll-over
     MAX_SIZE_LOG_FILES:              20          # The maximum size one log file can become
+#    PROTOCOL:                       tcp
+#    HOSTNAME:                 localhost
+    RECEIVER_PORT:                 4248
+    COMMANDER_PORT:                4249
     TEXTUALOG_IP_ADDRESS:     127.0.0.1          # The IP address of the textualog listening server
     TEXTUALOG_LISTENING_PORT:     19996          # The port number on which the textualog server is listening
 
@@ -27,9 +31,11 @@ Process Manager Control Server:                  # PM_CS
     STORAGE_MNEMONIC:                PM          # The mnemonic to be used in the filename storing the housekeeping data
 
 Notify Hub:
+    
     SERVICE_TYPE:            NOTIFY_HUB
     COLLECTOR_PORT:                4245
     PUBLISHER_PORT:                4246
+    REQUESTS_PORT:                 4247
     
 Metrics Hub:
     SERVICE_TYPE:           METRICS_HUB

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/egse/confman/__init__.py

@@ -139,6 +139,8 @@ from egse.env import get_site_id
 from egse.exceptions import InternalError
 from egse.listener import EVENT_ID
 from egse.log import logger
+from egse.notifyhub.event import NotificationEvent
+from egse.notifyhub.services import EventPublisher
 from egse.obsid import ObservationIdentifier
 from egse.plugin import entry_points
 from egse.protocol import CommandProtocol
@@ -757,6 +759,11 @@ class ConfigurationManagerController(ConfigurationManagerInterface):
                         EVENT_ID.SETUP, {"event_type": "new_setup", "setup_id": self._setup_id}
                     )
 
+            with EventPublisher() as pub:
+                pub.publish(
+                    NotificationEvent(event_type="new_setup", source_service="cm_cs", data={"setup_id": self._setup_id})
+                )
+
             return self._setup
         except SettingsError as exc:
             return Failure(f"The Setup file can not be loaded from {setup_file}.", exc)
@@ -941,6 +948,11 @@ class ConfigurationManagerController(ConfigurationManagerInterface):
                         EVENT_ID.SETUP, {"event_type": "new_setup", "setup_id": setup_id}
                     )
 
+            with EventPublisher() as pub:
+                pub.publish(
+                    NotificationEvent(event_type="new_setup", source_service="cm_cs", data={"setup_id": self._setup_id})
+                )
+
         return setup
 
     def get_next_setup_id_for_site(self, site: str) -> int:

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/egse/confman/confman_cs.py

@@ -23,6 +23,7 @@ from egse.confman import ConfigurationManagerProtocol
 from egse.confman import ConfigurationManagerProxy
 from egse.control import ControlServer
 from egse.env import get_conf_data_location
+from egse.logger import remote_logging
 from egse.process import SubProcess
 from egse.registry.client import RegistryClient
 from egse.response import Failure
@@ -136,24 +137,25 @@ def start():
 
     multiprocessing.current_process().name = "cm_cs"
 
-    try:
-        check_prerequisites()
-    except RuntimeError as exc:
-        logger.info(exc)
-        return 0
-
-    try:
-        control_server = ConfigurationManagerControlServer()
-        control_server.serve()
-    except KeyboardInterrupt:
-        print("Shutdown requested...exiting")
-    except SystemExit as exit_code:
-        print(f"System Exit with code {exit_code}.")
-        sys.exit(exit_code.code)
-    except Exception:
-        import traceback
-
-        traceback.print_exc(file=sys.stdout)
+    with remote_logging():
+        try:
+            check_prerequisites()
+        except RuntimeError as exc:
+            logger.info(exc)
+            return 0
+
+        try:
+            control_server = ConfigurationManagerControlServer()
+            control_server.serve()
+        except KeyboardInterrupt:
+            print("Shutdown requested...exiting")
+        except SystemExit as exit_code:
+            print(f"System Exit with code {exit_code}.")
+            sys.exit(exit_code.code)
+        except Exception:
+            import traceback
+
+            traceback.print_exc(file=sys.stdout)
 
     return 0
 

{cgse-0.14.0 → cgse-0.15.0}/libs/cgse-core/src/egse/control.py

@@ -25,12 +25,14 @@ from egse.listener import Listeners
 from egse.log import logger
 from egse.logger import close_all_zmq_handlers
 from egse.metrics import get_metrics_repo
+from egse.notifyhub.services import EventSubscriber
 from egse.process import ProcessStatus
 from egse.registry.client import RegistryClient
 from egse.settings import Settings
 from egse.settings import get_site_id
 from egse.signal import FileBasedSignaling
 from egse.system import SignalCatcher
+from egse.system import Timer
 from egse.system import camel_to_kebab
 from egse.system import camel_to_snake
 from egse.system import do_every
@@ -165,10 +167,16 @@ class ControlServer(metaclass=abc.ABCMeta):
 
         self.dev_ctrl_cmd_sock = self.zcontext.socket(zmq.REP)
 
+        # Set up the event subscription
+
+        self.event_subscription = EventSubscriber(subscriptions=self.get_event_subscriptions())
+        self.event_subscription.connect()
+
         # Initialise the poll set
 
         self.poller.register(self.dev_ctrl_service_sock, zmq.POLLIN)
         self.poller.register(self.dev_ctrl_mon_sock, zmq.POLLIN)  # FIXME: I think this should not be registered
+        self.poller.register(self.event_subscription.socket, zmq.POLLIN)
 
         token = os.getenv("INFLUXDB3_AUTH_TOKEN")
         project = os.getenv("PROJECT")
@@ -186,6 +194,14 @@ class ControlServer(metaclass=abc.ABCMeta):
                 "Metrics will not be propagated to InfluxDB."
             )
 
+    def get_event_subscriptions(self) -> list[str]:
+        """Override this in the subclass to actually subscribe to events."""
+        return []
+
+    def get_event_handlers(self) -> dict[str, Callable]:
+        """Override this in the subclass to provide methods to handle each of the subscriptions."""
+        return {}
+
     @abc.abstractmethod
     def get_communication_protocol(self) -> str:
         """Returns the communication protocol used by the Control Server.
@@ -451,6 +467,11 @@ class ControlServer(metaclass=abc.ABCMeta):
 
         self.scheduled_tasks.append({"task": callback, "name": name, "after": scheduled_time, "when": when})
 
+    def setup_event_subscription(self):
+        for event_type, handler in self.get_event_handlers().items():
+            self.logger.info(f"Registering handler {type_name(handler)} for {event_type}")
+            self.event_subscription.register_handler(event_type, handler)
+
     def serve(self) -> None:
         """Activation of the Control Server.
 
@@ -474,6 +495,8 @@ class ControlServer(metaclass=abc.ABCMeta):
 
         self.before_serve()
 
+        self.setup_event_subscription()
+
         # check if Storage Manager is available
 
         storage_manager = self.is_storage_manager_active()
@@ -508,6 +531,10 @@ class ControlServer(metaclass=abc.ABCMeta):
             if self.dev_ctrl_service_sock in socks:
                 self.service_protocol.execute()
 
+            if self.event_subscription.socket in socks:
+                with Timer("Handling notification event"):
+                    self.event_subscription.handle_event()
+
             # Handle sending out monitoring information periodically, based on the MON_DELAY time that is specified in
             # the YAML configuration file for the device
 
@@ -581,6 +608,8 @@ class ControlServer(metaclass=abc.ABCMeta):
         self.dev_ctrl_service_sock.close(linger=0)
         self.dev_ctrl_cmd_sock.close(linger=0)
 
+        self.event_subscription.disconnect()
+
         close_all_zmq_handlers()
 
         # Since we closed all ZeroMQ handlers, we shall use standard logging from here.