@camera.ui/server 0.0.105 → 0.0.107

package/dist/server/src/_camera_ui_tools/camera_ui_rpc/client.py

@@ -21,7 +21,7 @@ from nats.js.api import Header
 
 from .channel import Channel, PrivateChannel
 from .chunking import ChunkingManager, create_chunks
-from .codec import decode, encode
+from .codec import decode, decode_message, encode, encode_message
 from .decorators import extract_nested_methods_with_decorators, extract_nested_methods_without_decorators
 from .errors import RPCException, create_error
 from .executor import get_executor
@@ -52,7 +52,13 @@ from .types import (
 )
 from .types import ProxyWithClose as ProxyWithCloseProtocol
 from .types import RPCClient as RPCClientProtocol
-from .utils import create_proxy, create_service_proxy, generate_id, is_async_function
+from .utils import (
+    create_proxy,
+    create_service_proxy,
+    generate_id,
+    generate_reply_prefix,
+    is_async_function,
+)
 
 T = TypeVar("T")
 
@@ -89,20 +95,41 @@ class RPCClient(RPCClientProtocol):
         self.service: RPCService = RPCService(cast(Any, self))
 
         self.nc: NATSClient | None = None
-        self.subscriptions: dict[str, list[Subscription]] = {}
+        self._subscription_seq: int = 0
+        self._subscription_entries: dict[int, dict[str, Any]] = {}
         self.chunking_manager: ChunkingManager = ChunkingManager()
         self._max_payload_size: int = 1024 * 1024  # Default 1MB
         self._connection_task: asyncio.Task[NATSClient] | None = None
 
+        # First dot-separated segment of every id this client generates.
+        # Equals the conn_id when one is configured (browser clients: the
+        # firewall allowlists `rpc.reply.<conn_id>.>`), otherwise a local
+        # random prefix. All reply subjects derived from those ids therefore
+        # fall under one wildcard: `rpc.reply.<reply_prefix>.>` — the muxed
+        # reply inbox.
+        self._reply_prefix: str = options.get("conn_id") or generate_reply_prefix()
+
+        # The single persistent reply-mux subscription entry (wildcard
+        # `rpc.reply.<reply_prefix>.>`). Lives in _subscription_entries so
+        # suspend()/connect() restore it like any other subscription.
+        self._mux_entry: dict[str, Any] | None = None
+
+        # 503/no-responder handlers keyed by reply-subject suffix (the part
+        # after `rpc.reply.`). Used by pull-iterator/stream paths whose
+        # per-message `reply` subject only ever carries no-responder statuses.
+        # One-shot: the mux dispatcher removes an entry when it fires
+        # (max_msgs=1 semantics).
+        self.status_handlers: dict[str, Callable[[Exception], None]] = {}
+
         self.pending_requests: dict[str, dict[str, Any]] = {}
         self.stream_handlers: dict[str, dict[str, Any]] = {}
         self.isolated_clients: list[RPCClient] = []
         self.pull_iterator_cleanups: dict[str, Callable[[], Coroutine[Any, Any, None]]] = {}
         self.callback_cleanups: dict[str, Callable[[], Coroutine[Any, Any, None]]] = {}
+        self._pull_iterator_settles: set[Callable[[], None]] = set()
 
         self._closed = False
         self._suspending = False
-        self._subscription_meta: list[dict[str, Any]] = []
 
         self.io_pool: ThreadPoolExecutor = get_executor()
 
@@ -190,6 +217,11 @@ class RPCClient(RPCClientProtocol):
 
         self.nc = await connect(**connect_opts)
 
+        # A client that was disconnect()ed is revivable by an explicit
+        # connect(). Without this reset, auto-connect in _call_once and the
+        # no-responder retry loop stay permanently disabled.
+        self._closed = False
+
         # Initialize service
         self.service.init(self.nc)
 
@@ -199,27 +231,30 @@ class RPCClient(RPCClientProtocol):
         # Reserve 8KB for NATS protocol overhead and MsgPack envelope per message
         self._max_payload_size = self._max_payload_size - 8192
 
-        # Restore subscriptions after reconnect (used by suspend/connect cycle)
-        if self._subscription_meta:
-            metas = list(self._subscription_meta)
-            self._subscription_meta.clear()
-            for meta in metas:
-                await self.subscribe(meta["pattern"], meta["handler"], **(meta.get("options") or {}))
+        # Register the muxed reply inbox (idempotent). Registered as a normal
+        # subscription entry so the restore loop below (re-)subscribes it on
+        # first connect and after every suspend cycle alike.
+        self._register_mux_entry()
+
+        # Restore subscriptions after reconnect (from suspend). Entries keep
+        # their identity so unsubscribe closures held by callers stay valid
+        # across the restore.
+        for entry in list(self._subscription_entries.values()):
+            sub = entry.get("sub")
+            if sub is None or getattr(sub, "_closed", False):
+                await self._nats_subscribe(entry)
 
         return self.nc
 
     async def disconnect(self) -> None:
         """Disconnect from NATS server."""
         self._closed = True
-        self._subscription_meta.clear()
 
