nonebot-plugin-tgforwarder 0.1.0__py3-none-any.whl

nonebot_plugin_tgforwarder/__init__.py

@@ -0,0 +1,162 @@
+from nonebot import get_driver, logger, on_command, on_type
+from nonebot.adapters import Message
+from nonebot.params import CommandArg
+from nonebot.permission import SUPERUSER
+from nonebot.plugin import PluginMetadata, get_plugin_config
+
+from .client import (
+    FatalPublicAPIError,
+    PublicAPIClientError,
+    PublicMessageClient,
+    RetryablePublicAPIError,
+)
+from .config import Config
+from .cursor import CursorStore
+from .dispatcher import MessageDispatcher, MessageHandler
+from .event import PublicMessageEvent
+from .models import MessagePage, PublicMediaItem, PublicMessage
+from .poller import PublicMessagePoller
+from .whitelist import (
+    GroupWhitelistStore,
+    WhitelistStoreError,
+    execute_whitelist_command,
+    is_private_message,
+)
+
+__plugin_meta__ = PluginMetadata(
+    name="TG-forwarder 公开消息轮询",
+    description="轮询 safewbot 公开消息 API，并向 NoneBot 回调或 matcher 分发消息",
+    usage=(
+        "配置 TGFORWARDER_API_TOKEN 和 SUPERUSERS；"
+        "私聊使用 /tgfwd add|del|list 管理来源群白名单"
+    ),
+    type="application",
+    config=Config,
+    supported_adapters=None,
+)
+
+plugin_config = get_plugin_config(Config)
+group_whitelist = GroupWhitelistStore(plugin_config.tgforwarder_whitelist_file)
+try:
+    group_whitelist.load()
+except WhitelistStoreError:
+    logger.exception(
+        "Failed to load tgforwarder group whitelist {}; denying all source groups",
+        plugin_config.tgforwarder_whitelist_file,
+    )
+
+public_message_matcher = on_type(
+    PublicMessageEvent,
+    priority=plugin_config.tgforwarder_matcher_priority,
+    block=False,
+)
+message_dispatcher = MessageDispatcher(
+    public_message_matcher,
+    dispatch_matcher=plugin_config.tgforwarder_dispatch_matcher,
+)
+
+
+tgfwd_command = on_command(
+    "tgfwd",
+    rule=is_private_message,
+    permission=SUPERUSER,
+    priority=1,
+    block=True,
+)
+
+
+@tgfwd_command.handle()
+async def _manage_group_whitelist(args: Message = CommandArg()) -> None:
+    try:
+        response = execute_whitelist_command(
+            args.extract_plain_text().strip(), group_whitelist
+        )
+    except WhitelistStoreError:
+        logger.exception("Failed to update tgforwarder group whitelist")
+        response = "群白名单保存失败，请检查日志和文件权限。"
+    await tgfwd_command.finish(response)
+
+
+def on_public_message(handler: MessageHandler) -> MessageHandler:
+    """Register a sync or async callback and return it for decorator use."""
+
+    return message_dispatcher.register(handler)
+
+
+def remove_public_message_handler(handler: MessageHandler) -> None:
+    message_dispatcher.unregister(handler)
+
+
+_token = plugin_config.tgforwarder_api_token.get_secret_value()
+_client = PublicMessageClient(
+    plugin_config.tgforwarder_api_base_url,
+    _token,
+    timeout=plugin_config.tgforwarder_request_timeout,
+)
+_poller = PublicMessagePoller(
+    _client,
+    CursorStore(plugin_config.tgforwarder_cursor_file),
+    message_dispatcher.dispatch,
+    allow_message=lambda message: group_whitelist.contains(message.source_chat_id),
+    initial_cursor=plugin_config.tgforwarder_initial_cursor,
+    page_limit=plugin_config.tgforwarder_page_limit,
+    poll_interval=plugin_config.tgforwarder_poll_interval,
+    retry_initial=plugin_config.tgforwarder_retry_initial,
+    retry_max=plugin_config.tgforwarder_retry_max,
+    retry_jitter=plugin_config.tgforwarder_retry_jitter,
+    dedup_cache_size=plugin_config.tgforwarder_dedup_cache_size,
+    shutdown_timeout=plugin_config.tgforwarder_shutdown_timeout,
+)
+
+driver = get_driver()
+
+
+@driver.on_startup
+async def _start_poller() -> None:
+    if not plugin_config.tgforwarder_enabled:
+        logger.info("tgforwarder public API poller is disabled")
+        return
+    if not _token:
+        logger.error(
+            "TGFORWARDER_API_TOKEN is empty; tgforwarder public API poller will not start"
+        )
+        return
+    await _poller.start()
+
+
+@driver.on_shutdown
+async def _stop_poller() -> None:
+    await _poller.stop()
+
+
+def get_poller() -> PublicMessagePoller:
+    """Return the plugin-managed poller for diagnostics and tests."""
+
+    return _poller
+
+
+def get_group_whitelist() -> GroupWhitelistStore:
+    """Return the plugin-managed source group whitelist."""
+
+    return group_whitelist
+
+
+__all__ = [
+    "FatalPublicAPIError",
+    "MessagePage",
+    "PublicAPIClientError",
+    "PublicMediaItem",
+    "PublicMessage",
+    "PublicMessageClient",
+    "PublicMessageEvent",
+    "RetryablePublicAPIError",
+    "Config",
+    "GroupWhitelistStore",
+    "WhitelistStoreError",
+    "get_group_whitelist",
+    "get_poller",
+    "on_public_message",
+    "public_message_matcher",
+    "remove_public_message_handler",
+    "tgfwd_command",
+]

