imbot-sdk-python 0.1.0__py3-none-any.whl

imbot_sdk/client.py

@@ -0,0 +1,1155 @@
+"""ImBotClient: WebSocket long-connection IM bot client.
+
+Manages the connection lifecycle (connect / reconnect / heartbeat /
+auto-reconnect), sends and receives messages, and exposes message /
+conversation / user / group / chatroom / RTC / file APIs over the JuggleIM
+WebSocket protocol.
+"""
+
+import threading
+import time
+from typing import Callable, List, Optional, Tuple
+
+import websocket  # websocket-client
+
+from . import messages as messages_pkg
+from .consts import ClientErrorCode, ConnectState
+from .data_accessor import DataAccessor, TimeoutError as AccessorTimeout
+from .listeners import (
+    ConnectionStatusChangeListener,
+    ConversationChangeListener,
+    MessageListener,
+)
+from .models import (
+    Conversation,
+    ConversationInfo,
+    ConversationMentionInfo,
+    Message,
+    MessageMentionInfo,
+)
+from .pb import appmessages_pb2 as pb
+from .pb import chatroom_pb2 as chatpb
+from .pb import connect_pb2 as cpb
+from .pb import rtcroom_pb2 as rtcpb
+
+# --- protocol constants ---
+PROTO_ID = "jug9le1m"
+VERSION1 = 1
+
+CMD_CONNECT = 0
+CMD_CONNECT_ACK = 1
+CMD_DISCONNECT = 2
+CMD_PUBLISH = 3
+CMD_PUBLISH_ACK = 4
+CMD_QUERY = 5
+CMD_QUERY_ACK = 6
+CMD_QUERY_CONFIRM = 7
+CMD_PING = 8
+CMD_PONG = 9
+
+QOS_NO_ACK = 0
+QOS_NEED_ACK = 1
+
+IM_ERROR_CODE_SUCCESS = 0
+IM_ERROR_CODE_CONNECT_LOGOUT = 10004
+
+SDK_VERSION = "1.0.0"
+
+# Heartbeat timings: ping every 10s, drop after
+# missing two heartbeat windows of downstream traffic.
+HEARTBEAT_INTERVAL = 10.0
+HEARTBEAT_RECEIVE_TIMEOUT = 2 * HEARTBEAT_INTERVAL
+
+# RTC join may return this code when the caller is already in the room.
+RTC_JOIN_ALREADY_IN_ROOM = 16002
+
+
+def _trans_client_error_code(code: int) -> int:
+    return ClientErrorCode.SUCCESS if code == IM_ERROR_CODE_SUCCESS else code
+
+
+def _ack_code(code: int, ack) -> int:
+    if code != ClientErrorCode.SUCCESS:
+        return code
+    if ack is not None and ack.code != IM_ERROR_CODE_SUCCESS:
+        return ack.code
+    return ClientErrorCode.SUCCESS
+
+
+class _ReconnectBackoff:
+    """Reconnect backoff: 300ms first, then 1s..32s doubling."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._next = 300
+
+    def reset(self) -> None:
+        with self._lock:
+            self._next = 300
+
+    def next_delay(self) -> float:
+        with self._lock:
+            out = self._next
+            if self._next < 1000:
+                self._next = 1000
+            elif self._next < 32000:
+                self._next *= 2
+            return out / 1000.0
+
+
+class ImBotClient:
+    def __init__(self, address: str, app_key: str) -> None:
+        self.address = address
+        self.app_key = app_key
+        self.token = ""
+        self.platform = "Bot"
+        self.auto_reconnect = True
+
+        # Optional low-level callbacks.
+        self.disconnect_callback: Optional[Callable[[int, object], None]] = None
+        self.on_message_callback: Optional[Callable[[object], None]] = None
+        self.on_stream_msg_callback: Optional[Callable[[object], None]] = None
+
+        self.user_id = ""
+
+        self._connect_listeners: List[ConnectionStatusChangeListener] = []
+        self._conver_listeners: List[ConversationChangeListener] = []
+        self._message_listeners: List[MessageListener] = []
+
+        self._conn: Optional[websocket.WebSocket] = None
+        self._state = ConnectState.DISCONNECT
+        self._accessor_cache = {}
+        self._accessor_lock = threading.Lock()
+        self._my_index = 0
+        self._index_lock = threading.Lock()
+        self._conn_ack_accessor = DataAccessor()
+        self._pong_event = threading.Event()
+        self._lock = threading.RLock()
+        self._conver_cache = {}
+
+        self._last_rx_ms = 0
+        self._pending_disconnect_code = 0
+        self._handshake_complete = False
+        self._suppress_auto_reconnect = False
+        self._reconnect_backoff = _ReconnectBackoff()
+        self._reconnect_busy = False
+        self._reconnect_lock = threading.Lock()
+
+        self._heartbeat_stop: Optional[threading.Event] = None
+        self._heartbeat_thread: Optional[threading.Thread] = None
+
+        self._inbox_time = 0
+        self._sendbox_time = 0
+        self._total_unread_count = 0
+
+    # ------------------------------------------------------------------
+    # state / low-level io
+    # ------------------------------------------------------------------
+    def get_state(self) -> ConnectState:
+        return self._state
+
+    def write_message(self, data: bytes) -> None:
+        with self._lock:
+            if self._state != ConnectState.CONNECTED or self._conn is None:
+                raise RuntimeError("not connected")
+            self._conn.send_binary(data)
+
+    def _write_message_safe(self, data: bytes) -> None:
+        try:
+            self.write_message(data)
+        except Exception:
+            pass
+
+    def _ws_url(self) -> str:
+        if self.address.startswith("wss://"):
+            host = self.address[len("wss://"):]
+            return "wss://" + host.rstrip("/") + "/imbot"
+        if self.address.startswith("ws://"):
+            host = self.address[len("ws://"):]
+            return "ws://" + host.rstrip("/") + "/imbot"
+        raise ValueError("unsupported websocket address: %s" % self.address)
+
+    def _close_conn(self) -> None:
+        with self._lock:
+            if self._conn is not None:
+                try:
+                    self._conn.close()
+                except Exception:
+                    pass
+                self._conn = None
+
+    def _next_index(self) -> int:
+        with self._index_lock:
+            self._my_index = (self._my_index + 1) & 0xFFFF
+            return self._my_index
+
+    # ------------------------------------------------------------------
+    # connect / disconnect
+    # ------------------------------------------------------------------
+    def add_connection_status_change_listener(self, listener: ConnectionStatusChangeListener) -> None:
+        if listener is not None:
+            self._connect_listeners.append(listener)
+
+    def _change_connection_status(self, status: ConnectState, code: int) -> None:
+        self._state = status
+        for listener in self._connect_listeners:
+            if listener is not None:
+                listener.on_status_change(status, code)
+
+    def connect(self, token: str) -> Tuple[int, Optional[object]]:
+        """Establish the connection. Returns ``(code, connect_ack)``.
+
+        ``code == ClientErrorCode.SUCCESS`` on success and ``user_id`` is set.
+        """
+        if self._state != ConnectState.DISCONNECT:
+            return ClientErrorCode.CONNECT_EXISTED, None
+        self._stop_heartbeat()
+        self._handshake_complete = False
+        self._pending_disconnect_code = 0
+        self._suppress_auto_reconnect = False
+        self._conn_ack_accessor = DataAccessor()
+
+        self.token = token
+        connect_body = cpb.ConnectMsgBody(
+            protoId=PROTO_ID,
+            sdkVersion=SDK_VERSION,
+            appkey=self.app_key,
+            token=self.token,
+            platform=self.platform,
+        )
+
+        try:
+            url = self._ws_url()
+        except ValueError:
+            self._change_connection_status(ConnectState.DISCONNECT, ClientErrorCode.SOCKET_FAILED)
+            return ClientErrorCode.SOCKET_FAILED, None
+
+        header = ["x-appkey: %s" % self.app_key, "x-token: %s" % self.token]
+        try:
+            conn = websocket.create_connection(url, header=header, timeout=10)
+            conn.settimeout(None)  # blocking reads in the listener loop
+        except Exception as exc:  # noqa: BLE001
+            print("addr:", url, "err:", exc)
+            self._change_connection_status(ConnectState.DISCONNECT, ClientErrorCode.SOCKET_FAILED)
+            return ClientErrorCode.SOCKET_FAILED, None
+
+        with self._lock:
+            self._conn = conn
+
+        ws_msg = cpb.ImWebsocketMsg(
+            version=VERSION1, cmd=CMD_CONNECT, qos=QOS_NEED_ACK, connectMsgBody=connect_body
+        )
+        try:
+            conn.send_binary(ws_msg.SerializeToString())
+        except Exception as exc:  # noqa: BLE001
+            print(exc)
+            self._close_conn()
+            self._change_connection_status(ConnectState.DISCONNECT, ClientErrorCode.CONNECT_TIMEOUT)
+            return ClientErrorCode.CONNECT_TIMEOUT, None
+
+        self._change_connection_status(ConnectState.CONNECTING, ClientErrorCode.SUCCESS)
+        threading.Thread(target=self._start_listener, daemon=True).start()
+
+        try:
+            conn_ack = self._conn_ack_accessor.get_with_timeout(10)
+        except AccessorTimeout:
+            self._close_conn()
+            self._change_connection_status(ConnectState.DISCONNECT, ClientErrorCode.CONNECT_TIMEOUT)
+            return ClientErrorCode.CONNECT_TIMEOUT, None
+
+        client_code = _trans_client_error_code(conn_ack.code)
+        if conn_ack.code == IM_ERROR_CODE_SUCCESS:
+            self.user_id = conn_ack.userId
+            self._mark_heartbeat_rx()
+            self._reconnect_backoff.reset()
+            self._handshake_complete = True
+            self._change_connection_status(ConnectState.CONNECTED, client_code)
+            self._start_heartbeat()
+            return client_code, conn_ack
+        self._close_conn()
+        self._change_connection_status(ConnectState.DISCONNECT, client_code)
+        return client_code, conn_ack
+
+    def reconnect(self) -> Tuple[int, Optional[object]]:
+        if self._state == ConnectState.CONNECTING:
+            return ClientErrorCode.CONNECT_EXISTED, None
+        self._suppress_auto_reconnect = False
+        self._close_conn()
+        self._change_connection_status(ConnectState.DISCONNECT, ClientErrorCode.SUCCESS)
+        return self.connect(self.token)
+
+    def disconnect(self) -> None:
+        self._suppress_auto_reconnect = True
+        self._stop_heartbeat()
+        if self._conn is not None:
+            dis = cpb.ImWebsocketMsg(
+                version=VERSION1, cmd=CMD_DISCONNECT, qos=QOS_NO_ACK,
+                disconnectMsgBody=cpb.DisconnectMsgBody(code=IM_ERROR_CODE_SUCCESS),
+            )
+            self._write_message_safe(dis.SerializeToString())
+        self._close_conn()
+
+    def logout(self) -> None:
+        self._suppress_auto_reconnect = True
+        self._stop_heartbeat()
+        if self._conn is not None:
+            dis = cpb.ImWebsocketMsg(
+                version=VERSION1, cmd=CMD_DISCONNECT, qos=QOS_NO_ACK,
+                disconnectMsgBody=cpb.DisconnectMsgBody(code=IM_ERROR_CODE_CONNECT_LOGOUT),
+            )
+            self._write_message_safe(dis.SerializeToString())
+        self._close_conn()
+
+    # ------------------------------------------------------------------
+    # read loop
+    # ------------------------------------------------------------------
+    def _start_listener(self) -> None:
+        while True:
+            with self._lock:
+                conn = self._conn
+            if conn is None:
+                break
+            try:
+                data = conn.recv()
+            except Exception as exc:  # noqa: BLE001
+                print(exc)
+                self._handle_read_loop_ended(exc)
+                break
+            if data is None or data == "":
+                continue
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+            self._mark_heartbeat_rx()
+            ws_msg = cpb.ImWebsocketMsg()
+            try:
+                ws_msg.ParseFromString(data)
+            except Exception as exc:  # noqa: BLE001
+                print("failed to decode pb data:", exc)
+                continue
+            threading.Thread(target=self._handle_msg, args=(ws_msg,), daemon=True).start()
+
+    def _handle_msg(self, ws_msg) -> None:
+        cmd = ws_msg.cmd
+        if cmd == CMD_CONNECT_ACK:
+            self._on_connect_ack(ws_msg.ConnectAckMsgBody)
+        elif cmd == CMD_DISCONNECT:
+            self._on_disconnect(ws_msg.disconnectMsgBody)
+        elif cmd == CMD_PUBLISH:
+            self._on_publish(ws_msg.publishMsgBody, ws_msg.qos)
+        elif cmd == CMD_PUBLISH_ACK:
+            self._on_publish_ack(ws_msg.pubAckMsgBody)
+        elif cmd == CMD_QUERY_ACK:
+            self._on_query_ack(ws_msg.qryAckMsgBody)
+        elif cmd == CMD_PONG:
+            self._on_pong()
+
+    def _on_connect_ack(self, msg) -> None:
+        self._conn_ack_accessor.put(msg)
+
+    def _on_publish_ack(self, msg) -> None:
+        if msg is None:
+            return
+        with self._accessor_lock:
+            accessor = self._accessor_cache.pop(msg.index, None)
+        if accessor is not None:
+            accessor.put(msg)
+
+    def _on_query_ack(self, msg) -> None:
+        if msg is None:
+            return
+        with self._accessor_lock:
+            accessor = self._accessor_cache.pop(msg.index, None)
+        if accessor is not None:
+            accessor.put(msg)
+
+    def _on_disconnect(self, msg) -> None:
+        self._suppress_auto_reconnect = True
+        self._stop_heartbeat()
+        if msg is None:
+            msg = cpb.DisconnectMsgBody()
+        if self.disconnect_callback is not None:
+            self.disconnect_callback(_trans_client_error_code(msg.code), msg)
+        self._pending_disconnect_code = _trans_client_error_code(msg.code)
+        self._close_conn()
+
+    def _on_pong(self) -> None:
+        self._pong_event.set()
+
+    def _on_publish(self, msg, need_ack: int) -> None:
+        if msg is None:
+            return
+        topic = msg.topic
+        if topic == "msg":
+            down = pb.DownMsg()
+            try:
+                down.ParseFromString(msg.data)
+                self._handle_down_msg(down)
+            except Exception as exc:  # noqa: BLE001
+                print("msg unmarshal error:", exc)
+        elif topic == "ntf":
+            ntf = pb.Notify()
+            try:
+                ntf.ParseFromString(msg.data)
+            except Exception as exc:  # noqa: BLE001
+                print("ntf unmarshal error:", exc)
+                ntf = None
+            if ntf is not None:
+                if ntf.type == pb.Msg:
+                    is_continue = True
+                    while is_continue:
+                        code, down_set = self.sync_msgs(
+                            pb.SyncMsgReq(
+                                syncTime=self._inbox_time,
+                                sendBoxSyncTime=self._sendbox_time,
+                            )
+                        )
+                        if code == ClientErrorCode.SUCCESS and down_set is not None:
+                            for down_msg in down_set.msgs:
+                                self._handle_down_msg(down_msg)
+                            is_continue = not down_set.isFinished
+                        else:
+                            print("ntf pull msg error, code:", code)
+                            is_continue = False
+                elif ntf.type == pb.ChatroomMsg:
+                    print("ntf chatroom msg ignored")
+        elif topic == "stream_msg":
+            stream = pb.StreamDownMsg()
+            try:
+                stream.ParseFromString(msg.data)
+                if self.on_stream_msg_callback is not None:
+                    self.on_stream_msg_callback(stream)
+            except Exception:  # noqa: BLE001
+                pass
+        else:
+            print(topic, msg.data)
+
+        if need_ack > 0:
+            ack = cpb.ImWebsocketMsg(
+                version=VERSION1, cmd=CMD_PUBLISH_ACK, qos=QOS_NO_ACK,
+                pubAckMsgBody=cpb.PublishAckMsgBody(index=msg.index),
+            )
+            self._write_message_safe(ack.SerializeToString())
+
+    def _handle_down_msg(self, down_msg) -> None:
+        if down_msg is None:
+            return
+        if self.on_message_callback is not None:
+            self.on_message_callback(down_msg)
+        msg = self._notify_message_receive(down_msg)
+        self._notify_conversation_for_message(msg, down_msg)
+        if down_msg.isSend:
+            self._sendbox_time = down_msg.msgTime
+        else:
+            self._inbox_time = down_msg.msgTime
+
+    # ------------------------------------------------------------------
+    # publish / query / ping
+    # ------------------------------------------------------------------
+    def publish(self, method: str, target_id: str, data: bytes) -> Tuple[int, Optional[object]]:
+        if self._state != ConnectState.CONNECTED:
+            return ClientErrorCode.CONNECT_CLOSED, None
+        index = self._next_index()
+        proto_msg = cpb.ImWebsocketMsg(
+            version=VERSION1, cmd=CMD_PUBLISH, qos=QOS_NEED_ACK,
+            publishMsgBody=cpb.PublishMsgBody(
+                index=index, topic=method, targetId=target_id, data=data or b""
+            ),
+        )
+        accessor = DataAccessor()
+        with self._accessor_lock:
+            self._accessor_cache[index] = accessor
+        self._write_message_safe(proto_msg.SerializeToString())
+        try:
+            pub_ack = accessor.get_with_timeout(10)
+        except AccessorTimeout:
+            with self._accessor_lock:
+                self._accessor_cache.pop(index, None)
+            return ClientErrorCode.SEND_TIMEOUT, None
+        return _trans_client_error_code(pub_ack.code), pub_ack
+
+    def query(self, method: str, target_id: str, data: bytes) -> Tuple[int, Optional[object]]:
+        if self._state != ConnectState.CONNECTED:
+            return ClientErrorCode.CONNECT_CLOSED, None
+        index = self._next_index()
+        proto_msg = cpb.ImWebsocketMsg(
+            version=VERSION1, cmd=CMD_QUERY, qos=QOS_NEED_ACK,
+            qryMsgBody=cpb.QueryMsgBody(
+                index=index, topic=method, targetId=target_id, data=data or b""
+            ),
+        )
+        accessor = DataAccessor()
+        with self._accessor_lock:
+            self._accessor_cache[index] = accessor
+        self._write_message_safe(proto_msg.SerializeToString())
+        try:
+            query_ack = accessor.get_with_timeout(10)
+        except AccessorTimeout:
+            with self._accessor_lock:
+                self._accessor_cache.pop(index, None)
+            return ClientErrorCode.QUERY_TIMEOUT, None
+        return _trans_client_error_code(query_ack.code), query_ack
+
+    def query_confirm(self, index: int) -> int:
+        if self._state != ConnectState.CONNECTED:
+            return ClientErrorCode.CONNECT_CLOSED
+        confirm = cpb.ImWebsocketMsg(
+            version=VERSION1, cmd=CMD_QUERY_CONFIRM, qos=QOS_NO_ACK,
+            qryConfirmMsgBody=cpb.QueryConfirmMsgBody(index=index),
+        )
+        self._write_message_safe(confirm.SerializeToString())
+        return ClientErrorCode.SUCCESS
+
+    def ping(self) -> int:
+        if self._state != ConnectState.CONNECTED:
+            return ClientErrorCode.CONNECT_CLOSED
+        self._pong_event.clear()
+        ping = cpb.ImWebsocketMsg(version=VERSION1, cmd=CMD_PING, qos=QOS_NEED_ACK)
+        self._write_message_safe(ping.SerializeToString())
+        if self._pong_event.wait(15):
+            return ClientErrorCode.SUCCESS
+        return ClientErrorCode.PING_TIMEOUT
+
+    # ------------------------------------------------------------------
+    # heartbeat & auto-reconnect
+    # ------------------------------------------------------------------
+    def _mark_heartbeat_rx(self) -> None:
+        self._last_rx_ms = int(time.time() * 1000)
+
+    def _send_ping_fire_and_forget(self) -> None:
+        if self._state != ConnectState.CONNECTED:
+            return
+        ping = cpb.ImWebsocketMsg(version=VERSION1, cmd=CMD_PING, qos=QOS_NEED_ACK)
+        self._write_message_safe(ping.SerializeToString())
+
+    def _stop_heartbeat(self) -> None:
+        if self._heartbeat_stop is not None:
+            self._heartbeat_stop.set()
+            self._heartbeat_stop = None
+        self._heartbeat_thread = None
+
+    def _start_heartbeat(self) -> None:
+        self._stop_heartbeat()
+        stop = threading.Event()
+        self._heartbeat_stop = stop
+
+        def run() -> None:
+            while not stop.wait(HEARTBEAT_INTERVAL):
+                if self._state != ConnectState.CONNECTED:
+                    return
+                self._send_ping_fire_and_forget()
+                last = self._last_rx_ms
+                if last == 0:
+                    continue
+                if (time.time() * 1000 - last) >= HEARTBEAT_RECEIVE_TIMEOUT * 1000:
+                    self._handle_heartbeat_timeout()
+                    return
+
+        self._heartbeat_thread = threading.Thread(target=run, daemon=True)
+        self._heartbeat_thread.start()
+
+    def _handle_heartbeat_timeout(self) -> None:
+        self._stop_heartbeat()
+        self._pending_disconnect_code = ClientErrorCode.PING_TIMEOUT
+        self._close_conn()
+
+    def _begin_reconnect_backoff(self) -> None:
+        if not self.auto_reconnect or self._suppress_auto_reconnect:
+            return
+        if not self.token:
+            return
+        with self._reconnect_lock:
+            if self._reconnect_busy:
+                return
+            self._reconnect_busy = True
+        threading.Thread(target=self._run_reconnect_backoff, daemon=True).start()
+
+    def _run_reconnect_backoff(self) -> None:
+        try:
+            while self.auto_reconnect and not self._suppress_auto_reconnect and self.token:
+                if self.get_state() != ConnectState.DISCONNECT:
+                    return
+                delay = self._reconnect_backoff.next_delay()
+                time.sleep(delay)
+                if self._suppress_auto_reconnect:
+                    return
+                if self.get_state() != ConnectState.DISCONNECT:
+                    return
+                code, ack = self.connect(self.token)
+                if code == ClientErrorCode.SUCCESS:
+                    return
+                if self._terminal_connect_failure(code, ack):
+                    return
+        finally:
+            with self._reconnect_lock:
+                self._reconnect_busy = False
+
+    @staticmethod
+    def _terminal_connect_failure(code: int, ack) -> bool:
+        if code == ClientErrorCode.CONNECT_EXISTED:
+            return True
+        if ack is not None and ack.code != IM_ERROR_CODE_SUCCESS:
+            return True
+        return False
+
+    def _handle_read_loop_ended(self, _exc) -> None:
+        self._stop_heartbeat()
+        had_session = self._handshake_complete
+        self._handshake_complete = False
+        already_disconnected = self._state == ConnectState.DISCONNECT
+        self._close_conn()
+        code = ClientErrorCode.CONNECT_CLOSED
+        if self._pending_disconnect_code != 0:
+            code = self._pending_disconnect_code
+            self._pending_disconnect_code = 0
+        if not already_disconnected:
+            self._change_connection_status(ConnectState.DISCONNECT, code)
+        if (
+            not already_disconnected
+            and had_session
+            and self.auto_reconnect
+            and not self._suppress_auto_reconnect
+            and self.token
+        ):
+            self._begin_reconnect_backoff()
+
+    # ------------------------------------------------------------------
+    # message sending & listeners
+    # ------------------------------------------------------------------
+    def add_message_listener(self, listener: MessageListener) -> None:
+        if listener is not None:
+            self._message_listeners.append(listener)
+
+    def send_message(self, conver: Conversation, up_msg) -> Tuple[int, Optional[object]]:
+        """Send an UpMsg to a conversation."""
+        if conver is None or up_msg is None or not conver.conversation:
+            return ClientErrorCode.UNKNOWN, None
+        topic = {
+            pb.Private: "p_msg",
+            pb.Group: "g_msg",
+            pb.Chatroom: "c_msg",
+            pb.PublicChannel: "pc_msg",
+        }.get(conver.conversation_type)
+        if topic is None:
+            return ClientErrorCode.UNKNOWN, None
+        return self.publish(topic, conver.conversation, up_msg.SerializeToString())
+
+    def build_up_msg(self, content, client_uid: str = "", **kwargs):
+        """Convenience: build a ``pb.UpMsg`` from a content model.
+
+        Encodes ``content`` (a ``messages.MessageContent``) into ``msgType`` /
+        ``msgContent`` / ``flags`` and returns a protobuf ``UpMsg``. Extra
+        protobuf fields may be passed via ``kwargs``.
+        """
+        up = pb.UpMsg(
+            msgType=content.get_content_type(),
+            msgContent=content.encode(),
+            flags=content.get_flags(),
+            clientUid=client_uid,
+        )
+        for key, value in kwargs.items():
+            setattr(up, key, value)
+        return up
+
+    def sync_msgs(self, req) -> Tuple[int, Optional[object]]:
+        code, qry_ack = self.query("sync_msgs", self.user_id, req.SerializeToString())
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = pb.DownMsgSet()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return ClientErrorCode.SUCCESS, resp
+        return ClientErrorCode.UNKNOWN, None
+
+    def add_msg_exset(self, req) -> int:
+        code, qry_ack = self.query("msg_exset", req.msgId, req.SerializeToString())
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None:
+            if qry_ack.code == IM_ERROR_CODE_SUCCESS:
+                return ClientErrorCode.SUCCESS
+            return qry_ack.code
+        return code
+
+    # --- message receive plumbing ---
+    def _notify_message_receive(self, down_msg) -> Optional[Message]:
+        msg = self._down_msg_to_message(down_msg)
+        if msg is None:
+            return None
+        for listener in self._message_listeners:
+            if listener is not None:
+                listener.on_message_receive(msg)
+        return msg
+
+    def _down_msg_to_message(self, down_msg) -> Optional[Message]:
+        if down_msg is None:
+            return None
+        return Message(
+            conversation=_conversation_from_down_msg(down_msg),
+            msg_id=down_msg.msgId,
+            has_read=down_msg.isRead,
+            msg_time=down_msg.msgTime,
+            sender_id=down_msg.senderId,
+            msg_type=down_msg.msgType,
+            msg_content=messages_pkg.decode_message_content(down_msg.msgType, down_msg.msgContent),
+            group_id=_group_id_from_down_msg(down_msg),
+            refered_message=self._down_msg_to_message(down_msg.referMsg) if down_msg.HasField("referMsg") else None,
+            mention_info=_mention_info_from_pb(down_msg.mentionInfo) if down_msg.HasField("mentionInfo") else None,
+        )
+
+    # ------------------------------------------------------------------
+    # history & message management
+    # ------------------------------------------------------------------
+    def _query_down_msg_set(self, method, target_id, req):
+        code, qry_ack = self.query(method, target_id, req.SerializeToString())
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = pb.DownMsgSet()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return ClientErrorCode.SUCCESS, resp
+        return code, None
+
+    def _query_into(self, method, target_id, req, resp_cls):
+        data = req.SerializeToString() if req is not None else None
+        code, qry_ack = self.query(method, target_id, data)
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = resp_cls()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return ClientErrorCode.SUCCESS, resp
+        return code, None
+
+    def qry_history_msgs(self, req):
+        return self._query_down_msg_set("qry_hismsgs", req.targetId, req)
+
+    def qry_first_unread_msg(self, req):
+        return self._query_into("qry_first_unread_msg", req.targetId, req, pb.DownMsg)
+
+    def del_his_msgs(self, req):
+        code, qry_ack = self.query("del_msg", req.targetId, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def recall_msg(self, req):
+        return self.query("recall_msg", req.targetId, req.SerializeToString())
+
+    def modify_msg(self, req):
+        return self.query("modify_msg", req.targetId, req.SerializeToString())
+
+    def mark_read_msg(self, req):
+        return self.query("mark_read", self.user_id, req.SerializeToString())
+
+    def qry_his_msgs_by_ids(self, target_id, req):
+        return self._query_down_msg_set("qry_hismsg_by_ids", target_id, req)
+
+    def qry_read_msg_detail(self, req):
+        return self._query_into("qry_read_detail", req.targetId, req, pb.QryReadDetailResp)
+
+    def clean_his_msgs(self, req):
+        code, qry_ack = self.query("clean_hismsg", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def qry_merged_msgs(self, msg_id, req):
+        return self._query_down_msg_set("qry_merged_msgs", msg_id, req)
+
+    def batch_translate(self, req):
+        return self._query_into("batch_trans", self.user_id, req, pb.TransReq)
+
+    def msg_search(self, req):
+        return self._query_into("msg_search", req.targetId, req, pb.SearchMsgsResp)
+
+    def msg_global_search(self, req):
+        return self._query_into("msg_global_search", self.user_id, req, pb.BatchSearchMsgsResp)
+
+    def set_top_msg(self, req):
+        code, qry_ack = self.query("set_top_msg", req.targetId, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def del_top_msg(self, req):
+        code, qry_ack = self.query("del_top_msg", req.targetId, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def sub_stream_msg(self, req):
+        code, qry_ack = self.query("sup_stream_msg", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    # ------------------------------------------------------------------
+    # conversation APIs
+    # ------------------------------------------------------------------
+    def add_conversation_change_listener(self, listener: ConversationChangeListener) -> None:
+        if listener is not None:
+            self._conver_listeners.append(listener)
+
+    def get_conversation(self, req):
+        return self._query_into("qry_conver", self.user_id, req, pb.Conversation)
+
+    def get_total_unread_count(self, req):
+        return self._query_into("qry_total_unread_count", self.user_id, req, pb.QryTotalUnreadCountResp)
+
+    def _query_conversations(self, method, req):
+        return self._query_into(method, self.user_id, req, pb.QryConversationsResp)
+
+    def get_conversations(self, req):
+        return self._query_conversations("qry_convers", req)
+
+    def get_pc_conversations(self, req):
+        return self._query_conversations("qry_pc_convers", req)
+
+    def get_top_conversations(self, req):
+        return self._query_into("qry_top_convers", self.user_id, req, pb.QryConversationsResp)
+
+    def clear_unread_count(self, req):
+        code, qry_ack = self.query("clear_unread", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def clear_total_unread_count(self, req):
+        code, qry_ack = self.query("clear_total_unread", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def get_mention_msgs(self, req):
+        return self._query_into("qry_mention_msgs", self.user_id, req, pb.QryMentionMsgsResp)
+
+    def sync_conversations(self, req):
+        return self._query_conversations("sync_convers", req)
+
+    def set_mute(self, req):
+        code, qry_ack = self.query("undisturb_convers", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def set_conversation_top(self, req):
+        code, qry_ack = self.query("top_convers", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def delete_conversations(self, req):
+        code, qry_ack = self.query("del_convers", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def set_unread(self, req):
+        code, qry_ack = self.query("mark_unread", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def create_conversation_info(self, req):
+        code, qry_ack = self.query("add_conver", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def create_conversation_tag(self, tag_id, tag_name):
+        req = pb.UserConverTags(tags=[pb.ConverTag(tag=tag_id, tagName=tag_name)])
+        code, qry_ack = self.query("create_user_conver_tags", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def destroy_conversation_tag(self, tag_id):
+        req = pb.UserConverTags(tags=[pb.ConverTag(tag=tag_id)])
+        code, qry_ack = self.query("del_user_conver_tags", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def update_conversation_tag_name(self, tag_id, tag_name):
+        return self.create_conversation_tag(tag_id, tag_name)
+
+    def get_conversation_tag_list(self):
+        code, qry_ack = self.query("qry_user_conver_tags", self.user_id, None)
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = pb.UserConverTags()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return ClientErrorCode.SUCCESS, resp
+        return code, None
+
+    def add_conversations_to_tag(self, req):
+        code, qry_ack = self.query("tag_add_convers", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def remove_conversations_from_tag(self, req):
+        code, qry_ack = self.query("tag_del_convers", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    # --- conversation change plumbing ---
+    def _notify_conversation_for_message(self, msg, down_msg) -> None:
+        if msg is None or msg.conversation is None:
+            return
+        info = _conversation_info_from_message(msg, down_msg)
+        key = _conversation_key(msg.conversation)
+        existed = key in self._conver_cache
+        self._conver_cache[key] = info
+        if existed:
+            self._notify_conversation_info_update([info])
+        else:
+            self._notify_conversation_info_add([info])
+        if down_msg is not None and not down_msg.isSend and not down_msg.isRead:
+            self._total_unread_count += 1
+            self._notify_total_unread_message_count_update(self._total_unread_count)
+
+    def _notify_conversation_info_add(self, convers):
+        for listener in self._conver_listeners:
+            if listener is not None:
+                listener.on_conversation_info_add(convers)
+
+    def _notify_conversation_info_update(self, convers):
+        for listener in self._conver_listeners:
+            if listener is not None:
+                listener.on_conversation_info_update(convers)
+
+    def _notify_conversation_info_delete(self, convers):
+        for listener in self._conver_listeners:
+            if listener is not None:
+                listener.on_conversation_info_delete(convers)
+
+    def _notify_total_unread_message_count_update(self, count):
+        for listener in self._conver_listeners:
+            if listener is not None:
+                listener.on_total_unread_message_count_update(count)
+
+    # ------------------------------------------------------------------
+    # user / friend / status
+    # ------------------------------------------------------------------
+    def fetch_user_info(self, user_id):
+        req = pb.UserIdReq(userId=user_id)
+        return self._query_into("qry_user_info", user_id, req, pb.UserInfo)
+
+    def fetch_group_info(self, group_id):
+        req = pb.GroupInfoReq(groupId=group_id)
+        return self._query_into("qry_group_info", group_id, req, pb.GroupInfo)
+
+    def fetch_friend_info(self, friend_user_id):
+        req = pb.FriendIdsReq(friendIds=[friend_user_id])
+        code, qry_ack = self.query("qry_friend_infos", self.user_id, req.SerializeToString())
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = pb.FriendInfos()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            if len(resp.items) > 0:
+                return ClientErrorCode.SUCCESS, resp.items[0]
+            return ClientErrorCode.SUCCESS, None
+        return code, None
+
+    def get_user_status(self, req):
+        return self._query_into("qry_user_status", self.user_id, req, pb.UserStatusList)
+
+    def subscribe_user_status(self, req):
+        code, qry_ack = self.query("sub_user_status", self.user_id, req.SerializeToString())
+        if code != ClientErrorCode.SUCCESS or qry_ack is None:
+            return code, None
+        if qry_ack.code != IM_ERROR_CODE_SUCCESS:
+            return qry_ack.code, None
+        resp = pb.UserStatusList()
+        try:
+            resp.ParseFromString(qry_ack.data)
+        except Exception:  # noqa: BLE001
+            return ClientErrorCode.UNKNOWN, None
+        return ClientErrorCode.SUCCESS, resp
+
+    def unsubscribe_user_status(self, req):
+        code, qry_ack = self.query("unsub_user_status", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def pub_user_status(self, up_msg):
+        return self.publish("pub_user_status", self.user_id, up_msg.SerializeToString())
+
+    def set_user_undisturb(self, req):
+        code, qry_ack = self.query("set_user_undisturb", self.user_id, req.SerializeToString())
+        return _ack_code(code, qry_ack)
+
+    def get_user_undisturb(self):
+        code, qry_ack = self.query("get_user_undisturb", self.user_id, pb.Nil().SerializeToString())
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            resp = pb.UserUndisturb()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return ClientErrorCode.SUCCESS, resp
+        return code, None
+
+    # ------------------------------------------------------------------
+    # chatroom
+    # ------------------------------------------------------------------
+    def join_chatroom(self, chatroom_id):
+        return self.join_chatroom_with_options(chatroom_id, -1, False)
+
+    def join_chatroom_with_prev_count(self, chatroom_id, prev_message_count):
+        return self.join_chatroom_with_options(chatroom_id, prev_message_count, False)
+
+    def join_chatroom_with_options(self, chatroom_id, prev_message_count, is_auto_create):
+        req = chatpb.ChatroomReq(chatId=chatroom_id, isAutoCreate=is_auto_create)
+        code, _ = self.query("c_join", chatroom_id, req.SerializeToString())
+        return code
+
+    def join_chatroom_auto_create(self, chatroom_id, is_auto_create):
+        return self.join_chatroom_with_options(chatroom_id, -1, is_auto_create)
+
+    def quit_chatroom(self, chatroom_id):
+        req = chatpb.ChatroomReq(chatId=chatroom_id)
+        code, _ = self.query("c_quit", chatroom_id, req.SerializeToString())
+        return code
+
+    def send_chatroom_msg(self, chatroom_id, up_msg):
+        return self.send_message(
+            Conversation(conversation_type=pb.Chatroom, conversation=chatroom_id), up_msg
+        )
+
+    def set_attributes(self, chatroom_id, attributes):
+        if not attributes:
+            return ClientErrorCode.SUCCESS, chatpb.ChatAttBatchResp()
+        atts = [chatpb.ChatAttReq(key=k, value=v, isForce=False) for k, v in attributes.items()]
+        req = chatpb.ChatAttBatchReq(atts=atts)
+        return self._chat_att_batch("c_batch_add_att", chatroom_id, req)
+
+    def remove_attributes(self, chatroom_id, keys):
+        if not keys:
+            return ClientErrorCode.SUCCESS, chatpb.ChatAttBatchResp()
+        atts = [chatpb.ChatAttReq(key=k, isForce=False) for k in keys]
+        req = chatpb.ChatAttBatchReq(atts=atts)
+        return self._chat_att_batch("c_batch_del_att", chatroom_id, req)
+
+    def _chat_att_batch(self, method, chatroom_id, req):
+        return self._query_into(method, chatroom_id, req, chatpb.ChatAttBatchResp)
+
+    def sync_chatroom_msgs(self, req):
+        code, resp = self._query_into("c_sync_msgs", req.chatroomId, req, chatpb.SyncChatroomMsgResp)
+        return (code, resp) if code == ClientErrorCode.SUCCESS else (ClientErrorCode.UNKNOWN, None)
+
+    def sync_chatroom_exts(self, req):
+        code, resp = self._query_into("c_sync_atts", req.chatroomId, req, chatpb.SyncChatroomAttResp)
+        return (code, resp) if code == ClientErrorCode.SUCCESS else (ClientErrorCode.UNKNOWN, None)
+
+    def add_chat_att(self, target_id, att):
+        return self._query_into("c_add_att", target_id, att, chatpb.ChatAttResp)
+
+    def del_chat_att(self, target_id, att):
+        return self._query_into("c_del_att", target_id, att, chatpb.ChatAttResp)
+
+    # ------------------------------------------------------------------
+    # rtc room
+    # ------------------------------------------------------------------
+    def create_rtc_room(self, room):
+        return self._query_into("rtc_create", self.user_id, room, rtcpb.RtcRoom)
+
+    def destroy_rtc_room(self, room_id):
+        code, _ = self.query("rtc_destroy", room_id, b"")
+        return code
+
+    def join_rtc_room(self, room):
+        code, qry_ack = self.query("rtc_join", room.roomId, room.SerializeToString())
+        if (code == ClientErrorCode.SUCCESS or code == RTC_JOIN_ALREADY_IN_ROOM) and qry_ack is not None:
+            resp = rtcpb.RtcRoom()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return code, resp
+        return code, None
+
+    def quit_rtc_room(self, room_id):
+        code, _ = self.query("rtc_quit", room_id, b"")
+        return code
+
+    def qry_rtc_room(self, room_id):
+        code, qry_ack = self.query("rtc_qry", room_id, None)
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None:
+            resp = rtcpb.RtcRoom()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return code, resp
+        return code, None
+
+    def rtc_room_ping(self, room_id):
+        code, _ = self.query("rtc_ping", room_id, None)
+        return code
+
+    def rtc_invite(self, req):
+        return self._query_into("rtc_invite", self.user_id, req, rtcpb.RtcAuth)
+
+    def qry_rtc_member_rooms(self):
+        code, qry_ack = self.query("rtc_member_rooms", self.user_id, None)
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None:
+            resp = rtcpb.RtcMemberRooms()
+            try:
+                resp.ParseFromString(qry_ack.data)
+            except Exception:  # noqa: BLE001
+                return ClientErrorCode.UNKNOWN, None
+            return code, resp
+        return code, None
+
+    def rtc_hangup(self, room_id):
+        code, qry_ack = self.query("rtc_hangup", room_id, None)
+        if code == ClientErrorCode.SUCCESS and qry_ack is not None and qry_ack.code == IM_ERROR_CODE_SUCCESS:
+            return ClientErrorCode.SUCCESS
+        if code != ClientErrorCode.SUCCESS:
+            return code
+        if qry_ack is not None:
+            return qry_ack.code
+        return ClientErrorCode.UNKNOWN
+
+    # ------------------------------------------------------------------
+    # file
+    # ------------------------------------------------------------------
+    def get_file_cred(self, req):
+        return self._query_into("file_cred", self.user_id, req, pb.QryFileCredResp)
+
+
+# ----------------------------------------------------------------------
+# module-level helpers
+# ----------------------------------------------------------------------
+def _conversation_from_down_msg(down_msg) -> Optional[Conversation]:
+    if down_msg is None:
+        return None
+    return Conversation(
+        conversation=down_msg.targetId,
+        conversation_type=down_msg.channelType,
+        sub_channel=down_msg.subChannel,
+    )
+
+
+def _mention_info_from_pb(info) -> Optional[MessageMentionInfo]:
+    if info is None:
+        return None
+    target_user_ids = [u.userId for u in info.targetUsers if u.userId]
+    return MessageMentionInfo(mention_type=info.mentionType, target_user_ids=target_user_ids)
+
+
+def _group_id_from_down_msg(down_msg) -> str:
+    if down_msg is None:
+        return ""
+    if down_msg.channelType == pb.Group:
+        return down_msg.targetId
+    if down_msg.HasField("groupInfo"):
+        return down_msg.groupInfo.groupId
+    return ""
+
+
+def _conversation_info_from_message(msg, down_msg) -> ConversationInfo:
+    info = ConversationInfo(
+        conversation=msg.conversation,
+        latest_message=msg,
+        sort_time=msg.msg_time,
+    )
+    if down_msg is None:
+        return info
+    info.unread_count = 0 if (down_msg.isSend or down_msg.isRead) else 1
+    if down_msg.HasField("mentionInfo"):
+        info.mention_info = ConversationMentionInfo(
+            sender_id=down_msg.senderId,
+            msg_id=down_msg.msgId,
+            msg_time=down_msg.msgTime,
+            mention_type=down_msg.mentionInfo.mentionType,
+        )
+    if down_msg.HasField("targetUserInfo"):
+        info.display_name = down_msg.targetUserInfo.nickname
+        info.portrait = down_msg.targetUserInfo.userPortrait
+    if down_msg.HasField("groupInfo"):
+        info.display_name = down_msg.groupInfo.groupName
+        info.portrait = down_msg.groupInfo.groupPortrait
+        info.mute = down_msg.groupInfo.isMute > 0
+    return info
+
+
+def _conversation_key(conver: Conversation) -> str:
+    if conver is None:
+        return ""
+    return "%d:%s:%s" % (int(conver.conversation_type), conver.conversation, conver.sub_channel)