-        # Cleanup pending requests
-        for pending in self.pending_requests.values():
-            if timeout_handle := pending.get("timeout"):
-                timeout_handle.cancel()
-            if reject := pending.get("reject"):
-                reject(create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed"))
-        self.pending_requests.clear()
+        # Cleanup pending requests. RPC calls are muxed (no per-call
+        # subscription); service-path calls still hold a per-call reply entry
+        # which the cleanup hook drops.
+        await self._cleanup_pending_requests()
+        self.status_handlers.clear()
 
         # Cleanup stream handlers
         for handler in self.stream_handlers.values():
@@ -230,6 +265,8 @@ class RPCClient(RPCClientProtocol):
                 pass
         self.stream_handlers.clear()
 
+        self._settle_pull_iterators()
+
         # Cleanup pull iterators
         await asyncio.gather(
             *[cleanup() for cleanup in self.pull_iterator_cleanups.values()], return_exceptions=True
@@ -243,11 +280,14 @@ class RPCClient(RPCClientProtocol):
         self.callback_cleanups.clear()
 
         # Unsubscribe all subscriptions
-        for subs in self.subscriptions.values():
-            for sub in subs:
+        for entry in list(self._subscription_entries.values()):
+            if sub := entry.get("sub"):
                 with contextlib.suppress(Exception):
                     await sub.unsubscribe()
-        self.subscriptions.clear()
+            entry["sub"] = None
+        self._subscription_entries.clear()
+        # Entries were dropped — a revive-connect() must re-register the mux.
+        self._mux_entry = None
 
         # Clear chunking manager
         self.chunking_manager = ChunkingManager()
@@ -261,6 +301,7 @@ class RPCClient(RPCClientProtocol):
                 *[client.disconnect() for client in self.isolated_clients],
                 return_exceptions=True,
             )
+            self.isolated_clients.clear()
 
         # Close connection with timeout
         if self.nc:
@@ -271,9 +312,10 @@ class RPCClient(RPCClientProtocol):
 
     async def suspend(self) -> None:
         """Suspend the connection without marking as closed, preserving subscription metadata for reconnect."""
-        # Block on_finish-driven unsubscribe from clearing _subscription_meta
-        # while we tear the transport down — the task ending here is not a user-
-        # initiated unsubscribe.
+        # Block on_finish-driven cleanup from dropping subscription entries
+        # while we tear the transport down — the msg tasks ending here are not
+        # user-initiated unsubscribes; connect() must be able to restore the
+        # entries.
         self._suspending = True
         try:
             await self._do_suspend()
@@ -281,13 +323,12 @@ class RPCClient(RPCClientProtocol):
             self._suspending = False
 
     async def _do_suspend(self) -> None:
-        # Cleanup pending requests
-        for pending in self.pending_requests.values():
-            if timeout_handle := pending.get("timeout"):
-                timeout_handle.cancel()
-            if reject := pending.get("reject"):
-                reject(create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed"))
-        self.pending_requests.clear()
+        # Cleanup pending requests. RPC calls are muxed (no per-call
+        # subscription); service-path calls still hold a per-call reply entry
+        # which the cleanup hook drops — otherwise a suspended in-flight call
+        # would be restored as a dead reply subscription on the next connect().
+        await self._cleanup_pending_requests()
+        self.status_handlers.clear()
 
         # Cleanup stream handlers
         for handler in self.stream_handlers.values():
@@ -298,6 +339,8 @@ class RPCClient(RPCClientProtocol):
                 pass
         self.stream_handlers.clear()
 
+        self._settle_pull_iterators()
+
         # Cleanup pull iterators
         await asyncio.gather(
             *[cleanup() for cleanup in self.pull_iterator_cleanups.values()], return_exceptions=True
@@ -310,12 +353,13 @@ class RPCClient(RPCClientProtocol):
         )
         self.callback_cleanups.clear()
 
-        # Unsubscribe all subscriptions
-        for subs in self.subscriptions.values():
-            for sub in subs:
+        # Unsubscribe all subscriptions but keep the entries — connect()
+        # restores them on the fresh transport.
+        for entry in list(self._subscription_entries.values()):
+            if sub := entry.get("sub"):
                 with contextlib.suppress(Exception):
                     await sub.unsubscribe()
-        self.subscriptions.clear()
+            entry["sub"] = None
 
         # Clear chunking manager
         self.chunking_manager = ChunkingManager()
@@ -334,6 +378,35 @@ class RPCClient(RPCClientProtocol):
                 await asyncio.wait_for(self.nc.close(), timeout=timeout)
             self.nc = None
 
+    async def _cleanup_pending_requests(self) -> None:
+        """Settle and tear down all in-flight call() requests.
+
+        Runs on disconnect/suspend: cancels the timeout, invokes the per-call
+        cleanup hook (which removes the reply/inbox subscriptions and their
+        entries) and rejects the awaiting caller.
+        """
+        for pending in list(self.pending_requests.values()):
+            if timeout_handle := pending.get("timeout"):
+                timeout_handle.cancel()
+            if cleanup := pending.get("cleanup"):
+                with contextlib.suppress(Exception):
+                    await cleanup()
+            future = pending.get("future")
+            if future is not None and not future.done():
+                future.set_exception(create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed"))
+        self.pending_requests.clear()
+
+    def _settle_pull_iterators(self) -> None:
+        """Force-settle every client-side pull iterator parked in a queue.get().
+
+        Runs on disconnect/suspend so consumers' `async for` loops terminate
+        with a connection error instead of hanging forever.
+        """
+        for settle in list(self._pull_iterator_settles):
+            with contextlib.suppress(Exception):
+                settle()
+        self._pull_iterator_settles.clear()
+
     def reconfigure(
         self,
         servers: list[str] | None = None,
@@ -396,7 +469,7 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        encoded = encode(data)
+        encoded = encode_message(data)
 
         replyTo = reply if reply else ""
 
@@ -446,6 +519,72 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
+        self._subscription_seq += 1
+        key = self._subscription_seq
+        entry: dict[str, Any] = {
+            "key": key,
+            "pattern": pattern,
+            "handler": handler,
+            # Determined once here instead of per delivered message.
+            "handler_is_async": is_async_function(handler),
+            "queue": queue,
+            "sub": None,
+        }
+        self._subscription_entries[key] = entry
+
+        await self._nats_subscribe(entry)
+
+        async def unsubscribe() -> None:
+            # Drop bookkeeping first — the NATS-level unsubscribe below may be
+            # interrupted when it tears down the very message task calling us.
+            self._subscription_entries.pop(key, None)
+            sub: Subscription | None = entry.get("sub")
+            entry["sub"] = None
+            if sub is not None:
+                with contextlib.suppress(Exception):
+                    await sub.unsubscribe()
+
+        return unsubscribe
+
+    async def _nats_subscribe(self, entry: dict[str, Any]) -> None:
+        """Create the NATS subscription for an entry.
+
+        Called from subscribe() and again from connect() when restoring
+        entries after a suspend cycle.
+        """
+        if not self.nc:
+            raise RuntimeError("Not connected")
+
+        pattern: str = entry["pattern"]
+        handler: Callable[[Any], None] | Callable[[Any], Coroutine[Any, Any, None]] = entry["handler"]
+        handler_is_async: bool = entry["handler_is_async"]
+
+        # Raw mode (muxed reply inbox): hand the undecoded Msg to the handler —
+        # it needs headers (503 status, chunk markers) and the subject, and
+        # does its own chunk reassembly and routing. The handler is
+        # synchronous; route inline, no task per message.
+        if entry.get("raw"):
+            raw_handler = cast(Callable[[Msg], None], handler)
+
+            async def raw_message_handler(msg: Msg) -> None:
+                try:
+                    raw_handler(msg)
+                except Exception as e:
+                    print(f"Error processing message for {pattern}:", e)
+                    print(traceback.format_exc())
+
+            raw_sub = await self.nc.subscribe(pattern, queue=entry.get("queue") or "", cb=raw_message_handler)
+            entry["sub"] = raw_sub
+            self._watch_subscription_end(entry, raw_sub)
+            return
+
+        # Payloads assembled from chunks are queued here and drained inline in
+        # the message handler below, so they run inside the same sequential
+        # per-subscription message flow as regular messages. Dispatching them
+        # eagerly (create_task) would run handlers concurrently and out of
+        # order, breaking backpressure-sensitive callers.
+        assembled_queue: list[Any] = []
+
         async def message_handler(msg: Msg) -> None:
             try:
                 chunk_type = msg.headers.get("x-chunked-transfer") if msg.headers else None
@@ -459,7 +598,7 @@ class RPCClient(RPCClientProtocol):
                         return
 
                     def on_complete(assembled_data: Any) -> None:
-                        asyncio.create_task(self._handle_assembled_data(handler, assembled_data))
+                        assembled_queue.append(assembled_data)
 
                     def on_error(error: Exception) -> None:
                         print(f"Error assembling chunks for {pattern}: {error}")
@@ -490,70 +629,212 @@ class RPCClient(RPCClientProtocol):
                         {"id": chunk_id, "chunkIndex": chunk_index, "data": msg.data, "isLast": False}
                     )
 
+                    # Drain any transfer completed by this chunk inline (see
+                    # assembled_queue above).
+                    while assembled_queue:
+                        await self._handle_assembled_data(handler, assembled_queue.pop(0), handler_is_async)
+
                 else:
-                    # Regular message - decode MessagePack data
-                    data = decode(msg.data)
-                    if is_async_function(handler):
+                    # Regular message - decode wire message (zero-copy
+                    # memoryview slices into msg.data for out-of-band
+                    # binaries; nats-py delivers one bytes object per
+                    # message, so the views are safe). Sync handlers run
+                    # inline on the event loop — the thread-pool hop costs
+                    # far more than the short callbacks used in this system.
+                    data = decode_message(msg.data)
+                    if handler_is_async:
                         await handler(data)  # type: ignore[misc]
                     else:
-                        loop = asyncio.get_event_loop()
-                        await loop.run_in_executor(self.io_pool, handler, data)
+                        handler(data)
 
             except Exception as e:
                 print(f"Error processing message for {pattern}:", e)
                 print(traceback.format_exc())
 
-        sub = await self.nc.subscribe(pattern, queue=queue, cb=message_handler)
-
-        # Ensure the subscription is ready
+        sub = await self.nc.subscribe(pattern, queue=entry.get("queue") or "", cb=message_handler)
+        # Yield once so nats-py's flusher pushes the SUB to the server before
+        # we return. Publishes from OTHER connections have no ordering
+        # guarantee against our pending SUB — without this yield a
+        # subscribe-then-peer-publishes pattern loses messages intermittently
+        # (reproduced via channel-native-request).
         await asyncio.sleep(0)
 
-        if pattern not in self.subscriptions:
-            self.subscriptions[pattern] = []
-        self.subscriptions[pattern].append(sub)
-
-        # Store subscription metadata for suspend/reconnect
-        options: dict[str, Any] = {}
-        if queue:
-            options["queue"] = queue
-        meta = {"pattern": pattern, "handler": handler, "options": options}
-        self._subscription_meta.append(meta)
+        entry["sub"] = sub
+        self._watch_subscription_end(entry, sub)
 
-        async def unsubscribe() -> None:
-            with contextlib.suppress(Exception):
-                await sub.unsubscribe()
+    def _watch_subscription_end(self, entry: dict[str, Any], sub: Subscription) -> None:
+        """Drop the entry when its msg task ends cleanly (user unsubscribe)."""
 
-            if pattern in self.subscriptions:
-                self.subscriptions[pattern] = [s for s in self.subscriptions[pattern] if s != sub]
-                if not self.subscriptions[pattern]:
-                    del self.subscriptions[pattern]
+        def on_finish(fut: asyncio.Task[None]) -> None:
+            # Mirrors the previous watcher-task semantics: only a clean end of
+            # the msg task drops the entry (cancellation/errors leave it be).
+            if fut.cancelled() or fut.exception() is not None:
+                return
+            # The msg task also ends during suspend teardown and when the
+            # entry has already been restored onto a new subscription — in
+            # both cases the entry must survive so connect() can restore
+            # it (or keep the restored one alive).
+            if self._suspending or entry.get("sub") is not sub:
+                return
+            entry["sub"] = None
+            self._subscription_entries.pop(entry["key"], None)
+            if entry is self._mux_entry:
+                self._mux_entry = None
 
-            # During suspend the NATS msg-task ends as a side-effect of the
-            # transport teardown — we want to keep _subscription_meta so that
-            # the next connect() can restore subscriptions.
-            if not self._suspending:
-                self._subscription_meta = [m for m in self._subscription_meta if m["pattern"] != pattern]
+            async def unsub() -> None:
+                with contextlib.suppress(Exception):
+                    await sub.unsubscribe()
 
-        async def on_finish(fut: asyncio.Task[None]) -> None:
-            with contextlib.suppress(Exception):
-                await asyncio.wait_for(fut, None)
-                await unsubscribe()
+            asyncio.create_task(unsub())
 
         msg_task: asyncio.Task[None] | None = getattr(sub, "_wait_for_msgs_task", None)
         if msg_task:
-            asyncio.create_task(on_finish(msg_task))
+            msg_task.add_done_callback(on_finish)
 
-        return unsubscribe
+    def _register_mux_entry(self) -> dict[str, Any]:
+        """Register (idempotently) the muxed reply inbox subscription entry.
 
-    async def _handle_assembled_data(self, handler: Callable[[Any], Any], data: Any) -> None:
+        The entry lives in _subscription_entries so connect()'s restore loop
+        (re-)subscribes it on first connect and after suspend cycles alike.
+        """
+        if self._mux_entry is None:
+            self._subscription_seq += 1
+            entry: dict[str, Any] = {
+                "key": self._subscription_seq,
+                "pattern": f"rpc.reply.{self._reply_prefix}.>",
+                "handler": self._handle_mux_message,
+                "handler_is_async": False,
+                "queue": "",
+                "sub": None,
+                "raw": True,
+            }
+            self._mux_entry = entry
+            self._subscription_entries[self._subscription_seq] = entry
+        return self._mux_entry
+
+    async def _ensure_mux_subscription(self) -> None:
+        """Ensure the single persistent reply-mux wildcard subscription exists.
+
+        Normally established by connect(); covers clients whose connection was
+        wired up out-of-band (tests). No-op when already subscribed.
+        """
+        entry = self._register_mux_entry()
+        sub: Subscription | None = entry.get("sub")
+        if self.nc and (sub is None or getattr(sub, "_closed", False)):
+            await self._nats_subscribe(entry)
+
+    def _handle_mux_message(self, msg: Msg) -> None:
+        """Dispatcher for the muxed reply inbox. Routes by message kind.
+
+        - 503/no-responder status (empty payload + status header 503): the
+          call/iterator is identified by the SUBJECT (`rpc.reply.<suffix>`) —
+          the server echoes the request's reply subject, there is no payload.
+        - chunked transfer header/chunk: reassemble via chunking_manager, then
+          route the assembled response by envelope id.
+        - regular response: decode and route by envelope id.
+        """
+        data = msg.data
+        headers = msg.headers
+
+        # No-responder status. Wire detail: the reply subject of an RPC call
+        # is exactly `rpc.reply.<call id>`, so the suffix IS the call id. For
+        # iterator/stream status inboxes the suffix is the registered token.
+        if (
+            (data is None or len(data) == 0)
+            and headers
+            and headers.get(Header.STATUS) == NO_RESPONDERS_STATUS
+        ):  # pyright: ignore[reportUnnecessaryComparison]
+            suffix = msg.subject[len("rpc.reply.") :]
+
+            # One-shot (mirrors the previous per-iterator max_msgs=1 inboxes).
+            status_handler = self.status_handlers.pop(suffix, None)
+            if status_handler is not None:
+                try:
+                    status_handler(errors.NoRespondersError(suffix))
+                except Exception as e:
+                    print(f"Error in no-responder status handler: {e}")
+                return
+
+            pending = self.pending_requests.pop(suffix, None)
+            if pending is not None:
+                if timeout_handle := pending.get("timeout"):
+                    timeout_handle.cancel()
+                future: asyncio.Future[Any] | None = pending.get("future")
+                if future is not None and not future.done():
+                    future.set_exception(errors.NoRespondersError(pending.get("subject") or suffix))
+            return
+
+        chunk_type = headers.get("x-chunked-transfer") if headers else None
+
+        if chunk_type == "header":
+            decoded = decode(data)
+            chunk_id = headers.get("x-chunk-id") if headers else None
+            if not chunk_id or decoded.get("transferId") != chunk_id:
+                print("Invalid chunk header on reply mux")
+                return
+            self.chunking_manager.start_receiving(
+                decoded["transferId"],
+                decoded["totalChunks"],
+                self._route_mux_response,
+                lambda error: print(f"Error assembling chunked RPC response: {error}"),
+                decoded.get("totalSize"),
+                decoded.get("chunkSize"),
+            )
+        elif chunk_type == "chunk":
+            chunk_id = headers.get("x-chunk-id") if headers else None
+            if not chunk_id:
+                print("Chunk missing chunk ID on reply mux")
+                return
+            chunk_index = int(headers.get("x-chunk-index", "0")) if headers else 0
+            self.chunking_manager.process_chunk(
+                {"id": chunk_id, "chunkIndex": chunk_index, "data": data, "isLast": False}
+            )
+        else:
+            self._route_mux_response(decode_message(data))
+
+    def _route_mux_response(self, data: Any) -> None:
+        """Settle the pending request a (possibly reassembled) response belongs to.
+
+        Unknown ids are dropped silently — late replies after a timeout, or
+        traffic of another client sharing the same conn_id prefix.
+        """
+        if not isinstance(data, dict):
+            return
+        response = cast(dict[str, Any], data)
+        request_id = response.get("id")
+        if not request_id:
+            return
+
+        pending = self.pending_requests.pop(request_id, None)
+        if pending is None:
+            return
+        if timeout_handle := pending.get("timeout"):
+            timeout_handle.cancel()
+
+        future: asyncio.Future[Any] | None = pending.get("future")
+        if future is None or future.done():
+            return
+
+        if "error" in response:
+            future.set_exception(RPCException.from_dict(response["error"]))
+        else:
+            result = response.get("result")
+            # Attach __methods to result for proxy method discovery
+            if "__methods" in response and result is not None and isinstance(result, dict):
+                result["__methods"] = response["__methods"]
+            future.set_result(result)
+
+    async def _handle_assembled_data(
+        self, handler: Callable[[Any], Any], data: Any, handler_is_async: bool | None = None
+    ) -> None:
         """Handle assembled data from chunks."""
+        if handler_is_async is None:
+            handler_is_async = is_async_function(handler)
         try:
-            if is_async_function(handler):
+            if handler_is_async:
                 await handler(data)  # pyright: ignore[reportGeneralTypeIssues]
             else:
-                # Run sync handlers in thread pool to avoid blocking
-                loop = asyncio.get_event_loop()
-                await loop.run_in_executor(self.io_pool, handler, data)
+                handler(data)
         except Exception as e:
             print(f"Error in handler: {e}")
 
@@ -583,7 +864,7 @@ class RPCClient(RPCClientProtocol):
             raise RuntimeError("Not connected")
 
         timeout_sec = (timeout or 5000) / 1000  # Convert to seconds
-        encoded = encode(data)
+        encoded = encode_message(data)
 
         try:
             msg = await self.nc.request(subject, encoded, timeout=timeout_sec, headers=headers)
@@ -596,10 +877,10 @@ class RPCClient(RPCClientProtocol):
                 error_data = None
                 if msg.data:
                     with contextlib.suppress(Exception):
-                        error_data = decode(msg.data)
+                        error_data = decode_message(msg.data)
                 raise create_error(error_code, error_msg, error_data)
 
-            decoded = decode(msg.data)
+            decoded = decode_message(msg.data)
 
             # Check if response contains an error field (for request handlers)
             if isinstance(decoded, dict) and "error" in decoded:
@@ -622,18 +903,23 @@ class RPCClient(RPCClientProtocol):
         subject: str,
         *args: Any,
         no_responder_retry: NoResponderRetryOptions | None = None,
+        discover: bool = False,
     ) -> Any:
         """Make an RPC call with no-responder retry.
 
         ``no_responder_retry`` overrides the client-wide retry config for this
         single call.
+
+        ``discover`` puts ``__discover: True`` on the request envelope, asking
+        the responder to attach its ``__methods`` list to the response.
+        Proxies request this only while their method cache is empty.
         """
         return await self._with_no_responder_retry(
-            lambda: self._call_once(subject, *args),
+            lambda: self._call_once(subject, *args, discover=discover),
             override=no_responder_retry,
         )
 
-    async def _call_once(self, subject: str, *args: Any) -> Any:
+    async def _call_once(self, subject: str, *args: Any, discover: bool = False) -> Any:
         """Make a single RPC call without retry."""
         if not self.is_connected and not self.is_closed:
             await self.connect()
@@ -641,29 +927,79 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        request_id = generate_id()
+        # Service calls (`<subject>.reply.<id>`) keep the legacy per-call
+        # subscription flow — separate refactor later.
+        if not subject.startswith("rpc."):
+            return await self._call_once_service(subject, *args)
+
+        # Normally established by connect(); covers clients whose connection
+        # was wired up out-of-band (tests). No-op when already subscribed.
+        await self._ensure_mux_subscription()
+
+        request_id = generate_id(self._reply_prefix)
         timeout = self.options.get("timeout", 30000)
-        # Use different reply patterns for RPC vs service calls
-        reply_subject = (
-            f"rpc.reply.{request_id}" if subject.startswith("rpc.") else f"{subject}.reply.{request_id}"
-        )
+        # The reply subject is derived from the id by pure string
+        # concatenation — this is the wire contract with every responder
+        # implementation (Node, Go, Python): they publish the response to
+        # `rpc.reply.<msg id>` and treat the id as opaque. Because the id
+        # starts with our reply prefix, the muxed reply inbox
+        # (`rpc.reply.<reply_prefix>.>`) catches it.
+        reply_subject = f"rpc.reply.{request_id}"
 
-        # Create future for the response
         future: asyncio.Future[Any] = asyncio.Future()
 
-        # Setup timeout
+        # No per-call subscriptions: responses (plain or chunked) and
+        # no-responder statuses all arrive on the muxed reply inbox, which
+        # routes them back here via pending_requests. Cleanup only has to
+        # drop the map entry and the timer.
         def handle_timeout() -> None:
-            if request_id in self.pending_requests:
-                del self.pending_requests[request_id]
-                if not future.done():
-                    future.set_exception(
-                        errors.TimeoutError(f"RPC call to {subject!r} timed out after {timeout}ms")
-                    )
+            if self.pending_requests.pop(request_id, None) is not None and not future.done():
+                future.set_exception(
+                    errors.TimeoutError(f"RPC call to {subject!r} timed out after {timeout}ms")
+                )
 
         timeout_handle = asyncio.get_event_loop().call_later(timeout / 1000, handle_timeout)
 
-        # Store pending request
-        self.pending_requests[request_id] = {"future": future, "timeout": timeout_handle}
+        # `subject` feeds the NoRespondersError context when a 503 status
+        # arrives on the call's muxed reply subject. disconnect()/suspend()
+        # cancel the timer and settle the future via _cleanup_pending_requests.
+        self.pending_requests[request_id] = {
+            "future": future,
+            "timeout": timeout_handle,
+            "subject": subject,
+        }
+
+        # Send request. `reply` is set to the call's own reply subject so the
+        # NATS server delivers a no-responder 503 status to the SAME subject
+        # the real response would use — the mux catches both.
+        message: RPCMessage = {"id": request_id, "method": "call", "params": args}
+        if discover:
+            # Envelope marker (never in params — must not leak into handler
+            # args): ask the responder for its __methods list.
+            message["__discover"] = True
+        try:
+            await self.publish(subject, message, reply=reply_subject)
+        except Exception:
+            if self.pending_requests.pop(request_id, None) is not None:
+                timeout_handle.cancel()
+            raise
+
+        return await future
+
+    async def _call_once_service(self, subject: str, *args: Any) -> Any:
+        """Legacy single-attempt call for service subjects (reply pattern
+        `<subject>.reply.<id>`): per-call reply subscription + one-shot
+        no-responder inbox. The rpc.* path is muxed — see _call_once.
+        """
+        if not self.nc:
+            raise RuntimeError("Not connected")
+
+        request_id = generate_id(self._reply_prefix)
+        timeout = self.options.get("timeout", 30000)
+        reply_subject = f"{subject}.reply.{request_id}"
+
+        # Create future for the response
+        future: asyncio.Future[Any] = asyncio.Future()
 
         # Handle no responders
         sub: Subscription | None = None
@@ -681,6 +1017,27 @@ class RPCClient(RPCClientProtocol):
                 with contextlib.suppress(Exception):
                     await unsubscribe()
 
+        # Setup timeout. The subscriptions are torn down by the except-branch
+        # below once the future's exception propagates out of `await future`.
+        def handle_timeout() -> None:
+            if request_id in self.pending_requests:
+                del self.pending_requests[request_id]
+                if not future.done():
+                    future.set_exception(
+                        errors.TimeoutError(f"RPC call to {subject!r} timed out after {timeout}ms")
+                    )
+
+        timeout_handle = asyncio.get_event_loop().call_later(timeout / 1000, handle_timeout)
+
+        # Store pending request. disconnect()/suspend() invoke the cleanup
+        # hook so a suspended in-flight call doesn't leave its reply
+        # subscription behind (it would be restored as a dead subscription).
+        self.pending_requests[request_id] = {
+            "future": future,
+            "timeout": timeout_handle,
+            "cleanup": unsubscribe_all,
+        }
+
         # Subscribe to reply
         async def handle_rpc_response(data: Any) -> None:
             response = data  # assuming data is already parsed as RPCResponse
@@ -690,16 +1047,22 @@ class RPCClient(RPCClientProtocol):
                 if pending:
                     del self.pending_requests[response["id"]]
                     pending["timeout"].cancel()
-                    await unsubscribe_all()
 
+                    # Settle the caller BEFORE tearing down subscriptions:
+                    # unsubscribing the reply subscription cancels the message
+                    # task this handler runs in, which could abort us mid-way.
                     if "error" in response:
-                        pending["future"].set_exception(RPCException.from_dict(response["error"]))
+                        if not pending["future"].done():
+                            pending["future"].set_exception(RPCException.from_dict(response["error"]))
                     else:
                         result = response.get("result")
                         # Attach __methods to result for proxy method discovery
                         if "__methods" in response and result is not None and isinstance(result, dict):
                             result["__methods"] = response["__methods"]
-                        pending["future"].set_result(result)
+                        if not pending["future"].done():
+                            pending["future"].set_result(result)
+
+                    await unsubscribe_all()
 
         async def request_callback(msg: Msg) -> None:
             # Check for no responders status (empty message with 503 status)
@@ -803,7 +1166,9 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        request_id = generate_id()
+        await self._ensure_mux_subscription()
+
+        request_id = generate_id(self._reply_prefix)
         stream_subject = f"stream.{subject}.{request_id}"
 
         # Stream state
@@ -812,7 +1177,6 @@ class RPCClient(RPCClientProtocol):
         error: Exception | None = None
 
         # Initialize variables
-        sub: Subscription | None = None
         unsubscribe: Callable[[], Coroutine[Any, Any, None]] | None = None
 
         def on_push(value: Any) -> None:
@@ -846,9 +1210,7 @@ class RPCClient(RPCClientProtocol):
 
             if request_id in self.stream_handlers:
                 del self.stream_handlers[request_id]
-            if sub and not sub._closed:  # pyright: ignore[reportPrivateUsage]
-                with contextlib.suppress(Exception):
-                    await sub.unsubscribe()
+            self.status_handlers.pop(request_id, None)
             if unsubscribe:
                 with contextlib.suppress(Exception):
                     await unsubscribe()
@@ -879,22 +1241,17 @@ class RPCClient(RPCClientProtocol):
                 stream_handler["error"](RPCException.from_dict(error_data))
                 await unsubscribe_all()
 
-        async def request_callback(msg: Msg) -> None:
-            # Check for no responders status (empty message with 503 status)
-            if (
-                (msg.data is None or len(msg.data) == 0)  # pyright: ignore[reportUnnecessaryComparison]
-                and msg.headers
-                and msg.headers.get(Header.STATUS) == NO_RESPONDERS_STATUS
-            ):
-                stream_handler = self.stream_handlers.get(request_id)
-                if stream_handler:
-                    stream_handler["error"](errors.NoRespondersError(subject))
-                await unsubscribe_all()
-
         unsubscribe = await self.subscribe(stream_subject, handle_stream_message)
 
-        inbox = self.nc.new_inbox()
-        sub = await self.nc.subscribe(inbox, cb=request_callback, max_msgs=1)
+        # No-responder detection via the muxed reply inbox: the request's
+        # reply subject `rpc.reply.<id>` only ever carries a 503 status —
+        # stream responders never publish a direct RPC response.
+        def on_no_responders(_err: Exception) -> None:
+            stream_handler = self.stream_handlers.get(request_id)
+            if stream_handler:
+                stream_handler["error"](errors.NoRespondersError(subject))
+
+        self.status_handlers[request_id] = on_no_responders
 
         try:
             # Send request
@@ -904,7 +1261,7 @@ class RPCClient(RPCClientProtocol):
                 "args": args,
             }
             message: RPCMessage = {"id": request_id, "method": "stream", "params": stream_params}
-            await self.publish(subject, message, reply=inbox)
+            await self.publish(subject, message, reply=f"rpc.reply.{request_id}")
 
             # Generator implementation
             while True:
@@ -938,25 +1295,60 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        iterator_id = generate_id()
+        await self._ensure_mux_subscription()
+
+        iterator_id = generate_id(self._reply_prefix)
         request_subject = f"_rpc.iterator.{iterator_id}.request"
         response_subject = f"_rpc.iterator.{iterator_id}.response"
+        # 503 status inbox for `next` requests, served by the muxed reply
+        # inbox: iterator_id starts with the reply prefix, so this subject
+        # falls under the mux wildcard. Real iterator responses keep arriving
+        # on response_subject — only no-responder statuses land here.
+        status_inbox = f"rpc.reply.{iterator_id}"
+
+        response_queue: asyncio.Queue[PullIteratorResponse] = asyncio.Queue()
+        ended = False
+        error: Exception | None = None
+
+        # Registered with the client for the iterator's lifetime: a consumer
+        # parked in `await response_queue.get()` must be force-settled when
+        # the connection tears down (disconnect/suspend), or its `async for`
+        # hangs forever.
+        def settle_on_disconnect() -> None:
+            nonlocal ended, error
+            if not ended:
+                ended = True
+                error = create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed")
+            err = (
+                error
+                if isinstance(error, RPCException)
+                else create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed")
+            )
+            settle_msg: PullIteratorResponse = {
+                "type": "error",
+                "id": iterator_id,
+                "error": err.to_dict(),
+            }
+            response_queue.put_nowait(settle_msg)
+
+        self._pull_iterator_settles.add(settle_on_disconnect)
 
         # Initialize the pull iterator using regular call method
         # We pass a special __pullIterator marker as the first argument
-        init_response = await self.call(
-            subject, {"__pullIterator": True, "__iteratorId": iterator_id, "args": args}
-        )
+        try:
+            init_response = await self.call(
+                subject, {"__pullIterator": True, "__iteratorId": iterator_id, "args": args}
+            )
+        except Exception:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
+            raise
 
         # The response should contain the iterator ID (same as we sent)
         if not init_response or init_response.get("iteratorId") != iterator_id:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
             raise RuntimeError("Failed to initialize pull iterator")
 
         # Subscribe to responses
-        response_queue: asyncio.Queue[PullIteratorResponse] = asyncio.Queue()
-        ended = False
-        error: Exception | None = None
-
         async def handle_response(msg: PullIteratorResponse) -> None:
             nonlocal ended, error
 
@@ -972,13 +1364,12 @@ class RPCClient(RPCClientProtocol):
         unsubscribe = await self.subscribe(response_subject, handle_response)
 
         async def cleanup() -> None:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
+            self.status_handlers.pop(iterator_id, None)
+
             if unsubscribe is not None:
                 await unsubscribe()
 
-            if sub and not sub._closed:  # pyright: ignore[reportPrivateUsage]
-                with contextlib.suppress(Exception):
-                    await sub.unsubscribe()
-
             # Send cancel request
             if not ended:
                 with contextlib.suppress(Exception):
@@ -988,37 +1379,33 @@ class RPCClient(RPCClientProtocol):
                     }
                     await self.publish(request_subject, cancel_request)
 