nonebot_plugin_tgforwarder/client.py

@@ -0,0 +1,161 @@
+from typing import Any, Optional
+
+import httpx
+from pydantic import ValidationError
+
+from .models import MessagePage, PublicAPIEnvelope, PublicAPIErrorEnvelope, validate_model
+
+
+class PublicAPIClientError(RuntimeError):
+    """Base class for public API failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.request_id = request_id
+
+
+class RetryablePublicAPIError(PublicAPIClientError):
+    """A transient failure that should be retried with the same cursor."""
+
+
+class FatalPublicAPIError(PublicAPIClientError):
+    """An authentication, request, or response-contract failure."""
+
+
+class PublicMessageClient:
+    endpoint_path = "/api/public/v1/messages"
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = 30.0,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._client = client
+        self._owns_client = client is None
+
+    def _http_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers={
+                    "Authorization": f"Bearer {self.token}",
+                    "Accept": "application/json",
+                    "User-Agent": "nonebot-plugin-tgforwarder/0.1.0",
+                },
+            )
+        return self._client
+
+    async def fetch_messages(self, *, cursor: int, limit: int) -> MessagePage:
+        try:
+            response = await self._http_client().get(
+                self.endpoint_path,
+                params={"cursor": cursor, "limit": limit},
+                headers={"Authorization": f"Bearer {self.token}"},
+            )
+        except (httpx.TimeoutException, httpx.NetworkError) as exc:
+            raise RetryablePublicAPIError(f"Public API request failed: {exc}") from exc
+        except httpx.RequestError as exc:
+            raise RetryablePublicAPIError(f"Public API request failed: {exc}") from exc
+
+        payload = self._decode_json(response)
+        if response.status_code != 200:
+            self._raise_for_error(response.status_code, payload)
+
+        try:
+            envelope = validate_model(PublicAPIEnvelope, payload)
+        except (ValidationError, TypeError, ValueError) as exc:
+            raise FatalPublicAPIError(
+                "Public API returned an invalid success response",
+                status_code=response.status_code,
+            ) from exc
+        if not envelope.ok:
+            raise FatalPublicAPIError(
+                "Public API success response has ok=false",
+                status_code=response.status_code,
+            )
+        self._validate_page(envelope.data, requested_cursor=cursor)
+        return envelope.data
+
+    @staticmethod
+    def _decode_json(response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            error_type = (
+                RetryablePublicAPIError
+                if response.status_code in {408, 429} or response.status_code >= 500
+                else FatalPublicAPIError
+            )
+            raise error_type(
+                "Public API returned a non-JSON response",
+                status_code=response.status_code,
+            ) from exc
+        if not isinstance(payload, dict):
+            raise FatalPublicAPIError(
+                "Public API response must be a JSON object",
+                status_code=response.status_code,
+            )
+        return payload
+
+    @staticmethod
+    def _raise_for_error(status_code: int, payload: dict[str, Any]) -> None:
+        message = f"Public API returned HTTP {status_code}"
+        error_code: Optional[str] = None
+        request_id: Optional[str] = None
+        try:
+            error = validate_model(PublicAPIErrorEnvelope, payload).error
+            message = error.message
+            error_code = error.code
+            request_id = error.request_id
+        except (ValidationError, TypeError, ValueError):
+            pass
+
+        error_type = (
+            RetryablePublicAPIError
+            if status_code in {408, 429} or status_code >= 500
+            else FatalPublicAPIError
+        )
+        raise error_type(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            request_id=request_id,
+        )
+
+    @staticmethod
+    def _validate_page(page: MessagePage, *, requested_cursor: int) -> None:
+        delivery_ids = [item.delivery_id for item in page.items]
+        if any(value <= requested_cursor for value in delivery_ids):
+            raise FatalPublicAPIError(
+                "Public API returned a delivery_id not greater than the requested cursor"
+            )
+        if delivery_ids != sorted(set(delivery_ids)):
+            raise FatalPublicAPIError(
+                "Public API returned duplicate or out-of-order delivery_id values"
+            )
+        expected_cursor = delivery_ids[-1] if delivery_ids else requested_cursor
+        if page.next_cursor != expected_cursor:
+            raise FatalPublicAPIError(
+                "Public API next_cursor does not match the last delivery_id"
+            )
+
+    async def aclose(self) -> None:
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+        self._client = None

nonebot_plugin_tgforwarder/config.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+from pydantic import BaseModel, Field, SecretStr
+
+
+class Config(BaseModel):
+    """NoneBot configuration for the public message API poller."""
+
+    tgforwarder_enabled: bool = True
+    tgforwarder_api_base_url: str = "http://127.0.0.1:8000"
+    tgforwarder_api_token: SecretStr = SecretStr("")
+    tgforwarder_cursor_file: Path = Path("data/tgforwarder-cursor.json")
+    tgforwarder_whitelist_file: Path = Path("data/tgforwarder-whitelist.json")
+    tgforwarder_initial_cursor: int = Field(default=0, ge=0)
+    tgforwarder_page_limit: int = Field(default=50, ge=1, le=100)
+    tgforwarder_poll_interval: float = Field(default=2.0, gt=0)
+    tgforwarder_request_timeout: float = Field(default=30.0, gt=0)
+    tgforwarder_retry_initial: float = Field(default=1.0, gt=0)
+    tgforwarder_retry_max: float = Field(default=60.0, gt=0)
+    tgforwarder_retry_jitter: float = Field(default=0.2, ge=0, le=1)
+    tgforwarder_dedup_cache_size: int = Field(default=2048, ge=1)
+    tgforwarder_dispatch_matcher: bool = True
+    tgforwarder_matcher_priority: int = 1
+    tgforwarder_shutdown_timeout: float = Field(default=5.0, gt=0)

nonebot_plugin_tgforwarder/cursor.py

@@ -0,0 +1,60 @@
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class CursorStoreError(RuntimeError):
+    pass
+
+
+class CursorStore:
+    """Persist a delivery cursor using an atomic same-directory replace."""
+
+    version = 1
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def load(self, default: int = 0) -> int:
+        if not self.path.exists():
+            return default
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+            cursor = payload["cursor"]
+            version = payload["version"]
+        except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+            raise CursorStoreError(f"Cannot read cursor file {self.path}") from exc
+        if (
+            version != self.version
+            or isinstance(cursor, bool)
+            or not isinstance(cursor, int)
+        ):
+            raise CursorStoreError(f"Invalid cursor file {self.path}")
+        if cursor < 0:
+            raise CursorStoreError(f"Cursor cannot be negative in {self.path}")
+        return cursor
+
+    def save(self, cursor: int) -> None:
+        if isinstance(cursor, bool) or not isinstance(cursor, int) or cursor < 0:
+            raise CursorStoreError("Cursor must be a non-negative integer")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.path.with_name(f".{self.path.name}.{os.getpid()}.tmp")
+        payload = {
+            "version": self.version,
+            "cursor": cursor,
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+        try:
+            with temporary.open("w", encoding="utf-8", newline="\n") as file:
+                json.dump(payload, file, ensure_ascii=False, separators=(",", ":"))
+                file.write("\n")
+                file.flush()
+                os.fsync(file.fileno())
+            temporary.replace(self.path)
+        except OSError as exc:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+            raise CursorStoreError(f"Cannot write cursor file {self.path}") from exc

nonebot_plugin_tgforwarder/dispatcher.py

@@ -0,0 +1,60 @@
+import inspect
+from collections.abc import Awaitable
+from typing import Any, Callable, TypeVar, Union, cast
+
+from nonebot import get_bots
+from nonebot.message import handle_event
+from nonebot.matcher import Matcher
+
+from .event import PublicMessageEvent
+from .models import PublicMessage
+
+MessageHandler = Callable[[PublicMessage], Union[None, Awaitable[None]]]
+HandlerType = TypeVar("HandlerType", bound=MessageHandler)
+
+
+class MessageDispatchUnavailable(RuntimeError):
+    pass
+
+
+class MessageDispatcher:
+    def __init__(self, matcher: type[Matcher], *, dispatch_matcher: bool = True) -> None:
+        self.matcher = matcher
+        self.dispatch_matcher = dispatch_matcher
+        self._callbacks: list[MessageHandler] = []
+
+    @property
+    def callbacks(self) -> tuple[MessageHandler, ...]:
+        return tuple(self._callbacks)
+
+    def register(self, handler: HandlerType) -> HandlerType:
+        if handler not in self._callbacks:
+            self._callbacks.append(handler)
+        return handler
+
+    def unregister(self, handler: MessageHandler) -> None:
+        try:
+            self._callbacks.remove(handler)
+        except ValueError:
+            pass
+
+    async def dispatch(self, message: PublicMessage) -> None:
+        matcher_handlers = bool(self.matcher.handlers) if self.dispatch_matcher else False
+        bots = get_bots() if matcher_handlers else {}
+        if not self._callbacks and not matcher_handlers:
+            raise MessageDispatchUnavailable(
+                "No public message callback or matcher handler is registered"
+            )
+        if matcher_handlers and not bots:
+            raise MessageDispatchUnavailable(
+                "A matcher handler is registered but no NoneBot bot is connected"
+            )
+
+        for callback in tuple(self._callbacks):
+            result = callback(message)
+            if inspect.isawaitable(result):
+                await cast(Awaitable[Any], result)
+
+        if matcher_handlers:
+            bot = next(iter(bots.values()))
+            await handle_event(bot, PublicMessageEvent(message=message))

nonebot_plugin_tgforwarder/event.py

@@ -0,0 +1,68 @@
+from typing import Any
+
+from nonebot.adapters import Event, Message, MessageSegment
+
+from .models import PublicMessage
+
+
+class PublicMessageSegment(MessageSegment["PublicEventMessage"]):
+    @classmethod
+    def get_message_class(cls) -> type["PublicEventMessage"]:
+        return PublicEventMessage
+
+    @classmethod
+    def text(cls, text: str) -> "PublicMessageSegment":
+        return cls(type="text", data={"text": text})
+
+    def __str__(self) -> str:
+        return str(self.data.get("text", ""))
+
+    def is_text(self) -> bool:
+        return self.type == "text"
+
+
+class PublicEventMessage(Message[PublicMessageSegment]):
+    @classmethod
+    def get_segment_class(cls) -> type[PublicMessageSegment]:
+        return PublicMessageSegment
+
+
+class PublicMessageEvent(Event):
+    """NoneBot event carrying one processed public API message."""
+
+    message: PublicMessage
+
+    def get_type(self) -> str:
+        return "message"
+
+    def get_event_name(self) -> str:
+        return "tgforwarder.public_message"
+
+    def get_event_description(self) -> str:
+        text = self.message.text.replace("\n", " ")
+        return (
+            f"Public message {self.message.delivery_id} from "
+            f"{self.message.source_backend}:{self.message.source_chat_id}: {text[:80]}"
+        )
+
+    def get_user_id(self) -> str:
+        return str(self.message.source_chat_id)
+
+    def get_session_id(self) -> str:
+        return f"{self.message.source_backend}:{self.message.source_chat_id}"
+
+    def get_message(self) -> PublicEventMessage:
+        return PublicEventMessage(PublicMessageSegment.text(self.message.text))
+
+    def is_tome(self) -> bool:
+        return False
+
+    def get_log_string(self) -> str:
+        return self.get_event_description()
+
+    @property
+    def raw_message(self) -> dict[str, Any]:
+        dump = getattr(self.message, "model_dump", None)
+        if dump is not None:
+            return dump()
+        return self.message.dict()

nonebot_plugin_tgforwarder/models.py

@@ -0,0 +1,84 @@
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import VERSION, BaseModel, Field
+
+
+if VERSION.startswith("1."):
+
+    class APIModel(BaseModel):
+        """Base model tolerant of fields added by newer API versions."""
+
+        class Config:
+            extra = "allow"
+
+else:
+    from pydantic import ConfigDict
+
+    class APIModel(BaseModel):
+        """Base model tolerant of fields added by newer API versions."""
+
+        model_config = ConfigDict(extra="allow")
+
+
+class PublicMediaItem(APIModel):
+    media_type: str
+    original_filename: Optional[str] = None
+    mime_type: Optional[str] = None
+    file_size: Optional[int] = None
+    source_message_id: Optional[int] = None
+    order: int = 0
+    file_unique_id: Optional[str] = None
+
+
+class PublicMessage(APIModel):
+    """A processed message returned by safewbot's public pull API."""
+
+    delivery_id: int = Field(ge=1)
+    created_at: datetime
+    source_backend: str
+    source_chat_id: int
+    source_message_id: int
+    source_chat_username: Optional[str] = None
+    grouped_id: Optional[int] = None
+    text: str = ""
+    media_type: str = "text"
+    media_items: list[PublicMediaItem] = Field(default_factory=list)
+    processed_at: datetime
+
+    @property
+    def deduplication_key(self) -> int:
+        return self.delivery_id
+
+
+class MessagePage(APIModel):
+    items: list[PublicMessage] = Field(default_factory=list)
+    next_cursor: int = Field(ge=0)
+    has_more: bool = False
+
+
+class PublicAPIEnvelope(APIModel):
+    ok: bool
+    data: MessagePage
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class PublicAPIErrorDetail(APIModel):
+    code: str = "unknown_error"
+    message: str = "Unknown API error"
+    details: dict[str, Any] = Field(default_factory=dict)
+    request_id: Optional[str] = None
+
+
+class PublicAPIErrorEnvelope(APIModel):
+    ok: bool = False
+    error: PublicAPIErrorDetail
+
+
+def validate_model(model_type: Any, value: Any) -> Any:
+    """Support both Pydantic 1 and 2 accepted by NoneBot 2.3."""
+
+    model_validate = getattr(model_type, "model_validate", None)
+    if model_validate is not None:
+        return model_validate(value)
+    return model_type.parse_obj(value)

