@camera.ui/server 0.0.104 → 0.0.106

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

@@ -1,11 +1,21 @@
 """MessagePack encoding/decoding using ormsgpack for better performance."""
 
+import struct
 from datetime import date, datetime, time
 from enum import Enum
 from typing import Any
 
 import ormsgpack
 
+# Precomputed option masks — avoids re-evaluating the flag OR on every call.
+# OPT_DATETIME_AS_TIMESTAMP_EXT: (De)serialize datetime as MessagePack timestamp extension
+# OPT_NON_STR_KEYS: Allow non-string dict keys
+# OPT_PASSTHROUGH_ENUM: Pass enums to default handler
+_PACK_OPTS: int = (
+    ormsgpack.OPT_NON_STR_KEYS | ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT | ormsgpack.OPT_PASSTHROUGH_ENUM
+)
+_UNPACK_OPTS: int = ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT | ormsgpack.OPT_NON_STR_KEYS
+
 
 def _default_handler(obj: Any) -> Any:
     """Default handler for custom types."""
@@ -33,16 +43,7 @@ def encode(data: Any) -> bytes:
         MessagePack encoded binary data
     """
     # Use ormsgpack with proper options for cross-language compatibility
-    # OPT_DATETIME_AS_TIMESTAMP_EXT: Encode datetime as MessagePack timestamp extension
-    # OPT_NON_STR_KEYS: Allow non-string dict keys
-    # OPT_PASSTHROUGH_ENUM: Pass enums to default handler
-    return ormsgpack.packb(
-        data,
-        default=_default_handler,
-        option=ormsgpack.OPT_NON_STR_KEYS
-        | ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT
-        | ormsgpack.OPT_PASSTHROUGH_ENUM,
-    )
+    return ormsgpack.packb(data, default=_default_handler, option=_PACK_OPTS)
 
 
 def _ext_hook(_code: int, _data: bytes) -> Any:
@@ -62,12 +63,270 @@ def decode(data: bytes | bytearray | memoryview) -> Any:
     Returns:
         Decoded data
     """
-    # Use ormsgpack with proper options
-    # OPT_DATETIME_AS_TIMESTAMP_EXT: Deserialize timestamp extension objects to datetime
-    # OPT_NON_STR_KEYS: Allow non-string dict keys
     # ext_hook: Handle extension types from Node.js msgpackr