-        async def request_callback(msg2: Msg) -> None:
+        def on_no_responders(_err: Exception) -> None:
             nonlocal ended, error
 
-            # Check for no responders status (empty message with 503 status)
-            if (
-                (msg2.data is None or len(msg2.data) == 0)  # pyright: ignore[reportUnnecessaryComparison]
-                and msg2.headers
-                and msg2.headers.get(Header.STATUS) == NO_RESPONDERS_STATUS
-            ):
-                ended = True
-                error = create_error("503", str(errors.NoRespondersError(subject)))
-
-                msg: PullIteratorResponse = {
-                    "type": "error",
-                    "id": iterator_id,
-                    "error": error.to_dict(),
-                }
-
-                await response_queue.put(msg)
+            ended = True
+            error = create_error("503", str(errors.NoRespondersError(subject)))
+            status_msg: PullIteratorResponse = {
+                "type": "error",
+                "id": iterator_id,
+                "error": error.to_dict(),
+            }
+            response_queue.put_nowait(status_msg)
 
-        inbox = self.nc.new_inbox()
-        sub = await self.nc.subscribe(inbox, cb=request_callback, max_msgs=1)
+        self.status_handlers[iterator_id] = on_no_responders
 
         try:
+            # Every `next` carries the no-responder status inbox: the
+            # registered status handler stays live until a 503 actually
+            # arrives, so this is the liveness signal when the responder dies
+            # MID-iteration (its subscription vanishes -> NATS 503s the reply
+            # subject, which the mux routes here).
             while True:
                 # Send next request
                 next_request: PullIteratorRequest = {
                     "id": iterator_id,
                     "type": "next",
                 }