nonebot_plugin_tgforwarder/poller.py

@@ -0,0 +1,188 @@
+import asyncio
+import random
+from collections import deque
+from collections.abc import Awaitable
+from contextlib import suppress
+from typing import Callable, Optional
+
+from nonebot import logger
+
+from .client import FatalPublicAPIError, PublicMessageClient, RetryablePublicAPIError
+from .cursor import CursorStore, CursorStoreError
+from .models import MessagePage, PublicMessage
+
+Dispatch = Callable[[PublicMessage], Awaitable[None]]
+AllowMessage = Callable[[PublicMessage], bool]
+
+
+class PublicMessagePoller:
+    def __init__(
+        self,
+        client: PublicMessageClient,
+        cursor_store: CursorStore,
+        dispatch: Dispatch,
+        *,
+        allow_message: Optional[AllowMessage] = None,
+        initial_cursor: int = 0,
+        page_limit: int = 50,
+        poll_interval: float = 2.0,
+        retry_initial: float = 1.0,
+        retry_max: float = 60.0,
+        retry_jitter: float = 0.2,
+        dedup_cache_size: int = 2048,
+        shutdown_timeout: float = 5.0,
+    ) -> None:
+        self.client = client
+        self.cursor_store = cursor_store
+        self.dispatch = dispatch
+        self.allow_message = allow_message
+        self.initial_cursor = initial_cursor
+        self.page_limit = page_limit
+        self.poll_interval = poll_interval
+        self.retry_initial = retry_initial
+        self.retry_max = max(retry_initial, retry_max)
+        self.retry_jitter = retry_jitter
+        self.shutdown_timeout = shutdown_timeout
+        self._seen_order: deque[int] = deque()
+        self._seen: set[int] = set()
+        self._dedup_cache_size = dedup_cache_size
+        self._stop_event = asyncio.Event()
+        self._task: Optional[asyncio.Task[None]] = None
+        self._committed_cursor = initial_cursor
+
+    async def start(self) -> None:
+        if self._task is not None and not self._task.done():
+            return
+        self._stop_event.clear()
+        self._task = asyncio.create_task(self.run(), name="tgforwarder-public-api-poller")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+        task = self._task
+        if task is not None and not task.done():
+            try:
+                await asyncio.wait_for(task, timeout=self.shutdown_timeout)
+            except asyncio.TimeoutError:
+                task.cancel()
+                with suppress(asyncio.CancelledError):
+                    await task
+        self._task = None
+        await self.client.aclose()
+
+    async def run(self) -> None:
+        try:
+            cursor = self.cursor_store.load(self.initial_cursor)
+        except CursorStoreError:
+            logger.exception(
+                "Failed to load tgforwarder cursor; using configured initial cursor {}",
+                self.initial_cursor,
+            )
+            cursor = self.initial_cursor
+        self._committed_cursor = cursor
+
+        retry_delay = self.retry_initial
+        logger.info(
+            "tgforwarder public API poller started at cursor {} (page limit {})",
+            cursor,
+            self.page_limit,
+        )
+        try:
+            while not self._stop_event.is_set():
+                try:
+                    page = await self.client.fetch_messages(
+                        cursor=cursor,
+                        limit=self.page_limit,
+                    )
+                    cursor = await self.process_page(page, cursor=cursor)
+                except RetryablePublicAPIError as exc:
+                    logger.warning(
+                        "Transient public API error at cursor {}: {}; retrying",
+                        cursor,
+                        exc,
+                    )
+                    await self._wait(self._jittered(retry_delay))
+                    retry_delay = min(self.retry_max, retry_delay * 2)
+                    continue
+                except FatalPublicAPIError as exc:
+                    logger.error(
+                        "Public API rejected the request or response at cursor {}: {} "
+                        "(status={}, code={}, request_id={})",
+                        cursor,
+                        exc,
+                        exc.status_code,
+                        exc.error_code,
+                        exc.request_id,
+                    )
+                    await self._wait(self.retry_max)
+                    continue
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    cursor = self._committed_cursor
+                    logger.exception(
+                        "Failed to dispatch or persist public message at cursor {}; "
+                        "the uncommitted message will be retried",
+                        cursor,
+                    )
+                    await self._wait(self._jittered(retry_delay))
+                    retry_delay = min(self.retry_max, retry_delay * 2)
+                    continue
+
+                retry_delay = self.retry_initial
+                if page.has_more:
+                    continue
+                await self._wait(self.poll_interval)
+        finally:
+            logger.info("tgforwarder public API poller stopped at cursor {}", cursor)
+
+    async def process_page(self, page: MessagePage, *, cursor: int) -> int:
+        current = cursor
+        self._committed_cursor = current
+        for message in page.items:
+            delivery_id = message.delivery_id
+            if delivery_id <= current or delivery_id in self._seen:
+                logger.debug("Skipping duplicate public delivery {}", delivery_id)
+                continue
+            allowed = self.allow_message is None or self.allow_message(message)
+            if allowed:
+                await self.dispatch(message)
+            else:
+                logger.info(
+                    "Skipping public delivery {} from non-whitelisted group {}",
+                    delivery_id,
+                    message.source_chat_id,
+                )
+            self.cursor_store.save(delivery_id)
+            current = delivery_id
+            self._committed_cursor = current
+            self._remember(delivery_id)
+            logger.debug(
+                "Committed public delivery {} from {}:{}",
+                delivery_id,
+                message.source_backend,
+                message.source_chat_id,
+            )
+        return current
+
+    def _remember(self, delivery_id: int) -> None:
+        if delivery_id in self._seen:
+            return
+        self._seen.add(delivery_id)
+        self._seen_order.append(delivery_id)
+        while len(self._seen_order) > self._dedup_cache_size:
+            expired = self._seen_order.popleft()
+            self._seen.discard(expired)
+
+    def _jittered(self, delay: float) -> float:
+        if self.retry_jitter <= 0:
+            return delay
+        spread = delay * self.retry_jitter
+        return max(0.0, random.uniform(delay - spread, delay + spread))
+
+    async def _wait(self, delay: float) -> None:
+        if delay <= 0:
+            return
+        try:
+            await asyncio.wait_for(self._stop_event.wait(), timeout=delay)
+        except asyncio.TimeoutError:
+            pass