-    return ormsgpack.unpackb(
-        data,
-        option=ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT | ormsgpack.OPT_NON_STR_KEYS,
-        ext_hook=_ext_hook,
-    )
+    return ormsgpack.unpackb(data, option=_UNPACK_OPTS, ext_hook=_ext_hook)
+
+
+# see node/src/codec.ts
+
+BINARY_EXTRACT_THRESHOLD = 16384
+"""Minimum byte length for a binary value to be extracted out-of-band."""
+
+_MAGIC = b"CUIB"
+_HEADER_SIZE = 8  # magic + u32 LE envLen
+_PLACEHOLDER_KEY = "__cui_bin__"
+
+_ENV_LEN_STRUCT = struct.Struct("<I")
+
+
+def _as_extractable_segment(value: Any) -> bytes | bytearray | memoryview | None:
+    """Return the segment buffer for extractable binaries, None otherwise."""
+    if isinstance(value, (bytes, bytearray)):
+        return value if len(value) >= BINARY_EXTRACT_THRESHOLD else None
+    if isinstance(value, memoryview):
+        if value.nbytes < BINARY_EXTRACT_THRESHOLD:
+            return None
+        # join()/len math below need a flat byte layout.
+        return value if value.c_contiguous else memoryview(value.tobytes())
+    return None
+
+
+def _extract_binaries(value: Any, segments: list[bytes | bytearray | memoryview]) -> Any:
+    """Depth-first copy-on-write transform: extracted binaries become
+    placeholder maps, untouched subtrees keep their identity (no copy for
+    binary-free messages). Only dicts, lists and tuples are traversed —
+    other class instances are left to msgpack.
+    """
+    segment = _as_extractable_segment(value)
+    if segment is not None:
+        index = len(segments)
+        segments.append(segment)
+        return {
+            _PLACEHOLDER_KEY: index,
+            "l": segment.nbytes if isinstance(segment, memoryview) else len(segment),
+        }
+
+    if isinstance(value, dict):
+        dict_copy: dict[Any, Any] | None = None
+        for key, item in value.items():  # pyright: ignore[reportUnknownVariableType]
+            # Fast skip for common scalar leaves (exact types only —
+            # subclasses take the full path below).
+            cls = item.__class__
+            if cls is str or cls is int or cls is float or cls is bool or item is None:
+                continue
+            transformed = _extract_binaries(item, segments)
+            if transformed is not item:
+                if dict_copy is None:
+                    dict_copy = dict(value)  # pyright: ignore[reportUnknownArgumentType]
+                dict_copy[key] = transformed
+        return dict_copy if dict_copy is not None else value
+
+    if isinstance(value, (list, tuple)):
+        list_copy: list[Any] | None = None
+        for i, item in enumerate(value):  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
+            cls = item.__class__
+            if cls is str or cls is int or cls is float or cls is bool or item is None:
+                continue
+            transformed = _extract_binaries(item, segments)
+            if transformed is not item:
+                if list_copy is None:
+                    list_copy = list(value)  # pyright: ignore[reportUnknownArgumentType]
+                list_copy[i] = transformed
+        return list_copy if list_copy is not None else value
+
+    return value
+
+
+def _is_binary_placeholder(value: Any) -> bool:
+    """Strict placeholder check. A user map that happens to carry the
+    __cui_bin__ key but has extra keys, a missing "l" or non-integer values
+    is NOT treated as a placeholder and passes through untouched.
+    """
+    if type(value) is not dict or len(value) != 2:  # pyright: ignore[reportUnknownArgumentType]
+        return False
+    index = value.get(_PLACEHOLDER_KEY)
+    length = value.get("l")
+    # type() is int: bools are ints in Python but not valid placeholders.
+    return type(index) is int and index >= 0 and type(length) is int and length >= 0
+
+
+class _RestoreState:
+    """Mutable cursor for the sequential restore pass."""
+
+    __slots__ = ("next", "offset", "out_of_order")
+
+    def __init__(self, offset: int) -> None:
+        self.offset = offset  # start offset of the next expected segment
+        self.next = 0  # next expected segment index
+        self.out_of_order = False  # placeholder index arrived out of order
+
+
+def _restore_sequential(value: Any, data: memoryview, state: _RestoreState) -> Any:
+    """Single-pass restore for the common case: placeholder indices appear in
+    increasing order during envelope traversal (an encoder that assigns
+    indices and serializes in one walk always produces this). Offsets are
+    then running prefix sums — no length-collection pass needed. Mutates the
+    freshly decoded envelope in place; on the first out-of-order index the
+    remaining placeholders are left untouched for the fallback pass.
+
+    Decoded envelopes only ever contain plain dicts/lists, so exact type
+    checks are safe; the placeholder check is _is_binary_placeholder inlined
+    for the hot path.
+    """
+    if type(value) is dict:
+        if len(value) == 2:
+            index = value.get(_PLACEHOLDER_KEY)
+            length = value.get("l")
+            # type() is int: bools are ints in Python but not valid placeholders.
+            if type(index) is int and index >= 0 and type(length) is int and length >= 0:
+                if state.out_of_order or index != state.next:
+                    state.out_of_order = True
+                    return value
+                end = state.offset + length
+                if end > data.nbytes:
+                    raise ValueError(
+                        f"Invalid CUIB frame: segment {state.next} exceeds payload size {data.nbytes}"
+                    )
+                view = data[state.offset : end]
+                state.offset = end
+                state.next += 1
+                return view
+        for key, item in value.items():
+            if type(item) is dict or type(item) is list:
+                value[key] = _restore_sequential(item, data, state)
+        return value
+    if type(value) is list:
+        for i, item in enumerate(value):
+            if type(item) is dict or type(item) is list:
+                value[i] = _restore_sequential(item, data, state)
+        return value
+    return value
+
+
+def _collect_segment_lengths(value: Any, lengths: dict[int, int]) -> None:
+    """Fallback pass 1: record remaining placeholders' lengths by index."""
+    if _is_binary_placeholder(value):
+        lengths[value[_PLACEHOLDER_KEY]] = value["l"]
+        return
+    if isinstance(value, list):
+        for item in value:  # pyright: ignore[reportUnknownVariableType]
+            _collect_segment_lengths(item, lengths)
+        return
+    if isinstance(value, dict):
+        for item in value.values():  # pyright: ignore[reportUnknownVariableType]
+            _collect_segment_lengths(item, lengths)
+
+
+def _restore_by_index(value: Any, views: dict[int, memoryview]) -> Any:
+    """Fallback pass 2: swap remaining placeholders for their segment views."""
+    if _is_binary_placeholder(value):
+        return views[value[_PLACEHOLDER_KEY]]
+    if isinstance(value, list):
+        for i, item in enumerate(value):  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
+            value[i] = _restore_by_index(item, views)
+        return value
+    if isinstance(value, dict):
+        for key, item in value.items():  # pyright: ignore[reportUnknownVariableType]
+            value[key] = _restore_by_index(item, views)
+        return value
+    return value
+
+
+def _restore_remaining(envelope: Any, data: memoryview, state: _RestoreState) -> Any:
+    """Out-of-order fallback: _restore_sequential already consumed the
+    in-order prefix (segments 0..state.next-1); place the remaining segments
+    via an explicit index -> length table. Segments always lie back-to-back
+    in index order, whatever order their placeholders appear in.
+    """
+    lengths: dict[int, int] = {}
+    _collect_segment_lengths(envelope, lengths)
+
+    views: dict[int, memoryview] = {}
+    offset = state.offset
+    for i in range(state.next, max(lengths) + 1 if lengths else state.next):
+        length = lengths.get(i)
+        if length is None:
+            raise ValueError(f"Invalid CUIB frame: missing placeholder for segment {i}")
+        end = offset + length
+        if end > data.nbytes:
+            raise ValueError(f"Invalid CUIB frame: segment {i} exceeds payload size {data.nbytes}")
+        views[i] = data[offset:end]
+        offset = end
+    state.offset = offset
+
+    return _restore_by_index(envelope, views)
+
+
+def encode_message(data: Any) -> bytes:
+    """
+    Encode a message for the wire.
+
+    Large binaries (bytes/bytearray/memoryview with byte length >=
+    BINARY_EXTRACT_THRESHOLD) are extracted into out-of-band segments after
+    the msgpack envelope; binary-free messages stay byte-identical to
+    encode(). The input structure is never mutated (copy-on-write).
+
+    Args:
+        data: Any serializable data
+
+    Returns:
+        Wire-encoded binary data
+    """
+    segments: list[bytes | bytearray | memoryview] = []
+    transformed = _extract_binaries(data, segments)
+
+    if not segments:
+        return encode(data)
+
+    envelope = encode(transformed)
+    # One join copy assembles the full frame — acceptable even for large
+    # frames, and cheaper than incremental writes from Python.
+    return b"".join((_MAGIC, _ENV_LEN_STRUCT.pack(len(envelope)), envelope, *segments))
+
+
+def decode_message(data: bytes | bytearray | memoryview) -> Any:
+    """
+    Decode a wire message.
+
+    Payloads without the CUIB magic are plain msgpack. For framed payloads
+    the placeholder maps are replaced by zero-copy memoryview slices into
+    ``data`` — binary values >= BINARY_EXTRACT_THRESHOLD (1 KiB) therefore
+    arrive as ``memoryview``, not ``bytes``. Consumers speaking the buffer
+    protocol (numpy, Rust bindings, ``len()``/slicing) handle views
+    directly; call ``bytes(view)`` where a real bytes object is required or
+    the data must outlive the receive buffer.
+
+    Args:
+        data: Wire-encoded binary data (one complete message)
+
+    Returns:
+        Decoded data
+    """
+    # Fast path for plain msgpack payloads: bytes/bytearray get a cheap
+    # startswith check without allocating a memoryview.
+    if isinstance(data, memoryview):
+        if data.nbytes < _HEADER_SIZE or data[:4] != _MAGIC:
+            return decode(data)
+        view = data
+    else:
+        if len(data) < _HEADER_SIZE or not data.startswith(_MAGIC):
+            return decode(data)
+        view = memoryview(data)
+    total = view.nbytes
+
+    env_len: int = _ENV_LEN_STRUCT.unpack_from(view, 4)[0]
+    segment_base = _HEADER_SIZE + env_len
+    if segment_base > total:
+        raise ValueError(f"Invalid CUIB frame: envelope length {env_len} exceeds payload size {total}")
+
+    envelope = decode(view[_HEADER_SIZE:segment_base])
+
+    state = _RestoreState(segment_base)
+    envelope = _restore_sequential(envelope, view, state)
+    if state.out_of_order:
+        envelope = _restore_remaining(envelope, view, state)
+
+    if state.offset != total:
+        raise ValueError(f"Invalid CUIB frame: expected payload size {state.offset}, got {total}")
+
+    return envelope

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