-                await self.publish(request_subject, next_request, reply=inbox)
+                await self.publish(request_subject, next_request, reply=status_inbox)
 
                 # Wait for response
                 response = await response_queue.get()
@@ -1057,47 +1444,83 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        iterator_id = generate_id()
+        await self._ensure_mux_subscription()
+
+        iterator_id = generate_id(self._reply_prefix)
         request_subject = f"_rpc.iterator.{iterator_id}.request"
         response_subject = f"_rpc.iterator.{iterator_id}.response"
         callback_subject = f"_rpc.cb.{iterator_id}"
+        # 503 status inbox for `next` requests — see call_pull_iterator.
+        status_inbox = f"rpc.reply.{iterator_id}"
 
         callback_methods = list(callbacks.keys())
 
-        # Track a task-chain of pending callback handlers. The iterator loop
-        # awaits this chain before yielding, so a slow handler blocks the
+        # A single long-lived consumer task drains callback messages from a
+        # queue in order (no task per message). The iterator loop waits for
+        # the queue to drain before yielding, so a slow handler blocks the
         # next `next()` request — which stalls the server at its own yield.
         # This is what gives true end-to-end backpressure.
-        callback_task: asyncio.Task[None] | None = None
+        callback_is_async = {name: is_async_function(fn) for name, fn in callbacks.items()}
+        cb_queue: asyncio.Queue[tuple[Callable[..., Any], list[Any], str, bool]] = asyncio.Queue()
+
+        async def consume_callbacks() -> None:
+            while True:
+                fn, fn_args, method, fn_is_async = await cb_queue.get()
+                try:
+                    if fn_is_async:
+                        await fn(*fn_args)
+                    else:
+                        fn(*fn_args)
+                except Exception as e:
+                    print(f"[rpc] Pull-callback handler '{method}' threw: {e}")
+                finally:
+                    cb_queue.task_done()
+
+        consumer_task = asyncio.create_task(consume_callbacks())
+
+        async def stop_consumer() -> None:
+            consumer_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await consumer_task
 
         # Subscribe to callback channel BEFORE init call.
         async def handle_cb_msg(msg: Any) -> None:
