motorcortex-python 1.0.0rc1__py3-none-any.whl

motorcortex/request.py

@@ -0,0 +1,668 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+"""
+motorcortex.request
+
+Provides the Request class for managing request connections to a Motorcortex server,
+including login, parameter retrieval, parameter updates, and group management.
+"""
+
+import atexit
+from threading import Event, Timer
+from concurrent.futures import ThreadPoolExecutor, Future
+from typing import Any, Callable, List, Optional, Union
+from pynng import Req0, TLSConfig  # type: ignore[import-untyped]
+
+from motorcortex.reply import Reply
+from motorcortex.setup_logger import logger
+from motorcortex.state_callback_handler import StateCallbackHandler
+from motorcortex.parameter_tree import ParameterTree
+from motorcortex.message_types import MessageTypes
+from motorcortex.nng_url import NngUrl
+from motorcortex.exceptions import McxConnectionError
+from motorcortex import _connection_state, _request_builders, _request_utils, motorcortex_pb2 as _pb
+# ConnectionState lives in _connection_state now — re-exported here so
+# ``from motorcortex.request import ConnectionState`` keeps working.
+from motorcortex._connection_state import ConnectionState
+
+
+def _close_at_exit(inst: "Request") -> None:
+    """Shutdown hook: close a ``Request`` the user forgot to clean up.
+
+    Registered via :func:`_register_shutdown` at construction. See
+    motorcortex.subscribe for the rationale on using
+    ``threading._register_atexit`` instead of plain ``atexit`` —
+    ``concurrent.futures._python_exit`` runs there and would join the
+    pool workers before any regular atexit handler could close the
+    socket.
+    """
+    try:
+        if getattr(inst, "_closed", True):
+            return
+        inst.close()
+    except Exception:
+        pass
+
+
+def _register_shutdown(inst: "Request") -> None:
+    """Register ``_close_at_exit(inst)`` on the ``threading`` atexit
+    registry so it fires before ``concurrent.futures._python_exit``.
+
+    Falls back to regular ``atexit`` if the private threading API is
+    absent.
+    """
+    try:
+        import threading
+        threading._register_atexit(_close_at_exit, inst)  # type: ignore[attr-defined]
+    except (AttributeError, ImportError):
+        atexit.register(_close_at_exit, inst)
+
+
+class Request:
+    """
+    Represents a request connection to a Motorcortex server.
+
+    The Request class allows you to:
+    - Establish and manage a connection to a Motorcortex server.
+    - Perform login authentication.
+    - Retrieve, set, and overwrite parameter values.
+    - Manage parameter groups for efficient batch operations.
+    - Save and load parameter trees.
+    - Chain asynchronous operations using a promise-like interface (`Reply`).
+
+    Methods:
+        url() -> Optional[str]
+            Returns the current connection URL.
+
+        connect(url: str, **kwargs) -> Reply
+            Establishes a connection to the server.
+
+        close() -> None
+            Closes the connection and cleans up resources.
+
+        send(encoded_msg: Any, do_not_decode_reply: bool = False) -> Optional[Reply]
+            Sends an encoded message to the server.
+
+        login(login: str, password: str) -> Reply
+            Sends a login request.
+
+        connectionState() -> ConnectionState
+            Returns the current connection state.
+
+        getParameterTreeHash() -> Reply
+            Requests the parameter tree hash from the server.
+
+        getParameterTree() -> Reply
+            Requests the parameter tree from the server.
+
+        save(path: str, file_name: str) -> Reply
+            Requests the server to save the parameter tree to a file.
+
+        setParameter(path: str, value: Any, type_name: Optional[str] = None, offset: int = 0, length: int = 0) -> Reply
+            Sets a new value for a parameter.
+
+        setParameterList(param_list: List[dict]) -> Reply
+            Sets new values for a list of parameters.
+
+        getParameter(path: str) -> Reply
+            Requests a parameter value and description.
+
+        getParameterList(path_list: List[str]) -> Reply
+            Requests values and descriptions for a list of parameters.
+
+        overwriteParameter(path: str, value: Any, force_activate: bool = False, type_name: Optional[str] = None) -> Reply
+            Overwrites a parameter value and optionally forces it to stay active.
+
+        releaseParameter(path: str) -> Reply
+            Releases the overwrite operation for a parameter.
+
+        createGroup(path_list: List[str], group_alias: str, frq_divider: int = 1) -> Reply
+            Creates a subscription group for a list of parameters.
+
+        removeGroup(group_alias: str) -> Reply
+            Unsubscribes from a group.
+
+    Examples:
+        >>> # Establish a connection
+        >>> req = motorcortex.Request(protobuf_types, parameter_tree)
+        >>> reply = req.connect("tls+tcp://localhost:6501", certificate="path/to/ca.crt")
+        >>> if reply.get():
+        ...     print("Connected!")
+        >>> # Login
+        >>> login_reply = req.login("user", "password")
+        >>> if login_reply.get().status == motorcortex.OK:
+        ...     print("Login successful")
+        >>> # Get a parameter
+        >>> param_reply = req.getParameter("MyDevice.MyParam")
+        >>> param = param_reply.get()
+        >>> print("Value:", param.value)
+        >>> # Set a parameter
+        >>> req.setParameter("MyDevice.MyParam", 42)
+        >>> # Clean up
+        >>> req.close()
+    """
+
+    def __init__(self, protobuf_types: "MessageTypes", parameter_tree: "ParameterTree", number_of_threads: int = 2) -> None:
+        """
+        Initialize a Request object.
+
+        Args:
+            protobuf_types: Motorcortex message types module.
+            parameter_tree: ParameterTree instance.
+            number_of_threads (int): Thread pool size (minimum 1, None - use default (CPU-based)).
+        """
+        self._socket: Optional[Req0] = None
+        self._url: Optional[str] = None
+        self._connected_event: Optional[Event] = None
+        self._connected: bool = False
+        self._protobuf_types: "MessageTypes" = protobuf_types
+        self._parameter_tree: "ParameterTree" = parameter_tree
+        self._connection_state: ConnectionState = ConnectionState.DISCONNECTED
+        self._pool: ThreadPoolExecutor = ThreadPoolExecutor(max_workers=number_of_threads,
+                                                             thread_name_prefix="mcx_req")
+        self._callback_handler: StateCallbackHandler = StateCallbackHandler()
+        self._token: Optional[str] = None
+        self._token_timer: Optional[Timer] = None
+        self._token_update_interval_sec: float = 30.0
+        # Net safeguard: if the caller forgets close(), the receive-loop
+        # worker stays blocked in recv() and Python's atexit
+        # ``_python_exit`` hook (concurrent.futures) joins it forever,
+        # hanging the interpreter. Register a weakref-based cleanup that
+        # fires ahead of that hook. Explicit close() makes this a no-op
+        # (``__closed`` flag is set and re-entry is guarded).
+        self._closed: bool = False
+        _register_shutdown(self)
+
+    def url(self) -> Optional[str]:
+        """Return the current connection URL."""
+        return self._url
+
+    def __repr__(self) -> str:
+        return (
+            f"Request(url={self._url!r}, "
+            f"state={self._connection_state.name})"
+        )
+
+    @property
+    def motorcortex_types(self) -> "MessageTypes":
+        """The ``MessageTypes`` instance passed at construction.
+
+        Exposed so callers (tests, higher-level helpers) can reach the
+        bundled protobuf module without constructing a second
+        ``MessageTypes`` — e.g. ``req.motorcortex_types.motorcortex().OK``.
+        """
+        return self._protobuf_types
+
+    # -- NNG pipe callbacks -------------------------------------------
+    #
+    # These used to be nested closures inside ``connect()`` that
+    # captured ``self`` plus the local ``connected_event`` / ``connected``
+    # vars. Promoting them to methods makes their behavior unit-testable
+    # by direct invocation (no live pipe event needed) and shrinks
+    # ``connect()`` accordingly. The NNG library passes a ``pipe`` arg
+    # we don't inspect — prefixed with ``_``.
+
+    def _on_pipe_connect(self, _pipe: Any) -> None:
+        """Socket accepted a peer pipe. Transition to ``CONNECTION_OK``
+        and wake anyone blocked in :func:`_request_utils.wait_for_connection`.
+        """
+        old_state = self._connection_state.name
+        self._connected = True
+        self._connection_state = ConnectionState.CONNECTION_OK
+        logger.debug(
+            "[REQUEST-CALLBACK] PRE_CONNECT fired — %s -> %s",
+            old_state, self._connection_state.name,
+        )
+        self._callback_handler.notify(self, self.connectionState())
+        if self._connected_event is not None:
+            self._connected_event.set()
+
+    def _on_pipe_remove(self, _pipe: Any) -> None:
+        """Socket pipe torn down. Pick the right terminal state via
+        :func:`_connection_state.next_state_after_pipe_remove`, then
+        wake waiters.
+        """
+        old_state = self._connection_state.name
+        self._connection_state = _connection_state.next_state_after_pipe_remove(
+            self._connection_state
+        )
+        logger.debug(
+            "[REQUEST-CALLBACK] POST_REMOVE fired — %s -> %s",
+            old_state, self._connection_state.name,
+        )
+        self._connected = False
+        self._callback_handler.notify(self, self.connectionState())
+        if self._connected_event is not None:
+            self._connected_event.set()
+
+    def connect(self, url: str, **kwargs: Any) -> "Reply[bool]":
+        """
+        Establish a connection to the Motorcortex server.
+
+        Args:
+            url: Connection URL.
+            **kwargs: Additional connection parameters. Supported keys include:
+                certificate (str, optional): Path to a TLS certificate file for secure connections.
+                conn_timeout_ms (int, optional): Connection timeout in milliseconds (default: 1000).
+                recv_timeout_ms (int, optional): Receive timeout in milliseconds (default: 500).
+                login (str, optional): Username for authentication (if required by server).
+                password (str, optional): Password for authentication (if required by server).
+                state_update (Callable, optional): Callback function to be called on connection state changes.
+                timeout_ms (int, optional): Alternative timeout in milliseconds (used by Request.parse).
+
+        Returns:
+            Reply: A promise that resolves when the connection is established.
+        """
+        self._connection_state = ConnectionState.CONNECTING
+        conn_timeout_ms, recv_timeout_ms, certificate, state_update = _request_utils.parse_connect_kwargs(**kwargs)
+
+        if state_update:
+            self._callback_handler.start(state_update)
+
+        self._url = url
+        tls_config = None
+        if certificate:
+            parsed = NngUrl(url)
+            # auth_mode=OPTIONAL: motorcortex deployments ship a self-signed
+            # end-entity cert that clients pin directly. Modern mbedTLS (3.6+)
+            # refuses to use a non-CA cert as a trust anchor under the
+            # REQUIRED mode pynng defaults to, producing a cryptic
+            # "Cryptographic error" on handshake. OPTIONAL performs the
+            # verification best-effort (still catches the obvious
+            # wrong-server case) without aborting on the CA:FALSE check.
+            tls_config = TLSConfig(
+                TLSConfig.MODE_CLIENT,
+                ca_files=certificate,
+                server_name=parsed.hostname,
+                auth_mode=TLSConfig.AUTH_MODE_OPTIONAL,
+            )
+
+        self._socket = Req0(recv_timeout=recv_timeout_ms, tls_config=tls_config)
+        self._connected_event = Event()
+        self._connected = False
+
+        self._socket.add_pre_pipe_connect_cb(self._on_pipe_connect)
+        self._socket.add_post_pipe_remove_cb(self._on_pipe_remove)
+
+        logger.debug(
+            "[REQUEST] dialing %s (timeout=%dms, tls=%s)",
+            url, conn_timeout_ms, bool(tls_config),
+        )
+        self._socket.dial(url, block=False)
+
+        return Reply(self._pool.submit(_request_utils.wait_for_connection, self._connected_event,
+                                        conn_timeout_ms / 1000.0, lambda: self._connected))
+
+    def close(self) -> None:
+        """
+        Close the request connection and clean up resources.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        logger.debug("[REQUEST] closing (state=%s)", self._connection_state.name)
+
+        self._connection_state = ConnectionState.DISCONNECTING
+        self._stopTokenRefresh()
+        if self._connected_event:
+            self._connected = False
+            self._connected_event.set()
+
+        if self._socket:
+            self._socket.close()
+
+        self._callback_handler.stop()
+        self._pool.shutdown(wait=True)
+
+    def send(self, encoded_msg: Any, do_not_decode_reply: bool = False) -> "Reply[Any]":
+        """Send an encoded message to the server.
+
+        Args:
+            encoded_msg: Encoded protobuf message.
+            do_not_decode_reply: If True, do not decode the reply.
+
+        Returns:
+            Reply: A promise for the server's reply.
+
+        Raises:
+            McxConnectionError: the underlying socket is closed
+                or was never opened. Protocol-level failures (bad
+                path, permission denied, etc.) do **not** raise —
+                they arrive on ``reply.get().status``. Transport
+                failures do.
+        """
+        if self._socket is None:
+            raise McxConnectionError(
+                "Cannot send: Request is not connected (socket is None). "
+                "Call Request.connect(...) first."
+            )
+        return Reply(self._pool.submit(
+            _request_utils.send_and_recv, self._socket, encoded_msg,
+            None if do_not_decode_reply else self._protobuf_types,
+        ))
+
+    def login(self, login: str, password: str) -> "Reply[_pb.StatusMsg]":
+        """
+        Send a login request to the server.
+
+        Args:
+            login: User login.
+            password: User password.
+
+        Returns:
+            Reply: A promise for the login reply.
+        """
+
+        login_msg = self._protobuf_types.createType('motorcortex.LoginMsg')
+        login_msg.password = password
+        login_msg.login = login
+
+        return self.send(self._protobuf_types.encode(login_msg))
+
+    def connectionState(self) -> ConnectionState:
+        """
+        Get the current connection state.
+
+        Returns:
+            ConnectionState: The current state.
+        """
+        return self._connection_state
+
+    def getParameterTreeHash(self) -> "Reply[_pb.ParameterTreeHashMsg]":
+        """
+        Request a parameter tree hash from the server.
+
+        Returns:
+            Reply: A promise for the parameter tree hash.
+        """
+
+        # getting and instantiating data type from the loaded dict
+        param_tree_hash_msg = self._protobuf_types.createType('motorcortex.GetParameterTreeHashMsg')
+
+        # encoding and sending data
+        return self.send(self._protobuf_types.encode(param_tree_hash_msg))
+
+    def getParameterTree(self) -> "Reply[_pb.ParameterTreeMsg]":
+        """
+        Request a parameter tree from the server.
+
+        Returns:
+            Reply: A promise for the parameter tree.
+        """
+
+        return Reply(self._pool.submit(
+            self._getParameterTree,
+            self.getParameterTreeHash(), self._protobuf_types, self._socket, self._url,
+        ))
+
+    def save(self, path: str, file_name: str) -> "Reply[_pb.StatusMsg]":
+        """
+        Request the server to save a parameter tree to a file.
+
+        Args:
+            path: Path to save the file.
+            file_name: Name of the file.
+
+        Returns:
+            Reply: A promise for the save operation.
+        """
+
+        param_save_msg = self._protobuf_types.createType('motorcortex.SaveMsg')
+        param_save_msg.path = path
+        param_save_msg.file_name = file_name
+
+        return self.send(self._protobuf_types.encode(param_save_msg))
+
+    def setParameter(self, path: str, value: Any, type_name: Optional[str] = None, offset: int = 0,
+                     length: int = 0) -> "Reply[_pb.StatusMsg]":
+        """
+        Set a new value for a parameter.
+
+        Args:
+            path: Parameter path.
+            value: New value.
+            type_name: Type name (optional).
+            offset: Offset in array (optional).
+            length: Number of elements to update (optional).
+
+        Returns:
+            Reply: A promise for the set operation.
+        """
+
+        if (offset == 0) and (length == 0):
+            return self.send(self._protobuf_types.encode(_request_builders.build_set_parameter_msg(
+                path, value, type_name, self._protobuf_types, self._parameter_tree)))
+        else:
+            return self.send(self._protobuf_types.encode(_request_builders.build_set_parameter_with_offset_msg(
+                offset, length, path, value, type_name, self._protobuf_types, self._parameter_tree)))
+
+    def setParameterList(self, param_list: List[dict]) -> "Reply[_pb.StatusMsg]":
+        """
+        Set new values to a parameter list
+
+        Args:
+                param_list([{'path'-`str`,'value'-`any`, 'offset', 'length'}]): a list of the parameters which values update
+
+        Returns:
+            Reply(StatusMsg): A Promise, which resolves when parameters from the list are updated,
+            otherwise fails.
+
+        Examples:
+                >>>  req.setParameterList([
+                >>>   {'path': 'root/Control/generator/enable', 'value': False},
+                >>>   {'path': 'root/Control/generator/amplitude', 'value': 1.4}])
+                >>>   {'path': 'root/Control/myArray6', 'value': [1.4, 1.5], 'offset': 1, 'length': 2}])
+        """
+
+        # instantiating message type
+        set_param_list_msg = self._protobuf_types.createType("motorcortex.SetParameterListMsg")
+        # filling with sub messages
+        for param in param_list:
+            type_name = param.get("type_name", None)
+            offset = param.get("offset", 0)
+            length = param.get("length", 0)
+            if (offset == 0) and (length == 0):
+                set_param_list_msg.params.extend([_request_builders.build_set_parameter_msg(
+                    param["path"], param["value"], type_name, self._protobuf_types, self._parameter_tree)])
+            else:
+                set_param_list_msg.params.extend([_request_builders.build_set_parameter_with_offset_msg(
+                    offset, length, param["path"], param["value"],
+                    type_name, self._protobuf_types, self._parameter_tree)])
+
+        # encoding and sending data
+        return self.send(self._protobuf_types.encode(set_param_list_msg))
+
+    def getParameter(self, path: str) -> "Reply[_pb.ParameterMsg]":
+        """
+        Request a parameter value and description from the server.
+
+        Args:
+            path: Parameter path.
+
+        Returns:
+            Reply: A promise for the parameter value.
+        """
+
+        return self.send(self._protobuf_types.encode(
+            _request_builders.build_get_parameter_msg(path, self._protobuf_types)))
+
+    def getParameterList(self, path_list: List[str]) -> "Reply[_pb.ParameterListMsg]":
+        """
+        Request values and descriptions for a list of parameters.
+
+        Args:
+            path_list: List of parameter paths.
+
+        Returns:
+            Reply: A promise for the parameter list.
+        """
+
+        # instantiating message type
+        get_param_list_msg = self._protobuf_types.createType('motorcortex.GetParameterListMsg')
+        # filling with sub messages
+        for path in path_list:
+            get_param_list_msg.params.extend([
+                _request_builders.build_get_parameter_msg(path, self._protobuf_types)])
+
+        # encoding and sending data
+        return self.send(self._protobuf_types.encode(get_param_list_msg))
+
+    def overwriteParameter(self, path: str, value: Any, force_activate: bool = False,
+                           type_name: Optional[str] = None) -> "Reply[_pb.StatusMsg]":
+        """
+        Overwrite a parameter value and optionally force it to stay active.
+
+        Args:
+            path: Parameter path.
+            value: New value.
+            force_activate: Force value to stay active.
+            type_name: Type name (optional).
+
+        Returns:
+            Reply: A promise for the overwrite operation.
+        """
+
+        return self.send(self._protobuf_types.encode(_request_builders.build_overwrite_parameter_msg(
+            path, value, force_activate, type_name, self._protobuf_types, self._parameter_tree)))
+
+    def releaseParameter(self, path: str) -> "Reply[_pb.StatusMsg]":
+        """
+        Release the overwrite operation for a parameter.
+
+        Args:
+            path: Parameter path.
+
+        Returns:
+            Reply: A promise for the release operation.
+        """
+
+        return self.send(self._protobuf_types.encode(
+            _request_builders.build_release_parameter_msg(path, self._protobuf_types)))
+
+    def createGroup(self, path_list: List[str], group_alias: str, frq_divider: int = 1) -> "Reply[_pb.GroupStatusMsg]":
+        """
+        Create a subscription group for a list of parameters.
+
+        Args:
+            path_list: List of parameter paths.
+            group_alias: Group alias.
+            frq_divider: Frequency divider.
+
+        Returns:
+            Reply: A promise for the group creation.
+        """
+
+        # instantiating message type
+        create_group_msg = self._protobuf_types.createType('motorcortex.CreateGroupMsg')
+        create_group_msg.alias = group_alias
+        create_group_msg.paths.extend(path_list if type(path_list) is list else [path_list])
+        create_group_msg.frq_divider = frq_divider if frq_divider > 1 else 1
+        # encoding and sending data
+        return self.send(self._protobuf_types.encode(create_group_msg))
+
+    def removeGroup(self, group_alias: str) -> "Reply[_pb.StatusMsg]":
+        """
+        Unsubscribe from a group.
+
+        Args:
+            group_alias: Group alias.
+
+        Returns:
+            Reply: A promise for the unsubscribe operation.
+        """
+
+        # instantiating message type
+        remove_group_msg = self._protobuf_types.createType('motorcortex.RemoveGroupMsg')
+        remove_group_msg.alias = group_alias
+        # encoding and sending data
+        return self.send(self._protobuf_types.encode(remove_group_msg))
+
+    @property
+    def token(self) -> Optional[str]:
+        """Return the current session token."""
+        return self._token
+
+    def getSessionToken(self) -> "Reply[_pb.SessionTokenMsg]":
+        """Request a session token from the server."""
+        msg = self._protobuf_types.createType('motorcortex.GetSessionTokenMsg')
+        return self.send(self._protobuf_types.encode(msg))
+
+    def restoreSession(self, token: str) -> "Reply[_pb.SessionTokenMsg]":
+        """Restore a session using a saved token."""
+        msg = self._protobuf_types.createType('motorcortex.RestoreSessionMsg')
+        msg.token = token
+        return self.send(self._protobuf_types.encode(msg))
+
+    def _startTokenRefresh(self, interval_sec: float = 30.0) -> None:
+        """Start periodic session token refresh.
+
+        Args:
+            interval_sec: Interval between token refreshes in seconds.
+        """
+        self._token_update_interval_sec = interval_sec
+        self._stopTokenRefresh()
+        # Fetch token immediately, then schedule periodic refresh
+        self._fetchToken()
+        self._scheduleTokenRefresh()
+
+    def _stopTokenRefresh(self) -> None:
+        """Stop periodic session token refresh."""
+        if self._token_timer:
+            self._token_timer.cancel()
+            self._token_timer = None
+
+    def _scheduleTokenRefresh(self) -> None:
+        """Schedule the next token refresh."""
+        self._stopTokenRefresh()
+        self._token_timer = Timer(self._token_update_interval_sec, self._onTokenTimer)
+        self._token_timer.daemon = True
+        self._token_timer.start()
+
+    def _onTokenTimer(self) -> None:
+        """Timer callback: fetch token and reschedule."""
+        self._fetchToken()
+        # Always reschedule if not disconnecting/disconnected
+        if self._connection_state not in (ConnectionState.DISCONNECTING, ConnectionState.DISCONNECTED):
+            self._scheduleTokenRefresh()
+
+    def _fetchToken(self) -> None:
+        """Fetch a session token from the server."""
+        if self._connection_state != ConnectionState.CONNECTION_OK:
+            return
+        try:
+            reply = self.getSessionToken()
+            if reply:
+                msg = reply.get(timeout_ms=5000)
+                if msg and hasattr(msg, 'token'):
+                    self._token = msg.token
+        except Exception as e:
+            logger.debug("[REQUEST] token refresh failed: %s", e)
+
+    # Pure protobuf message builders live in ``motorcortex._request_builders``.
+    # They used to be private ``__buildXxxMsg`` static methods on this class;
+    # moving them out lets them be unit-tested without spinning up a socket.
+
+    @staticmethod
+    def _getParameterTree(
+            hash_reply: Reply,
+            protobuf_types: MessageTypes,
+            socket: Req0,
+            url: Optional[str] = None,
+    ) -> Any:
+        """Thunk that unwraps ``hash_reply`` and delegates to
+        :func:`motorcortex._request_utils.fetch_parameter_tree`.
+
+        Runs inside the request-pool worker (see ``getParameterTree``),
+        which is why it takes a pre-queued :class:`Reply` — we can't do
+        the ``.get()`` on the caller thread or we'd block the pool-submit.
+        """
+        tree_hash = hash_reply.get()
+        return _request_utils.fetch_parameter_tree(
+            tree_hash.hash, protobuf_types, socket, url,
+        )
+