@@ -138,19 +138,27 @@ async def handle_normal_rpc(
     handler: Callable[..., Any],
     params: Any,
     io_pool: ThreadPoolExecutor,
+    handler_is_async: bool | None = None,
 ) -> Any:
-    """Handle normal RPC call - common logic for client and service."""
+    """Handle normal RPC call - common logic for client and service.
+
+    ``handler_is_async`` lets callers on hot paths pass the async-ness
+    determined once at registration time instead of re-inspecting per call.
+    Sync handlers run inline on the event loop — the thread-pool hop costs
+    far more than the short callbacks used in this system, and inline
+    execution preserves per-subscription ordering.
+    """
     # Ensure params is a list
     if not isinstance(params, list):
         params = [params] if params is not None else []
 
+    if handler_is_async is None:
+        handler_is_async = is_async_function(handler)
+
     # Call the handler
-    if is_async_function(handler):
+    if handler_is_async:
         return await handler(*params)
-    else:
-        loop = asyncio.get_event_loop()
-        func = partial(handler, *params)
-        return await loop.run_in_executor(io_pool, func)
+    return handler(*params)
 
 
 def format_error_dict(e: Exception) -> RPCError:
@@ -170,6 +178,7 @@ async def handle_pull_iterator_request(
     iterator_id: str,
     client: RPCClient,
     io_pool: ThreadPoolExecutor,
+    on_finished: Callable[[], Any] | None = None,
 ) -> Callable[[], Coroutine[Any, Any, None]]:
     """Handle pull-based iterator request."""
     generator: AsyncGenerator[Any, None]