-            nonlocal callback_task
             if not isinstance(msg, dict):
                 return
             method = msg.get("method")
-            fn = callbacks.get(method) if method else None
+            if not isinstance(method, str):
+                return
+            fn = callbacks.get(method)
             if fn is None:
                 return
-            fn_args = msg.get("args") or []
+            cb_queue.put_nowait((fn, msg.get("args") or [], method, callback_is_async[method]))
 
-            prev = callback_task
+        cb_unsub = await self.subscribe(callback_subject, handle_cb_msg)
 
-            async def run_chained() -> None:
-                if prev is not None:
-                    with contextlib.suppress(Exception):
-                        await prev
-                try:
-                    if is_async_function(fn):
-                        await fn(*fn_args)
-                    else:
-                        fn(*fn_args)
-                except Exception as e:
-                    print(f"[rpc] Pull-callback handler '{method}' threw: {e}")
+        response_queue: asyncio.Queue[PullIteratorResponse] = asyncio.Queue()
+        ended = False
+        error: Exception | None = None
 
-            callback_task = asyncio.create_task(run_chained())
+        # See call_pull_iterator: force-settle a parked queue.get() on
+        # connection teardown so the consumer's `async for` terminates.
+        def settle_on_disconnect() -> None:
+            nonlocal ended, error
+            if not ended:
+                ended = True
+                error = create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed")
+            err = (
+                error
+                if isinstance(error, RPCException)
+                else create_error(ErrorCode.CONNECTION_CLOSED, "Connection closed")
+            )
+            settle_msg: PullIteratorResponse = {
+                "type": "error",
+                "id": iterator_id,
+                "error": err.to_dict(),
+            }
+            response_queue.put_nowait(settle_msg)
 