nonebot_plugin_tgforwarder/whitelist.py

@@ -0,0 +1,140 @@
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from nonebot.adapters import Event
+
+
+class WhitelistStoreError(RuntimeError):
+    pass
+
+
+class GroupWhitelistStore:
+    """Persist allowed source group IDs using an atomic same-directory replace."""
+
+    version = 1
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._groups: set[int] = set()
+
+    @property
+    def groups(self) -> tuple[int, ...]:
+        return tuple(sorted(self._groups))
+
+    def contains(self, group_id: int) -> bool:
+        return group_id in self._groups
+
+    def load(self) -> tuple[int, ...]:
+        self._groups.clear()
+        if not self.path.exists():
+            return self.groups
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+            version = payload["version"]
+            groups = payload["groups"]
+        except (OSError, json.JSONDecodeError, KeyError, TypeError) as exc:
+            raise WhitelistStoreError(
+                f"Cannot read group whitelist file {self.path}"
+            ) from exc
+        if version != self.version or not isinstance(groups, list):
+            raise WhitelistStoreError(f"Invalid group whitelist file {self.path}")
+        if any(
+            isinstance(group_id, bool) or not isinstance(group_id, int)
+            for group_id in groups
+        ):
+            raise WhitelistStoreError(f"Invalid group whitelist file {self.path}")
+        self._groups = set(groups)
+        return self.groups
+
+    def add(self, group_id: int) -> bool:
+        self._validate_group_id(group_id)
+        if group_id in self._groups:
+            return False
+        groups = self._groups | {group_id}
+        self._save(groups)
+        self._groups = groups
+        return True
+
+    def remove(self, group_id: int) -> bool:
+        self._validate_group_id(group_id)
+        if group_id not in self._groups:
+            return False
+        groups = self._groups - {group_id}
+        self._save(groups)
+        self._groups = groups
+        return True
+
+    @staticmethod
+    def _validate_group_id(group_id: int) -> None:
+        if isinstance(group_id, bool) or not isinstance(group_id, int):
+            raise WhitelistStoreError("Group ID must be an integer")
+
+    def _save(self, groups: set[int]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.path.with_name(f".{self.path.name}.{os.getpid()}.tmp")
+        payload = {
+            "version": self.version,
+            "groups": sorted(groups),
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+        try:
+            with temporary.open("w", encoding="utf-8", newline="\n") as file:
+                json.dump(payload, file, ensure_ascii=False, separators=(",", ":"))
+                file.write("\n")
+                file.flush()
+                os.fsync(file.fileno())
+            temporary.replace(self.path)
+        except OSError as exc:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+            raise WhitelistStoreError(
+                f"Cannot write group whitelist file {self.path}"
+            ) from exc
+
+
+def execute_whitelist_command(raw_argument: str, store: GroupWhitelistStore) -> str:
+    parts = raw_argument.split()
+    if not parts:
+        return _usage()
+
+    action = parts[0].lower()
+    if action == "list":
+        if len(parts) != 1:
+            return _usage()
+        groups = store.groups
+        if not groups:
+            return "群白名单为空。"
+        return f"群白名单（{len(groups)}）：\n" + "\n".join(map(str, groups))
+
+    if action not in {"add", "del"} or len(parts) != 2:
+        return _usage()
+    try:
+        group_id = int(parts[1])
+    except ValueError:
+        return "群号必须是整数。\n" + _usage()
+
+    if action == "add":
+        if store.add(group_id):
+            return f"已加入群白名单：{group_id}"
+        return f"群号已在白名单中：{group_id}"
+
+    if store.remove(group_id):
+        return f"已从群白名单删除：{group_id}"
+    return f"群号不在白名单中：{group_id}"
+
+
+def is_private_message(event: Event) -> bool:
+    """Fail closed for adapters without a recognizable private-message marker."""
+
+    return any(
+        getattr(event, attribute, None) == "private"
+        for attribute in ("message_type", "detail_type")
+    )
+
+
+def _usage() -> str:
+    return "用法：/tgfwd add 群号 | /tgfwd del 群号 | /tgfwd list"

nonebot_plugin_tgforwarder-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.1
+Name: nonebot-plugin-tgforwarder
+Version: 0.1.0
+Summary: Poll safewbot's public message API and dispatch processed messages to NoneBot
+Author: EasiFlux
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: nonebot2>=2.3.1
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Description-Content-Type: text/markdown
+
+# nonebot-plugin-tgforwarder
+
+一个 NoneBot2 插件，通过轮询 `safewbot` 的公开消息 HTTP API 获取已经完成规则处理或审核发布的消息，并把它们交给 Python 回调或 NoneBot matcher。
+
+## 实现边界
+
+数据流：
+
+```text
+safewbot 公开消息 API
+  -> HTTP 轮询
+  -> cursor / delivery_id 去重与消息建模
+  -> Python 回调或 NoneBot 自定义事件 matcher
+  -> 业务自己的后续转发逻辑
+```
+
+本插件仅调用：
+
+```http
+GET /api/public/v1/messages?cursor=<int>&limit=<1..100>
+Authorization: Bearer <API endpoint token>
+```
+
+不包含以下能力：
+
+- SafeW 普通账号登录或私密群监听；
+- SafeW Bot API 的 `getUpdates` / webhook；
+- `safewbot` Web 管理 API；
+- 媒体文件下载。
+
+公开 API 当前只返回处理后的文本和媒体元数据，不返回本地文件路径、下载 URL 或媒体二进制。插件不会读取或修改 `safewbot` 仓库。
+
+## 安装
+
+```bash
+pip install nonebot-plugin-tgforwarder
+```
+
+在 NoneBot 项目中加载插件：
+
+```python
+nonebot.load_plugin("nonebot_plugin_tgforwarder")
+```
+
+先在 `safewbot` 管理后台创建“对外 API”目标，绑定需要的来源，并保存只显示一次的 Token。
+
+## 配置
+
+在 NoneBot 的 `.env` 中配置：
+
+```dotenv
+TGFORWARDER_API_BASE_URL=http://127.0.0.1:8000
+TGFORWARDER_API_TOKEN=tgf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `TGFORWARDER_ENABLED` | `true` | 是否启动轮询器 |
+| `TGFORWARDER_API_BASE_URL` | `http://127.0.0.1:8000` | `safewbot` Web 服务根地址 |
+| `TGFORWARDER_API_TOKEN` | 空 | 公开 API 目标 Token；为空时记录错误且不启动 |
+| `TGFORWARDER_CURSOR_FILE` | `data/tgforwarder-cursor.json` | 跨重启游标文件 |
+| `TGFORWARDER_WHITELIST_FILE` | `data/tgforwarder-whitelist.json` | 来源群白名单文件 |
+| `TGFORWARDER_INITIAL_CURSOR` | `0` | 游标文件不存在或损坏时的起始游标 |
+| `TGFORWARDER_PAGE_LIMIT` | `50` | 单页条数，范围 `1..100` |
+| `TGFORWARDER_POLL_INTERVAL` | `2.0` | 无更多消息时的轮询间隔（秒） |
+| `TGFORWARDER_REQUEST_TIMEOUT` | `30.0` | HTTP 请求超时（秒） |
+| `TGFORWARDER_RETRY_INITIAL` | `1.0` | 首次重试等待（秒） |
+| `TGFORWARDER_RETRY_MAX` | `60.0` | 最大退避等待（秒） |
+| `TGFORWARDER_RETRY_JITTER` | `0.2` | 退避随机抖动比例，范围 `0..1` |
+| `TGFORWARDER_DEDUP_CACHE_SIZE` | `2048` | 内存中的 `delivery_id` 去重容量 |
+| `TGFORWARDER_DISPATCH_MATCHER` | `true` | 是否向 NoneBot matcher 分发事件 |
+| `TGFORWARDER_MATCHER_PRIORITY` | `1` | 自定义事件 matcher 优先级 |
+| `TGFORWARDER_SHUTDOWN_TIMEOUT` | `5.0` | 关闭时等待当前处理完成的最长时间 |
+
+游标文件与一个公开 API 目标配套使用。切换到另一个 API 目标时，应更换或删除游标文件；Token 仅在同一目标上轮换时可以保留原游标。
+
+## 群白名单
+
+插件默认拒绝所有来源群。只有 `PublicMessage.source_chat_id` 已加入白名单的消息才会分发给 Python 回调或 NoneBot matcher。
+
+将 Bot 主人的账号配置为 NoneBot 超级用户：
+
+```dotenv
+SUPERUSERS=["123456789"]
+```
+
+Bot 主人可以在与 Bot 的私聊中管理白名单：
+
+```text
+/tgfwd add 群号
+/tgfwd del 群号
+/tgfwd list
+```
+
+非白名单群的消息会跳过分发并提交游标，防止阻塞同一 API 队列中的其他群。之后再加入白名单，也不会补发此前已经跳过的历史消息。
+
+## 消费消息
+
+### Python 回调
+
+回调不依赖已连接的 NoneBot Bot，适合把消息交给自己的服务层：
+
+```python
+from nonebot_plugin_tgforwarder import PublicMessage, on_public_message
+
+
+@on_public_message
+async def consume(message: PublicMessage) -> None:
+    print(message.delivery_id, message.source_chat_id, message.text)
+```
+
+### NoneBot matcher
+
+自定义 matcher 需要至少一个已连接的 NoneBot Bot，用于进入 NoneBot 的事件处理管线：
+
+```python
+from nonebot_plugin_tgforwarder import PublicMessageEvent, public_message_matcher
+
+
+@public_message_matcher.handle()
+async def consume_event(event: PublicMessageEvent) -> None:
+    message = event.message
+    print(message.delivery_id, message.media_items)
+```
+
+如果白名单内的消息没有任何已注册回调或 matcher handler，插件不会推进该条游标，避免静默丢弃消息。
+
+## 交付、重试与去重
+
+- `delivery_id` 是 API 目标内可见记录的增量游标，不要求连续；
+- 每条消息分发成功后立即原子写入游标，因此同页后续消息失败不会重放此前已提交条目；
+- 网络错误、超时、HTTP `408`、`429` 和 `5xx` 使用原 cursor 指数退避重试；
+- HTTP `401`、`422` 及响应契约错误会记录完整的非敏感诊断，并按最大间隔继续探测；日志不会输出 Token；
+- 关闭时先通知轮询器停止，超时后取消任务，并关闭 HTTP 客户端；
+- API 没有业务 ACK，所以端到端语义是“至少一次”。回调中的外部副作用应以 `delivery_id` 做幂等；
+- 一个回调失败时不提交当前消息，后续会重试。此前已执行但未完成整条确认的回调也可能再次执行。
+
+## 测试
+
+```bash
+pdm install -G dev
+pdm test
+```
+
+测试覆盖公开 API 鉴权与响应解析、错误分类、响应游标约束、游标和白名单原子持久化、白名单命令，以及逐条提交和失败重放行为。
+
+## 发布
+
+版本号、`CHANGELOG.md`、Git 标签和 GitHub Release 由 release-please 管理。提交信息遵循 Conventional Commits：
+
+- `fix:` 触发补丁版本；
+- `feat:` 触发次版本；
+- `feat!:`、`fix!:` 或提交正文中的 `BREAKING CHANGE:` 触发主版本。
+
+合并 release-please 创建的发布 PR 后，工作流会创建 Release、构建发行包并通过 PyPI Trusted Publishing 发布。

nonebot_plugin_tgforwarder-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+nonebot_plugin_tgforwarder-0.1.0.dist-info/METADATA,sha256=t3dc0nUfO6TYjA2vfIQIlZstNFY8PAaa3Jh_RVWspyk,6195
+nonebot_plugin_tgforwarder-0.1.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+nonebot_plugin_tgforwarder-0.1.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+nonebot_plugin_tgforwarder/__init__.py,sha256=ahXHBQfnyS3AnLXKNY0QskUD0f24pDrR1h51weLWRIU,4749
+nonebot_plugin_tgforwarder/client.py,sha256=W-ncwi-ToJCVyxegISt8iP2Gre65aCxh4buukgh9edY,5754
+nonebot_plugin_tgforwarder/config.py,sha256=PEiOddGC-IJDnGuXPIXizVY_2syEiQln2ZfE04FDSaM,1145
+nonebot_plugin_tgforwarder/cursor.py,sha256=CEJOEDXo2F_9CRi8jPb1mitPO4Tr8-L_EzE44QSqFQ8,2145
+nonebot_plugin_tgforwarder/dispatcher.py,sha256=QJfRtnEcA8am1behe0PlJ_-tosgiWvoMe-TNOQE_q6A,2086
+nonebot_plugin_tgforwarder/event.py,sha256=UpziGxBEKJ15_xOQFkQycDSDnCDgXzdiLiuPP9_HVRE,1960
+nonebot_plugin_tgforwarder/models.py,sha256=3hlSfzyH8L7r_wKQmM-Pf3Z6VswYxag-hTBonAlHm7Q,2207
+nonebot_plugin_tgforwarder/poller.py,sha256=jbXrMOYlZkNTkTmH7CqqhC1edY2yvlAfUPtzfoPn5nE,7111
+nonebot_plugin_tgforwarder/whitelist.py,sha256=ZDR3eYkzZeslv55o-HW6Shhxd5as2Yos0KKv1b1vLm8,4561
+nonebot_plugin_tgforwarder-0.1.0.dist-info/RECORD,,

nonebot_plugin_tgforwarder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

nonebot_plugin_tgforwarder-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+