Skip to content

Build and run agents you can see, understand and trust.

feat(channel): hold the long connections in a dedicated worker (#2390)

DavdGaofb78a31eb5c1
diff --git a/src/agentscope/app/_app.py b/src/agentscope/app/_app.py
index 091a17d13..60e319d5d 100644
--- a/src/agentscope/app/_app.py
+++ b/src/agentscope/app/_app.py
@@ -87,6 +87,7 @@ def create_app(
mcp_hubs: list[MCPHubBase] | None = None,
skill_hubs: list[SkillHubBase] | None = None,
*,
+ enable_channel_worker: bool = True,
extra_credentials: list[Type[CredentialBase]] | None = None,
extra_middlewares: list[FastAPIMiddleware] | None = None,
extra_agent_middlewares: AgentMiddlewareFactory | None = None,
@@ -189,6 +190,15 @@ def create_app(
The MCP hubs that provide MCPs.
skill_hubs (`list[SkillHubBase] | None`, optional):
The SkillHubs that provide skills.
+ enable_channel_worker (`bool`, defaults to ``True``):
+ Whether this process holds the channels' long connections.
+ ``True`` (embedded deployment) suits a desktop build or a
+ single API process. Set ``False`` when running dedicated
+ channel workers: a platform gives one bot's events to one
+ connection, so every replica connecting would either waste
+ connections or duplicate messages. The channel API, the
+ client factory and webhook delivery stay available either
+ way — only the connections move.
extra_credentials (`list[Type[CredentialBase]] | None`, optional):
Additional :class:`~agentscope.credential.CredentialBase`
subclasses to register before the app starts. Equivalent to
@@ -347,6 +357,7 @@ def create_app(
app.state.enable_index_worker = (
enable_index_worker and knowledge_base_manager is not None
)
+ app.state.enable_channel_worker = enable_channel_worker
# Validate custom sub-agent templates for duplicate types and store in
# app.state
diff --git a/src/agentscope/app/_lifespan.py b/src/agentscope/app/_lifespan.py
index bd46ff9bd..f5050e14e 100644
--- a/src/agentscope/app/_lifespan.py
+++ b/src/agentscope/app/_lifespan.py
@@ -49,6 +49,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
knowledge_base_manager = app.state.knowledge_base_manager
blob_store = app.state.blob_store
enable_index_worker = app.state.enable_index_worker
+ enable_channel_worker = app.state.enable_channel_worker
resource_access_policy = app.state.resource_access_policy
async with AsyncExitStack() as stack:
@@ -104,12 +105,12 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
app.state.resource_access_service = resource_access_service
# Channel wiring is built here (before ChatService) so the chat
- # service can hand the dispatcher to get_toolkit: a session that
- # came from a channel gets that channel's platform tools. The
- # type registry has no lifecycle and was built in create_app; the
- # reconcile/heartbeat loops start later via the dispatcher's
- # lifespan context.
+ # service can hand the client factory to get_toolkit: a session
+ # that came from a channel gets that channel's platform tools.
+ # The clients hold no connection, so they exist in every process
+ # regardless of who runs the dispatcher.
from .channel import (
+ ChannelClients,
ChannelGateway,
ChannelLifecycleDispatcher,
)
@@ -118,16 +119,13 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
# registered — otherwise the dispatcher's reconcile would hit
# storage backends that don't implement channel methods.
channel_type_registry = app.state.channel_type_registry
+ channel_clients = None
channel_dispatcher = None
if channel_type_registry:
- channel_dispatcher = ChannelLifecycleDispatcher(
- storage=storage,
- message_bus=message_bus,
- type_registry=channel_type_registry,
- gateway=ChannelGateway(
+ channel_clients = await stack.enter_async_context(
+ ChannelClients(
storage=storage,
- message_bus=message_bus,
- workspace_manager=workspace_manager,
+ type_registry=channel_type_registry,
),
)
app.state.channel_service = ChannelService(
@@ -135,6 +133,21 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
message_bus=message_bus,
type_registry=channel_type_registry,
)
+ # The dispatcher is what holds the long connections, so a
+ # deployment that runs dedicated channel workers turns it
+ # off here and every replica stays connection-free.
+ if enable_channel_worker:
+ channel_dispatcher = ChannelLifecycleDispatcher(
+ storage=storage,
+ message_bus=message_bus,
+ type_registry=channel_type_registry,
+ gateway=ChannelGateway(
+ storage=storage,
+ message_bus=message_bus,
+ workspace_manager=workspace_manager,
+ ),
+ )
+ app.state.channel_clients = channel_clients
app.state.channel_dispatcher = channel_dispatcher
chat_service = ChatService(
@@ -149,7 +162,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
extra_agent_tools=app.state.extra_agent_tools,
custom_subagent_templates=app.state.custom_subagent_templates,
custom_agent_cls=app.state.custom_agent_cls,
- channel_dispatcher=channel_dispatcher,
+ channel_clients=channel_clients,
)
app.state.chat_service = chat_service
diff --git a/src/agentscope/app/_router/_channel.py b/src/agentscope/app/_router/_channel.py
index 1e71008d3..338d1295a 100644
--- a/src/agentscope/app/_router/_channel.py
+++ b/src/agentscope/app/_router/_channel.py
@@ -16,14 +16,14 @@ from fastapi import APIRouter, Depends, HTTPException, status
from ..channel import (
ChannelError,
- ChannelLifecycleDispatcher,
+ ChannelClients,
ChannelStatus,
ChannelTypeRegistry,
ChannelTypeSchema,
)
from .._service import ChannelService
from ..deps import (
- get_channel_dispatcher,
+ get_channel_clients,
get_channel_service,
get_channel_type_registry,
get_current_user_id,
@@ -232,12 +232,13 @@ async def disable_channel(
async def channel_status(
channel_id: str,
storage: StorageBase = Depends(get_storage),
- dispatcher: ChannelLifecycleDispatcher = Depends(get_channel_dispatcher),
+ service: ChannelService = Depends(get_channel_service),
user_id: str = Depends(get_current_user_id),
) -> ChannelStatus:
- """The channel's live connection status."""
+ """The channel's live connection status, from whichever node holds
+ it — this replica need not be the one connected."""
await _owned(channel_id, user_id, storage)
- return await dispatcher.get_status(channel_id)
+ return await service.get_status(channel_id)
@channel_router.get("/{channel_id}/sessions")
@@ -256,14 +257,20 @@ async def list_channel_sessions(
async def list_chat_ids(
channel_id: str,
storage: StorageBase = Depends(get_storage),
- dispatcher: ChannelLifecycleDispatcher = Depends(get_channel_dispatcher),
+ service: ChannelService = Depends(get_channel_service),
+ clients: ChannelClients = Depends(get_channel_clients),
user_id: str = Depends(get_current_user_id),
) -> ChannelChatIdsResponse:
- """Known chats for routing config: platform list ∪ passively seen."""
+ """Known chats for routing config: platform list ∪ passively seen.
+
+ The platform list is fetched over REST through a client, so it
+ answers from a replica that holds no connection.
+ """
await _owned(channel_id, user_id, storage)
chats: list[ChannelChatId] = []
platform_ids: set[str] = set()
- for chat in await dispatcher.list_bot_chats(channel_id):
+ channel = await clients.get(channel_id)
+ for chat in await channel.list_bot_chats() if channel else []:
cid = chat.get("chat_id", "")
if cid:
platform_ids.add(cid)
@@ -274,7 +281,7 @@ async def list_chat_ids(
source="platform",
),
)
- for cid in await dispatcher.list_seen_chat_ids(channel_id):
+ for cid in await service.list_seen_chat_ids(channel_id):
if cid not in platform_ids:
chats.append(ChannelChatId(chat_id=cid, source="recorded"))
return ChannelChatIdsResponse(chats=chats)
diff --git a/src/agentscope/app/_service/_channel.py b/src/agentscope/app/_service/_channel.py
index 849d34de3..bb583fae1 100644
--- a/src/agentscope/app/_service/_channel.py
+++ b/src/agentscope/app/_service/_channel.py
@@ -5,6 +5,7 @@ Validates, writes the record, and publishes a lifecycle notification so
every node's :class:`ChannelLifecycleDispatcher` reconciles its running
instances against storage. Holds no channel instances.
"""
+import time
from datetime import datetime
from ..._utils._common import _generate_id
@@ -15,6 +16,7 @@ from ..storage import (
SessionSettings,
StorageBase,
)
+from ..channel._base import ChannelHeartbeat, ChannelStatus
from ..channel._errors import ChannelError
from ..channel._registry import ChannelTypeRegistry
@@ -146,6 +148,51 @@ class ChannelService:
await self._storage.delete_channel(channel_id, bot_id)
await self._notify(channel_id)
+ # -- Read-side (cluster-wide, no local instances needed) --
+
+ async def get_status(self, channel_id: str) -> ChannelStatus:
+ """The channel's connection status, from whichever node holds it.
+
+ Nodes that run a channel heartbeat their view into a registry,
+ so this answers correctly from an API replica that holds no
+ connection. Reports older than the heartbeat TTL are ignored —
+ the namespace expires as a whole, so a node that stopped
+ reporting can leave its last entry behind indefinitely while a
+ successor keeps the namespace alive.
+
+ Args:
+ channel_id (`str`): The channel to report on.
+ """
+ try:
+ entries = await self._bus.registry_getall(
+ MessageBusKeys.channel_liveness(channel_id),
+ )
+ except Exception: # pylint: disable=broad-except
+ return ChannelStatus(state="stopped")
+
+ now = time.time()
+ best: ChannelStatus | None = None
+ for raw in entries.values():
+ beat = ChannelHeartbeat.model_validate_json(raw)
+ if not beat.is_fresh(now):
+ continue
+ if beat.status.state == "connected":
+ return beat.status
+ if best is None or best.state == "stopped":
+ best = beat.status
+ return best or ChannelStatus(state="stopped")
+
+ async def list_seen_chat_ids(self, channel_id: str) -> list[str]:
+ """Chat_ids passively recorded from inbound messages.
+
+ Args:
+ channel_id (`str`): The channel to list seen chats for.
+ """
+ fields = await self._bus.registry_getall(
+ MessageBusKeys.channel_seen_chats(channel_id),
+ )
+ return sorted(fields.keys())
+
# -- internals --
async def _require(self, channel_id: str) -> ChannelRecord:
diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.py
index f769aa533..755865e28 100644
--- a/src/agentscope/app/_service/_chat.py
+++ b/src/agentscope/app/_service/_chat.py
@@ -73,7 +73,7 @@ from ...message import AssistantMsg, HintBlock, Msg, ToolCallState
from ...permission import AdditionalWorkingDirectory
if TYPE_CHECKING:
- from ..channel import ChannelLifecycleDispatcher
+ from ..channel import ChannelClients
@dataclass(frozen=True)
@@ -125,7 +125,7 @@ class ChatService:
custom_subagent_templates: dict[str, SubAgentTemplate] | None = None,
custom_agent_cls: type[Agent] | None = None,
extra_projectors: list[EventProjector] | None = None,
- channel_dispatcher: "ChannelLifecycleDispatcher | None" = None,
+ channel_clients: "ChannelClients | None" = None,
) -> None:
"""Initialize chat service.
@@ -187,11 +187,11 @@ class ChatService:
injection style). Each is invoked once per produced
event to mirror a UI feed onto another session; see
:class:`~agentscope.app._types.EventProjector`.
- channel_dispatcher (`ChannelLifecycleDispatcher | None`, \
-optional):
- The node's channel dispatcher, forwarded to
- the run context so a channel-originated session's
- agent gets that channel's platform tools.
+ channel_clients (`ChannelClients | None`, optional):
+ Factory for unconnected channel instances, used to give
+ a channel-originated session's agent that channel's
+ platform tools and chat context. Neither needs the long
+ connection, so the run gets them wherever it lands.
"""
self._storage = storage
self._workspace_manager = workspace_manager
@@ -216,7 +216,7 @@ optional):
except (TypeError, ValueError):
pass
self._extra_agent_tools = extra_agent_tools
- self._channel_dispatcher = channel_dispatcher
+ self._channel_clients = channel_clients
self._sub_agent_templates = custom_subagent_templates
self._agent_cls = custom_agent_cls or Agent
self._projection = SessionProjection(message_bus)
@@ -771,11 +771,11 @@ optional):
# system-prompt attachment share it.
# -------------------------------------------------------------
channel = (
- self._channel_dispatcher.get_local_channel(
+ await self._channel_clients.get(
session_record.source_channel_id,
)
if session_record.source_channel_id
- and self._channel_dispatcher is not None
+ and self._channel_clients is not None
else None
)
channel_tools = (
diff --git a/src/agentscope/app/channel/__init__.py b/src/agentscope/app/channel/__init__.py
index fd77b25a6..80d71481f 100644
--- a/src/agentscope/app/channel/__init__.py
+++ b/src/agentscope/app/channel/__init__.py
@@ -12,9 +12,11 @@ from ._base import (
ChannelCapability,
ChannelConfirmationResultEvent,
ChannelEvent,
+ ChannelHeartbeat,
ChannelStatus,
ChatKind,
)
+from ._clients import ChannelClients
from ._dispatcher import ChannelLifecycleDispatcher
from ._errors import ChannelError
from ._gateway import ChannelGateway
@@ -24,9 +26,11 @@ from ._feishu import FeishuChannel
__all__ = [
"ChannelBase",
+ "ChannelClients",
"ChannelCapability",
"ChannelConfirmationResultEvent",
"ChannelError",
+ "ChannelHeartbeat",
"ChannelEvent",
"ChannelStatus",
"ChatKind",
diff --git a/src/agentscope/app/channel/_base.py b/src/agentscope/app/channel/_base.py
index 60ca91334..da0a85369 100644
--- a/src/agentscope/app/channel/_base.py
+++ b/src/agentscope/app/channel/_base.py
@@ -145,6 +145,35 @@ class ChannelStatus(BaseModel):
last_error: str = ""
+# How long a node's status report stays trustworthy.
+LIVENESS_TTL_SECS = 30
+
+
+class ChannelHeartbeat(BaseModel):
+ """One node's report of a channel's status, stamped with the time it
+ was written.
+
+ The bus expires a registry namespace as a whole rather than per
+ field, so a node that stops reporting — a worker that restarted
+ under a fresh id, say — leaves its last entry behind while its
+ successor keeps the namespace alive. Readers therefore drop reports
+ older than :data:`LIVENESS_TTL_SECS` instead of trusting expiry.
+ """
+
+ status: ChannelStatus
+ reported_at: float
+ """Wall-clock seconds since the epoch. Compared across nodes, so a
+ little clock skew is expected and harmless at this TTL."""
+
+ def is_fresh(self, now: float) -> bool:
+ """Whether this report is recent enough to believe.
+
+ Args:
+ now (`float`): The reader's current epoch time.
+ """
+ return now - self.reported_at <= LIVENESS_TTL_SECS
+
+
class ChatKind(str, Enum):
"""A chat's audience shape, used to tailor the agent's context.
@@ -350,6 +379,16 @@ class ChannelBase(ABC):
blocks.extend(data)
return blocks
+ async def aclose(self) -> None:
+ """Release resources acquired outside :meth:`start_listening`.
+
+ An instance built by
+ :class:`~agentscope.app.channel.ChannelClients` never runs the
+ connection loop, so whatever its REST calls opened lazily has no
+ ``finally`` to close it. Override to close those; the connection
+ loop keeps releasing its own. Default: nothing to do.
+ """
+
async def send_reaction( # pylint: disable=unused-argument
self,
event: ChannelEvent,
diff --git a/src/agentscope/app/channel/_clients.py b/src/agentscope/app/channel/_clients.py
new file mode 100644
index 000000000..a962e73b2
--- /dev/null
+++ b/src/agentscope/app/channel/_clients.py
@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+"""Channel instances for processes that do not hold the connection.
+
+A channel has exactly one piece of connection-bound state: the inbound
+long connection opened by ``start_listening``. Everything else — sending
+a reply, adding a reaction, listing chats, the platform tools handed to
+the agent — is plain REST against the platform, needing only the stored
+credentials.
+
+So a process that never connects can still do all of it: build the same
+channel class from its record and simply never call ``start_listening``.
+That is what this factory does, and it is what lets the long connection
+live in one worker while runs execute on any node.
+
+Instances are cached per channel and rebuilt when the record's
+``updated_at`` moves, so a credential rotation takes effect without a
+restart. A cached instance is shared by concurrent runs — channels must
+therefore keep no state across calls.
+
+A replaced instance is retired rather than closed: a run that borrowed
+it still holds it — its platform tools stay callable for the whole turn
+— and closing the HTTP client underneath would break them. Retired
+instances are released when the
+factory shuts down, which bounds what a rotation costs to one idle
+client per rotation.
+"""
+from types import TracebackType
+
+from ..._logging import logger
+from ..storage import StorageBase
+from ._base import ChannelBase
+from ._registry import ChannelTypeRegistry
+
+
+class ChannelClients:
+ """Builds and caches unconnected channel instances by channel id."""
+
+ def __init__(
+ self,
+ storage: StorageBase,
+ type_registry: ChannelTypeRegistry,
+ ) -> None:
+ """Bind storage and the registry that knows the channel classes.
+
+ Args:
+ storage (`StorageBase`): Source of channel records.
+ type_registry (`ChannelTypeRegistry`): Builds instances from
+ a record's type, credentials and config.
+ """
+ self._storage = storage
+ self._types = type_registry
+ self._cache: dict[str, tuple[str, ChannelBase]] = {}
+ self._retired: list[ChannelBase] = []
+
+ async def __aenter__(self) -> "ChannelClients":
+ """Enter the factory's lifecycle; nothing is built up front."""
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ tb: TracebackType | None,
+ ) -> None:
+ """Release every instance this factory built.
+
+ Nothing is borrowing them by now: the runs that could have are
+ torn down with the process.
+ """
+ for channel_id in list(self._cache):
+ self._retire(channel_id)
+ for channel in self._retired:
+ try:
+ await channel.aclose()
+ except Exception: # pylint: disable=broad-except
+ logger.warning("a channel client did not close cleanly")
+ self._retired.clear()
+
+ def _retire(self, channel_id: str) -> None:
+ """Drop a cached instance without closing it.
+
+ A concurrent run may still hold this instance through the
+ platform tools attached to its toolkit, so closing here would
+ pull the connection out from under an in-flight call. It is
+ released at shutdown instead.
+
+ Args:
+ channel_id (`str`): The channel whose instance to retire.
+ """
+ cached = self._cache.pop(channel_id, None)
+ if cached is not None:
+ self._retired.append(cached[1])
+
+ async def get(self, channel_id: str) -> ChannelBase | None:
+ """Return an instance for ``channel_id``, or ``None``.
+
+ Never calls ``start_listening``, so this opens no connection and
+ starts no background task — only the platform's REST surface is
+ usable on the returned instance.
+
+ Args:
+ channel_id (`str`): The channel to build a client for.
+
+ Returns:
+ `ChannelBase | None`: The instance, or ``None`` when the
+ record is gone, disabled, or its type is not registered.
+ """
+ record = await self._storage.get_channel(channel_id)
+ if record is None or not record.enabled:
+ self._retire(channel_id)
+ return None
+
+ version = str(record.updated_at)
+ cached = self._cache.get(channel_id)
+ if cached is not None and cached[0] == version:
+ return cached[1]
+
+ try:
+ channel = self._types.create_channel(
+ channel_type=record.channel_type,
+ channel_id=record.id,
+ credentials=record.credentials,
+ config=record.platform_config,
+ )
+ except Exception: # pylint: disable=broad-except
+ logger.exception(
+ "channel client '%s' could not be built",
+ channel_id,
+ )
+ return None
+
+ # Retire the rotated instance; borrowers keep working.
+ self._retire(channel_id)
+ self._cache[channel_id] = (version, channel)
+ return channel
diff --git a/src/agentscope/app/channel/_discord/_channel.py b/src/agentscope/app/channel/_discord/_channel.py
index 4228cfca4..3335d585b 100644
--- a/src/agentscope/app/channel/_discord/_channel.py
+++ b/src/agentscope/app/channel/_discord/_channel.py
@@ -108,6 +108,7 @@ class DiscordChannel(ChannelBase):
self._config = config
self.status = ChannelStatus()
self._client: "discord.Client | None" = None
+ self._client_lock = asyncio.Lock()
self._stopped = False
@property
@@ -115,6 +116,44 @@ class DiscordChannel(ChannelBase):
"""The unique channel instance identifier."""
return self._channel_id
+ async def aclose(self) -> None:
+ """Close the client this instance logged in lazily.
+
+ The connection loop closes its own in ``start_listening``; this
+ covers the client-only instances, which never run it.
+ """
+ if self._client is not None and not self._stopped:
+ await self._client.close()
+ self._client = None
+
+ async def _ensure_client(self) -> "discord.Client":
+ """Return a client able to call the REST API, connected or not.
+
+ :class:`~agentscope.app.channel.ChannelClients` builds instances
+ that never run :meth:`start_listening`; ``login`` alone gives
+ those a working REST client. Its gateway cache stays empty, so
+ every read below goes through ``fetch_*`` rather than ``get_*``.
+ """
+ if self._client is not None:
+ return self._client
+ # Publish only after login succeeds: a half-built client handed
+ # to a concurrent caller would make unauthenticated requests,
+ # and a failed one would be cached forever, skipping login.
+ async with self._client_lock:
+ if self._client is None:
+ import discord
+
+ intents = discord.Intents.default()
+ intents.message_content = True
+ client = discord.Client(intents=intents)
+ try:
+ await client.login(self._bot_token)
+ except Exception:
+ await client.close()
+ raise
+ self._client = client
+ return self._client
+
# -- Lifecycle --
async def start_listening(
@@ -343,16 +382,25 @@ class DiscordChannel(ChannelBase):
)
async def list_bot_chats(self) -> list[dict]:
- """List every text channel the bot can see as ``{chat_id, name}``."""
+ """List every text channel the bot can see as ``{chat_id, name}``.
+
+ Paginates over REST rather than reading ``client.guilds`` /
+ ``guild.text_channels``: those are the gateway cache, which is
+ empty on an instance that only logged in.
+ """
+ import discord
+
+ client = await self._ensure_client()
results: list[dict] = []
- for guild in self._client.guilds:
- for channel in guild.text_channels:
- results.append(
- {
- "chat_id": str(channel.id),
- "name": f"{guild.name}#{channel.name}",
- },
- )
+ async for guild in client.fetch_guilds():
+ for channel in await guild.fetch_channels():
+ if isinstance(channel, discord.TextChannel):
+ results.append(
+ {
+ "chat_id": str(channel.id),
+ "name": f"{guild.name}#{channel.name}",
+ },
+ )
return results
async def chat_kind(self, chat_id: str) -> ChatKind | None:
@@ -402,11 +450,8 @@ class DiscordChannel(ChannelBase):
cid = int(chat_id)
except (TypeError, ValueError):
return None
- return self._client.get_channel(
- cid,
- ) or await self._client.fetch_channel(
- cid,
- )
+ client = await self._ensure_client()
+ return client.get_channel(cid) or await client.fetch_channel(cid)
def _build_view(
self,
diff --git a/src/agentscope/app/channel/_dispatcher.py b/src/agentscope/app/channel/_dispatcher.py
index 8bf5812f5..be8ea3735 100644
--- a/src/agentscope/app/channel/_dispatcher.py
+++ b/src/agentscope/app/channel/_dispatcher.py
@@ -6,6 +6,10 @@ node's live channel set match the enabled records, driven by lifecycle
notifications and a periodic sweep (which also self-heals lost
notifications and refreshes the status heartbeat).
+It answers no queries. With the connections in a dedicated worker the
+API replicas have no dispatcher to ask, so status is published to the
+bus and read from there instead.
+
It also forwards each channel-bound run's output back to the platform:
on an outbound signal it subscribes to the run's event stream (gap-free
— subscribe **first**, then replay the log, deduplicating by Redis-Stream
@@ -15,6 +19,8 @@ rendering (streaming, confirmation cards); the dispatcher only feeds it
the events.
"""
import asyncio
+import socket
+import time
from contextlib import aclosing, asynccontextmanager
from dataclasses import dataclass
from typing import AsyncGenerator, AsyncIterator
@@ -25,18 +31,20 @@ from ...event import EventType
from ..message_bus import MessageBus, MessageBusKeys
from ..storage import ChannelRecord, StorageBase
from ._base import (
+ LIVENESS_TTL_SECS,
ChannelBase,
ChannelConfirmationResultEvent,
ChannelEvent,
- ChannelStatus,
+ ChannelHeartbeat,
)
from ._gateway import ChannelGateway
from ._registry import ChannelTypeRegistry
# Max seconds to wait for a channel-bound run's reply before giving up.
RESPONSE_TIMEOUT_SECS = 60.0
-# TTL (seconds) of a node's per-channel status heartbeat.
-LIVENESS_TTL_SECS = 30
+# How often the heartbeat is refreshed; well inside
+# ``LIVENESS_TTL_SECS`` so a live node never looks expired to a reader.
+LIVENESS_REFRESH_SECS = 10
# Events that end a reply's event stream.
_TERMINAL_EVENTS = frozenset(
@@ -78,24 +86,15 @@ class ChannelLifecycleDispatcher:
self._types = type_registry
self._gateway = gateway
self._instances: dict[str, ChannelInstance] = {}
- self._node_id = _generate_id()
+ self._node_id = f"{socket.gethostname()}:{_generate_id()[:8]}"
self._tasks: list[asyncio.Task] = []
self._forward_tasks: set[asyncio.Task] = set()
- def get_local_channel(self, channel_id: str) -> ChannelBase | None:
- """Return this node's live channel for ``channel_id``, if running —
- how a channel-originated run's agent tools reach it.
-
- Args:
- channel_id (`str`): The channel to look up.
- """
- inst = self._instances.get(channel_id)
- return inst.channel if inst else None
-
@asynccontextmanager
async def lifespan(self) -> AsyncIterator[None]:
"""Start reconcile/heartbeat loops; stop all instances on exit."""
await self.reconcile()
+ await self._publish_status()
self._tasks = [
asyncio.create_task(self._listen(), name="channel-lifecycle"),
asyncio.create_task(self._periodic(), name="channel-heartbeat"),
@@ -190,6 +189,14 @@ class ChannelLifecycleDispatcher:
Exception,
): # pylint: disable=broad-except
pass
+ # Withdraw this node's report rather than leaving it to age out.
+ try:
+ await self._bus.registry_del(
+ MessageBusKeys.channel_liveness(channel_id),
+ self._node_id,
+ )
+ except Exception: # pylint: disable=broad-except
+ logger.debug("channel '%s' status withdrawal failed", channel_id)
logger.info("channel '%s' stopped", channel_id)
# -- Loops --
@@ -369,43 +376,43 @@ class ChannelLifecycleDispatcher:
pass
async def _periodic(self) -> None:
- """Periodic reconcile (self-heals lost lifecycle events)."""
- interval = max(5.0, LIVENESS_TTL_SECS / 2)
- while True:
- await asyncio.sleep(interval)
- await self.reconcile()
-
- # -- Read APIs (for the router) --
-
- async def get_status(self, channel_id: str) -> ChannelStatus:
- """The channel's live connection status, or ``stopped`` if it is not
- running here (disabled / not yet started).
-
- Args:
- channel_id (`str`): The channel to report on.
- """
- inst = self._instances.get(channel_id)
- return inst.channel.status if inst else ChannelStatus(state="stopped")
-
- async def list_bot_chats(self, channel_id: str) -> list[dict]:
- """Chats the bot is in, via the local channel if running.
+ """Reconcile and publish status on a fixed interval.
- Args:
- channel_id (`str`): The channel to query.
+ The reconcile self-heals lost lifecycle events; the heartbeat is
+ what makes status readable from processes that hold no
+ connection — with a dedicated channel worker that is every API
+ replica.
"""
- inst = self._instances.get(channel_id)
- return await inst.channel.list_bot_chats() if inst else []
+ while True:
+ await asyncio.sleep(LIVENESS_REFRESH_SECS)
+ await self.reconcile()
+ await self._publish_status()
- async def list_seen_chat_ids(self, channel_id: str) -> list[str]:
- """Chat_ids passively recorded from inbound messages.
+ async def _publish_status(self) -> None:
+ """Write this node's view of each local channel's status.
- Args:
- channel_id (`str`): The channel to list seen chats for.
+ Each report carries the time it was written: the namespace TTL
+ expires the whole hash, not this node's field, so a reader
+ cannot tell a live entry from one a restarted predecessor left
+ behind without the stamp.
"""
- fields = await self._bus.registry_getall(
- MessageBusKeys.channel_seen_chats(channel_id),
- )
- return sorted(fields.keys())
+ now = time.time()
+ for channel_id, inst in list(self._instances.items()):
+ try:
+ await self._bus.registry_set(
+ MessageBusKeys.channel_liveness(channel_id),
+ self._node_id,
+ ChannelHeartbeat(
+ status=inst.channel.status,
+ reported_at=now,
+ ).model_dump_json(),
+ ttl_secs=LIVENESS_TTL_SECS,
+ )
+ except Exception: # pylint: disable=broad-except
+ logger.warning(
+ "channel '%s' status heartbeat failed",
+ channel_id,
+ )
async def dispatch(
self,
diff --git a/src/agentscope/app/channel/_feishu/_channel.py b/src/agentscope/app/channel/_feishu/_channel.py
index 27b1e11f6..2d29819e5 100644
--- a/src/agentscope/app/channel/_feishu/_channel.py
+++ b/src/agentscope/app/channel/_feishu/_channel.py
@@ -191,12 +191,9 @@ class FeishuChannel(ChannelBase):
Args:
emit (`Callable`): Gateway callback for inbound events.
"""
- import httpx
-
self._emit = emit
self.status.state = "connecting"
self._loop = asyncio.get_running_loop()
- self._http = httpx.AsyncClient(timeout=30.0)
backoff = 1.0
attempts = 0
ever_connected = False
@@ -1127,7 +1124,7 @@ class FeishuChannel(ChannelBase):
Returns:
`str | None`: The resource key, or ``None`` on error.
"""
- if not self._http or not self._token:
+ if not await self._ensure_ready():
return None
try:
resp = await self._http.post(
@@ -1154,8 +1151,49 @@ class FeishuChannel(ChannelBase):
logger.debug("Feishu upload request failed")
return None
+ async def aclose(self) -> None:
+ """Close the HTTP client this instance opened lazily.
+
+ The connection loop closes its own in ``start_listening``; this
+ covers the client-only instances, which never run it.
+ """
+ if self._http is not None:
+ await self._http.aclose()
+ self._http = None
+ self._token = None
+
+ async def _ensure_ready(self) -> bool:
+ """Make the instance able to call the platform, connected or not.
+
+ Outbound is plain REST, so an instance built by
+ :class:`~agentscope.app.channel.ChannelClients` — one that never
+ ran ``start_listening`` — must reach the platform too. Both the
+ HTTP client and the tenant token are therefore created on first
+ use rather than during connection setup.
+
+ Returns:
+ `bool`: Whether an authenticated client is available.
+ """
+ if self._token is None:
+ # Callers treat this as a readiness check and promise their
+ # own ``None`` on failure, so a network or auth blip must
+ # not escape and turn a read endpoint into a 500.
+ try:
+ await self._refresh_token()
+ except Exception: # pylint: disable=broad-except
+ logger.warning(
+ "Feishu '%s' could not obtain a token",
+ self._channel_id,
+ )
+ return False
+ return self._token is not None
+
async def _refresh_token(self) -> None:
"""Fetch a fresh tenant access token and cache it."""
+ if self._http is None:
+ import httpx
+
+ self._http = httpx.AsyncClient(timeout=30.0)
resp = await self._http.post(
f"{_API}/auth/v3/tenant_access_token/internal",
json={"app_id": self._app_id, "app_secret": self._app_secret},
@@ -1185,7 +1223,7 @@ class FeishuChannel(ChannelBase):
Returns:
`dict | None`: The parsed response, or ``None`` on error.
"""
- if not self._http or not self._token:
+ if not await self._ensure_ready():
return None
headers = {
"Authorization": f"Bearer {self._token}",
@@ -1299,6 +1337,8 @@ class FeishuChannel(ChannelBase):
Returns:
`DataBlock | None`: The block, or ``None`` on error.
"""
+ if not await self._ensure_ready():
+ return None
url = (
f"{_API}/im/v1/messages/{message_id}"
f"/resources/{key}?type={resource_type}"
diff --git a/src/agentscope/app/channel/worker/__init__.py b/src/agentscope/app/channel/worker/__init__.py
new file mode 100644
index 000000000..35126dc20
--- /dev/null
+++ b/src/agentscope/app/channel/worker/__init__.py
@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""Out-of-process channel worker entry point.
+
+A platform hands one bot's events to one connection: Feishu, DingTalk
+and Slack pick a single connection out of the ones a bot has open, while
+Discord broadcasts to all of them. So having every API replica connect
+either wastes connections or processes each message several times — the
+connections belong in a process whose count is chosen for them rather
+than for HTTP traffic.
+
+This worker is that process. It owns:
+
+- a :class:`~agentscope.app.channel.ChannelLifecycleDispatcher`, which
+ reconciles the live connections against the stored channel records
+ and heartbeats their status;
+- a :class:`~agentscope.app.channel.ChannelGateway`, which turns each
+ inbound event into a run trigger on the message bus.
+
+It does **not** run agents, serve HTTP, or deliver replies — a reply is
+plain REST, so whichever node runs the agent sends it directly. Pair
+this with ``create_app(..., enable_channel_worker=False)`` so the API
+replicas hold no connections.
+
+This module is a library: a deployment wires its concrete backends
+through :func:`run_channel_worker` from whatever bootstrap script it
+uses (systemd unit, Kubernetes Deployment, docker-compose ``command``,
+...). The shape mirrors :func:`agentscope.app.create_app` — pass
+already-constructed backend instances and the worker manages their
+lifecycle through an :class:`AsyncExitStack`.
+
+Example::
+
+ import asyncio
+ import os
+
+ from agentscope.app.channel import FeishuChannel
+ from agentscope.app.channel.worker import run_channel_worker
+ from agentscope.app.message_bus import RedisMessageBus
+ from agentscope.app.storage import RedisStorage
+ from agentscope.app.workspace_manager import LocalWorkspaceManager
+
+ async def main() -> None:
+ await run_channel_worker(
+ storage=RedisStorage(url=os.environ["REDIS_URL"]),
+ message_bus=RedisMessageBus(url=os.environ["REDIS_URL"]),
+ workspace_manager=LocalWorkspaceManager(),
+ channels=[FeishuChannel],
+ )
+
+ if __name__ == "__main__":
+ asyncio.run(main())
+"""
+import asyncio
+import signal
+from contextlib import AsyncExitStack
+
+from ...._logging import logger
+from ...message_bus import MessageBus
+from ...storage import StorageBase
+from ...workspace_manager import WorkspaceManagerBase
+from .._base import ChannelBase
+from .._dispatcher import ChannelLifecycleDispatcher
+from .._gateway import ChannelGateway
+from .._registry import ChannelTypeRegistry
+
+
+async def run_channel_worker(
+ *,
+ storage: StorageBase,
+ message_bus: MessageBus,
+ workspace_manager: WorkspaceManagerBase,
+ channels: list[type[ChannelBase]],
+) -> None:
+ """Hold the channels' long connections until interrupted.
+
+ Args:
+ storage (`StorageBase`):
+ Persistent storage. Source of truth for which channels to
+ run and with which credentials, and where the gateway
+ creates the sessions inbound messages land in. Must be a
+ backend implementing the channel methods.
+ message_bus (`MessageBus`):
+ Shared bus. Carries lifecycle notifications in, run
+ triggers out, and the per-channel status heartbeat. Must be
+ the distributed backend the API replicas use, or they will
+ never see this worker's channels.
+ workspace_manager (`WorkspaceManagerBase`):
+ Assigns each derived session its workspace id under the
+ deployment's isolation policy.
+ channels (`list[type[ChannelBase]]`):
+ Channel classes this worker may run, the same list the API
+ process is given — a record whose type is missing here is
+ skipped with an error.
+ """
+ async with AsyncExitStack() as stack:
+ await stack.enter_async_context(storage)
+ await stack.enter_async_context(message_bus)
+ await stack.enter_async_context(workspace_manager)
+
+ dispatcher = ChannelLifecycleDispatcher(
+ storage=storage,
+ message_bus=message_bus,
+ type_registry=ChannelTypeRegistry(channels),
+ gateway=ChannelGateway(
+ storage=storage,
+ message_bus=message_bus,
+ workspace_manager=workspace_manager,
+ ),
+ )
+ await stack.enter_async_context(dispatcher.lifespan())
+ logger.info("Channel worker ready (%d types)", len(channels))
+
+ # Install handlers on the running loop rather than using
+ # ``signal.signal`` so the interaction with asyncio is
+ # well-defined — the default handler would raise
+ # KeyboardInterrupt at an arbitrary await point.
+ loop = asyncio.get_running_loop()
+ stop = loop.create_future()
+
+ def _request_stop() -> None:
+ """Resolve the shutdown future once."""
+ if not stop.done():
+ stop.set_result(None)
+
+ for sig in (signal.SIGINT, signal.SIGTERM):
+ try:
+ loop.add_signal_handler(sig, _request_stop)
+ except NotImplementedError:
+ # Windows event loops do not implement this; tests and
+ # Linux/macOS deployments are unaffected.
+ pass
+
+ try:
+ await stop
+ finally:
+ logger.info("Channel worker shutting down")
diff --git a/src/agentscope/app/deps.py b/src/agentscope/app/deps.py
index 0eabb8fe3..93eecf50f 100644
--- a/src/agentscope/app/deps.py
+++ b/src/agentscope/app/deps.py
@@ -4,7 +4,7 @@ from fastapi import Header, HTTPException, Request, status
from .workspace_manager import WorkspaceManagerBase
from .channel import (
- ChannelLifecycleDispatcher,
+ ChannelClients,
ChannelTypeRegistry,
)
from ._manager import (
@@ -419,19 +419,21 @@ async def get_channel_service(request: Request) -> ChannelService:
return request.app.state.channel_service
-async def get_channel_dispatcher(
+async def get_channel_clients(
request: Request,
-) -> ChannelLifecycleDispatcher:
- """Return this node's channel lifecycle dispatcher.
+) -> ChannelClients:
+ """Return the factory for unconnected channel instances.
+
+ Present in every process, whether or not this one holds the
+ channels' long connections.
Args:
request (`Request`): The incoming FastAPI request.
Returns:
- `ChannelLifecycleDispatcher`: The dispatcher stored in
- ``app.state``, source of per-channel runtime status.
+ `ChannelClients`: The factory stored in ``app.state``.
"""
- return request.app.state.channel_dispatcher
+ return request.app.state.channel_clients
async def get_channel_type_registry(
diff --git a/tests/channel_clients_test.py b/tests/channel_clients_test.py
new file mode 100644
index 000000000..8371a5168
--- /dev/null
+++ b/tests/channel_clients_test.py
@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+"""Tests for the connection-free half of the channel runtime.
+
+A process that does not hold a channel's long connection must still be
+able to use the channel: attach its platform tools to an agent, deliver
+a reply, and report its status. These cover the two pieces that make
+that work — the client factory and the status heartbeat.
+"""
+import time
+from datetime import datetime
+from typing import Any, AsyncIterator
+from unittest import IsolatedAsyncioTestCase
+
+from pydantic import BaseModel
+
+from agentscope.app._service import ChannelService
+from agentscope.app.channel import (
+ ChannelBase,
+ ChannelClients,
+ ChannelEvent,
+ ChannelHeartbeat,
+ ChannelStatus,
+ ChannelTypeRegistry,
+)
+from agentscope.app.channel._base import LIVENESS_TTL_SECS
+from agentscope.app.message_bus import InMemoryMessageBus, MessageBusKeys
+from agentscope.app.storage import (
+ ChannelBinding,
+ ChannelRecord,
+ RoutingConfig,
+ SessionSettings,
+)
+
+
+class _FakeChannel(ChannelBase):
+ """Records whether anything ever opened its connection."""
+
+ channel_type = "fake"
+ display_name = "Fake"
+ platform_bot_id_field = "bot_id"
+
+ class Credentials(BaseModel):
+ """Credentials for the fake platform."""
+
+ bot_id: str
+
+ class Config(BaseModel):
+ """Options for the fake platform."""
+
+ def __init__(
+ self,
+ channel_id: str,
+ credentials: "Credentials",
+ config: "Config", # pylint: disable=unused-argument
+ ) -> None:
+ """Store the identity and start disconnected."""
+ self._channel_id = channel_id
+ self.bot_id = credentials.bot_id
+ self.status = ChannelStatus()
+ self.listened = False
+ self.closed = False
+
+ @property
+ def channel_id(self) -> str:
+ """The unique channel instance identifier."""
+ return self._channel_id
+
+ async def start_listening( # pylint: disable=unused-argument
+ self,
+ emit: Any,
+ ) -> None:
+ """Mark that a connection was opened."""
+ self.listened = True
+
+ async def aclose(self) -> None:
+ """Record that the factory released this instance."""
+ self.closed = True
+
+ async def send_response(
+ self,
+ event: ChannelEvent,
+ events: AsyncIterator[dict],
+ ) -> None:
+ """No-op; delivery is not what these tests exercise."""
+
+
+class _Storage:
+ """Storage stub serving one mutable channel record."""
+
+ def __init__(self, record: ChannelRecord | None) -> None:
+ self.record = record
+ self.calls = 0
+
+ async def get_channel(
+ self,
+ channel_id: str, # pylint: disable=unused-argument
+ ) -> ChannelRecord | None:
+ """Return the single record this stub serves."""
+ self.calls += 1
+ return self.record
+
+
+def _record(bot_id: str = "bot-1", enabled: bool = True) -> ChannelRecord:
+ """Build a minimal enabled channel record for the fake platform."""
+ now = datetime.now().isoformat()
+ return ChannelRecord(
+ id="chan-1",
+ channel_type="fake",
+ user_id="owner-1",
+ enabled=enabled,
+ credentials={"bot_id": bot_id},
+ routing=RoutingConfig(
+ bindings=[ChannelBinding(match_value="*", agent_id="agent-x")],
+ ),
+ session=SessionSettings(chat_model_config={"type": "x"}),
+ created_at=now,
+ updated_at=now,
+ )
+
+
+class ChannelClientsTest(IsolatedAsyncioTestCase):
+ """The factory hands out usable channels without connecting."""
+
+ def _clients(self, storage: _Storage) -> ChannelClients:
+ return ChannelClients(
+ storage=storage,
+ type_registry=ChannelTypeRegistry([_FakeChannel]),
+ )
+
+ async def test_builds_without_opening_a_connection(self) -> None:
+ """The instance is usable but never listened — that is what lets
+ it live in a process that holds no connection."""
+ clients = self._clients(_Storage(_record()))
+
+ channel = await clients.get("chan-1")
+
+ self.assertIsInstance(channel, _FakeChannel)
+ self.assertFalse(channel.listened)
+ self.assertEqual(channel.bot_id, "bot-1")
+
+ async def test_cached_until_the_record_changes(self) -> None:
+ """A rotated credential takes effect without a restart."""
+ storage = _Storage(_record())
+ clients = self._clients(storage)
+
+ first = await clients.get("chan-1")
+ self.assertIs(await clients.get("chan-1"), first)
+
+ rotated = _record(bot_id="bot-2")
+ rotated.updated_at = "2099-01-01T00:00:00"
+ storage.record = rotated
+
+ second = await clients.get("chan-1")
+ self.assertIsNot(second, first)
+ self.assertEqual(second.bot_id, "bot-2")
+
+ async def test_missing_or_disabled_channel_has_no_client(self) -> None:
+ """A disabled channel is dropped from the cache, not served."""
+ storage = _Storage(_record())
+ clients = self._clients(storage)
+ await clients.get("chan-1")
+
+ storage.record = _record(enabled=False)
+ self.assertIsNone(await clients.get("chan-1"))
+
+ storage.record = None
+ self.assertIsNone(await clients.get("chan-1"))
+
+ async def test_a_replaced_instance_stays_usable_for_borrowers(
+ self,
+ ) -> None:
+ """A run that already took this instance may still be streaming
+ a reply through it, so rotation must not close it underneath."""
+ storage = _Storage(_record())
+ async with self._clients(storage) as clients:
+ borrowed = await clients.get("chan-1")
+
+ rotated = _record(bot_id="bot-2")
+ rotated.updated_at = "2099-01-01T00:00:00"
+ storage.record = rotated
+ await clients.get("chan-1")
+ self.assertFalse(borrowed.closed)
+
+ storage.record = _record(enabled=False)
+ await clients.get("chan-1")
+ self.assertFalse(borrowed.closed)
+
+ async def test_shutdown_releases_cached_and_retired_instances(
+ self,
+ ) -> None:
+ """Nothing the factory built outlives it."""
+ storage = _Storage(_record())
+ async with self._clients(storage) as clients:
+ retired = await clients.get("chan-1")
+
+ rotated = _record(bot_id="bot-2")
+ rotated.updated_at = "2099-01-01T00:00:00"
+ storage.record = rotated
+ cached = await clients.get("chan-1")
+
+ self.assertTrue(retired.closed)
+ self.assertTrue(cached.closed)
+
+ async def test_unregistered_type_has_no_client(self) -> None:
+ """A record whose class this process was not given is skipped."""
+ clients = ChannelClients(
+ storage=_Storage(_record()),
+ type_registry=ChannelTypeRegistry([]),
+ )
+ self.assertIsNone(await clients.get("chan-1"))
+
+
+class ChannelStatusTest(IsolatedAsyncioTestCase):
+ """Status is read from the heartbeat, not from local instances."""
+
+ def _service(self, bus: InMemoryMessageBus) -> ChannelService:
+ return ChannelService(
+ storage=_Storage(_record()),
+ message_bus=bus,
+ type_registry=ChannelTypeRegistry([_FakeChannel]),
+ )
+
+ async def _beat(
+ self,
+ bus: InMemoryMessageBus,
+ node_id: str,
+ state: str,
+ age_secs: float = 0.0,
+ ) -> None:
+ """Write one node's report, optionally backdated."""
+ await bus.registry_set(
+ MessageBusKeys.channel_liveness("chan-1"),
+ node_id,
+ ChannelHeartbeat(
+ status=ChannelStatus(state=state),
+ reported_at=time.time() - age_secs,
+ ).model_dump_json(),
+ ttl_secs=LIVENESS_TTL_SECS,
+ )
+
+ async def test_no_heartbeat_reads_as_stopped(self) -> None:
+ """Nothing is holding the channel, so nothing reports it."""
+ bus = InMemoryMessageBus()
+ self.assertEqual(
+ await self._service(bus).get_status("chan-1"),
+ ChannelStatus(state="stopped"),
+ )
+
+ async def test_reports_the_holder_from_another_node(self) -> None:
+ """The reading replica holds no connection of its own."""
+ bus = InMemoryMessageBus()
+ await self._beat(bus, "worker-a", "connected")
+
+ self.assertEqual(
+ await self._service(bus).get_status("chan-1"),
+ ChannelStatus(state="connected"),
+ )
+
+ async def test_a_restarted_node_leaves_no_ghost(self) -> None:
+ """The namespace TTL expires the hash, not one node's field, so
+ a worker that restarted under a fresh id would otherwise report
+ ``connected`` forever."""
+ bus = InMemoryMessageBus()
+ await self._beat(
+ bus,
+ "worker-a-old",
+ "connected",
+ age_secs=LIVENESS_TTL_SECS + 1,
+ )
+ await self._beat(bus, "worker-a-new", "connecting")
+
+ self.assertEqual(
+ await self._service(bus).get_status("chan-1"),
+ ChannelStatus(state="connecting"),
+ )
+
+ async def test_only_stale_reports_read_as_stopped(self) -> None:
+ """Every holder went away; nothing fresh is left to believe."""
+ bus = InMemoryMessageBus()
+ await self._beat(
+ bus,
+ "worker-a",
+ "connected",
+ age_secs=LIVENESS_TTL_SECS + 1,
+ )
+
+ self.assertEqual(
+ await self._service(bus).get_status("chan-1"),
+ ChannelStatus(state="stopped"),
+ )
+
+ async def test_connected_wins_over_a_retrying_node(self) -> None:
+ """During a failover one node is still serving; say so."""
+ bus = InMemoryMessageBus()
+ await self._beat(bus, "worker-a", "retrying")
+ await self._beat(bus, "worker-b", "connected")
+
+ self.assertEqual(
+ await self._service(bus).get_status("chan-1"),
+ ChannelStatus(state="connected"),
+ )
diff --git a/tests/channel_worker_test.py b/tests/channel_worker_test.py
new file mode 100644
index 000000000..3299e6628
--- /dev/null
+++ b/tests/channel_worker_test.py
@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""Tests for the standalone channel worker's lifecycle.
+
+The worker is the process that owns the platforms' long connections, so
+what matters here is that it opens its backends, stays up, and releases
+them on the way out.
+
+Shutdown is deliberately not driven by a real signal: the worker only
+installs handlers where the event loop supports them, so on Windows a
+raised SIGTERM would take the default action and kill the test process
+rather than fail a test. The two halves are checked separately instead
+— that the handlers are registered, and that teardown releases
+everything.
+"""
+import asyncio
+import signal
+import sys
+from types import TracebackType
+from typing import Any
+from unittest import IsolatedAsyncioTestCase, skipIf
+
+from agentscope.app.channel.worker import run_channel_worker
+
+
+class _TrackedContext:
+ """Async-context backend recording when it opened and closed."""
+
+ def __init__(self) -> None:
+ self.entered = False
+ self.exited = False
+
+ async def __aenter__(self) -> "_TrackedContext":
+ """Record that the worker opened this backend."""
+ self.entered = True
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ tb: TracebackType | None,
+ ) -> None:
+ """Record that the worker released this backend."""
+ self.exited = True
+
+
+class _Storage(_TrackedContext):
+ """Storage stub with no channels to run."""
+
+ async def list_all_channels(self) -> list:
+ """No records, so the worker opens no connections."""
+ return []
+
+
+class _Bus(_TrackedContext):
+ """Bus stub whose lifecycle subscription never yields."""
+
+ async def subscribe( # pylint: disable=unused-argument
+ self,
+ key: str,
+ **kwargs: Any,
+ ) -> Any:
+ """Block forever, as a live subscription would."""
+ await asyncio.Event().wait()
+ yield {} # pragma: no cover
+
+ async def registry_set(self, *args: Any, **kwargs: Any) -> None:
+ """Accept heartbeats."""
+
+
+class ChannelWorkerLifecycleTest(IsolatedAsyncioTestCase):
+ """The worker holds its backends open until told to stop."""
+
+ async def _start(
+ self,
+ ) -> tuple[asyncio.Task, _Storage, _Bus, _TrackedContext]:
+ """Run a worker over stub backends and wait for it to come up."""
+ storage, bus, workspaces = _Storage(), _Bus(), _TrackedContext()
+ worker = asyncio.create_task(
+ run_channel_worker(
+ storage=storage,
+ message_bus=bus,
+ workspace_manager=workspaces,
+ channels=[],
+ ),
+ )
+ await asyncio.sleep(0.05)
+ return worker, storage, bus, workspaces
+
+ async def test_backends_are_opened_and_the_worker_stays_up(self) -> None:
+ """It is a long-running process: it must not return on its own."""
+ worker, storage, bus, workspaces = await self._start()
+ try:
+ self.assertTrue(storage.entered)
+ self.assertTrue(bus.entered)
+ self.assertTrue(workspaces.entered)
+ self.assertFalse(worker.done())
+ finally:
+ worker.cancel()
+ await asyncio.gather(worker, return_exceptions=True)
+
+ async def test_teardown_releases_every_backend(self) -> None:
+ """Whatever the worker opened is closed when it unwinds."""
+ worker, storage, bus, workspaces = await self._start()
+
+ worker.cancel()
+ await asyncio.gather(worker, return_exceptions=True)
+
+ self.assertTrue(storage.exited)
+ self.assertTrue(bus.exited)
+ self.assertTrue(workspaces.exited)
+
+ @skipIf(
+ sys.platform == "win32",
+ "Windows event loops do not implement add_signal_handler.",
+ )
+ async def test_shutdown_signals_are_handled(self) -> None:
+ """A container stops the worker with SIGTERM, so both signals
+ must be claimed rather than left to kill the process."""
+ worker, _, _, _ = await self._start()
+ try:
+ loop = asyncio.get_running_loop()
+ registered = loop._signal_handlers # pylint: disable=W0212
+ self.assertIn(signal.SIGTERM, registered)
+ self.assertIn(signal.SIGINT, registered)
+ finally:
+ worker.cancel()
+ await asyncio.gather(worker, return_exceptions=True)