-        cb_unsub = await self.subscribe(callback_subject, handle_cb_msg)
+        self._pull_iterator_settles.add(settle_on_disconnect)
 
         # Init the pull-callback session via regular RPC call.
         init_params: PullCallbackParams = {
@@ -1112,17 +1535,17 @@ class RPCClient(RPCClientProtocol):
         try:
             init_response = await self.call(subject, init_params)
         except Exception:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
             await cb_unsub()
+            await stop_consumer()
             raise
 
         if not init_response or init_response.get("iteratorId") != iterator_id:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
             await cb_unsub()
+            await stop_consumer()
             raise RuntimeError("Failed to initialize pull-callback iterator")
 
-        response_queue: asyncio.Queue[PullIteratorResponse] = asyncio.Queue()
-        ended = False
-        error: Exception | None = None
-
         async def handle_response(msg: PullIteratorResponse) -> None:
             nonlocal ended, error
             if msg.get("type") == "error":
@@ -1135,32 +1558,27 @@ class RPCClient(RPCClientProtocol):
 
         resp_unsub = await self.subscribe(response_subject, handle_response)
 
-        async def request_callback(msg2: Msg) -> None:
+        def on_no_responders(_err: Exception) -> None:
             nonlocal ended, error
-            if (
-                (msg2.data is None or len(msg2.data) == 0)  # pyright: ignore[reportUnnecessaryComparison]
-                and msg2.headers
-                and msg2.headers.get(Header.STATUS) == NO_RESPONDERS_STATUS
-            ):
-                ended = True
-                error = create_error("503", str(errors.NoRespondersError(subject)))
-                msg: PullIteratorResponse = {
-                    "type": "error",
-                    "id": iterator_id,
-                    "error": error.to_dict(),
-                }
-                await response_queue.put(msg)
 
-        inbox = self.nc.new_inbox()
-        sub = await self.nc.subscribe(inbox, cb=request_callback, max_msgs=1)
+            ended = True
+            error = create_error("503", str(errors.NoRespondersError(subject)))
+            status_msg: PullIteratorResponse = {
+                "type": "error",
+                "id": iterator_id,
+                "error": error.to_dict(),
+            }
+            response_queue.put_nowait(status_msg)
+
+        self.status_handlers[iterator_id] = on_no_responders
 
         async def cleanup() -> None:
+            self._pull_iterator_settles.discard(settle_on_disconnect)
+            self.status_handlers.pop(iterator_id, None)
             await cb_unsub()
+            await stop_consumer()
             if resp_unsub is not None:
                 await resp_unsub()
-            if sub and not sub._closed:  # pyright: ignore[reportPrivateUsage]
-                with contextlib.suppress(Exception):
-                    await sub.unsubscribe()
             if not ended:
                 with contextlib.suppress(Exception):
                     cancel_request: PullIteratorRequest = {
@@ -1170,12 +1588,14 @@ class RPCClient(RPCClientProtocol):
                     await self.publish(request_subject, cancel_request)
 
         try:
+            # See call_pull_iterator: every `next` carries the no-responder
+            # status inbox — it is the mid-iteration responder-death signal.
             while True:
                 next_request: PullIteratorRequest = {
                     "id": iterator_id,
                     "type": "next",
                 }
-                await self.publish(request_subject, next_request, reply=inbox)
+                await self.publish(request_subject, next_request, reply=status_inbox)
 
                 response = await response_queue.get()
 
@@ -1183,15 +1603,18 @@ class RPCClient(RPCClientProtocol):
                     if error_data := response.get("error"):
                         raise RPCException.from_dict(error_data)
                 elif response.get("type") == "done":
+                    # Drain trailing frames delivered before the done signal —
+                    # the old task-chain would have run them to completion too.
+                    await cb_queue.join()
                     break
                 elif response.get("type") == "value":
-                    # Wait for all callback handlers dispatched so far. If a
-                    # handler awaits a bounded queue (backpressure), this
-                    # stalls the iterator here until the handler releases,
-                    # which suspends the server at its own yield.
-                    if callback_task is not None:
-                        with contextlib.suppress(Exception):
-                            await callback_task
+                    # Wait until every callback message received so far has
+                    # been processed (batch boundary only after all frames of
+                    # the batch). If a handler awaits a bounded queue
+                    # (backpressure), this stalls the iterator here until the
+                    # handler releases, which suspends the server at its own
+                    # yield.
+                    await cb_queue.join()
                     yield None
         finally:
             await cleanup()
@@ -1225,15 +1648,16 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
-        request_id = generate_id()
+        request_id = generate_id(self._reply_prefix)
         callback_subject = f"rpc.cb.{request_id}"
+        callback_is_async = is_async_function(callback)
 
         # Subscribe to callback messages
         async def handle_callback_msg(msg: Any) -> None:
             if isinstance(msg, dict):
                 if msg.get("type") == "data":
                     try:
-                        if is_async_function(callback):
+                        if callback_is_async:
                             await callback(msg.get("data"))
                         else:
                             callback(msg.get("data"))
@@ -1292,6 +1716,7 @@ class RPCClient(RPCClientProtocol):
 
         unsubscribers: list[Callable[[], Coroutine[Any, Any, None]]] = []
         pull_iterator_ids: list[str] = []
+        callback_ids: list[str] = []
 
         # Extract methods based on option
         handlers_map = (
@@ -1303,12 +1728,26 @@ class RPCClient(RPCClientProtocol):
 
         for method, handler in handlers_map.items():
             subject = f"rpc.{namespace}.{method}"
+            # Determined once per handler instead of per message.
+            handler_is_async = is_async_function(handler)
 
             async def handle_message(
-                msg: Any, handler: Any = handler, method_names: list[str] = method_names
+                msg: Any,
+                handler: Any = handler,
+                method_names: list[str] = method_names,
+                handler_is_async: bool = handler_is_async,
             ) -> None:
                 message = msg
-                response: RPCResponse = {"id": message["id"], "__methods": method_names}
+                response: RPCResponse = {"id": message["id"]}
+
+                # Method discovery on demand: only a request whose envelope
+                # carries __discover (a proxy with an empty method cache) pays
+                # for the namespace's method list — attaching it to every
+                # response would be dead wire weight once the proxy cache is
+                # filled. Old clients never send __discover and never read
+                # __methods on this path.
+                if isinstance(message, dict) and message.get("__discover") is True:
+                    response["__methods"] = method_names
 
                 try:
                     # Handle stream request
@@ -1384,6 +1823,7 @@ class RPCClient(RPCClientProtocol):
                             iterator_id,
                             client,
                             client.io_pool,
+                            on_finished=partial(client.pull_iterator_cleanups.pop, iterator_id, None),
                         )
 
                         # Store cleanup function for later
@@ -1409,6 +1849,7 @@ class RPCClient(RPCClientProtocol):
                             pc_oneway_methods,
                             client,
                             client.io_pool,
+                            on_finished=partial(client.pull_iterator_cleanups.pop, pc_iterator_id, None),
                         )
 
                         client.pull_iterator_cleanups[pc_iterator_id] = pc_cleanup
@@ -1442,8 +1883,10 @@ class RPCClient(RPCClientProtocol):
                             message["id"],
                             client,
                             client.io_pool,
+                            on_finished=partial(client.callback_cleanups.pop, message["id"], None),
                         )
                         client.callback_cleanups[message["id"]] = cb_cleanup