@@ -229,7 +238,28 @@ async def handle_pull_iterator_request(
 
     # Track if iterator is active
     active = True
-    unsub_func = None
+    finished = False
+    unsub_func: Callable[[], Coroutine[Any, Any, None]] | None = None
+
+    def finish() -> None:
+        """Natural end (done/cancel/error): drop the request subscription and
+        let the owner remove its cleanup-map entry via on_finished. Without
+        this, every finished session leaves its `_rpc.iterator.*.request`
+        subscription and cleanup closure behind until the whole client
+        disconnects. The unsubscribe is scheduled as a task —
+        Subscription.unsubscribe() cancels the message task this handler runs
+        in, so it must not be awaited from here.
+        """
+        nonlocal active, finished
+        if finished:
+            return
+        finished = True
+        active = False
+        if on_finished is not None:
+            with contextlib.suppress(Exception):
+                on_finished()
+        if unsub_func is not None:
+            asyncio.create_task(unsub_func())
 
     # Subscribe to iterator requests
     async def handle_pull_request(msg: PullIteratorRequest) -> None:
@@ -248,7 +278,10 @@ async def handle_pull_iterator_request(
                     "id": iterator_id,
                     "type": "done",
                 }
-                await client.publish(response_subject, response)
+                try:
+                    await client.publish(response_subject, response)
+                finally:
+                    finish()
             elif msg.get("type") == "next":
                 try:
                     value = await generator.__anext__()
@@ -264,7 +297,10 @@ async def handle_pull_iterator_request(
                         "id": iterator_id,
                         "type": "done",
                     }
-                    await client.publish(response_subject, done_response)
+                    try:
+                        await client.publish(response_subject, done_response)
+                    finally:
+                        finish()
 
         except Exception as e:
             active = False
@@ -273,14 +309,18 @@ async def handle_pull_iterator_request(
                 "type": "error",
                 "error": format_error_dict(e),
             }
-            await client.publish(response_subject, error_response)
+            try:
+                await client.publish(response_subject, error_response)
+            finally:
+                finish()
 
     unsub_func = await client.subscribe(request_subject, handle_pull_request)
 
     # Return cleanup function
     async def cleanup() -> None:
-        nonlocal active
+        nonlocal active, finished
         active = False
+        finished = True
         if unsub_func is not None:
             await unsub_func()
         # Ensure generator is closed
@@ -330,6 +370,7 @@ async def handle_pull_callback_request(
     oneway_methods: list[str],
     client: RPCClient,
     io_pool: ThreadPoolExecutor,
+    on_finished: Callable[[], Any] | None = None,
 ) -> Callable[[], Coroutine[Any, Any, None]]:
     """Handle a pull-iterator-with-callbacks request.
 
@@ -398,8 +439,27 @@ async def handle_pull_callback_request(
     response_subject = f"_rpc.iterator.{iterator_id}.response"
 
     active = True
+    finished = False
     unsub_func: Callable[[], Coroutine[Any, Any, None]] | None = None
 
+    def finish() -> None:
+        """Natural end: see handle_pull_iterator_request — drop the request
+        subscription and the owner's cleanup-map entry per finished session.
+        Unsubscribe is scheduled as a task because Subscription.unsubscribe()
+        cancels the message task this handler runs in.
+        """
+        nonlocal active, finished
+        if finished:
+            return
+        finished = True
+        active = False
+        invoker.active = False
+        if on_finished is not None:
+            with contextlib.suppress(Exception):
+                on_finished()
+        if unsub_func is not None:
+            asyncio.create_task(unsub_func())
+
     async def handle_pull_request(msg: PullIteratorRequest) -> None:
         nonlocal active
 
@@ -416,7 +476,10 @@ async def handle_pull_callback_request(
                     "id": iterator_id,
                     "type": "done",
                 }
-                await client.publish(response_subject, response)
+                try:
+                    await client.publish(response_subject, response)
+                finally:
+                    finish()
             elif msg.get("type") == "next":
                 try:
                     # Drive the generator to its next yield. The yielded
@@ -434,7 +497,10 @@ async def handle_pull_callback_request(
                         "id": iterator_id,
                         "type": "done",
                     }
-                    await client.publish(response_subject, done_response)
+                    try:
+                        await client.publish(response_subject, done_response)
+                    finally:
+                        finish()
 
         except Exception as e:
             active = False
@@ -444,13 +510,17 @@ async def handle_pull_callback_request(
                 "type": "error",
                 "error": format_error_dict(e),
             }
-            await client.publish(response_subject, error_response)
+            try:
+                await client.publish(response_subject, error_response)
+            finally:
+                finish()
 
     unsub_func = await client.subscribe(request_subject, handle_pull_request)
 
     async def cleanup() -> None:
-        nonlocal active
+        nonlocal active, finished
         active = False
+        finished = True
         invoker.active = False
         if unsub_func is not None:
             await unsub_func()
@@ -468,6 +538,7 @@ async def handle_callback_request(
     request_id: str,
     client: RPCClient,
     io_pool: ThreadPoolExecutor,
+    on_finished: Callable[[], Any] | None = None,
 ) -> Callable[[], Coroutine[Any, Any, None]]:
     """Handle callback subscription request."""
 
@@ -510,9 +581,26 @@ async def handle_callback_request(
             else:
                 handler_cleanup()
 
+    # Handler cleanup must run exactly once — the cancel message and a later
+    # register_handler/disconnect cleanup would otherwise both invoke it.
+    cleaned_up = False
+
+    async def run_handler_cleanup() -> None:
+        nonlocal cleaned_up
+        if cleaned_up:
+            return
+        cleaned_up = True
+        await invoke_cleanup()
+
     # Subscribe to cancel subject
     async def on_cancel(_msg: Any) -> None:
-        await invoke_cleanup()
+        if on_finished is not None:
+            with contextlib.suppress(Exception):
+                on_finished()
+        await run_handler_cleanup()
+        # Unsubscribe outside this callback's own message task —
+        # Subscription.unsubscribe() cancels the task it is called from.
+        asyncio.create_task(cancel_unsub())
 
     cancel_unsub = await client.subscribe(
         f"{callback_subject}.cancel",
@@ -522,6 +610,6 @@ async def handle_callback_request(
     # Return combined cleanup
     async def cleanup() -> None:
         await cancel_unsub()
-        await invoke_cleanup()
+        await run_handler_cleanup()
 
     return cleanup

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

@@ -4,6 +4,7 @@ import asyncio
 import contextlib
 import json
 from collections.abc import Awaitable, Callable, Coroutine
+from functools import partial
 from typing import TYPE_CHECKING, Any, cast
 
 from nats.aio.client import Client as NATSClient
@@ -19,7 +20,7 @@ from nats.micro.service import (
     Service as NATSService,
 )
 
-from .codec import decode, encode
+from .codec import decode, decode_message, encode
 from .decorators import extract_nested_methods_with_decorators
 from .handler import (
     format_error_dict,
@@ -29,6 +30,7 @@ from .handler import (
 )
 from .svcm import Svcm
 from .types import ErrorCode, RPCClientOptions
+from .utils import is_async_function
 
 if TYPE_CHECKING:
     from .client import RPCClient
@@ -41,14 +43,20 @@ class RPCService:
         self.__client: RPCClient = client
         self.__svc: Svcm | None = None
         self.__services: list[NATSService] = []
-        self.__initialized: bool = False
+        self.__nc: NATSClient | None = None
 
     def init(self, nc: NATSClient) -> None:
-        """Initialize the service manager."""
-        if self.__initialized:
+        """Initialize the service manager.
+
+        Re-initializes when the underlying connection changed (suspend() +
+        connect() creates a fresh NATS connection) — a Svcm bound to the old,
+        closed connection would break service registration after every
+        reconnect cycle.
+        """
+        if self.__nc is nc:
             return
 
-        self.__initialized = True
+        self.__nc = nc
         self.__svc = Svcm(nc)
         self.__services = []
 
@@ -113,6 +121,9 @@ class RPCService:
 
             # Add endpoint with auto-encoding/decoding
             def make_endpoint_handler(h: Callable[..., Any]) -> Callable[[Request], Awaitable[None]]:
+                # Determined once per endpoint instead of per message.
+                h_is_async = is_async_function(h)
+
                 async def handle_rpc_message(rpc_msg: dict[str, Any], original_msg: Request) -> None:
                     """Handle RPC protocol message."""
                     response = {"id": rpc_msg["id"]}
@@ -162,6 +173,7 @@ class RPCService:
                                 iterator_id,
                                 service_client,
                                 service_client.io_pool,
+                                on_finished=partial(pull_iterator_cleanups.pop, iterator_id, None),
                             )
 
                             # Store cleanup function for later
@@ -177,6 +189,7 @@ class RPCService:
                                 h,
                                 rpc_msg.get("params", []),
                                 service_client.io_pool,
+                                h_is_async,
                             )
                             response["result"] = result
 
@@ -246,8 +259,9 @@ class RPCService:
                                 }
                             )
                         else:
-                            # Regular message - decode as RPC message
-                            decoded = decode(msg.data)
+                            # Regular message - decode wire message (zero-copy
+                            # binary views into msg.data)
+                            decoded = decode_message(msg.data)
                             await handle_rpc_message(decoded, msg)
                     except Exception as e:
                         # Send error response

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

@@ -198,6 +198,12 @@ class RPCClientOptions(TypedDict):
     name: str
     """Client name for identification"""
 
+    conn_id: NotRequired[str]
+    """Connection id used as the reply prefix of every call id. When set, the
+    muxed reply inbox subscribes ``rpc.reply.<conn_id>.>`` (server-side
+    firewalls allowlist exactly that wildcard for browser clients). When
+    omitted, a random local prefix is generated instead."""
+
     auth: NotRequired[RPCAuthOptions]
     """Authentication credentials with 'user' and 'pass' keys"""
 
@@ -251,6 +257,13 @@ class RPCMessage(TypedDict):
     error: NotRequired[RPCError | None]
     """Optional error (unused in requests)"""
 
+    __discover: NotRequired[bool]
+    """Method-discovery request (internal metadata for proxies). When True,
+    the responder attaches the namespace's ``__methods`` list to the response.
+    Proxies set this only while their method cache is empty. Lives on the
+    envelope (not in params) so it never leaks into handler arguments; old
+    responders ignore it."""
+
 
 class RPCResponse(TypedDict):
     """RPC response message format."""