motorcortex-python 1.0.3__py3-none-any.whl → 1.2.1__py3-none-any.whl

motorcortex/__init__.py

@@ -41,6 +41,7 @@ from motorcortex.exceptions import (
     McxTimeout,
 )
 from motorcortex.motorcortex_pb2 import StatusCode as _PbStatusCode
+from motorcortex import _request_utils
 from motorcortex.setup_logger import logger  # not re-exported — ``__all__`` gates package surface
 
 # Build an ``IntEnum`` facade over the protobuf ``StatusCode`` enum so
@@ -286,7 +287,7 @@ def connect(
             state_update (Callable, optional): Custom callback for connection state changes.
                 If provided, disables the built-in reconnect logic.
             req_number_of_threads (int, optional): Thread pool size for request connection. Defaults to 2.
-            sub_number_of_threads (int, optional): Thread pool size for subscribe connection. Defaults to 2.
+            sub_number_of_threads (int, optional): Thread pool size for subscribe connection. Defaults to 2, clamped up to the minimum of 4 that ``Subscribe`` requires (connect worker, recv loop, reconnect loop, subscription updaters).
 
     Returns:
         tuple: (req, sub)
@@ -312,7 +313,15 @@ def connect(
 
     if reconnect and not kwargs.get("state_update"):
 
+        # The initial CONNECTION_OK edge can land after connect() returns
+        # (the cookie probe + hello finish in the background), so it must
+        # not be mistaken for a reconnect that needs a re-login.
+        initial_ok_seen = [False]
+
         def stateUpdate(req, sub, state):
+            if state == ConnectionState.CONNECTION_OK and not initial_ok_seen[0]:
+                initial_ok_seen[0] = True
+                return
             _reconnect_state_update(
                 req, sub, state,
                 motorcortex_types=motorcortex_types,
@@ -342,7 +351,12 @@ def connect(
             )
         # Open subscribe connection
         sub = Subscribe(req, motorcortex_types, kwargs.get("sub_number_of_threads", 2))
-        if not sub.connect(makeUrl(sub_address, sub_port), **kwargs).get():
+        sub_reply = sub.connect(makeUrl(sub_address, sub_port), **kwargs)
+        # Wait for the dial only: the cookie probe and hello carry on in
+        # the background (up to 2 s on an old server that never answers)
+        # while login and a cached tree load go ahead.
+        dialed = getattr(sub, "_dialed", None)
+        if not (dialed.result() if dialed is not None else sub_reply.get()):
             raise McxConnectionError(
                 "Failed to establish subscribe connection: {}:{}".format(sub_address, sub_port)
             )
@@ -360,7 +374,18 @@ def connect(
             )
 
         # Requesting a parameter tree
-        param_tree_reply = req.getParameterTree()
+        # On a cache miss, wait for the cookie-probe verdict so an old
+        # server (no compressed tree handler, silently drops the request)
+        # gets the plain tree straight away instead of waiting on a reply
+        # that never comes. A cache hit never calls this.
+        def compressed_hint():
+            try:
+                sub_reply.get(timeout_ms=_request_utils.CAPABILITY_PROBE_TIMEOUT_MS + 3000)
+            except Exception:
+                return None
+            return getattr(sub, "_server_has_routing", None)
+
+        param_tree_reply = req.getParameterTree(compressed=compressed_hint)
         tree = param_tree_reply.get()
         param_tree.load(tree)
     except Exception:

motorcortex/_request_utils.py

@@ -19,8 +19,12 @@ import hashlib
 import json
 import os
 import tempfile
+import zlib
 from threading import Event
-from typing import Any, Callable, Optional, Tuple
+from typing import Any, Callable, Optional, Tuple, Union
+
+from pynng._nng import lib  # type: ignore[import-untyped]
+from pynng.exceptions import check_err  # type: ignore[import-untyped]
 
 from motorcortex.exceptions import McxConnectionError
 from motorcortex.setup_logger import logger
@@ -28,6 +32,12 @@ from motorcortex.setup_logger import logger
 
 _CACHE_PREFIX = "mcx-python-pt"
 
+#: Old servers silently drop unknown request hashes — cap how long a
+#: capability probe (routing cookie, compressed tree) may wait so a
+#: pre-2.36 server costs at most 2 s per probe. Mirrors
+#: CAPABILITY_PROBE_TIMEOUT_MS in motorcortex-cpp and motorcortex-js.
+CAPABILITY_PROBE_TIMEOUT_MS = 2000
+
 
 def parse_connect_kwargs(
         conn_timeout_ms: int = 0,
@@ -113,6 +123,7 @@ def fetch_parameter_tree(
         protobuf_types: Any,
         socket: Any,
         url: Optional[str] = None,
+        compressed: Union[Optional[bool], Callable[[], Optional[bool]]] = None,
 ) -> Any:
     """Fetch the parameter tree, hitting the local cache first.
 
@@ -131,10 +142,43 @@ def fetch_parameter_tree(
             :func:`send_and_recv`.
         url: Connection URL — hashed into the cache filename so two
             engines with the same ``tree_hash`` don't collide.
+        compressed: Server-capability hint from the routing-cookie probe
+            (same scheme as motorcortex-js). The cookie handler and the
+            compressed tree handler both landed in core 2.36, so:
+            ``False`` — the server did not hand out a cookie, so it has no
+            compressed handler: skip straight to the plain request.
+            ``True`` — the server is >= 2.36: request compressed with the
+            socket's own timeout, so a big reply on a slow link never
+            races a short cap.
+            ``None`` — unknown (no Subscribe, raw ``Request`` use): try
+            compressed, capped at ``CAPABILITY_PROBE_TIMEOUT_MS``.
+            May also be a callable returning one of those; it is only
+            called on a cache miss, so a still-running probe never delays
+            a cached tree load.
 
     Returns:
         A ``ParameterTreeMsg`` — either the cached one or the freshly
         fetched one (also persisted to the cache).
+
+    On a cache miss, a compressed tree is tried first
+    (``motorcortex-core >= 2.36.0``): a single zlib/deflate blob,
+    typically 7-13x smaller than the plain reply. The server deflates
+    the *full wire reply* — a 4-byte little-endian type-hash prefix
+    followed by the ``ParameterTreeMsg`` body, same as any other RPC
+    reply — so the inflated blob goes through the canonical
+    ``MessageTypes.decode()``, which strips the prefix and resolves the
+    type by hash. Any failure — timeout on an old server that silently
+    drops the unrecognised request hash, a non-OK status from a
+    2.36.1-2.38 core, an unknown or unexpected type hash, or an
+    inflate/parse error — falls through to the plain
+    ``GetParameterTreeMsg`` request. Both paths decode to the same
+    ``ParameterTreeMsg`` type, so callers (and the cache write below)
+    can't tell the difference. Tried for every URL scheme (ipc, tcp,
+    ws, tls+tcp, wss) — the request is just bytes over
+    :func:`send_and_recv`. Old servers never answer the unknown hash, and
+    the socket's ``recv_timeout`` is infinite by default, so an uncapped
+    attempt would hang the connect forever — hence the ``compressed``
+    hint and the per-request probe cap.
     """
     path = parameter_tree_cache_path(url, tree_hash)
     cached = load_parameter_tree_file(path, protobuf_types)
@@ -143,6 +187,51 @@ def fetch_parameter_tree(
         return cached
     logger.debug("[REQUEST] Failed to find parameter tree in the cache")
 
+    if callable(compressed):
+        compressed = compressed()
+    if compressed is False:
+        logger.debug("[REQUEST] server predates the compressed tree — requesting plain")
+        request_msg = protobuf_types.createType("motorcortex.GetParameterTreeMsg")
+        handle = send_and_recv(socket, protobuf_types.encode(request_msg), protobuf_types)
+        return save_parameter_tree_file(path, handle)
+
+    try:
+        compressed_request = protobuf_types.createType(
+            "motorcortex.GetParameterTreeCompressedMsg")
+        compressed_reply = send_and_recv(
+            socket, protobuf_types.encode(compressed_request), protobuf_types,
+            timeout_ms=None if compressed else CAPABILITY_PROBE_TIMEOUT_MS)
+        if compressed_reply is not None \
+                and getattr(compressed_reply, "status", 1) == 0 \
+                and getattr(compressed_reply, "compressed", b""):
+            # The server deflates the *full wire reply* here, not a bare
+            # ParameterTreeMsg: inflating yields the same hash-prefixed
+            # framing every other RPC reply uses (matches the message's
+            # own docstring: "the exact bytes a GetParameterTreeMsg reply
+            # carries"). Run it through the canonical decode() — which
+            # strips the type-hash prefix and resolves the type by hash —
+            # instead of ParseFromString on the raw blob; parsing the blob
+            # directly is exactly the bug this branch used to have: the
+            # prefix corrupted every parse and silently forced the plain
+            # fallback. An unknown hash (KeyError in decode) or a decode
+            # to some other type falls through to the plain request rather
+            # than caching garbage as a ParameterTreeMsg.
+            tree_msg = protobuf_types.decode(
+                zlib.decompress(compressed_reply.compressed))
+            decoded_name = getattr(
+                getattr(tree_msg, "DESCRIPTOR", None), "full_name", None)
+            if decoded_name != "motorcortex.ParameterTreeMsg":
+                raise ValueError(
+                    "compressed tree decoded to unexpected type "
+                    f"{decoded_name or type(tree_msg).__name__}")
+            logger.debug("[REQUEST] parameter tree fetched compressed")
+            return save_parameter_tree_file(path, tree_msg)
+    except Exception as e:
+        logger.debug(
+            "[REQUEST] compressed tree unavailable (%s: %s) — falling back to plain",
+            type(e).__name__, e,
+        )
+
     request_msg = protobuf_types.createType("motorcortex.GetParameterTreeMsg")
     handle = send_and_recv(socket, protobuf_types.encode(request_msg), protobuf_types)
     return save_parameter_tree_file(path, handle)
@@ -152,6 +241,7 @@ def send_and_recv(
         socket: Any,
         encoded_msg: Any,
         protobuf_types: Optional[Any],
+        timeout_ms: Optional[int] = None,
 ) -> Any:
     """One-shot synchronous request/reply over an nng Req0 socket.
 
@@ -168,6 +258,12 @@ def send_and_recv(
         encoded_msg: Bytes to send.
         protobuf_types: If truthy, decoded wire reply is returned.
             Otherwise the raw buffer is returned.
+        timeout_ms: Receive timeout for this one request, set on the nng
+            context so the worker thread is released when it expires
+            (``pynng.Timeout`` is raised). ``None`` keeps the socket's
+            ``recv_timeout``. A ``Reply.get(timeout_ms=...)`` alone only
+            stops the caller waiting — the worker stays blocked in
+            ``recv()`` for as long as the socket timeout allows.
 
     Returns:
         Decoded reply (when ``protobuf_types`` supplied and buffer is
@@ -175,6 +271,8 @@ def send_and_recv(
     """
     ctx = socket.new_context()
     try:
+        if timeout_ms is not None:
+            check_err(lib.nng_ctx_set_ms(ctx.context, b"recv-timeout", timeout_ms))
         ctx.send(encoded_msg)
         buffer = ctx.recv()
         if buffer:
@@ -182,7 +280,10 @@ def send_and_recv(
                 return protobuf_types.decode(buffer)
             return buffer
     except Exception as e:
-        logger.error("[SEND] Error during send/recv: %s: %s", type(e).__name__, e)
+        # A capped request timing out is an expected probe outcome on old
+        # servers, not an error worth shouting about.
+        log = logger.debug if timeout_ms is not None else logger.error
+        log("[SEND] Error during send/recv: %s: %s", type(e).__name__, e)
         raise
     finally:
         ctx.close()

motorcortex/_sp_stream.py

@@ -0,0 +1,331 @@
+#!/usr/bin/python3
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+"""Stream-based SP (nanomsg) pub/sub client transport.
+
+Replaces the pynng ``Sub0`` socket for the subscribe data channel so the
+client can send the routing hello as the first upstream message — a raw
+``nng_stream`` has no protocol layer, so we speak the SP wire format
+ourselves. Uses only pynng's bundled cffi bindings (``pynng._nng``): the
+full public ``nng_stream_* / nng_aio_*`` API ships in every pynng wheel.
+
+Wire format per scheme (mirrors motorcortex-cpp src/sp_stream.cpp, which
+is the proven reference — see its comments for the full rationale):
+
+- ws/wss:    subprotocol ``pub.sp.nanomsg.org`` on the HTTP upgrade;
+             message mode — one send/recv is one SP message, no length
+             prefix, no byte handshake.
+- tcp/tls:   8-byte handshake ``\\x00SP\\x00`` + u16-BE proto + u16-BE 0
+             (we announce 33/sub, require peer 32/pub), then each message
+             is a u64-BE length prefix + body.
+- ipc:       same handshake, but a 9-byte per-message header: type byte
+             ``0x01`` + u64-BE length. The type byte is load-bearing.
+
+nng 1.11.0 caveat (learned in cpp): never ``nng_aio_cancel`` an aio on a
+raw TLS stream — it crashes ``nng_stream_close`` intermittently. This
+implementation never cancels: every aio is owned by exactly one blocking
+call which waits for it to finish (success, error, or timeout) before
+freeing it. Closing the stream from another thread makes a pending recv
+finish with an error, which is the supported wakeup path.
+
+Stream lifetime vs. concurrent close(): a bare local capture of
+``self._stream`` before an nng call is not enough — close() both nulls
+the attribute *and* frees the underlying stream, so a racing capture can
+still end up handing a freed pointer to nng between close()'s two steps.
+Every blocking nng call therefore goes through ``_issue()``, which
+captures the stream, increments ``_io_inflight``, AND actually calls
+``nng_stream_send``/``nng_stream_recv`` — all under ``_io_cond`` in one
+atomic step (not just the capture: an earlier version issued the nng
+call *after* releasing the lock, which left a window where
+``nng_stream_close`` could run first and the op would then be issued
+against an already-closed stream — nng accepts that silently and never
+completes it, hanging ``nng_aio_wait`` forever when the aio has no
+timeout of its own, i.e. exactly ``recv_msg()``'s default). close() sets
+``_closing``/nulls ``self._stream`` under the same lock, calls
+``nng_stream_close`` (which wakes any pending aio — pending meaning
+already issued, which ``_issue()`` now guarantees), and only frees the
+stream once ``_io_inflight`` drops back to zero. That ordering — close,
+then wait for in-flight callers to finish with the local pointer they
+already captured, then free — is what makes the free race-free without
+ever touching ``nng_aio_cancel``.
+"""
+
+import struct
+import threading
+from typing import Optional
+
+from pynng._nng import ffi, lib  # type: ignore[import-untyped]
+from pynng.exceptions import check_err  # type: ignore[import-untyped]
+
+from motorcortex.setup_logger import logger
+
+_SP_PROTO_SUB = 33
+_SP_PROTO_PUB = 32
+_HANDSHAKE_LEN = 8
+
+#: One recv buffer per stream in ws message mode. nng's ws transport caps
+#: read-ahead at one frame and the server pipe buffer is 1 MiB, so a
+#: larger message cannot arrive whole (it would be truncated server-side
+#: first). Mirrors WS_MAX_MSG in cpp sp_stream.h.
+WS_MAX_MSG = 1 << 20
+
+#: Refuse absurd length prefixes on byte-stream schemes (64 MiB).
+_MAX_BODY = 1 << 26
+
+
+class SpStreamError(Exception):
+    """Transport-level failure on the SP stream."""
+
+
+class SpProtocolError(SpStreamError):
+    """Peer completed the byte handshake but is not an SP pub (32)."""
+
+
+def _tls_pointer(tls_config):
+    """Raw ``nng_tls_config *`` out of a pynng TLSConfig.
+
+    ``TLSConfig._tls_config`` is private but stable across pynng 0.9.x;
+    isolate the access here so a pynng bump touches one line.
+    """
+    return tls_config._tls_config
+
+
+def _alloc_aio(timeout_ms: int):
+    ap = ffi.new("nng_aio **")
+    check_err(lib.nng_aio_alloc(ap, ffi.NULL, ffi.NULL))
+    aio = ap[0]
+    lib.nng_aio_set_timeout(aio, timeout_ms if timeout_ms > 0 else -1)
+    return aio
+
+
+class SpStream:
+    def __init__(self) -> None:
+        self._dialer = None
+        self._stream = None
+        self._ws_mode = False
+        self._ipc_mode = False
+        self._recv_buf = None  # allocated lazily in Task 2
+        # Guards the stream-lifetime TOCTOU between a live nng call and a
+        # concurrent close(); see the module docstring.
+        self._io_cond = threading.Condition()
+        self._io_inflight = 0
+        self._closing = False
+
+    @property
+    def connected(self) -> bool:
+        return self._stream is not None
+
+    def connect(self, url: str, tls_config=None, timeout_ms: int = 5000) -> None:
+        """Dial + (non-ws) SP handshake. Raises on any failure; the
+        stream is fully closed again before an exception propagates."""
+        self.close()
+        # Re-arm under _io_cond, only after close() fully completed, so
+        # the flag flip is atomic against a concurrent close()'s own
+        # locked ``_closing = True`` transition (a close() racing the
+        # reopen after this point is caught by Subscribe's ``_closed``
+        # re-checks, which close any stream dialed past it).
+        with self._io_cond:
+            self._closing = False
+        self._ws_mode = url.startswith("ws://") or url.startswith("wss://")
+        self._ipc_mode = url.startswith("ipc://")
+
+        dp = ffi.new("nng_stream_dialer **")
+        check_err(lib.nng_stream_dialer_alloc(dp, url.encode()))
+        self._dialer = dp[0]
+        try:
+            if self._ws_mode:
+                # mcxpub0 keeps stock pub0's SP wire name, so every
+                # existing client's subprotocol offer is accepted.
+                check_err(lib.nng_stream_dialer_set_string(
+                    self._dialer, b"ws:protocol", b"pub.sp.nanomsg.org"))
+            if tls_config is not None:
+                check_err(lib.nng_stream_dialer_set_ptr(
+                    self._dialer, b"tls-config", _tls_pointer(tls_config)))
+
+            aio = _alloc_aio(timeout_ms)
+            lib.nng_stream_dialer_dial(self._dialer, aio)
+            lib.nng_aio_wait(aio)
+            rv = lib.nng_aio_result(aio)
+            if rv == 0:
+                self._stream = ffi.cast(
+                    "nng_stream *", lib.nng_aio_get_output(aio, 0))
+            lib.nng_aio_free(aio)
+            check_err(rv)
+
+            if not self._ws_mode:
+                self._handshake(timeout_ms)
+        except Exception:
+            self.close()
+            raise
+
+    def _handshake(self, timeout_ms: int) -> None:
+        ours = b"\x00SP\x00" + struct.pack(">H", _SP_PROTO_SUB) + b"\x00\x00"
+        self._io(True, ours, timeout_ms)
+        peer = self._io(False, _HANDSHAKE_LEN, timeout_ms)
+        expected = b"\x00SP\x00" + struct.pack(">H", _SP_PROTO_PUB) + b"\x00\x00"
+        if peer[:6] != expected[:6]:
+            raise SpProtocolError(
+                f"peer is not an SP pub socket (got {peer!r})")
+
+    def send_msg(self, data: bytes, timeout_ms: int = 2000) -> None:
+        if self._stream is None:
+            raise SpStreamError("send on a closed SpStream")
+        if self._ws_mode:
+            self._io(True, data, timeout_ms)  # message mode: 1 send = 1 msg
+            return
+        prefix = struct.pack(">Q", len(data))
+        if self._ipc_mode:
+            prefix = b"\x01" + prefix  # load-bearing type byte
+        self._io(True, prefix, timeout_ms)
+        self._io(True, data, timeout_ms)
+
+    def _issue(self, op, buf, offset: int, length: int, timeout_ms: int):
+        """Allocate an aio, set its iov, and hand it to ``op`` (a raw
+        ``nng_stream_send``/``nng_stream_recv`` — the *call*, not just
+        the registration) — all atomically under ``_io_cond``.
+
+        This has to be one critical section, not "capture the stream,
+        release the lock, then call ``op``" (the original shape): a
+        concurrent ``close()`` also serializes on ``_io_cond`` for its
+        own ``_closing = True`` transition, so whichever of the two
+        critical sections runs first fully determines a safe outcome —
+        either the op is issued while the stream is still known-open
+        (and ``close()``'s later ``nng_stream_close()`` correctly wakes
+        it, per nng's contract for *already-registered* ops), or
+        ``close()`` has already flipped ``_closing`` and this call bails
+        out before ever touching nng. The two-step version left a gap
+        between "session granted" / "op actually issued" that
+        ``close()`` could land in: ``nng_stream_close()`` running before
+        ``nng_stream_recv()``/``nng_stream_send()`` for that same aio
+        leaves it waiting forever — with a finite ``timeout_ms`` the
+        aio's own timer eventually rescues it, but ``recv_msg()``'s
+        default infinite timeout (the receive loop's steady state) has
+        no such backstop, so this used to hang the process instead of
+        surfacing the intended "stream closed" `None`.
+
+        Raises ``SpStreamError`` (stream already closing/closed) or lets
+        an ``nng_aio_set_iov`` failure propagate — in both cases nothing
+        was issued and ``_io_inflight`` was never incremented, so the
+        caller has nothing to undo. On success returns the aio with
+        ``_io_inflight`` already bumped; the caller owns freeing it and
+        decrementing the counter once the op settles.
+        """
+        with self._io_cond:
+            if self._closing or self._stream is None:
+                raise SpStreamError("stream closed mid-transfer")
+            stream = self._stream
+            aio = _alloc_aio(timeout_ms)
+            try:
+                iov = ffi.new("nng_iov *")
+                iov.iov_buf = buf + offset
+                iov.iov_len = length
+                check_err(lib.nng_aio_set_iov(aio, 1, iov))
+            except Exception:
+                lib.nng_aio_free(aio)
+                raise
+            self._io_inflight += 1
+            op(stream, aio)
+        return aio
+
+    def _settle(self, aio):
+        """Wait for an ``_issue()``-returned aio outside the lock (the
+        blocking part must never hold ``_io_cond`` — that would stall
+        ``close()``'s own attempt to grab it), then release the
+        in-flight slot. Returns ``(rv, got)``."""
+        try:
+            lib.nng_aio_wait(aio)
+            rv = lib.nng_aio_result(aio)
+            got = lib.nng_aio_count(aio) if rv == 0 else 0
+        finally:
+            lib.nng_aio_free(aio)
+            with self._io_cond:
+                self._io_inflight -= 1
+                self._io_cond.notify_all()
+        return rv, got
+
+    def _io(self, is_send: bool, data_or_len, timeout_ms: int):
+        """Blocking send of ``bytes`` / recv of exactly N bytes.
+        One aio per call; always waited on, never cancelled. Every nng
+        call is issued via ``_issue()`` so it can't race a concurrent
+        close() into hanging (see its docstring)."""
+        if is_send:
+            buf = ffi.new("uint8_t[]", bytes(data_or_len))
+            need = len(data_or_len)
+        else:
+            need = int(data_or_len)
+            buf = ffi.new("uint8_t[]", need)
+        op = lib.nng_stream_send if is_send else lib.nng_stream_recv
+        done = 0
+        while done < need:
+            aio = self._issue(op, buf, done, need - done, timeout_ms)
+            rv, got = self._settle(aio)
+            if rv != 0:
+                check_err(rv)
+            if got == 0:
+                raise SpStreamError("stream closed mid-transfer")
+            done += got
+        return None if is_send else bytes(ffi.buffer(buf, need))
+
+    def recv_msg(self, timeout_ms: int = -1) -> Optional[bytes]:
+        """Block for one whole SP message.
+
+        Returns ``None`` when the stream is closed/dead (remote close,
+        local close() from another thread, desync) — the receive loop's
+        exit signal. The ws invariant (nng caps ws read-ahead at one
+        frame) means one recv into a WS_MAX_MSG buffer is exactly one
+        message; byte-stream schemes reassemble via the length prefix.
+        """
+        if self._stream is None:
+            return None
+        try:
+            if self._ws_mode:
+                return self._recv_ws(timeout_ms)
+            hdr_len = 9 if self._ipc_mode else 8
+            hdr = self._io(False, hdr_len, timeout_ms)
+            if self._ipc_mode:
+                if hdr[0] != 0x01:
+                    logger.error("[SPSTREAM] ipc type-byte desync (0x%02x)", hdr[0])
+                    return None
+                hdr = hdr[1:]
+            (length,) = struct.unpack(">Q", hdr)
+            if length == 0 or length > _MAX_BODY:
+                logger.error("[SPSTREAM] absurd frame length %d — desync", length)
+                return None
+            return self._io(False, length, timeout_ms)
+        except Exception as e:
+            logger.debug("[SPSTREAM] recv_msg terminating: %s", e)
+            return None
+
+    def _recv_ws(self, timeout_ms: int) -> Optional[bytes]:
+        if self._recv_buf is None:
+            self._recv_buf = ffi.new("uint8_t[]", WS_MAX_MSG)
+        try:
+            aio = self._issue(lib.nng_stream_recv, self._recv_buf, 0, WS_MAX_MSG, timeout_ms)
+        except Exception:
+            return None
+        rv, got = self._settle(aio)
+        if rv != 0 or got == 0:
+            return None
+        return bytes(ffi.buffer(self._recv_buf, got))
+
+    def close(self) -> None:
+        with self._io_cond:
+            self._closing = True
+            stream, self._stream = self._stream, None
+            dialer, self._dialer = self._dialer, None
+        if stream is not None:
+            lib.nng_stream_close(stream)  # wakes any pending recv/send
+            # Wait for every in-flight _issue()/_settle() caller to
+            # finish with the (now-closed, error-returning) stream
+            # pointer it already captured before we free it — this is
+            # what makes the free race-free; see module docstring and
+            # _issue()'s docstring for why issuing the op is folded into
+            # the same critical section as this ``_closing`` flip.
+            with self._io_cond:
+                while self._io_inflight > 0:
+                    self._io_cond.wait()
+            lib.nng_stream_free(stream)
+        if dialer is not None:
+            lib.nng_stream_dialer_free(dialer)

motorcortex/motorcortex_hash.json

@@ -43,6 +43,14 @@
         "type": "motorcortex.SessionTokenMsg",
         "hash": "0x7c3e91ab"
     },
+    {
+        "type": "motorcortex.GetSubCookieMsg",
+        "hash": "0x5505c0b0"
+    },
+    {
+        "type": "motorcortex.SubCookieMsg",
+        "hash": "0x90ff084b"
+    },
     {
         "type": "motorcortex.RestoreSessionMsg",
         "hash": "0x8aef888a"
@@ -67,6 +75,14 @@
         "type": "motorcortex.ParameterTreeHashMsg",
         "hash": "0xc8cef26b"
     },
+    {
+        "type": "motorcortex.GetParameterTreeCompressedMsg",
+        "hash": "0x2347001b"
+    },
+    {
+        "type": "motorcortex.CompressedParameterTreeMsg",
+        "hash": "0x769fb6e8"
+    },
     {
         "type": "motorcortex.CreateGroupMsg",
         "hash": "0x9eab1b83"
@@ -149,7 +165,7 @@
     },
     {
         "type": "motorcortex.StatusCode",
-        "hash": "0xd785e9fa"
+        "hash": "0x6a1f3a02"
     },
     {
         "type": "motorcortex.ErrorLevel",