+                        callback_ids.append(message["id"])
 
                         response["result"] = {"ok": True}
                         reply_subject = f"rpc.reply.{message['id']}"
@@ -1454,6 +1897,7 @@ class RPCClient(RPCClientProtocol):
                             handler,
                             message.get("params", []),
                             client.io_pool,
+                            handler_is_async,
                         )
                         response["result"] = result
 
@@ -1462,7 +1906,13 @@ class RPCClient(RPCClientProtocol):
                         await client.publish(reply_subject, response)
 
                 except Exception as e:
-                    response["error"] = format_error_dict(e)
+                    error_dict = format_error_dict(e)
+                    response["error"] = error_dict
+
+                    # Diagnostic aid: a METHOD_NOT_FOUND error always carries
+                    # the method list, discovery requested or not (rare, small).
+                    if error_dict["code"] == ErrorCode.METHOD_NOT_FOUND.value:
+                        response["__methods"] = method_names
 
                     try:
                         # If handler raised an exception, send error response
@@ -1482,23 +1932,23 @@ class RPCClient(RPCClientProtocol):
             # Unsubscribe all handlers
             await asyncio.gather(*(unsub() for unsub in unsubscribers), return_exceptions=True)
 
+            # Cleanup pull iterators / callbacks — only the ones THIS
+            # register_handler call created. The client maps are shared across
+            # register_handler calls; sweeping them wholesale would kill the
+            # live sessions of every other namespace.
             async def cleanup_iterator(iterator_id: str) -> None:
