Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(feishu): dispatch card actions on supported WebSocket SDKs

Bingxi Zhao (Frank)0843e7d51828
diff --git a/deeptutor/partners/channels/feishu.py b/deeptutor/partners/channels/feishu.py
index f7d06972c..53de22a66 100644
--- a/deeptutor/partners/channels/feishu.py
+++ b/deeptutor/partners/channels/feishu.py
@@ -1,9 +1,12 @@
"""Feishu/Lark channel implementation using lark-oapi SDK with WebSocket long connection."""
import asyncio
+import base64
from collections import OrderedDict
from dataclasses import dataclass
+from http import HTTPStatus
import importlib.util
+import inspect
import json
import os
import re
@@ -25,6 +28,54 @@ from deeptutor.partners.helpers import split_markdown_table_row
FEISHU_AVAILABLE = importlib.util.find_spec("lark_oapi") is not None
+
+def _card_aware_ws_client(base_client: type[Any], ws_module: Any) -> type[Any]:
+ """Dispatch card callbacks skipped by supported lark-oapi WebSocket clients.
+
+ The SDK's event dispatcher already understands card actions; older WS
+ clients return before calling it. Keep the original CARD frame type when
+ writing the callback response so Feishu can replace the clicked card.
+ """
+
+ class CardAwareClient(base_client):
+ async def _handle_data_frame(self, frame: Any) -> None:
+ message_type = ws_module._get_by_key(frame.headers, ws_module.HEADER_TYPE)
+ if message_type != ws_module.MessageType.CARD.value:
+ await super()._handle_data_frame(frame)
+ return
+
+ headers = frame.headers
+ message_id = ws_module._get_by_key(headers, ws_module.HEADER_MESSAGE_ID)
+ part_count = int(ws_module._get_by_key(headers, ws_module.HEADER_SUM))
+ part_number = int(ws_module._get_by_key(headers, ws_module.HEADER_SEQ))
+ payload = frame.payload
+ if part_count > 1:
+ payload = self._combine(message_id, part_count, part_number, payload)
+ if payload is None:
+ return
+
+ response = ws_module.Response(code=HTTPStatus.OK)
+ try:
+ started = time.monotonic()
+ result = self._event_handler.do_without_validation(payload)
+ elapsed_ms = round((time.monotonic() - started) * 1000)
+ header = headers.add()
+ header.key = ws_module.HEADER_BIZ_RT
+ header.value = str(elapsed_ms)
+ if result is not None:
+ response.data = base64.b64encode(
+ ws_module.JSON.marshal(result).encode(ws_module.UTF_8)
+ )
+ except Exception:
+ logger.exception("Feishu card callback failed (message_id={})", message_id)
+ response = ws_module.Response(code=HTTPStatus.INTERNAL_SERVER_ERROR)
+
+ frame.payload = ws_module.JSON.marshal(response).encode(ws_module.UTF_8)
+ await self._write_message(frame.SerializeToString())
+
+ return CardAwareClient
+
+
# Message type display mapping
MSG_TYPE_MAP = {
"image": "[image]",
@@ -319,6 +370,7 @@ class FeishuChannel(BaseChannel):
self._confirmed_streams: OrderedDict[str, None] = OrderedDict()
self._working_reactions: OrderedDict[str, tuple[str, float]] = OrderedDict()
self._reaction_cleanup_tasks: dict[tuple[str, str], asyncio.Task[None]] = {}
+ self._reaction_expiry_tasks: dict[str, asyncio.Task[None]] = {}
self._model_pickers: OrderedDict[str, _ModelPicker] = OrderedDict()
self._model_picker_lock = Lock()
self._loop: asyncio.AbstractEventLoop | None = None
@@ -373,6 +425,8 @@ class FeishuChannel(BaseChannel):
import lark_oapi as lark
from lark_oapi.core.const import FEISHU_DOMAIN, LARK_DOMAIN
+ ws_module = lark.ws.client
+
self._running = True
self._loop = asyncio.get_running_loop()
sdk_domain = LARK_DOMAIN if self.config.domain == "lark" else FEISHU_DOMAIN
@@ -406,16 +460,22 @@ class FeishuChannel(BaseChannel):
)
event_handler = builder.build()
- # Create WebSocket client for long connection
- self._ws_client = lark.ws.Client(
+ # The supported SDK's WS client drops CARD frames before its callback
+ # dispatcher runs. Route those frames while preserving the SDK's normal
+ # EVENT path and response envelope.
+ ws_client_cls = _card_aware_ws_client(lark.ws.Client, ws_module)
+ ws_kwargs: dict[str, Any] = {
+ "event_handler": event_handler,
+ "log_level": lark.LogLevel.INFO,
+ "domain": sdk_domain,
+ }
+ # extra_ua_tags was added after the minimum supported SDK version.
+ if "extra_ua_tags" in inspect.signature(lark.ws.Client.__init__).parameters:
+ ws_kwargs["extra_ua_tags"] = ["channel"]
+ self._ws_client = ws_client_cls(
self.config.app_id,
self.config.app_secret,
- event_handler=event_handler,
- log_level=lark.LogLevel.INFO,
- domain=sdk_domain,
- # Without this tag Feishu uses the personal-client protocol and may
- # omit group @mention events over WebSocket.
- extra_ua_tags=["channel"],
+ **ws_kwargs,
)
# Start WebSocket client in a separate thread with reconnect loop.
@@ -469,12 +529,16 @@ class FeishuChannel(BaseChannel):
"""
self._running = False
self._confirmed_streams.clear()
- cleanup_tasks = list(self._reaction_cleanup_tasks.values())
+ cleanup_tasks = [
+ *self._reaction_cleanup_tasks.values(),
+ *self._reaction_expiry_tasks.values(),
+ ]
for task in cleanup_tasks:
task.cancel()
if cleanup_tasks:
await asyncio.gather(*cleanup_tasks, return_exceptions=True)
self._reaction_cleanup_tasks.clear()
+ self._reaction_expiry_tasks.clear()
self._working_reactions.clear()
with self._model_picker_lock:
self._model_pickers.clear()
@@ -548,7 +612,11 @@ class FeishuChannel(BaseChannel):
and now - created_at < self._WORKING_REACTION_TTL
):
break
- expired.append(self._working_reactions.popitem(last=False))
+ message_id, receipt = self._working_reactions.popitem(last=False)
+ expiry_task = self._reaction_expiry_tasks.pop(message_id, None)
+ if expiry_task:
+ expiry_task.cancel()
+ expired.append((message_id, receipt))
return expired
def _remove_reaction_sync(self, message_id: str, reaction_id: str) -> bool:
@@ -577,6 +645,26 @@ class FeishuChannel(BaseChannel):
loop = asyncio.get_running_loop()
return await loop.run_in_executor(None, self._remove_reaction_sync, message_id, reaction_id)
+ def _clear_reaction_receipt(self, message_id: str, receipt: tuple[str, float]) -> None:
+ if self._working_reactions.get(message_id) != receipt:
+ return
+ self._working_reactions.pop(message_id, None)
+ expiry_task = self._reaction_expiry_tasks.pop(message_id, None)
+ if expiry_task and expiry_task is not asyncio.current_task():
+ expiry_task.cancel()
+
+ def _schedule_reaction_expiry(self, message_id: str, receipt: tuple[str, float]) -> None:
+ async def expire() -> None:
+ try:
+ await asyncio.sleep(self._WORKING_REACTION_TTL)
+ if self._working_reactions.get(message_id) == receipt:
+ await self._finish_reaction(message_id)
+ finally:
+ if self._reaction_expiry_tasks.get(message_id) is asyncio.current_task():
+ self._reaction_expiry_tasks.pop(message_id, None)
+
+ self._reaction_expiry_tasks[message_id] = asyncio.create_task(expire())
+
def _schedule_reaction_cleanup(self, message_id: str, receipt: tuple[str, float]) -> None:
key = (message_id, receipt[0])
if key in self._reaction_cleanup_tasks:
@@ -590,8 +678,7 @@ class FeishuChannel(BaseChannel):
if not self._client:
return
if await self._delete_reaction(*key):
- if self._working_reactions.get(message_id) == receipt:
- self._working_reactions.pop(message_id, None)
+ self._clear_reaction_receipt(message_id, receipt)
return
finally:
self._reaction_cleanup_tasks.pop(key, None)
@@ -607,8 +694,7 @@ class FeishuChannel(BaseChannel):
if delay:
await asyncio.sleep(delay)
if await self._delete_reaction(message_id, reaction_id):
- if self._working_reactions.get(message_id) == receipt:
- self._working_reactions.pop(message_id, None)
+ self._clear_reaction_receipt(message_id, receipt)
return
self._schedule_reaction_cleanup(message_id, receipt)
@@ -626,7 +712,15 @@ class FeishuChannel(BaseChannel):
None, self._add_reaction_sync, message_id, emoji_type
)
if reaction_id:
- self._working_reactions[message_id] = (reaction_id, time.monotonic())
+ previous = self._working_reactions.get(message_id)
+ if previous:
+ previous_expiry = self._reaction_expiry_tasks.pop(message_id, None)
+ if previous_expiry:
+ previous_expiry.cancel()
+ self._schedule_reaction_cleanup(message_id, previous)
+ receipt = (reaction_id, time.monotonic())
+ self._working_reactions[message_id] = receipt
+ self._schedule_reaction_expiry(message_id, receipt)
for old_message_id, old_receipt in self._prune_working_reactions():
self._schedule_reaction_cleanup(old_message_id, old_receipt)
diff --git a/tests/services/partners/test_feishu_domain_initialization.py b/tests/services/partners/test_feishu_domain_initialization.py
index 0d0b5beeb..78c33075a 100644
--- a/tests/services/partners/test_feishu_domain_initialization.py
+++ b/tests/services/partners/test_feishu_domain_initialization.py
@@ -48,14 +48,16 @@ async def test_feishu_channel_selects_domain_for_rest_and_websocket_clients(
return _Chain(event_calls, object())
class WSClient:
- def __init__(self, *args: Any, **kwargs: Any) -> None:
- ws_clients.append({"args": args, "kwargs": kwargs})
+ def __init__(
+ self, *args: Any, extra_ua_tags: list[str] | None = None, **kwargs: Any
+ ) -> None:
+ ws_clients.append({"args": args, "kwargs": {**kwargs, "extra_ua_tags": extra_ua_tags}})
lark = SimpleNamespace(
Client=Client,
EventDispatcherHandler=EventDispatcherHandler,
LogLevel=SimpleNamespace(INFO="INFO"),
- ws=SimpleNamespace(Client=WSClient),
+ ws=SimpleNamespace(Client=WSClient, client=SimpleNamespace()),
)
const = SimpleNamespace(FEISHU_DOMAIN="FEISHU_DOMAIN", LARK_DOMAIN="LARK_DOMAIN")
diff --git a/tests/services/partners/test_feishu_final_delivery.py b/tests/services/partners/test_feishu_final_delivery.py
index 2529b3a1a..f493fa3f1 100644
--- a/tests/services/partners/test_feishu_final_delivery.py
+++ b/tests/services/partners/test_feishu_final_delivery.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import asyncio
import time
from types import SimpleNamespace
from unittest.mock import MagicMock
@@ -96,3 +97,18 @@ async def test_long_turn_still_removes_its_working_reaction() -> None:
channel._remove_reaction_sync.assert_called_once_with("om_user", "reaction-1")
assert "om_user" not in channel._working_reactions
+
+
+async def test_abandoned_turn_reaction_expires_without_another_message() -> None:
+ channel = _channel()
+ channel._WORKING_REACTION_TTL = 0.01
+ channel._add_reaction_sync = MagicMock(return_value="reaction-1")
+ channel._remove_reaction_sync = MagicMock(return_value=True)
+
+ await channel._add_reaction("om_user")
+ expiry = channel._reaction_expiry_tasks["om_user"]
+ await asyncio.wait_for(expiry, timeout=1)
+
+ channel._remove_reaction_sync.assert_called_once_with("om_user", "reaction-1")
+ assert "om_user" not in channel._working_reactions
diff --git a/tests/services/partners/test_feishu_ws_card_callback.py b/tests/services/partners/test_feishu_ws_card_callback.py
new file mode 100644
index 000000000..abf07a1e0
--- /dev/null
+++ b/tests/services/partners/test_feishu_ws_card_callback.py
@@ -0,0 +1,124 @@
+"""Card actions must reach the handler over the configured Feishu WS transport."""
+
+from __future__ import annotations
+
+import base64
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from deeptutor.partners.channels.feishu import _card_aware_ws_client
+
+
+def _card_frame(ws_module, payload: bytes):
+ frame = ws_module.Frame()
+ frame.SeqID = 1
+ frame.LogID = 1
+ frame.service = 1
+ frame.method = 1
+ for key, value in (
+ (ws_module.HEADER_TYPE, ws_module.MessageType.CARD.value),
+ (ws_module.HEADER_MESSAGE_ID, "card-action-1"),
+ (ws_module.HEADER_SUM, "1"),
+ (ws_module.HEADER_SEQ, "0"),
+ ):
+ header = frame.headers.add()
+ header.key = key
+ header.value = value
+ frame.payload = payload
+ return frame
+
+
+async def test_card_frame_dispatches_and_returns_in_place_card_response() -> None:
+ lark = pytest.importorskip("lark_oapi")
+ import lark_oapi.ws.client as ws_module
+
+ client_type = _card_aware_ws_client(lark.ws.Client, ws_module)
+ client = object.__new__(client_type)
+ response_card = {"card": {"type": "raw", "data": {"elements": []}}}
+ client._event_handler = SimpleNamespace(
+ do_without_validation=MagicMock(return_value=response_card)
+ )
+ client._write_message = AsyncMock()
+ frame = _card_frame(ws_module, b'{"type":"card.action.trigger"}')
+
+ await client._handle_data_frame(frame)
+
+ client._event_handler.do_without_validation.assert_called_once_with(
+ b'{"type":"card.action.trigger"}'
+ )
+ client._write_message.assert_awaited_once()
+ sent = ws_module.Frame.FromString(client._write_message.await_args.args[0])
+ assert ws_module._get_by_key(sent.headers, ws_module.HEADER_TYPE) == "card"
+ envelope = json.loads(sent.payload)
+ assert envelope["code"] == 200
+ assert json.loads(base64.b64decode(envelope["data"])) == response_card
+
+
+async def test_card_callback_failure_returns_error_frame() -> None:
+ lark = pytest.importorskip("lark_oapi")
+ import lark_oapi.ws.client as ws_module
+
+ client = object.__new__(_card_aware_ws_client(lark.ws.Client, ws_module))
+ client._event_handler = SimpleNamespace(
+ do_without_validation=MagicMock(side_effect=ValueError("invalid callback"))
+ )
+ client._write_message = AsyncMock()
+
+ await client._handle_data_frame(_card_frame(ws_module, b"{}"))
+
+ sent = ws_module.Frame.FromString(client._write_message.await_args.args[0])
+ assert json.loads(sent.payload)["code"] == 500
+
+
+async def test_real_sdk_dispatcher_routes_card_action_over_websocket() -> None:
+ lark = pytest.importorskip("lark_oapi")
+ from lark_oapi.event.callback.model.p2_card_action_trigger import (
+ CallBackCard,
+ P2CardActionTriggerResponse,
+ )
+ import lark_oapi.ws.client as ws_module
+
+ callback = MagicMock()
+
+ def handle(data):
+ callback(data)
+ result = P2CardActionTriggerResponse()
+ result.card = CallBackCard()
+ result.card.type = "raw"
+ result.card.data = {"elements": []}
+ return result
+
+ handler = (
+ lark.EventDispatcherHandler.builder("", "").register_p2_card_action_trigger(handle).build()
+ )
+ client = object.__new__(_card_aware_ws_client(lark.ws.Client, ws_module))
+ client._event_handler = handler
+ client._write_message = AsyncMock()
+ payload = json.dumps(
+ {
+ "schema": "2.0",
+ "header": {"event_type": "card.action.trigger", "token": ""},
+ "event": {
+ "operator": {"open_id": "ou_owner"},
+ "action": {"value": {"picker_id": "picker-1", "action": "page", "page": 1}},
+ "context": {"open_message_id": "om_picker"},
+ },
+ }
+ ).encode()
+
+ await client._handle_data_frame(_card_frame(ws_module, payload))
+
+ callback.assert_called_once()
+ assert callback.call_args.args[0].event.operator.open_id == "ou_owner"
+ sent = ws_module.Frame.FromString(client._write_message.await_args.args[0])
+ envelope = json.loads(sent.payload)
+ assert envelope["code"] == 200
+ assert json.loads(base64.b64decode(envelope["data"])) == {
+ "card": {"type": "raw", "data": {"elements": []}}
+ }