-                if cleanup := client.pull_iterator_cleanups.get(iterator_id):
-                    await cleanup()
-                    del client.pull_iterator_cleanups[iterator_id]
+                if fn := client.pull_iterator_cleanups.pop(iterator_id, None):
+                    await fn()
 
-            # Cleanup pull iterators
             await asyncio.gather(
                 *(cleanup_iterator(iterator_id) for iterator_id in pull_iterator_ids),
                 return_exceptions=True,
             )
 
-            # Cleanup callbacks
-            callback_cleanups = list(client.callback_cleanups.items())
-            for cb_id, cb_cleanup in callback_cleanups:
-                with contextlib.suppress(Exception):
-                    await cb_cleanup()
-                client.callback_cleanups.pop(cb_id, None)
+            for cb_id in callback_ids:
+                if cb_cleanup := client.callback_cleanups.pop(cb_id, None):
+                    with contextlib.suppress(Exception):
+                        await cb_cleanup()
 
             if isolated_connection:
                 # Disconnect isolated client if it was created
@@ -1515,28 +1965,29 @@ class RPCClient(RPCClientProtocol):
         if not self.nc:
             raise RuntimeError("Not connected")
 
+        handler_is_async = is_async_function(handler)
+
         async def handle_request(msg: Msg) -> None:
             try:
-                # Decode request
-                data = decode(msg.data)
+                # Decode request (zero-copy binary views into msg.data)
+                data = decode_message(msg.data)
 
-                # Call handler with subject
-                if is_async_function(handler):
+                # Call handler with subject. Sync handlers run inline —
+                # cheaper than the thread-pool hop and preserves ordering.
+                if handler_is_async:
                     result = await handler(data)  # pyright: ignore[reportGeneralTypeIssues]
                 else:
-                    loop = asyncio.get_event_loop()
-                    func = partial(handler, data)
-                    result = await loop.run_in_executor(self.io_pool, func)
+                    result = handler(data)
 
                 # Send response
                 if msg.reply:
-                    response = encode(result)
+                    response = encode_message(result)
                     await msg.respond(response)
 
             except Exception as e:
                 # Send error response
                 if msg.reply:
-                    error_response = encode(
+                    error_response = encode_message(
                         {
                             "error": str(e),
                             "code": e.code if isinstance(e, RPCException) else ErrorCode.INTERNAL_ERROR.value,
@@ -1545,8 +1996,8 @@ class RPCClient(RPCClientProtocol):
                     await msg.respond(error_response)
 
         sub = await self.nc.subscribe(pattern, cb=handle_request)
-
-        # Ensure the subscription is ready
+        # See _nats_subscribe: yield so the flusher sends the SUB before we
+        # return — cross-connection publishes have no ordering guarantee.
         await asyncio.sleep(0)
 
         async def unsubscribe() -> None: