From 818c994afaa5496a9acc00f4803f24f9846cc160 Mon Sep 17 00:00:00 2001 From: timeance <30307526+timeance@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:40:26 +0800 Subject: [PATCH] feat: implement battle reports with consistent identity and request admission --- .github/workflows/ci.yml | 4 + _conf_schema.json | 165 +++++++++ client.py | 546 ++++++++++++++++++++++++++++ commands.py | 181 +++++++++ docs/API_NOTES.md | 2 +- docs/VALIDATION.md | 14 +- main.py | 225 ++++++++++++ models.py | 274 ++++++++++++++ pending.py | 125 +++++++ quota.py | 42 +++ render.py | 346 ++++++++++++++++++ service.py | 314 ++++++++++++++++ settings.py | 84 +++++ storage.py | 266 ++++++++++++++ templates/_macros.html | 9 + templates/base.html | 135 +++++++ templates/match.html | 30 ++ templates/overview.html | 13 + templates/recent.html | 16 + tests/test_client.py | 704 ++++++++++++++++++++++++++++++++++++ tests/test_client_quota.py | 613 +++++++++++++++++++++++++++++++ tests/test_commands.py | 160 ++++++++ tests/test_main.py | 523 +++++++++++++++++++++++++++ tests/test_models.py | 176 +++++++++ tests/test_pending.py | 219 +++++++++++ tests/test_quota_storage.py | 402 ++++++++++++++++++++ tests/test_render.py | 256 +++++++++++++ tests/test_service.py | 472 ++++++++++++++++++++++++ tests/test_storage.py | 264 ++++++++++++++ tools/build_delivery.py | 254 +++++++++++++ tools/render_previews.py | 198 ++++++++++ 31 files changed, 7030 insertions(+), 2 deletions(-) create mode 100644 _conf_schema.json create mode 100644 client.py create mode 100644 commands.py create mode 100644 main.py create mode 100644 models.py create mode 100644 pending.py create mode 100644 quota.py create mode 100644 render.py create mode 100644 service.py create mode 100644 settings.py create mode 100644 storage.py create mode 100644 templates/_macros.html create mode 100644 templates/base.html create mode 100644 templates/match.html create mode 100644 templates/overview.html create mode 100644 templates/recent.html create mode 100644 tests/test_client.py create mode 100644 tests/test_client_quota.py create mode 100644 tests/test_commands.py create mode 100644 tests/test_main.py create mode 100644 tests/test_models.py create mode 100644 tests/test_pending.py create mode 100644 tests/test_quota_storage.py create mode 100644 tests/test_render.py create mode 100644 tests/test_service.py create mode 100644 tests/test_storage.py create mode 100644 tools/build_delivery.py create mode 100644 tools/render_previews.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c6a04a0..caa95fb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -49,3 +49,7 @@ jobs: PY - name: Check Python syntax run: python -m compileall -q . + - name: Run offline tests + run: python -m pytest -q + - name: Build and verify delivery archives + run: python tools/build_delivery.py --output dist diff --git a/_conf_schema.json b/_conf_schema.json new file mode 100644 index 0000000..dbf4eca --- /dev/null +++ b/_conf_schema.json @@ -0,0 +1,165 @@ +{ + "access": { + "type": "object", + "description": "数据源接入", + "items": { + "enabled": { + "description": "启用在线查询", + "type": "bool", + "default": false, + "hint": "请先取得 BATrace 对本插件的独立接入许可,填写获准客户端标识后再开启。", + "obvious_hint": true + }, + "client_id": { + "description": "获准客户端标识", + "type": "string", + "default": "", + "hint": "由 BATrace 运营方为本插件单独分配,请勿借用其他项目的标识。", + "secret": true + }, + "api_token": { + "description": "访问令牌(如需要)", + "type": "string", + "default": "", + "hint": "仅在运营方要求 Bearer 令牌时填写。", + "secret": true + }, + "base_url": { + "description": "API 地址", + "type": "string", + "default": "https://bot.batrace.top", + "hint": "以运营方确认的 HTTPS 地址为准。" + } + } + }, + "query": { + "type": "object", + "description": "查询与命令", + "items": { + "default_limit": { + "description": "默认近期场数", + "type": "int", + "default": 5, + "hint": "范围 1 到「最大近期场数」之间。" + }, + "max_limit": { + "description": "最大近期场数", + "type": "int", + "default": 20, + "hint": "上限 20;仅展示当前接口返回的样本,不代表玩家完整生涯历史。" + }, + "cooldown_seconds": { + "description": "同一用户查询间隔(秒)", + "type": "float", + "default": 3.0, + "hint": "限制查询命令的触发间隔,命中缓存也适用;帮助、查看绑定、解绑、额度查看及候选确认不受此冷却限制。" + }, + "chinese_aliases": { + "description": "启用中文子命令别名", + "type": "bool", + "default": true, + "hint": "如 /ba 帮助;英文主命令始终可用。" + } + } + }, + "limits": { + "type": "object", + "description": "每日请求额度", + "hint": "全插件每天最多 100 次上游请求,此总上限固定不可修改。所有额度北京时间每天 0 点重置;保存后重载插件生效,不清零已用次数。", + "items": { + "user_daily_limit": { + "description": "每用户每日请求额度", + "type": "int", + "default": 20, + "hint": "0–100;0 表示不单独限制,仍受全插件每日 100 次上限约束。同一平台用户跨群及私聊累计;按实际上游 HTTP 请求计数,重试及失败计入,命中缓存不计入。", + "obvious_hint": true + }, + "group_daily_limit": { + "description": "每群每日请求额度", + "type": "int", + "default": 100, + "hint": "0–100;0 表示不单独限制,仍受全插件每日 100 次上限约束。群内所有用户共用,私聊不扣群额度。管理员查询同样计入。" + } + } + }, + "output": { + "type": "object", + "description": "战报显示", + "items": { + "image_enabled": { + "description": "发送图片战报", + "type": "bool", + "default": true, + "hint": "调用 AstrBot 图文渲染服务生成战报图;渲染失败时自动回退为同内容文字。" + }, + "theme": { + "description": "图片主题", + "type": "string", + "default": "dark", + "options": [ + "dark", + "light" + ], + "labels": [ + "深色", + "浅色" + ] + }, + "timezone": { + "description": "显示时区", + "type": "string", + "default": "Asia/Shanghai", + "hint": "IANA 时区名,例如 Asia/Shanghai 或 Asia/Hong_Kong。仅改变战报显示,额度仍固定按北京时间 0 点重置。" + } + } + }, + "maintenance": { + "type": "object", + "description": "维护与请求限制", + "items": { + "request_interval": { + "description": "上游请求最小间隔(秒)", + "type": "float", + "default": 1.0, + "hint": "根据获准接入频率调整,对所有在线查询全局生效。" + }, + "concurrency": { + "description": "上游并发上限", + "type": "int", + "default": 2 + }, + "queue_size": { + "description": "待处理请求上限", + "type": "int", + "default": 20 + }, + "request_timeout": { + "description": "单次请求超时(秒)", + "type": "float", + "default": 20.0 + }, + "wait_timeout": { + "description": "总等待上限(秒)", + "type": "float", + "default": 45.0 + }, + "retries": { + "description": "临时故障重试次数", + "type": "int", + "default": 1, + "hint": "范围 0–2 次;鉴权失败、人机验证及数据结构错误不会重试。" + }, + "cache_max_entries": { + "description": "API 缓存容量(条)", + "type": "int", + "default": 1000 + }, + "stale_hours": { + "description": "故障时旧缓存最长保留(小时)", + "type": "float", + "default": 24.0, + "hint": "0 表示禁用旧缓存回退;使用旧缓存时战报会明确标明抓取时间。" + } + } + } +} diff --git a/client.py b/client.py new file mode 100644 index 0000000..ae57f40 --- /dev/null +++ b/client.py @@ -0,0 +1,546 @@ +"""Independent BATrace adapter with bounded scheduling and persistent caching. + +Creating a client never probes the source. All network methods require explicit +access enablement and this plugin's own operator-approved client identity. +""" + +from __future__ import annotations + +import asyncio +from contextlib import contextmanager +from contextvars import ContextVar +from dataclasses import dataclass, field +from datetime import datetime, timezone +from email.utils import parsedate_to_datetime +import hashlib +import json +import math +import time +from typing import Any, Awaitable, Callable, Protocol, TypeVar +from urllib.parse import urlsplit + +import httpx + +if __package__: + from .quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day + from .models import ( + FetchResult, Match, Participant, Player, canonical_id, parse_match, parse_player, + parse_recent, parse_search, utc_datetime, + ) +else: # Direct module imports for framework-independent tests. + from quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day + from models import ( + FetchResult, Match, Participant, Player, canonical_id, parse_match, parse_player, + parse_recent, parse_search, utc_datetime, + ) + +T = TypeVar("T") + + +class CacheStorage(Protocol): + async def get_cache(self, key: str) -> tuple[Any, Any, Any] | None: ... + async def put_cache(self, key: str, payload: Any, ttl: float) -> None: ... + async def clear_cache(self) -> None: ... + async def prune_cache(self, max_entries: int = 1000, max_age_seconds: float = 604800) -> Any: ... + async def cache_count(self) -> int: ... + async def consume_request(self, actor: QuotaActor | None = None, *, user_limit: int = 20, + group_limit: int = 100, ready: Callable[[], bool] | None = None) -> dict: ... + async def quota_usage(self, actor: QuotaActor | None = None) -> dict: ... + + +@dataclass(frozen=True) +class ClientConfig: + enabled: bool = False + base_url: str = "https://bot.batrace.top" + client_id: str = "" + api_token: str = field(default="", repr=False) + request_interval: float = 1.0 + concurrency: int = 2 + queue_size: int = 20 + request_timeout: float = 20.0 + wait_timeout: float = 45.0 + retries: int = 1 + cache_max_entries: int = 1000 + stale_hours: float = 24.0 + user_daily_limit: int = 20 + group_daily_limit: int = 100 + + +class ClientError(Exception): + code = "client_error" + + +class NotConfiguredError(ClientError): + code = "not_configured" + + +class AuthenticationError(ClientError): + code = "authentication" + + +class RateLimitError(ClientError): + code = "rate_limited" + + def __init__(self, message: str = "数据源请求受限,请稍后重试。", *, retry_after: float | None = None): + super().__init__(message) + self.retry_after = retry_after + + +class RequestTimeoutError(ClientError): + code = "timeout" + + +class UpstreamError(ClientError): + code = "upstream" + + +class NoDataError(ClientError): + code = "no_data" + + +class SchemaError(ClientError): + code = "schema" + + +class IdentityMismatchError(ClientError): + code = "identity_mismatch" + + +def participant_for(match: Match, player_id: str) -> Participant | None: + """Empty rosters are unknown; a nonempty roster must contain the target.""" + person = next((p for p in match.players if p.player_id == player_id), None) + if match.players and person is None: + raise IdentityMismatchError("数据源返回了目标玩家未参与的对局,已中止本次查询。") + return person + + +class QueueFullError(ClientError): + code = "queue_full" + + +class ClientClosedError(ClientError): + code = "closed" + + +@dataclass +class _Flight: + task: asyncio.Task + waiters: int = 0 + force: bool = False + + +class BatraceClient: + """One shared instance per plugin; injected HTTP client remains caller-owned. + + search(query), player(id), recent(id, limit), match(id) return FetchResult. + ``force=True`` bypasses fresh cache but keeps the same admission/rate limits. + close() cancels and awaits owned jobs; it closes only an internally-created + AsyncClient. The caller closes an injected AsyncClient and Storage itself. + """ + + def __init__( + self, config: ClientConfig | None = None, *, + storage: CacheStorage | None = None, http_client: httpx.AsyncClient | None = None, + ): + self.config = config or ClientConfig() + c = self.config + if any(not math.isfinite(x) or x < 0 for x in (c.request_interval, c.stale_hours)): + raise ValueError("interval and stale age must be finite and nonnegative") + if any(not math.isfinite(x) or x <= 0 for x in (c.request_timeout, c.wait_timeout)): + raise ValueError("timeouts must be finite and positive") + if any(isinstance(x, bool) or not isinstance(x, int) for x in ( + c.concurrency, c.queue_size, c.retries, c.cache_max_entries, + )) or not (1 <= c.concurrency <= 8 and 0 <= c.queue_size <= 1000 + and 0 <= c.retries <= 2 and c.cache_max_entries > 0): + raise ValueError("invalid scheduler/cache bounds") + if any(type(x) is not int or not 0 <= x <= GLOBAL_DAILY_LIMIT + for x in (c.user_daily_limit, c.group_daily_limit)): + raise ValueError("user and group daily limits must be integers between 0 and 100") + self._storage = storage + self._http = http_client + self._owns_http = http_client is None + self._closed = False + self._slots = asyncio.Semaphore(c.concurrency) + self._start_lock = asyncio.Lock() + self._cache_lock = asyncio.Lock() + self._last_start: float | None = None + self._not_before = 0.0 + self._flights: dict[tuple[str, QuotaActor | None], _Flight] = {} + self._actor: ContextVar[QuotaActor | None] = ContextVar("ba_stats_actor", default=None) + # Standalone adapter tests may omit Storage. The plugin always supplies + # SQLite; identified requests require it so user/group limits persist. + self._local_quota_day = "" + self._local_quota_used = 0 + self._generation = 0 + self._requests = 0 + self._cache_hits = 0 + self._stale_hits = 0 + self._last_error: str | None = None + # Includes origin AND identity, so a different deployment/credential can + # never accidentally read another source's cached identity response. + source = json.dumps([c.base_url.rstrip("/"), c.client_id, c.api_token]) + self._namespace = "batrace:v1:" + hashlib.sha256(source.encode()).hexdigest()[:24] + + @property + def namespace(self) -> str: + """Stable binding identity: credential rotation must not change it.""" + origin = self.config.base_url.rstrip("/") + return "batrace:" + hashlib.sha256(origin.encode()).hexdigest()[:16] + + @property + def configured(self) -> bool: + c = self.config + if not c.enabled or not c.client_id.strip() or "ba-dragon" in c.client_id.casefold(): + return False + if any(ch in c.client_id + c.api_token for ch in "\r\n"): + return False + try: + u = urlsplit(c.base_url) + _ = u.port + return bool(u.scheme == "https" and u.hostname and not u.username and not u.password + and not u.query and not u.fragment and u.path in {"", "/"}) + except ValueError: + return False + + def _check_ready(self) -> None: + if self._closed: + raise ClientClosedError("数据源客户端已关闭,请稍后重试。") + if not self.configured: + raise NotConfiguredError("数据源接入未配置:需开启在线查询并填写本插件独立的获准客户端标识。") + + def status(self) -> dict[str, Any]: + """Safe admin diagnostics: never return token, header, query or URL.""" + return { + "configured": self.configured, "closed": self._closed, + "inflight": len(self._flights), "requests": self._requests, + "cache_hits": self._cache_hits, "stale_hits": self._stale_hits, + "last_error": self._last_error, + } + + @contextmanager + def request_scope(self, actor: QuotaActor): + """Carry the trusted event identity into all child requests/retries.""" + if self._storage is None: + raise RuntimeError("用户与群额度需要持久化存储。") + token = self._actor.set(actor) + try: + yield + finally: + self._actor.reset(token) + + def _local_usage(self) -> int: + day = quota_day(time.time()) + if self._local_quota_day != day: + self._local_quota_day, self._local_quota_used = day, 0 + return self._local_quota_used + + async def _check_daily_quota(self) -> None: + """Read-only preflight; reservation at send time remains authoritative.""" + usage = (await self._storage.quota_usage(self._actor.get()) if self._storage is not None + else {"global": self._local_usage(), "user": None, "group": None}) + for scope, limit in (("global", GLOBAL_DAILY_LIMIT), ("user", self.config.user_daily_limit), + ("group", self.config.group_daily_limit)): + if usage[scope] is not None and limit and usage[scope] >= limit: + raise QuotaExceededError(scope, limit, usage[scope]) + + async def _consume_request(self) -> None: + if self._storage is not None: + await self._storage.consume_request( + self._actor.get(), user_limit=self.config.user_daily_limit, + group_limit=self.config.group_daily_limit, + ready=self._send_ready, + ) + return + if self._local_usage() >= GLOBAL_DAILY_LIMIT: + raise QuotaExceededError("global", GLOBAL_DAILY_LIMIT, self._local_quota_used) + self._local_quota_used += 1 + + async def search(self, query: str, *, force: bool = False) -> FetchResult[list[Player]]: + if not isinstance(query, str) or not query.strip() or len(query) > 200: + raise ValueError("query must contain 1–200 characters") + async def load() -> Any: + return await self._request("/api/players/search", {"q": query, "limit": 20}) + return await self._get("search", [query, 20], load, parse_search, 600, force) + + async def player(self, id: str, *, force: bool = False) -> FetchResult[Player]: + pid = canonical_id(id) + async def load() -> Any: + search = await self._request("/api/players/search", {"q": pid, "limit": 20}) + try: + candidates = parse_search(search) + except (ValueError, TypeError, OverflowError) as exc: + raise SchemaError("玩家搜索返回的数据结构发生变化,暂无法解析。") from exc + if not any(p.id == pid for p in candidates): + raise IdentityMismatchError("数据源未返回对应的规范玩家 ID,无法核实身份。") + analysis = await self._request("/api/analysis/player", {"stbid": pid}) + return {"search": search, "analysis": analysis} + return await self._get("player", [pid], load, lambda p: parse_player(p, pid), 900, force) + + async def recent(self, id: str, limit: int = 5, *, force: bool = False) -> FetchResult[list[Match]]: + pid = canonical_id(id) + if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 20: + raise ValueError("recent limit must be between 1 and 20") + async def load() -> Any: + return await self._request("/api/players/matches", {"stbid": pid, "limit": limit}) + def decode(raw: Any) -> list[Match]: + matches = parse_recent(raw) + for match in matches: + participant_for(match, pid) + return matches[:limit] + return await self._get("recent", [pid, limit], load, decode, 600, force) + + async def match(self, id: str, *, force: bool = False) -> FetchResult[Match]: + mid = canonical_id(id) + async def load() -> Any: + return await self._request("/api/match", {"matchid": mid}) + return await self._get("match", [mid], load, lambda p: parse_match(p, mid), 86400, force) + + async def _get( + self, operation: str, parameters: list[Any], loader: Callable[[], Awaitable[Any]], + decoder: Callable[[Any], T], ttl: float, force: bool, + ) -> FetchResult[T]: + self._check_ready() + digest = hashlib.sha256(json.dumps(parameters, ensure_ascii=False).encode()).hexdigest() + key = f"{self._namespace}:{operation}:{digest}" + # Keep cache shared, but only coalesce network jobs for the same sender + # and group. Another caller must not spend or bypass the owner's quota. + flight_key = (key, self._actor.get()) + # force joins an already running refresh; no duplicate bypass lane. + flight = self._flights.get(flight_key) + if flight is not None and flight.task.done(): + self._flights.pop(flight_key, None) + flight = None + if flight is None: + if len(self._flights) >= self.config.concurrency + self.config.queue_size: + self._last_error = QueueFullError.code + raise QueueFullError("当前请求排队已满,请稍后重试。") + task = asyncio.create_task(self._load(key, loader, decoder, ttl, lambda: flight.force)) + flight = _Flight(task, force=force) + self._flights[flight_key] = flight + def finished(t: asyncio.Task) -> None: + if self._flights.get(flight_key) is flight: + self._flights.pop(flight_key, None) + if not t.cancelled(): + t.exception() # retrieve errors even if every waiter was cancelled + task.add_done_callback(finished) + elif force: + # A bind revalidation joining a cache lookup must promote the shared + # job before it decides whether a fresh cache hit is acceptable. + flight.force = True + flight.waiters += 1 + try: + return await asyncio.shield(flight.task) + except asyncio.CancelledError: + if self._closed: + raise ClientClosedError("数据源客户端已关闭,请稍后重试。") from None + raise + finally: + flight.waiters -= 1 + if not flight.waiters and not flight.task.done(): + flight.task.cancel() + await asyncio.gather(flight.task, return_exceptions=True) + + @staticmethod + def _decode(decoder: Callable[[Any], T], payload: Any) -> T: + try: + return decoder(payload) + except ClientError: + raise + except (ValueError, TypeError, OverflowError, OSError, KeyError) as exc: + raise SchemaError("数据源返回的数据结构发生变化,暂无法解析。") from exc + + async def _load( + self, key: str, loader: Callable[[], Awaitable[Any]], decoder: Callable[[Any], T], + ttl: float, force: Callable[[], bool], + ) -> FetchResult[T]: + cached: tuple[T, datetime, datetime] | None = None + generation = self._generation + try: + async with asyncio.timeout(self.config.wait_timeout): + if self._storage is not None: + hit = await self._storage.get_cache(key) + if hit is not None: + try: + payload, fetched, expires = hit + fetched, expires = utc_datetime(fetched), utc_datetime(expires) + if fetched is None or expires is None or fetched > expires: + raise ValueError("invalid cache timestamps") + cached = (self._decode(decoder, payload), fetched, expires) + except (ClientError, ValueError, TypeError, OverflowError, OSError): + cached = None # old/incompatible cache must be refetched + now = datetime.now(timezone.utc) + if cached and not force() and cached[2] > now and cached[1] <= now: + self._cache_hits += 1 + return self._result(cached[0], cached[1]) + await self._check_daily_quota() + async with self._slots: + self._check_ready() + raw = await loader() + data = self._decode(decoder, raw) + fetched_at = datetime.now(timezone.utc) + if isinstance(data, Match): + # A structural complete flag is insufficient for a just-ended + # match: keep it short until at least five minutes after end. + end = None + if data.started_at is not None and data.duration_seconds is not None: + end = data.started_at.timestamp() + data.duration_seconds + if not data.complete or end is None or time.time() - end < 300: + ttl = 60 + if self._storage is not None: + async with self._cache_lock: + if generation == self._generation: + await self._storage.put_cache(key, raw, ttl) + # Enforce the configured bound at every insertion; + # rely on Storage's constructor bound as well. + await self._storage.prune_cache( + max_entries=self.config.cache_max_entries, max_age_seconds=604800, + ) + self._last_error = None + return self._result(data, fetched_at) + except TimeoutError: + error: ClientError = RequestTimeoutError("本次查询超过总等待时间,请稍后重试。") + except (ClientError, QuotaExceededError) as exc: + error = exc + self._last_error = error.code + # No fallback for identity, authorization, not-found or schema failures. + if isinstance(error, (RequestTimeoutError, UpstreamError, RateLimitError)) and cached: + # Quota can become exhausted while this job waits/backoffs. Do not + # disguise that local limit as a temporary-source stale fallback. + try: + await self._check_daily_quota() + except QuotaExceededError as quota_error: + self._last_error = quota_error.code + raise + age = (datetime.now(timezone.utc) - cached[1]).total_seconds() + if 0 <= age <= self.config.stale_hours * 3600: + self._stale_hits += 1 + return self._result(cached[0], cached[1], stale=True, reason=error.code) + raise error + + @staticmethod + def _result(data: T, fetched_at: datetime, *, stale: bool = False, reason: str | None = None) -> FetchResult[T]: + records = data if isinstance(data, list) else [data] + times = [x.updated_at for x in records if getattr(x, "updated_at", None) is not None] + return FetchResult(data, fetched_at, stale, max(times) if times else None, reason) + + def _send_ready(self) -> bool: + self._check_ready() + now = time.monotonic() + return now >= self._not_before and (self._last_start is None + or now >= self._last_start + self.config.request_interval) + + async def _pace(self) -> None: + """Wait at the send gate; the caller holds _start_lock until dispatch.""" + while True: + now = time.monotonic() + at = max(self._not_before, (self._last_start + self.config.request_interval) + if self._last_start is not None else now) + if at <= now: + break + await asyncio.sleep(at - now) + self._check_ready() + + @staticmethod + def _retry_after(value: str | None) -> float | None: + if value is None: + return None + try: + seconds = float(value) + except ValueError: + try: + stamp = parsedate_to_datetime(value) + if stamp.tzinfo is None: + return None + seconds = stamp.timestamp() - time.time() + except (ValueError, TypeError, OverflowError): + return None + return max(0.0, seconds) if math.isfinite(seconds) else None + + async def _request(self, path: str, params: dict[str, Any]) -> Any: + if self._http is None: + self._http = httpx.AsyncClient() + c = self.config + headers = {"Accept": "application/json", "User-Agent": "astrbot-plugin-ba-stats", "X-Client": c.client_id} + if c.api_token: + # Optional Bearer scheme is a deployment choice, NOT a verified + # BATrace requirement; configure only if operator-approved. + headers["Authorization"] = "Bearer " + c.api_token + for attempt in range(c.retries + 1): + await self._check_daily_quota() + async with self._start_lock: + while True: + await self._pace() + try: + await self._consume_request() + except AdmissionDeferred: + # Quota rolled back before commit: wait without holding + # SQLite and reserve against the final admission date. + continue + break + self._last_start = time.monotonic() + self._requests += 1 + # No suspension between releasing the gate and handing off to HTTP; + # only request starts are serialized, never response processing. + delay = 30.0 + try: + response = await self._http.get( + c.base_url.rstrip("/") + path, params=params, headers=headers, + timeout=c.request_timeout, follow_redirects=False, + ) + except httpx.TimeoutException: + error: ClientError = RequestTimeoutError("连接或读取数据源超时,请稍后重试。") + except httpx.RequestError: + error = UpstreamError("暂时无法连接到数据源,请稍后重试。") + else: + status = response.status_code + if status in {401, 403}: + raise AuthenticationError("数据源鉴权失败或拒绝访问,请管理员检查客户端标识与令牌配置。") + content_type = response.headers.get("content-type", "").split(";")[0].lower() + is_json = content_type == "application/json" or content_type.endswith("+json") + if not is_json and any(mark in response.text for mark in ( + "TencentEOCaptchaWidget", "EO-Bot-Captcha-Token", "Security Verification", "__tst_status", + )): + raise AuthenticationError("数据源触发了人机验证,当前接入暂不可用,请管理员联系运营方核实。") + if status == 429: + delay = self._retry_after(response.headers.get("Retry-After")) + delay = delay if delay is not None else 30.0 + error = RateLimitError(retry_after=delay) + self._not_before = max(self._not_before, time.monotonic() + delay) + if delay >= c.wait_timeout: + raise error + elif status >= 500: + error = UpstreamError(f"""数据源服务暂时异常(HTTP {status}),请稍后重试。""") + else: + if not is_json: + raise SchemaError("数据源返回了非 JSON 格式的响应,暂无法解析。") + try: + payload = response.json() + except ValueError as exc: + raise SchemaError("数据源返回的 JSON 内容无效,暂无法解析。") from exc + if status == 404: + raise NoDataError("数据源暂未收录该记录,无法据此判断账号是否存在。") + if not 200 <= status < 300: + raise ClientError(f"""数据源拒绝了本次请求(HTTP {status})。""") + return payload + if attempt >= c.retries: + raise error + # Backoff belongs to the same bounded job/deadline and rate gate. + self._not_before = max(self._not_before, time.monotonic() + delay) + raise UpstreamError("数据源请求失败") # unreachable, keeps type checkers precise + + async def clear_cache(self) -> None: + async with self._cache_lock: + self._generation += 1 # an older in-flight result must not refill cleared cache + if self._storage is not None: + await self._storage.clear_cache() + + async def close(self) -> None: + self._closed = True + jobs = [f.task for f in self._flights.values()] + for job in jobs: + job.cancel() + if jobs: + await asyncio.gather(*jobs, return_exceptions=True) + self._flights.clear() + if self._owns_http and self._http is not None: + await self._http.aclose() diff --git a/commands.py b/commands.py new file mode 100644 index 0000000..1ecc8b0 --- /dev/null +++ b/commands.py @@ -0,0 +1,181 @@ +"""Parse arguments after the framework's registered ``ba`` command. + +Adapters replace actual At components with ``mention_token(index)`` and pass +their IDs in ``mentions`` in component order. NUL is reserved for these tokens: +adapters must reject NUL in Plain input. Typed ``@user:`` is always literal text. +Names which look like reserved words or numeric IDs can use ``name:``. +""" + +from __future__ import annotations + +from dataclasses import dataclass +import re +import shlex + + +@dataclass(frozen=True) +class Target: + kind: str # me | mention | stb | steam | name + value: str + + +@dataclass(frozen=True) +class Request: + action: str + target: Target | None = None + limit: int = 5 + code: str = "" # match ID for match; request code for select/cancel + index: int = 0 # one-based candidate index + + +_ALIASES = { + "帮助": "help", "我": "me", "自己": "me", "战绩": "stats", + "近期": "recent", "最近": "recent", "上一场": "last", + "单局": "match", "搜索": "search", "绑定": "bind", + "当前绑定": "binding", "解绑": "unbind", "选择": "select", + "取消": "cancel", "状态": "status", "缓存": "cache", "清理": "clear", "额度": "quota", +} +_NUMBER = re.compile(r"[0-9]+\Z") + + +def mention_token(index: int) -> str: + """Encode a trusted component position, not a user-typed account marker.""" + return f"\x00at:{index}\x00" + + +def _target(parts: list[str], mentions: dict[str, str], aliases: bool) -> Target: + if not parts: + raise ValueError("请指定玩家:me、@群友、stb:玩家ID、steam:SteamID64 或 name:昵称。") + value = " ".join(parts) + if not value.strip(): + raise ValueError("玩家名称或 ID 不能为空。") + if "\x00" in value: + if len(parts) != 1 or value not in mentions: + raise ValueError("请单独使用聊天软件的 @ 提及功能选择群友;昵称请使用文字输入。") + return Target("mention", mentions[value]) + prefix, separator, suffix = value.partition(":") + if separator and prefix.lower() in {"name", "stb", "steam"}: + kind = prefix.lower() + if not suffix.strip(): + raise ValueError("玩家名称或 ID 不能为空。") + if kind != "name" and any(char.isspace() for char in suffix): + raise ValueError("玩家 ID 不能包含空格。") + if kind == "steam" and not _NUMBER.fullmatch(suffix): + raise ValueError("steam: 后请填写纯数字的 SteamID64。") + return Target(kind, suffix) + if value.lower() == "me" or (aliases and value in {"我", "自己"}): + return Target("me", "") + if any(part.startswith("@user:") for part in parts): + raise ValueError("请通过聊天软件的 @ 提及功能选择群友,不要手动输入 @user: 文本。") + if _NUMBER.fullmatch(value): + raise ValueError("纯数字可能有歧义,请补充前缀:stb:(STB ID)、steam:(SteamID64)或 name:(纯数字昵称)。") + if re.search(r"https?://|www\.|steamcommunity\.com/", value, re.IGNORECASE): + raise ValueError("暂不支持直接输入主页链接,请改用 stb:、steam: 或 name:昵称。") + if value.startswith("@"): + raise ValueError("请通过聊天软件的 @ 提及功能选择群友;如果玩家昵称本身以 @ 开头,请使用 name:昵称。") + return Target("name", value) + + +def _count(value: str, maximum: int) -> int: + try: + count = int(value) if _NUMBER.fullmatch(value) else 0 + except ValueError: + count = 0 + if not 1 <= count <= maximum: + raise ValueError(f"对局数量须为 1 到 {maximum} 的整数。") + return count + + +def parse_command( + text: str, + mentions: list[str] | None = None, + default_limit: int = 5, + max_limit: int = 20, + chinese_aliases: bool = True, +) -> Request: + """Return one canonical request; all syntax errors are Chinese ValueErrors. + + Actions: help/stats/recent/last/match/search/bind/binding/unbind/select/ + cancel/status/quota/cache_clear. Match IDs are in ``code``; search queries in + ``target=Target('name', query)``. Empty arguments mean help. + """ + if (type(default_limit) is not int or type(max_limit) is not int + or not 1 <= default_limit <= max_limit): + raise ValueError("默认数量和最大数量须为有效正整数,且默认数量不能超过上限。") + try: + parts = shlex.split(text) + except ValueError as exc: + raise ValueError("引号未配对,包含空格的昵称请用成对的英文双引号(\"\")括起来。") from exc + if not parts: + return Request("help", limit=default_limit) + + def keyword(word: str) -> str: + return _ALIASES.get(word, word.lower()) if chinese_aliases else word.lower() + + action = keyword(parts.pop(0)) + if action not in {"stats", "bind", "recent", "last"} and any("\x00" in part for part in parts): + raise ValueError("此命令请使用文字参数;@ 提及仅用于指定查询或绑定的群友。") + compact = re.fullmatch(r"recent([0-9]+)", action) + if compact: + parts.insert(0, compact[1]) + action = "recent" + if action == "me": + if not parts: + return Request("stats", Target("me", ""), default_limit) + subcommand = keyword(parts.pop(0)) + compact = re.fullmatch(r"recent([0-9]+)", subcommand) + if compact: + parts.insert(0, compact[1]) + subcommand = "recent" + if subcommand == "last" and not parts: + return Request("last", Target("me", ""), default_limit) + if subcommand != "recent" or len(parts) > 1: + raise ValueError("用法:me、me recent [数量] 或 me last。") + limit = _count(parts[0], max_limit) if parts else default_limit + return Request("recent", Target("me", ""), limit) + if action in {"help", "binding", "unbind", "status", "quota"}: + if parts: + raise ValueError(f"""{action} 命令不需要额外参数,请直接发送。""") + return Request(action, limit=default_limit) + if action == "cache": + if len(parts) != 1 or keyword(parts[0]) != "clear": + raise ValueError("用法:cache clear。") + return Request("cache_clear", limit=default_limit) + if action in {"match", "cancel", "select"}: + expected = 2 if action == "select" else 1 + if len(parts) != expected or not parts[0] or any(c.isspace() for c in parts[0]): + raise ValueError({"match": "用法:match <对局ID>。", "cancel": "用法:cancel <请求码>。", + "select": "用法:select <请求码> <序号>。"}[action]) + index = 0 + if action == "select": + try: + index = int(parts[1]) if _NUMBER.fullmatch(parts[1]) else 0 + except ValueError: + index = 0 + if index < 1: + raise ValueError("候选序号须为从 1 开始的整数。") + return Request(action, limit=default_limit, code=parts[0], index=index) + if action == "search": + if not parts or not " ".join(parts).strip(): + raise ValueError("用法:search <昵称>。") + return Request("search", Target("name", " ".join(parts)), default_limit) + trusted_mentions = {mention_token(index): user for index, user in enumerate(mentions or ())} + if action == "recent": + limit = default_limit + if "--limit" in parts: + position = parts.index("--limit") + if position == 0 or position != len(parts) - 2: + raise ValueError("用法:recent <玩家> --limit <数量>。") + limit = _count(parts[-1], max_limit) + parts = parts[:position] + elif len(parts) == 1 and _NUMBER.fullmatch(parts[0]): + return Request("recent", Target("me", ""), _count(parts[0], max_limit)) + if any(part.startswith("--") for part in parts): + raise ValueError("近期查询仅支持末尾的 --limit <数量> 参数。") + target = _target(parts, trusted_mentions, chinese_aliases) if parts else Target("me", "") + return Request("recent", target, limit) + if action in {"stats", "bind", "last"}: + if action == "last" and not parts: + return Request("last", Target("me", ""), default_limit) + return Request(action, _target(parts, trusted_mentions, chinese_aliases), default_limit) + raise ValueError("未知命令,请使用 ba help 查看帮助。") diff --git a/docs/API_NOTES.md b/docs/API_NOTES.md index 3dfcacc..8af5164 100644 --- a/docs/API_NOTES.md +++ b/docs/API_NOTES.md @@ -131,7 +131,7 @@ storage 为 duck type:`get_cache(key) -> (JSON payload, fetched_at, expires_at AstrBot 适配器从事件的 `get_platform_id()/get_sender_id()/get_group_id()` 生成 `QuotaActor`,通过 `with client.request_scope(actor)` 覆盖整个业务调用;`ContextVar` 传播到子任务、后续接口及重试。身份不来自命令里的查询对象或 @ 目标。用户按平台实例跨群及私聊累计,群按平台实例和群 ID 汇总,全局覆盖本插件数据库内全部平台。 -每次 `_request` 的每个 HTTP 尝试,在节流排队后、发送前调用 `Storage.consume_request`。SQLite 事务同时检查三层额度,再一起增加;不足则抛出 `QuotaExceededError`,其他层不增加。新鲜缓存判断后、网络退避前以及旧缓存回退前会只读检查额度,避免额度耗尽后因排队超时返回旧缓存。失败及重试计入;缓存命中、队列中取消、本地命令和图像渲染不计入。为防止断电或取消造成超额,已持久记账的尝试不退款;很小的记账后、发送前中断窗口可能保守多记一次。 +每次 `_request` 的每个 HTTP 尝试,在节流排队后、发送前调用 `Storage.consume_request`。SQLite 事务同时检查三层额度,再一起增加;不足则抛出 `QuotaExceededError`,其他层不增加。事务取得写锁后及提交前核对发送准入;退避发生变化或跨越北京时间日界时回滚,离开事务后重新排队,按最终准入日期记账。提交后直接交给 HTTP,不再进入退避等待。新鲜缓存判断后、网络退避前以及旧缓存回退前会只读检查额度,避免额度耗尽后因排队超时返回旧缓存。失败及重试计入;缓存命中、记账前取消、本地命令和图像渲染不计入。为防止断电或取消造成超额,已持久记账的尝试不退款;很小的提交与交给 HTTP 之间的中断窗口可能保守多记一次。 查询概览通常包含多个 HTTP,部分请求已发出后额度不足,会保留已用次数并中止剩余调用;绑定逻辑不会据不完整结果修改原绑定。额度不足时可读取新鲜缓存,但不会以 stale 回退隐藏该错误。网络合并仅限同一用户、同一群,防止其他调用者的强制刷新扣到原发起者。 diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 2219b29..271c7af 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -7,7 +7,7 @@ | 项目 | 结果 | | --- | --- | | 首版代码与文档 | 已实现;按项目框架、插件实现两个 PR 审阅 | -| 离线业务与契约测试 | **392 passed,19.49 秒**(含新增每日额度) | +| 离线业务与契约测试 | **435 passed,24.70 秒**(含文案导入及 PR 审查回归) | | 本地卡片渲染 | 18 组 HTML/文字、36 张 PNG;布局与外部请求检查全通过 | | 成品目视检查 | 主代理查看 4 张代表图;渲染子代理另查看 9 张 | | Python 语法检查 | 全部通过 | @@ -26,6 +26,18 @@ Gemini 返回的 331 条文案全部匹配导出基线;回填 68 条变化, 项目 CI 使用 Python 3.11 / 3.12,执行依赖兼容性、元数据和语法检查;插件实现 PR 增加完整离线测试和安装包构建检查。CI 不调用真实战绩 API,也不发送 QQ 消息。 +PR 审查统一了以下行为,并增加对应回归验证: + +- 近期列表、单局详情和展示层共用目标玩家身份核对;有参与者但缺少目标时明确拒绝。 +- 真实 At 组件保留来源,显式昵称和搜索文本中的 `@user:` 不再被误判;手写标记仍不能借用真实提及。 +- 常用单位按来源 ID 聚合,名称仅用于展示;不同 ID 同名时在图片和文字中统一区分。 +- 所有 SQLite 业务写入共用事务边界;异常和重复取消时等待回滚完成后才释放连接锁。 +- HTTP 发送准入同时协调节流、共享退避和额度记账,响应处理保持并发。 + +文案导入后重新生成 18 组 HTML/文字、36 张 PNG,布局与外部请求检查全部通过;复查手机概览,标题和常用单位区正常。预览仍全部为合成样本。 + +最终全量运行:`python -m pytest -q`,435 passed(24.70 秒)。新增准入测试验证事务中跨日回滚、退避期间跨午夜后新日最多 100 次 HTTP;取消回滚与响应并发均有覆盖。旧间隔测试的 15ms 时间窗口在 Windows 全量运行中出现抖动,改为 80ms 间隔并保留 70ms 下界和并发断言后,全量通过。 + ## 核对基线 - 目标仓库初始 `main`:`c4272e87413734ec317fe937faa868bbbf70eb08`,原来仅有 Apache-2.0 LICENSE。 diff --git a/main.py b/main.py new file mode 100644 index 0000000..b49d6b6 --- /dev/null +++ b/main.py @@ -0,0 +1,225 @@ +"""AstrBot v4.29.4 接口适配;命令只经宿主的唤醒及指令过滤器进入。""" +from __future__ import annotations + +import asyncio +from dataclasses import fields +import hashlib +from pathlib import Path +import re +import shutil +import time + +from astrbot.api import AstrBotConfig +from astrbot.api.event import AstrMessageEvent, filter +from astrbot.api.message_components import At, Plain +from astrbot.api.star import Context, Star, StarTools + +from .client import BatraceClient, ClientConfig, ClientError +from .commands import mention_token, parse_command +from .quota import GLOBAL_DAILY_LIMIT, QuotaActor +from .render import Renderer +from .service import Caller, StatsService +from .settings import Settings +from .storage import Storage + + +def extract_arguments(event, prefixes): + """Rebuild Plain/At components; keep quoted nickname spacing and true IDs.""" + parts, mentions = [], [] + for component in event.get_messages(): + if isinstance(component, Plain): + # NUL separates trusted components; ordinary @user: names stay literal. + if "\x00" in component.text: + raise ValueError("命令文本包含不支持的控制字符。") + parts.append(component.text) + elif isinstance(component, At): + user = str(component.qq) + if user == str(event.get_self_id()) and not "".join(parts).strip(): + continue + if user == "all": + raise ValueError("不能使用 @全体成员 查询玩家。") + parts.append(f" {mention_token(len(mentions))} ") + mentions.append(user) + raw = "".join(parts).strip() + choices = sorted({str(p) for p in prefixes if p}, key=len, reverse=True) + for prefix in choices + [""]: + match = re.match(r"^" + re.escape(prefix) + r"ba(?:\s+|$)", raw, re.IGNORECASE) + if match: + return raw[match.end():], mentions + # Some adapters expose normalized text with command prefixes already removed. + if not mentions: + match = re.match(r"^ba(?:\s+|$)", event.get_message_str().strip(), re.IGNORECASE) + if match: + return event.get_message_str().strip()[match.end():], [] + raise ValueError("未能识别命令内容,请确认使用了当前配置的 AstrBot 命令前缀后重试。") + + +def quota_actor(event): + """Account to the actual sender and group, never the queried/@ player.""" + def identifier(value, required=True): + if value is None and not required: + return "" + if isinstance(value, bool) or not isinstance(value, (str, int)): + raise ValueError("无法确认消息的用户或群身份。") + result = str(value).strip() + if required and not result: + raise ValueError("无法确认消息的用户或群身份。") + return result + return QuotaActor(identifier(event.get_platform_id()), identifier(event.get_sender_id()), + identifier(event.get_group_id(), required=False)) + + +class BAStatsPlugin(Star): + def __init__(self, context: Context, config: AstrBotConfig): + super().__init__(context) + self.settings = Settings.from_config(config) + self.data_dir = StarTools.get_data_dir("astrbot_plugin_ba_stats") + self.storage = Storage(self.data_dir, max_entries=self.settings.cache_max_entries) + values = {f.name: getattr(self.settings, f.name) for f in fields(ClientConfig)} + self.client = BatraceClient(ClientConfig(**values), storage=self.storage) + self.service = StatsService(self.client, self.storage, self.settings) + self.renderer = Renderer(self.settings.theme, self.settings.timezone) + self._images = self.data_dir / "images" + self._image_lock = asyncio.Lock() + self._tasks = set() + self._closed = False + + async def initialize(self): + await self.storage.open() + self._images.mkdir(parents=True, exist_ok=True) + self._prune_images() + + async def _run(self, awaitable): + if self._closed: + awaitable.close() + raise asyncio.CancelledError + task = asyncio.create_task(awaitable) + self._tasks.add(task) + try: + return await asyncio.wait_for(task, self.settings.wait_timeout) + finally: + self._tasks.discard(task) + + def _prune_images(self): + files = sorted(self._images.glob("*.jpg"), key=lambda p: p.stat().st_mtime, reverse=True) + for index, path in enumerate(files): + if index >= 48 or time.time() - path.stat().st_mtime > 86400: + path.unlink(missing_ok=True) + + async def _image(self, view, umo): + html = self.renderer.template(view) + # Scope renderer endpoint/session too: different AstrBot sessions can use + # different render services. Content itself remains the same result. + digest = hashlib.sha256((umo + html).encode()).hexdigest() + destination = self._images / f"{digest}.jpg" + async with self._image_lock: + if destination.exists() and time.time() - destination.stat().st_mtime <= 86400: + return str(destination) + # Final HTML is DATA, never a second Jinja template. This preserves + # literal {{...}} in nicknames after the first HTML escaping pass. + source = await self.html_render( + "{{ body | safe }}", {"body": html}, return_url=False, + options={"type": "jpeg", "quality": 85, "full_page": True, + "viewport_width": 390, "device_scale_factor_level": "ultra"}, umo=umo) + if not Path(source).is_file(): + raise ValueError("渲染服务未返回本地图片。") + shutil.copyfile(source, destination) + self._prune_images() + return str(destination) + + async def _status(self): + status = self.client.status() + usage = await self.storage.quota_usage() + labels = {"authentication": "鉴权失败", "rate_limited": "限流", "timeout": "超时", + "schema": "响应结构变化", "identity_mismatch": "身份校验失败", + "no_data": "暂无收录", "upstream": "上游暂不可用", "queue_full": "队列已满", + "not_configured": "接入未配置", "closed": "客户端已关闭", "daily_quota": "每日额度已用完"} + return (f"断箭战报 v0.1.0\n接入配置:{'已填写(不代表联调通过)' if status['configured'] else '未配置'}\n" + f"今日总请求:{usage['global']}/{GLOBAL_DAILY_LIMIT}(固定上限);北京时间 0 点重置\n" + f"本次运行请求:{status['requests']};进行中:{status['inflight']}\n" + f"API 缓存:{await self.storage.cache_count()} 条;命中:{status['cache_hits']};旧缓存:{status['stale_hits']}\n" + f"图片缓存:{len(list(self._images.glob('*.jpg')))} 张\n" + f"最近错误:{labels.get(status['last_error'], '无' if not status['last_error'] else '请求失败')}\n" + "真实接口与 QQ 平台验收待完成。") + + async def _quota(self, actor): + usage = await self.storage.quota_usage(actor) + def line(label, used, limit): + if limit == 0: + return f"{label}:已用 {used} 次,不单独限制" + return f"{label}:已用 {used}/{limit} 次,剩余 {max(0, limit - used)} 次" + lines = [f"今日请求额度 · {usage['day']}(北京时间)", + line("个人", usage['user'], self.settings.user_daily_limit)] + if actor.group: + lines.append(line("本群", usage['group'], self.settings.group_daily_limit)) + lines.extend([line("全插件", usage['global'], GLOBAL_DAILY_LIMIT), + "北京时间每天 0 点重置;个人额度跨群及私聊累计。", + "按实际发出的上游 HTTP 请求计数(含重试与失败);命中缓存、本地命令及图片渲染不计入。"]) + return "\n".join(lines) + + @filter.command("ba", alias={"BA", "Ba", "bA"}) + async def ba(self, event: AstrMessageEvent): + if self._closed: + return + event.stop_event() + config = self.context.get_config(event.unified_msg_origin) + prefixes = config.get("wake_prefix", ["/"]) if config is not None else ["/"] + prefix = str(prefixes[0]) if prefixes else "" + try: + text, mentions = extract_arguments(event, prefixes) + request = parse_command(text, mentions, self.settings.default_limit, + self.settings.max_limit, self.settings.chinese_aliases) + caller = Caller(str(event.get_platform_id()), event.unified_msg_origin, + str(event.get_sender_id()), prefix + "ba") + if request.action == "quota": + yield event.plain_result(await self._quota(quota_actor(event))) + return + if request.action in {"status", "cache_clear"}: + self.service.pending.begin(caller.scope) + if not event.is_admin(): + yield event.plain_result("此命令仅供 AstrBot 管理员使用。") + return + if request.action == "status": + yield event.plain_result(await self._status()) + else: + await self.client.clear_cache() + async with self._image_lock: + for path in self._images.glob("*.jpg"): + path.unlink(missing_ok=True) + yield event.plain_result("已清理 API 缓存与图片缓存;账号绑定及今日已用额度不受影响。") + return + with self.client.request_scope(quota_actor(event)): + response = await self._run(self.service.execute(request, caller)) + if response.text: + yield event.plain_result(response.text) + if response.view is not None: + for view in self.renderer.views(response.view): + if self.settings.image_enabled: + try: + path = await self._run(self._image(view, event.unified_msg_origin)) + except (Exception,): + self.logger.warning("断箭战报图片渲染失败,已使用相同查询结果回复文字。") + else: + yield event.image_result(path) + continue + yield event.plain_result(self.renderer.text(view)) + except (ClientError, ValueError) as exc: + yield event.plain_result(str(exc)) + except asyncio.TimeoutError: + yield event.plain_result("查询等待超时,请稍后重试。") + except Exception as exc: + # Neither response bodies nor credential-bearing URLs enter logs. + self.logger.error("断箭战报请求失败(%s)。", type(exc).__name__) + yield event.plain_result("本次查询未完成,请稍后重试;如持续出现,请管理员使用 ba status 检查插件状态。") + + async def terminate(self): + self._closed = True + tasks = list(self._tasks) + for task in tasks: + task.cancel() + if tasks: + await asyncio.gather(*tasks, return_exceptions=True) + self._tasks.clear() + self.service.close() + await self.client.close() + await self.storage.close() diff --git a/models.py b/models.py new file mode 100644 index 0000000..31e52e7 --- /dev/null +++ b/models.py @@ -0,0 +1,274 @@ +"""Plugin-owned normalized models; missing source values remain unknown. + +IDs are strings. All adapter-produced datetimes are aware UTC. Ratings and +unit/value exchanges are distinct; these models claim no lifetime coverage. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from datetime import datetime +import math +from typing import Any, Generic, Literal, TypeVar +from urllib.parse import quote + +Outcome = Literal["win", "loss", "unknown"] +Mode = Literal["ranked", "custom", "unknown"] +T = TypeVar("T") + + +@dataclass +class Player: + id: str + name: str + steam_id: str | None = None + elo: float | None = None + source_url: str | None = None + updated_at: datetime | None = None + elo_observed_at: datetime | None = None + + +@dataclass +class Participant: + player_id: str + name: str + team: str | None = None + outcome: Outcome = "unknown" + elo: float | None = None + elo_delta: float | None = None + kills: int | None = None + losses: int | None = None + destroyed_value: float | None = None + lost_value: float | None = None + units: list[dict[str, Any]] = field(default_factory=list) + + +@dataclass +class Match: + id: str + map_name: str | None = None + mode: Mode = "unknown" + started_at: datetime | None = None + duration_seconds: float | None = None + winner_team: str | None = None + players: list[Participant] = field(default_factory=list) + complete: bool = False + source_url: str | None = None + updated_at: datetime | None = None + + +@dataclass +class FetchResult(Generic[T]): + data: T + fetched_at: datetime + stale: bool = False + source_updated_at: datetime | None = None + stale_reason: str | None = None + + +def utc_datetime(value: Any) -> datetime | None: + """Parse Unix seconds or ISO with an explicit zone; never guess local time.""" + from datetime import timezone + import math + + if value is None: + return None + if isinstance(value, bool): + raise ValueError("invalid timestamp") + if isinstance(value, (int, float)): + if not math.isfinite(value): + raise ValueError("invalid timestamp") + return datetime.fromtimestamp(value, timezone.utc) + if isinstance(value, datetime): + parsed = value + elif isinstance(value, str): + parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) + else: + raise ValueError("invalid timestamp") + if parsed.tzinfo is None or parsed.utcoffset() is None: + raise ValueError("timestamp needs an explicit timezone") + return parsed.astimezone(timezone.utc) + + +SOURCE_URL = "https://dash.batrace.top/" + + +def canonical_id(value: Any) -> str: + if isinstance(value, bool) or not isinstance(value, (str, int)): + raise ValueError("expected a string or integer ID") + result = str(value) + if not result or result != result.strip() or len(result) > 128: + raise ValueError("invalid ID") + return result + + +def _object(value: Any) -> dict[str, Any]: + if not isinstance(value, dict): + raise ValueError("expected an object") + return value + + +def _number(value: Any, *, count: bool = False) -> float | int | None: + if value is None: + return None + if isinstance(value, bool) or not isinstance(value, (int, float)): + raise ValueError("expected a number") + if not math.isfinite(value): + raise ValueError("expected a finite number") + if count: + if value < 0 or int(value) != value: + raise ValueError("expected a nonnegative count") + return int(value) + return value + + +def _name(value: Any) -> str: + if value is None: + return "" + if not isinstance(value, str): + raise ValueError("expected a name") + return value + + +def parse_search(payload: Any) -> list[Player]: + """Search has an explicit players array; missing arrays are schema failures.""" + rows = _object(payload).get("players") + if not isinstance(rows, list): + raise ValueError("missing players array") + result: dict[str, Player] = {} + for row in rows: + p = _object(row) + pid = canonical_id(p.get("id")) + candidate = Player( + id=pid, name=_name(p.get("name")), elo=_number(p.get("rating")), + updated_at=utc_datetime(p.get("updated_at")), + source_url=SOURCE_URL + "player/" + quote(pid, safe=""), + ) + # Preserve first-seen ordering and identity; a duplicate ID may be renamed. + if pid not in result or ( + candidate.updated_at is not None + and (result[pid].updated_at is None or candidate.updated_at > result[pid].updated_at) + ): + result[pid] = candidate + return list(result.values()) + + +def parse_player(payload: Any, requested_id: str) -> Player: + """Verify a canonical search echo, then use dated analysis rating observations. + + The info endpoint's documented shape has no ID, so it cannot prove identity. + This private cache envelope contains responses from search and analysis. + """ + envelope = _object(payload) + candidates = parse_search(envelope.get("search")) + player = next((p for p in candidates if p.id == requested_id), None) + if player is None: + raise ValueError("canonical player ID was not echoed") + analysis = _object(envelope.get("analysis")) + if "matchCount" not in analysis and "trend" not in analysis: + raise ValueError("missing player analysis") + if "matchCount" in analysis: + _number(analysis["matchCount"], count=True) + trend = _object(analysis.get("trend", {})) + points = trend.get("points", []) + if not isinstance(points, list): + raise ValueError("invalid trend points") + observations: list[tuple[datetime, float]] = [] + for row in points: + point = _object(row) + rating = _number(point.get("ratingAfter")) + at = utc_datetime(point.get("endTime")) + if rating is not None and at is not None: + observations.append((at, rating)) + if observations: + at, rating = max(observations, key=lambda item: item[0]) + # Search rating is a profile snapshot; retain it if it is demonstrably newer. + if player.elo is None or player.updated_at is None or at >= player.updated_at: + player.elo = rating + player.elo_observed_at = at + return player + + +def parse_match(payload: Any, requested_id: str, *, detail: bool = True) -> Match: + """Adapt the observed protobuf-shaped matchInfo, not arbitrary JSON objects. + + Only the reference-confirmed protobuf defaults are applied (team and four + numeric counters). Ratings, times, names and mode never default to zero. + """ + root = _object(payload) + info = _object(root.get("matchInfo")) + if "matchId" in root and canonical_id(root["matchId"]) != requested_id: + raise ValueError("match ID mismatch") + rows = info.get("Data") + if not isinstance(rows, dict): + raise ValueError("missing match participant data") + players: list[Participant] = [] + seen: set[str] = set() + for raw in rows.values(): + row = _object(raw) + pid = canonical_id(row.get("Id")) + if pid in seen: + raise ValueError("duplicate participant ID") + seen.add(pid) + team = row.get("TeamId", 0) + if isinstance(team, bool) or not isinstance(team, int): + raise ValueError("invalid team ID") + old, new = _number(row.get("OldRating")), _number(row.get("NewRating")) + units = row.get("UnitData", {}) + if not isinstance(units, dict): + raise ValueError("invalid unit data") + normalized_units = [] + for unit in units.values(): + unit = _object(unit) + normalized_units.append({ + "id": canonical_id(unit.get("Id")), + "name": _name(unit.get("Name")) or None, + "count": 1, + }) + players.append(Participant( + player_id=pid, name=_name(row.get("Name")), team=str(team), + elo=new, elo_delta=(new - old if old is not None and new is not None else None), + kills=_number(row.get("Destruction", 0), count=True), + losses=_number(row.get("Losses", 0), count=True), + destroyed_value=_number(row.get("DestructionScore", 0)), + lost_value=_number(row.get("LossesScore", 0)), units=normalized_units, + )) + duration = _number(info.get("TotalPlayTimeInSec")) + if duration is not None and duration < 0: + raise ValueError("negative duration") + start = utc_datetime(info.get("StartTime")) + end = utc_datetime(info.get("EndTime")) + if start is None and end is not None and duration is not None: + from datetime import timedelta + start = end - timedelta(seconds=duration) + if end is not None and start is not None and end < start: + raise ValueError("match ends before it starts") + # The reference infers victory from rating changes. This is not an + # authoritative outcome field: retain unknown even for consistent deltas. + # Type enum meanings are not documented by the reference; zero ELO change + # alone cannot distinguish custom, incomplete and unrated matches. + complete = detail and bool(players) and end is not None and all( + isinstance(row, dict) and isinstance(row.get("UnitData"), dict) for row in rows.values() + ) + return Match( + id=requested_id, map_name=(f"地图#{canonical_id(info['MapId'])}" if "MapId" in info else None), + started_at=start, duration_seconds=duration, + players=players, complete=complete, + source_url=SOURCE_URL + "match/" + quote(requested_id, safe=""), + ) + + +def parse_recent(payload: Any) -> list[Match]: + rows = _object(payload).get("matches") + if not isinstance(rows, list): + raise ValueError("missing matches array") + result: dict[str, Match] = {} + for raw in rows: + row = _object(raw) + mid = canonical_id(row.get("matchId")) + match = parse_match({"matchInfo": row.get("data")}, mid, detail=False) + if mid not in result or len(match.players) > len(result[mid].players): + result[mid] = match + from datetime import timezone + minimum = datetime.min.replace(tzinfo=timezone.utc) + return sorted(result.values(), key=lambda m: (m.started_at or minimum, m.id), reverse=True) diff --git a/pending.py b/pending.py new file mode 100644 index 0000000..7a4850f --- /dev/null +++ b/pending.py @@ -0,0 +1,125 @@ +"""Single-use candidate selection, isolated by platform/session/user. + +Methods are synchronous and locked: call begin before awaiting the network, +then publish with its generation. Requests and candidates stay opaque. +""" + +from __future__ import annotations + +from collections import OrderedDict +from dataclasses import dataclass +import itertools +import math +import secrets +import threading +import time +from typing import Any, Callable, Iterable + + +Scope = tuple[str, str, str] + + +@dataclass(frozen=True) +class Pending: + scope: Scope + generation: int + code: str + request: Any + candidates: tuple[Any, ...] + created_at: float + expires_at: float + + +@dataclass +class _Slot: + generation: int + expires_at: float + pending: Pending | None = None + + +class PendingManager: + def __init__( + self, + ttl: float = 120, + max_entries: int = 1000, + clock: Callable[[], float] = time.monotonic, + ) -> None: + if not math.isfinite(ttl) or ttl <= 0 or type(max_entries) is not int or max_entries < 1: + raise ValueError("候选有效期和容量须大于零。") + self.ttl = ttl + self.max_entries = max_entries + self._clock = clock + self._generations = itertools.count(1) + self._slots: OrderedDict[Scope, _Slot] = OrderedDict() + self._lock = threading.Lock() + + def _prune(self, now: float) -> None: + for scope in [scope for scope, slot in self._slots.items() if slot.expires_at <= now]: + del self._slots[scope] + + def begin(self, scope: Scope) -> int: + """Invalidate the old request immediately, before network work starts.""" + with self._lock: + now = self._clock() + self._prune(now) + self._slots.pop(scope, None) + while len(self._slots) >= self.max_entries: + self._slots.popitem(last=False) + generation = next(self._generations) + self._slots[scope] = _Slot(generation, now + self.ttl) + return generation + + def is_current(self, scope: Scope, generation: int) -> bool: + """Check an unexpired generation without consuming or extending it.""" + with self._lock: + self._prune(self._clock()) + slot = self._slots.get(scope) + return slot is not None and slot.generation == generation + + def clear(self) -> None: + """Invalidate all work on shutdown without recycling generations.""" + with self._lock: + self._slots.clear() + + def publish( + self, scope: Scope, generation: int, request: Any, candidates: Iterable[Any] + ) -> Pending | None: + """Return None if replaced, expired, consumed, or already published.""" + values = tuple(candidates) + with self._lock: + now = self._clock() + self._prune(now) + slot = self._slots.get(scope) + if slot is None or slot.generation != generation or slot.pending is not None: + return None + if not values: + del self._slots[scope] + return None + pending = Pending(scope, generation, f"{generation:x}{secrets.token_hex(2)}", + request, values, now, now + self.ttl) + slot.pending = pending + slot.expires_at = pending.expires_at + return pending + + def consume(self, scope: Scope, code: str, index: int) -> tuple[Any, Any]: + """Atomically consume a one-based choice; invalid choices preserve it.""" + with self._lock: + self._prune(self._clock()) + slot = self._slots.get(scope) + pending = slot.pending if slot is not None else None + if pending is None or pending.code != code: + raise ValueError("该选择请求不存在、已过期,或不属于当前会话,请重新发起查询。") + if type(index) is not int or not 1 <= index <= len(pending.candidates): + raise ValueError(f"候选序号须为 1 到 {len(pending.candidates)} 的整数。") + del self._slots[scope] + return pending.request, pending.candidates[index - 1] + + def cancel(self, scope: Scope, code: str) -> bool: + """Cancel only the matching request; return False for any stale code.""" + with self._lock: + self._prune(self._clock()) + slot = self._slots.get(scope) + if slot is None or slot.pending is None or slot.pending.code != code: + return False + del self._slots[scope] + return True diff --git a/quota.py b/quota.py new file mode 100644 index 0000000..f9f001b --- /dev/null +++ b/quota.py @@ -0,0 +1,42 @@ +"""Daily upstream request quotas, independent of credentials and caches.""" + +from dataclasses import dataclass +from datetime import datetime, timedelta, timezone + + +GLOBAL_DAILY_LIMIT = 100 +_BEIJING = timezone(timedelta(hours=8)) + + +@dataclass(frozen=True) +class QuotaActor: + platform: str + user: str + group: str = "" + + def __post_init__(self) -> None: + if any(not isinstance(value, str) or not value.strip() + for value in (self.platform, self.user)): + raise ValueError("配额的平台实例和用户 ID 必须为非空字符串。") + if not isinstance(self.group, str) or (self.group and not self.group.strip()): + raise ValueError("群 ID 必须为非空字符串;私聊请使用空字符串。") + + +class QuotaExceededError(ValueError): + code = "daily_quota" + + def __init__(self, scope: str, limit: int, used: int) -> None: + self.scope = scope + self.limit = limit + self.used = used + label = {"global": "全插件", "user": "本用户", "group": "本群"}[scope] + super().__init__(f"""{label}今日请求额度已用完(已用 {used}/{limit} 次),将于北京时间 0 点重置。""") + + +class AdmissionDeferred(Exception): + """The send gate changed before quota commit; retry without spending.""" + + +def quota_day(timestamp: float) -> str: + """Return the UTC+08:00 calendar date, independent of the host timezone.""" + return datetime.fromtimestamp(timestamp, _BEIJING).date().isoformat() diff --git a/render.py b/render.py new file mode 100644 index 0000000..2567093 --- /dev/null +++ b/render.py @@ -0,0 +1,346 @@ +"""One presentation contract for HTML cards and their plain-text fallback. + +Service -> Renderer view contract (independent of models.py): + kind: "overview" | "recent" | "match"; title: optional display title. + player: {id: str, name: str, source_url?: str}; required for player cards. + metrics: [{label: str, value: number | str | None, unit?: str, + format?: "integer" | "decimal" | "percent" | "signed", note?: str}]. + Numbers default to two decimals; counts use integer. Percent values are + already on the 0..100 scale. Strings are display text, never HTML. + rows (recent): [{id, started_at, map_name, mode, outcome, duration_seconds, + elo_delta, kills, losses, destroyed_value, lost_value, unit_exchange, + value_exchange, source_url}]. Every field except id may be absent. + match (match): {id, map_name, mode, started_at, duration_seconds, winner}. + teams (match): [{name, outcome, players: [{id, name, elo, elo_delta, kills, + losses, destroyed_value, lost_value, unit_exchange, value_exchange}]}]. + Team sizes are unrestricted; never pad absent players with dummy rows. + common_units (overview, optional): [{name: str, count?: int}]. + scope: str describing actual sample / mode / coverage (never inferred). + fetched_at, source_updated_at: aware datetime or ISO 8601 with timezone. + stale: bool; source_url: optional public http(s) link; notes?: list[str]. + synthetic?: bool marks previews explicitly as synthetic sample data. + +Outcome: win/loss/unknown; mode: ranked/custom/unknown (other labels preserved). +Unit counts (kills/losses) and values (destroyed_value/lost_value) are displayed +separately. Renderer does not derive statistics, coverage, ratios, or winners. +None, blank, nonfinite, and absent values display as 暂无; real zero stays zero. +Missing/naive timestamps display as 暂无, rather than guessing a timezone. + +Renderer(theme='dark', timezone='Asia/Shanghai').template(view) returns final +escaped HTML. For AstrBot use the FIXED template '{{ body | safe }}' with +data={'body': html}; never pass the generated HTML as another Jinja template. +This preserves nicknames containing literal Jinja tags. text(view) uses exactly +the same normalized presentation data. For recent cards, iterate +views(view), which splits rows into pages of 5, before calling either method. +Each page preserves scope, identity, timestamps and page/row coverage. These +methods never query a service or load a remote avatar/font/resource. +""" + +from __future__ import annotations + +from collections.abc import Mapping +from copy import deepcopy +from datetime import datetime +from decimal import Decimal, InvalidOperation +from pathlib import Path +from urllib.parse import urlsplit +from zoneinfo import ZoneInfo + +from jinja2 import Environment, FileSystemLoader, select_autoescape + +MISSING = "暂无" +_TITLES = {"overview": "玩家概览", "recent": "近期战绩", "match": "单局战报"} +_OUTCOMES = {"win": "胜利", "loss": "失利", "unknown": "胜负暂无"} +_MODES = {"ranked": "排位", "custom": "自定义", "unknown": "暂无"} + + +def _plain(value, default=MISSING) -> str: + # str() also strips a caller-supplied Markup object's HTML trust flag. + if value is None or isinstance(value, bool): + return default + result = str(value).strip() + return result if result else default + + +def _number(value) -> Decimal | None: + if isinstance(value, bool) or not isinstance(value, (int, float, Decimal)): + return None + try: + parsed = Decimal(str(value)) + return parsed if parsed.is_finite() else None + except (InvalidOperation, ValueError): + return None + + +def _numeric(value, style="decimal") -> str: + parsed = _number(value) + if parsed is None: + return MISSING + if style == "integer": + return str(int(parsed)) if parsed == parsed.to_integral_value() else MISSING + return format(parsed, "+.2f" if style == "signed" else ".2f") + + +def _safe_url(value) -> str: + if not isinstance(value, str) or not value: + return "" + # Links are shown, never fetched. Reject credentials and ambiguous spellings. + if any(character.isspace() or ord(character) < 32 for character in value) or "\\" in value: + return "" + try: + parts = urlsplit(value) + if ( + parts.scheme.lower() not in {"http", "https"} + or not parts.hostname + or parts.username is not None + or parts.password is not None + ): + return "" + parts.port # Invalid/out-of-range ports raise ValueError. + except ValueError: + return "" + return str(value) + + +def _mapping(value) -> Mapping: + return value if isinstance(value, Mapping) else {} + + +def _records(value) -> list[Mapping]: + return [_mapping(item) for item in value] if isinstance(value, (list, tuple)) else [] + + +def _outcome(value) -> dict: + key = value if isinstance(value, str) and value in _OUTCOMES else "unknown" + return {"key": key, "label": _OUTCOMES[key]} + + +class Renderer: + """Render self-contained cards without network access or model imports.""" + + def __init__(self, theme: str = "dark", timezone: str = "Asia/Shanghai"): + if theme not in {"dark", "light"}: + raise ValueError("theme must be dark or light") + self.theme = theme + self.timezone = ZoneInfo(timezone) + self._environment = Environment( + loader=FileSystemLoader(Path(__file__).with_name("templates")), + autoescape=select_autoescape(("html",)), + trim_blocks=True, + lstrip_blocks=True, + ) + + def views(self, view: dict, page_size: int = 5) -> list[dict]: + """Return independent recent pages; all other cards have one page.""" + if isinstance(page_size, bool) or not isinstance(page_size, int) or not 1 <= page_size <= 5: + raise ValueError("page_size must be an integer from 1 to 5") + if view.get("kind", "overview") != "recent": + return [deepcopy(view)] + rows = view.get("rows") or [] + if not isinstance(rows, (list, tuple)): + rows = [] + count = max(1, (len(rows) + page_size - 1) // page_size) + result = [] + for index in range(count): + page = deepcopy(view) + page.update( + rows=deepcopy(list(rows[index * page_size : (index + 1) * page_size])), + page=index + 1, + page_count=count, + row_start=index * page_size + 1 if rows else 0, + row_total=len(rows), + ) + result.append(page) + return result + + def _time(self, value) -> str: + try: + if isinstance(value, str): + value = datetime.fromisoformat(value.replace("Z", "+00:00")) + if not isinstance(value, datetime) or value.utcoffset() is None: + return MISSING + return value.astimezone(self.timezone).strftime("%Y-%m-%d %H:%M %Z") + except (ValueError, OverflowError): + return MISSING + + @staticmethod + def _duration(value) -> str: + parsed = _number(value) + if parsed is None or parsed < 0: + return MISSING + seconds = int(parsed) + minutes, seconds = divmod(seconds, 60) + hours, minutes = divmod(minutes, 60) + return f"{hours}时{minutes:02d}分{seconds:02d}秒" if hours else f"{minutes}分{seconds:02d}秒" + + @staticmethod + def _metric(metric: Mapping) -> dict: + value = metric.get("value") + style = metric.get("format", "decimal") + if style not in {"integer", "decimal", "percent", "signed"}: + style = "decimal" + formatted = _plain(value) if isinstance(value, str) else _numeric(value, style) + unit = _plain(metric.get("unit"), "") + if style == "percent" and not unit: + unit = "%" + if formatted == MISSING: + unit = "" + display = formatted + (unit if unit == "%" else " " + unit) if unit else formatted + return { + "label": _plain(metric.get("label")), + "value": formatted, + "unit": unit, + "display": display, + "note": _plain(metric.get("note"), ""), + } + + def _exchange(self, item: Mapping, *, elo: bool = False) -> list[dict]: + fields = [ + ("kills", "摧毁单位", "integer", "个"), + ("losses", "损失单位", "integer", "个"), + ("unit_exchange", "单位交换比", "decimal", ""), + ("destroyed_value", "摧毁价值", "decimal", ""), + ("lost_value", "损失价值", "decimal", ""), + ("value_exchange", "价值交换比", "decimal", ""), + ] + if elo: + fields = [("elo", "ELO", "decimal", ""), ("elo_delta", "ELO 变化", "signed", "")] + fields + return [ + self._metric({"label": label, "value": item.get(key), "format": style, "unit": unit}) + for key, label, style, unit in fields + ] + + def _prepare(self, view: dict) -> dict: + kind = view.get("kind", "overview") + if kind not in _TITLES: + raise ValueError("unknown card kind") + player = _mapping(view.get("player")) + match = _mapping(view.get("match")) + prepared = { + "kind": kind, + "title": _plain(view.get("title"), _TITLES[kind]), + "theme": self.theme, + "player": { + "name": _plain(player.get("name")), + "id": _plain(player.get("id")), + "source_url": _safe_url(player.get("source_url")), + }, + "metrics": [self._metric(item) for item in _records(view.get("metrics"))], + "scope": _plain(view.get("scope")), + "fetched_at": self._time(view.get("fetched_at")), + "source_updated_at": self._time(view.get("source_updated_at")), + "stale": view.get("stale") is True, + "source_url": _safe_url(view.get("source_url")) or _safe_url(player.get("source_url")), + "synthetic": view.get("synthetic") is True, + "notes": [_plain(note) for note in view.get("notes", [])] if isinstance(view.get("notes"), (list, tuple)) else [], + "common_units": [ + {"name": _plain(item.get("name")), "count": _numeric(item.get("count"), "integer")} + for item in _records(view.get("common_units")) + ], + "rows": [], + "teams": [], + "pagination": "", + } + for item in _records(view.get("rows")): + prepared["rows"].append({ + "id": _plain(item.get("id")), + "started_at": self._time(item.get("started_at")), + "map_name": _plain(item.get("map_name")), + "mode": _MODES.get(_plain(item.get("mode")), _plain(item.get("mode"))), + "outcome": _outcome(item.get("outcome")), + "duration": self._duration(item.get("duration_seconds")), + "elo_delta": _numeric(item.get("elo_delta"), "signed"), + "exchange": self._exchange(item), + "source_url": _safe_url(item.get("source_url")), + }) + prepared["match"] = { + "id": _plain(match.get("id")), + "map_name": _plain(match.get("map_name")), + "mode": _MODES.get(_plain(match.get("mode")), _plain(match.get("mode"))), + "started_at": self._time(match.get("started_at")), + "duration": self._duration(match.get("duration_seconds")), + "winner": _plain(match.get("winner")), + } + for team in _records(view.get("teams")): + prepared["teams"].append({ + "name": _plain(team.get("name")), + "outcome": _outcome(team.get("outcome")), + "players": [ + {"id": _plain(item.get("id")), "name": _plain(item.get("name")), "metrics": self._exchange(item, elo=True)} + for item in _records(team.get("players")) + ], + }) + page = _number(view.get("page")) + page_count = _number(view.get("page_count")) + row_total = _number(view.get("row_total")) + row_start = _number(view.get("row_start")) + if kind == "recent" and all(value is not None and value == value.to_integral_value() for value in (page, page_count, row_total, row_start)): + end = int(row_start) + len(prepared["rows"]) - 1 if prepared["rows"] else 0 + prepared["pagination"] = f"第 {int(page)}/{int(page_count)} 页 · 本页 {int(row_start)}–{end} 场 / 共 {int(row_total)} 场" + return prepared + + def template(self, view: dict) -> str: + prepared = self._prepare(view) + return self._environment.get_template(f"{prepared['kind']}.html").render(view=prepared) + + def text(self, view: dict) -> str: + """Use the HTML presentation values verbatim in a readable fallback.""" + data = self._prepare(view) + lines = [f"断箭战报 · {data['title']}"] + if data["synthetic"]: + lines.append("合成样本 · 非真实玩家战绩") + if data["kind"] != "match" or data["player"]["id"] != MISSING: + lines.extend([data["player"]["name"], f"玩家 ID:{data['player']['id']}"]) + lines.append(f"统计范围:{data['scope']}") + if data["pagination"]: + lines.append(data["pagination"]) + for metric in data["metrics"]: + lines.append(f"{metric['label']}:{metric['display']}" + (f"({metric['note']})" if metric["note"] else "")) + if data["kind"] == "overview": + if not data["metrics"]: + lines.append("统计指标:暂无") + lines.append("常用单位 / 兵种") + lines.extend(f"{unit['name']}:{unit['count']}" + (" 个" if unit["count"] != MISSING else "") for unit in data["common_units"]) + if not data["common_units"]: + lines.append(MISSING) + elif data["kind"] == "recent": + for index, row in enumerate(data["rows"], 1): + lines.extend([ + f"{index}. {row['map_name']} · {row['outcome']['label']}", + f"对局 ID:{row['id']}", + f"时间:{row['started_at']} · 模式:{row['mode']} · 时长:{row['duration']}", + f"ELO 变化:{row['elo_delta']}", + ";".join(f"{metric['label']}:{metric['display']}" for metric in row["exchange"]), + ]) + if row["source_url"]: + lines.append(f"对局来源:{row['source_url']}") + if not data["rows"]: + lines.append("近期对局:暂无") + else: + match = data["match"] + lines.extend([ + f"对局 ID:{match['id']}", + f"地图:{match['map_name']} · 模式:{match['mode']}", + f"时间:{match['started_at']} · 时长:{match['duration']}", + f"胜方:{match['winner']}", + ]) + for team in data["teams"]: + lines.append(f"{team['name']} · {team['outcome']['label']} · {len(team['players'])} 人") + for player in team["players"]: + lines.append(f"{player['name']} · 玩家 ID:{player['id']}") + lines.append(";".join(f"{metric['label']}:{metric['display']}" for metric in player["metrics"])) + if not team["players"]: + lines.append("队员:暂无") + if not data["teams"]: + lines.append("分队与玩家:暂无") + lines.extend(data["notes"]) + if data["stale"]: + lines.append("旧缓存 · 以抓取时间为准") + lines.extend([ + f"抓取时间:{data['fetched_at']}", + f"来源更新:{data['source_updated_at']}", + f"数据来源:{data['source_url'] or MISSING}", + ]) + if data["player"]["source_url"] and data["player"]["source_url"] != data["source_url"]: + lines.append(f"玩家来源:{data['player']['source_url']}") + return "\n".join(lines) diff --git a/service.py b/service.py new file mode 100644 index 0000000..0dde3de --- /dev/null +++ b/service.py @@ -0,0 +1,314 @@ +"""平台无关的查询、身份选择和战报组装。生产路径从不读取演示数据。""" +from __future__ import annotations + +import asyncio +from collections import Counter, OrderedDict +from dataclasses import asdict, dataclass +from datetime import datetime, timezone +import itertools +import time + +from .client import participant_for +from .commands import Request, Target +from .models import FetchResult, Match, Participant, Player +from .pending import PendingManager +from .storage import Binding + + +@dataclass(frozen=True) +class Caller: + platform: str + session: str + user: str + prefix: str = "/ba" + + @property + def scope(self): + return self.platform, self.session, self.user + + +@dataclass +class Response: + text: str = "" + view: dict | None = None + + +def ratio(numerator, denominator): + if numerator is None or denominator is None: + return None + if denominator == 0: + return "无损失" if numerator > 0 else None + return numerator / denominator + + +def freshness(*results): + return { + "fetched_at": min(r.fetched_at for r in results), + "stale": any(r.stale for r in results), + "source_updated_at": min((r.source_updated_at for r in results if r.source_updated_at), default=None), + } + + +def participant_view(p: Participant): + return dict(id=p.player_id, name=p.name, elo=p.elo, elo_delta=p.elo_delta, + kills=p.kills, losses=p.losses, destroyed_value=p.destroyed_value, + lost_value=p.lost_value, unit_exchange=ratio(p.kills, p.losses), + value_exchange=ratio(p.destroyed_value, p.lost_value)) + + +def recent_rows(matches, player_id): + rows = [] + for match in matches: + person = participant_for(match, player_id) + if person is None: + continue + row = participant_view(person) + row.update(id=match.id, started_at=match.started_at, map_name=match.map_name, + mode=match.mode, outcome=person.outcome, + duration_seconds=match.duration_seconds, source_url=match.source_url) + rows.append(row) + return rows + + +def match_view(result, player=None): + match = result.data + if player is not None: + participant_for(match, player.id) + teams = OrderedDict() + for person in match.players: + key = person.team if person.team is not None else "未知" + if key not in teams: + teams[key] = {"name": f"分队 {key}", "outcome": "unknown", "players": []} + teams[key]["players"].append(participant_view(person)) + if match.winner_team is not None and person.team is not None: + teams[key]["outcome"] = "win" if person.team == match.winner_team else "loss" + view = {"kind": "match", "match": { + "id": match.id, "map_name": match.map_name, "mode": match.mode, + "started_at": match.started_at, "duration_seconds": match.duration_seconds, + "winner": f"分队 {match.winner_team}" if match.winner_team is not None else None, + }, "teams": list(teams.values()), "scope": f"单局 · 实际收录 {len(match.players)} 名玩家", + "source_url": match.source_url, **freshness(result)} + if player: + view["player"] = asdict(player) + if not match.complete: + view["notes"] = ["本局数据可能尚未完整。"] + return view + + +class StatsService: + def __init__(self, client, storage, settings): + self.client, self.storage, self.settings = client, storage, settings + self.pending = PendingManager() + self._cooldowns = OrderedDict() + self._mutations = OrderedDict() + self._serial = itertools.count(1) + self._binding_lock = asyncio.Lock() + + def help(self, caller): + p = caller.prefix + return f"""【断箭战报】使用指南 +首次使用:{p} search 昵称 → 找到目标后发送 {p} bind stb:玩家ID → 按提示发送 {p} select <请求码> <序号> 确认一次即可。 +说明:绑定仅用于设定默认查询对象,不代表 Steam 账号所有权认证。 + +常用命令: +• {p} me:查看自己的玩家概览 +• {p} stats <玩家>:查看指定玩家概览(支持 me / @群友 / stb:ID / name:昵称) +• {p} recent [数量] / {p} me recent [数量]:查看自己近期战绩(默认 {self.settings.default_limit} 场) +• {p} recent <玩家> --limit <数量>:查看指定玩家近期战绩(如 {p} recent name:"Player 2" --limit 10) +• {p} last [玩家] / {p} me last:查看最近一场可用单局战报 +• {p} match <对局ID>:查看指定单局战报 +• {p} search <昵称>:搜索玩家候选 +• {p} bind <玩家> / {p} binding / {p} unbind:绑定、查看或解除默认账号 +• {p} select <请求码> <序号> / {p} cancel <请求码>:确认或取消候选选择 +• {p} quota:查看个人、本群及全插件今日请求额度 +• {p} help:查看本帮助 + +输入与额度提示: +• 纯数字昵称请加前缀(如 name:12345);与关键词重名请写 name:me。 +• steam:SteamID64 需等待权威映射确认,当前请先用昵称搜索再选择 STB ID。 +• 管理员命令:{p} status(查看状态)、{p} cache clear(清理缓存)。 +• 全插件每日固定上限 100 次(个人默认 20 次、每群默认 100 次),北京时间 0 点重置;按实际发出的上游 HTTP 请求计数(含重试与失败),命中缓存不计入。 +• 命令前缀遵循 AstrBot 配置;图片渲染失败时会自动回复同内容的文字战报。""" + + def _mutation(self, caller): + key = (caller.platform, caller.user) + token = next(self._serial) + self._mutations.pop(key, None) + self._mutations[key] = token + while len(self._mutations) > 1000: + self._mutations.popitem(last=False) + return token + + def _cooldown(self, caller): + key = (caller.platform, caller.user) + now = time.monotonic() + previous = self._cooldowns.get(key, -float("inf")) + remaining = self.settings.cooldown_seconds - (now - previous) + if remaining > 0: + raise ValueError(f"""查询过于频繁,请 {remaining:.0f} 秒后再试。""") + self._cooldowns.pop(key, None) + self._cooldowns[key] = now + while len(self._cooldowns) > 1000: + self._cooldowns.popitem(last=False) + + async def execute(self, request: Request, caller: Caller): + action = request.action + if action == "cancel": + ok = self.pending.cancel(caller.scope, request.code) + return Response("已取消本次操作。" if ok else "该请求已失效或不属于当前会话,无法取消。") + if action == "select": + original, candidate = self.pending.consume(caller.scope, request.code, request.index) + generation = self.pending.begin(caller.scope) + if original.action == "bind": + mutation = self._mutation(caller) + verified = await self.client.player(candidate.id, force=True) + if verified.data.id != candidate.id or verified.stale: + raise ValueError("未能重新核实该账号身份,原绑定保持不变,请稍后重试。") + async with self._binding_lock: + if (not self.pending.is_current(caller.scope, generation) + or self._mutations.get((caller.platform, caller.user)) != mutation): + return Response("本次选择已被后续操作覆盖,原绑定未作修改。") + player = verified.data + await self.storage.set_binding(caller.platform, caller.user, Binding( + self.client.namespace, player.id, player.name, player.source_url or "")) + return Response(f"""已绑定默认账号:{player.name or '未命名玩家'} +STB ID:{player.id} +{player.source_url or ''} +现在可以发送 {caller.prefix} me 查看战报。""") + return await self._report(original, candidate.id) + + generation = self.pending.begin(caller.scope) + if action == "help": + return Response(self.help(caller)) + if action == "binding": + binding = await self.storage.get_binding(caller.platform, caller.user) + if binding is None: + return Response(f"""你还没有绑定默认账号,请发送 {caller.prefix} bind name:昵称 进行绑定。""") + return Response(f"""当前默认账号:{binding.display_name or '未命名玩家'} +STB ID:{binding.player_id} +{binding.source_url} +注:昵称为绑定时记录,后续查询始终以该 STB ID 为准。""") + if action == "unbind": + self._mutation(caller) + async with self._binding_lock: + removed = await self.storage.unbind(caller.platform, caller.user) + return Response("已解除默认账号绑定。" if removed else "当前尚未绑定任何账号。") + self._cooldown(caller) + if action == "match": + return Response(view=match_view(await self.client.match(request.code))) + target = request.target or Target("me", "") + if target.kind == "steam": + raise ValueError("SteamID64 与 STB ID 的对应关系尚未验证,两种 ID 不能直接互换。请先用 search <昵称> 搜索,再选择对应的 STB ID。") + if target.kind in {"me", "mention"}: + user = caller.user if target.kind == "me" else target.value + binding = await self.storage.get_binding(caller.platform, user) + if binding is None: + raise ValueError("你尚未绑定默认账号,请先使用 bind name:昵称 进行绑定。" if target.kind == "me" + else "对方尚未绑定默认游戏账号。") + if binding.namespace != self.client.namespace: + raise ValueError("当前绑定的账号属于其他数据源环境,与当前接入不一致,请重新绑定。") + target = Target("stb", binding.player_id) + if target.kind == "stb": + if action != "bind": + return await self._report(request, target.value) + result = await self.client.player(target.value) + candidates = [result.data] + else: + result = await self.client.search(target.value) + candidates = list({p.id: p for p in result.data}.values()) + candidates.sort(key=lambda p: p.name != target.value) + if not candidates: + return Response("未找到匹配的候选玩家,建议换用更准确的昵称重试(未搜到不代表该玩家不存在)。") + if action not in {"bind", "search"} and len(candidates) == 1 and candidates[0].name == target.value: + return await self._report(request, candidates[0].id) + if action == "bind" and result.stale: + raise ValueError("当前仅命中旧缓存,暂无法完成绑定核验,原绑定保持不变,请稍后重试。") + operation = Request("stats", limit=request.limit) if action == "search" else request + selected = candidates[:10] + pending = self.pending.publish(caller.scope, generation, operation, selected) + if pending is None: + return Response("本次查询已被新操作覆盖,请使用最新的候选列表。") + lines = ["选择后绑定此账号(只需确认一次):" if action == "bind" else "请选择要查询的账号:", + "以下为当前接口返回的候选(不代表全库完整结果);如需缩小范围,请提供更准确的昵称。"] + if len(candidates) == 1 and candidates[0].name != target.value and target.kind == "name": + lines.append("仅找到相似昵称结果,请仔细核对 STB ID 与来源链接后再确认。") + if result.stale: + lines.append(f"旧缓存 · 抓取于 {result.fetched_at.isoformat()}") + for index, player in enumerate(selected, 1): + lines.extend([f"{index}. {player.name or '未命名玩家'} · STB ID:{player.id}", + player.source_url or "来源链接暂无", + f"{caller.prefix} select {pending.code} {index}"]) + lines.append(f"""请在 120 秒内发送上方对应指令确认;取消请发送:{caller.prefix} cancel {pending.code}""") + return Response("\n".join(lines)) + + async def _report(self, request, player_id): + player_result = await self.client.player(player_id) + player = player_result.data + if player.id != player_id: + raise ValueError("上游返回的玩家身份与请求不一致。") + limit = request.limit if request.action == "recent" else self.settings.max_limit + result = await self.client.recent(player.id, limit) + matches = result.data + if request.action == "last": + for match in matches: + if participant_for(match, player.id) is None: + continue + try: + detail = await self.client.match(match.id) + except Exception as exc: + if getattr(exc, "code", "") in {"not_found", "not_recorded", "no_data"}: + continue + raise + view = match_view(detail, player) + view.update(freshness(player_result, result, detail)) + return Response(view=view) + return Response(f"{player.name} · STB ID:{player.id}\n当前返回样本中暂无可用单局战报。\n{player.source_url or ''}") + rows = recent_rows(matches, player.id) + times = [m.started_at for m in matches if m.started_at and any(p.player_id == player.id for p in m.players)] + scope = f"近期接口样本 · 实际 {len(rows)} 场(请求最多 {limit} 场);非完整历史,模式以单局标注为准" + view = {"kind": "recent" if request.action == "recent" else "overview", + "player": asdict(player), "rows": rows, "scope": scope, + "source_url": player.source_url, **freshness(player_result, result)} + if times: + from zoneinfo import ZoneInfo + zone = ZoneInfo(self.settings.timezone) + view["scope"] += f" · {min(times).astimezone(zone):%Y-%m-%d %H:%M} 至 {max(times).astimezone(zone):%Y-%m-%d %H:%M}" + if view["kind"] == "overview": + outcomes = Counter(row["outcome"] for row in rows) + known = outcomes["win"] + outcomes["loss"] + view["metrics"] = [ + {"label": "ELO", "value": player.elo}, + {"label": "样本场数", "value": len(rows), "format": "integer"}, + {"label": "胜 / 负 / 未知", "value": f"{outcomes['win']} / {outcomes['loss']} / {outcomes['unknown']}"}, + {"label": "已知结果胜率", "value": 100 * outcomes["win"] / known if known else None, + "format": "percent", "note": f"分母为 {known} 场已知胜负样本"}, + ] + counts = Counter() + names = {} + for match in matches: + person = participant_for(match, player.id) + if person is not None: + for unit in person.units: + uid = unit["id"] + counts[uid] += unit["count"] + if unit.get("name"): + # Matches arrive newest first; names never define identity. + names.setdefault(uid, unit["name"]) + labels = {uid: names.get(uid, f"单位#{uid}") for uid in counts} + duplicates = Counter(labels.values()) + view["common_units"] = [ + {"id": uid, "name": f"{labels[uid]}(ID:{uid})" if duplicates[labels[uid]] > 1 else labels[uid], + "count": count} + for uid, count in counts.most_common(5) + ] + view["notes"] = ["常用单位按当前样本中的出场记录数统计;未收录名称时显示来源单位 ID。"] + if player.elo_observed_at: + from zoneinfo import ZoneInfo + at = player.elo_observed_at.astimezone(ZoneInfo(self.settings.timezone)) + view["notes"].append(f"ELO 对应时间:{at:%Y-%m-%d %H:%M %Z}") + return Response(view=view) + + def close(self): + self.pending.clear() + self._cooldowns.clear() + self._mutations.clear() diff --git a/settings.py b/settings.py new file mode 100644 index 0000000..1758839 --- /dev/null +++ b/settings.py @@ -0,0 +1,84 @@ +"""单一配置来源:AstrBotConfig;启动时校验并快照。""" +from dataclasses import dataclass +from zoneinfo import ZoneInfo, ZoneInfoNotFoundError + + +def bounded(data, key, default, lower, upper, cast=float): + try: + value = cast(data.get(key, default)) + except (TypeError, ValueError): + raise ValueError(f"配置 {key} 必须为数值。") from None + if not lower <= value <= upper: + raise ValueError(f"配置 {key} 必须在 {lower}–{upper} 之间。") + return value + + +def daily_limit(data, key, default): + value = data.get(key, default) + if type(value) is not int or not 0 <= value <= 100: + raise ValueError(f"配置 {key} 必须是 0–100 的整数;0 表示不单独限制。") + return value + + +@dataclass(frozen=True) +class Settings: + enabled: bool = False + base_url: str = "https://bot.batrace.top" + client_id: str = "" + api_token: str = "" + default_limit: int = 5 + max_limit: int = 20 + cooldown_seconds: float = 3 + chinese_aliases: bool = True + image_enabled: bool = True + theme: str = "dark" + timezone: str = "Asia/Shanghai" + request_interval: float = 1 + concurrency: int = 2 + queue_size: int = 20 + request_timeout: float = 20 + wait_timeout: float = 45 + retries: int = 1 + cache_max_entries: int = 1000 + stale_hours: float = 24 + user_daily_limit: int = 20 + group_daily_limit: int = 100 + + @classmethod + def from_config(cls, config): + access = config.get("access", {}) + query = config.get("query", {}) + output = config.get("output", {}) + maintenance = config.get("maintenance", {}) + limits = config.get("limits", {}) + maximum = bounded(query, "max_limit", 20, 1, 20, int) + timezone = str(output.get("timezone", "Asia/Shanghai")) + try: + ZoneInfo(timezone) + except (ZoneInfoNotFoundError, ValueError): + raise ValueError("时区无效,请填写 Asia/Shanghai 等 IANA 时区名。") from None + theme = output.get("theme", "dark") + if theme not in {"dark", "light"}: + raise ValueError("主题必须为 dark 或 light。") + return cls( + enabled=bool(access.get("enabled", False)), + base_url=str(access.get("base_url", cls.base_url)).strip(), + client_id=str(access.get("client_id", "")).strip(), + api_token=str(access.get("api_token", "")).strip(), + default_limit=bounded(query, "default_limit", 5, 1, maximum, int), + max_limit=maximum, + cooldown_seconds=bounded(query, "cooldown_seconds", 3, 0, 60), + chinese_aliases=bool(query.get("chinese_aliases", True)), + image_enabled=bool(output.get("image_enabled", True)), + theme=theme, timezone=timezone, + request_interval=bounded(maintenance, "request_interval", 1, 0.1, 60), + concurrency=bounded(maintenance, "concurrency", 2, 1, 5, int), + queue_size=bounded(maintenance, "queue_size", 20, 1, 100, int), + request_timeout=bounded(maintenance, "request_timeout", 20, 1, 120), + wait_timeout=bounded(maintenance, "wait_timeout", 45, 1, 180), + retries=bounded(maintenance, "retries", 1, 0, 2, int), + cache_max_entries=bounded(maintenance, "cache_max_entries", 1000, 10, 10000, int), + stale_hours=bounded(maintenance, "stale_hours", 24, 0, 168), + user_daily_limit=daily_limit(limits, "user_daily_limit", 20), + group_daily_limit=daily_limit(limits, "group_daily_limit", 100), + ) diff --git a/storage.py b/storage.py new file mode 100644 index 0000000..5a440dc --- /dev/null +++ b/storage.py @@ -0,0 +1,266 @@ +"""SQLite bindings and persistent JSON cache in the plugin data directory.""" + +from __future__ import annotations + +import asyncio +from contextlib import asynccontextmanager +from dataclasses import dataclass, field +import json +import math +from pathlib import Path +import time +from typing import AsyncIterator, Callable + +import aiosqlite + +if __package__: + from .quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day +else: # The standalone storage tests import this module without AstrBot. + from quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day + + +@dataclass(frozen=True) +class Binding: + namespace: str + player_id: str + display_name: str + source_url: str = "" + updated_at: float = field(default_factory=time.time) + + def __post_init__(self) -> None: + if not isinstance(self.player_id, str) or not self.player_id: + raise ValueError("玩家 ID 须为非空字符串。") + if not isinstance(self.namespace, str) or not self.namespace: + raise ValueError("数据源命名空间不能为空。") + + +class Storage: + def __init__( + self, + data_dir: str | Path, + *, + max_entries: int = 1000, + max_age_seconds: float = 604800, + clock: Callable[[], float] | None = None, + ) -> None: + if (type(max_entries) is not int or max_entries < 0 + or not math.isfinite(max_age_seconds) or max_age_seconds < 0): + raise ValueError("缓存容量和最长保留时间须为非负有限数值。") + self.path = Path(data_dir) / "ba_stats.sqlite3" + self.max_entries = max_entries + self.max_age_seconds = max_age_seconds + self._clock = clock if clock is not None else time.time + self._db: aiosqlite.Connection | None = None + self._lock = asyncio.Lock() + + def _connection(self) -> aiosqlite.Connection: + if self._db is None: + raise RuntimeError("数据库尚未打开。") + return self._db + + @asynccontextmanager + async def _transaction(self) -> AsyncIterator[aiosqlite.Connection]: + """Keep every write and its cancellation cleanup inside the connection lock.""" + async with self._lock: + db = self._connection() + try: + async with db.execute("BEGIN IMMEDIATE"): + pass + yield db + await db.commit() + except BaseException: + # aiosqlite still runs queued SQL after its waiter is cancelled. + # Drain rollback, even on repeated cancellation, before reuse. + rollback = asyncio.create_task(db.rollback()) + while not rollback.done(): + try: + await asyncio.shield(rollback) + except asyncio.CancelledError: + continue + rollback.result() + raise + + async def open(self) -> None: + async with self._lock: + if self._db is not None: + return + self.path.parent.mkdir(parents=True, exist_ok=True) + db = await aiosqlite.connect(self.path) + try: + await db.executescript(""" + CREATE TABLE IF NOT EXISTS bindings ( + platform TEXT NOT NULL, user_id TEXT NOT NULL, + namespace TEXT NOT NULL, player_id TEXT NOT NULL, + display_name TEXT NOT NULL, source_url TEXT NOT NULL, + updated_at REAL NOT NULL, PRIMARY KEY (platform, user_id) + ); + CREATE TABLE IF NOT EXISTS cache ( + cache_key TEXT PRIMARY KEY, payload TEXT NOT NULL, + fetched_at REAL NOT NULL, expires_at REAL NOT NULL + ); + CREATE INDEX IF NOT EXISTS cache_fetched_at ON cache (fetched_at); + CREATE TABLE IF NOT EXISTS request_quotas ( + day TEXT NOT NULL, scope TEXT NOT NULL, + platform TEXT NOT NULL, subject TEXT NOT NULL, + used INTEGER NOT NULL CHECK (used >= 0), + PRIMARY KEY (day, scope, platform, subject) + ); + """) + await db.commit() + except BaseException: + await db.close() + raise + self._db = db + + async def close(self) -> None: + async with self._lock: + if self._db is not None: + await self._db.close() + self._db = None + + async def get_binding(self, platform: str, user: str) -> Binding | None: + async with self._lock: + async with self._connection().execute( + "SELECT namespace, player_id, display_name, source_url, updated_at " + "FROM bindings WHERE platform = ? AND user_id = ?", (platform, user) + ) as cursor: + row = await cursor.fetchone() + return Binding(*row) if row is not None else None + + async def set_binding(self, platform: str, user: str, binding: Binding) -> None: + async with self._transaction() as db: + await db.execute( + "INSERT INTO bindings VALUES (?, ?, ?, ?, ?, ?, ?) " + "ON CONFLICT(platform, user_id) DO UPDATE SET namespace=excluded.namespace, " + "player_id=excluded.player_id, display_name=excluded.display_name, " + "source_url=excluded.source_url, updated_at=excluded.updated_at", + (platform, user, binding.namespace, binding.player_id, binding.display_name, + binding.source_url, binding.updated_at), + ) + + async def unbind(self, platform: str, user: str) -> bool: + async with self._transaction() as db: + async with db.execute( + "DELETE FROM bindings WHERE platform = ? AND user_id = ?", (platform, user) + ) as cursor: + removed = cursor.rowcount > 0 + return removed + + async def get_cache(self, key: str) -> tuple[dict | list, float, float] | None: + """Return retained entries, including expired ones, for labelled fallback.""" + async with self._lock: + async with self._connection().execute( + "SELECT payload, fetched_at, expires_at FROM cache WHERE cache_key = ?", (key,) + ) as cursor: + row = await cursor.fetchone() + if row is None: + return None + return json.loads(row[0]), float(row[1]), float(row[2]) + + async def put_cache(self, key: str, payload: dict | list, ttl: float) -> None: + if not isinstance(payload, (dict, list)): + raise ValueError("缓存内容须为字典或列表。") + if not math.isfinite(ttl) or ttl < 0: + raise ValueError("缓存有效期须为非负有限秒数。") + serialized = json.dumps(payload, ensure_ascii=False, allow_nan=False) + async with self._transaction() as db: + now = self._clock() + await db.execute( + "INSERT INTO cache VALUES (?, ?, ?, ?) ON CONFLICT(cache_key) DO UPDATE SET " + "payload=excluded.payload, fetched_at=excluded.fetched_at, expires_at=excluded.expires_at", + (key, serialized, now, now + ttl), + ) + await self._prune(db, self.max_entries, self.max_age_seconds) + + async def clear_cache(self) -> None: + async with self._transaction() as db: + await db.execute("DELETE FROM cache") + + async def _prune(self, db: aiosqlite.Connection, maximum: int, max_age: float) -> int: + async with db.execute("DELETE FROM cache WHERE fetched_at <= ?", (self._clock() - max_age,)) as cursor: + removed = cursor.rowcount + async with db.execute( + "DELETE FROM cache WHERE cache_key IN (SELECT cache_key FROM cache " + "ORDER BY fetched_at DESC, cache_key ASC LIMIT -1 OFFSET ?)", (maximum,) + ) as cursor: + return removed + cursor.rowcount + + async def prune_cache(self, max_entries: int | None = None, max_age_seconds: float | None = None) -> int: + """Use constructor bounds unless overridden; never touch bindings.""" + max_entries = self.max_entries if max_entries is None else max_entries + max_age_seconds = self.max_age_seconds if max_age_seconds is None else max_age_seconds + if (type(max_entries) is not int or max_entries < 0 + or not math.isfinite(max_age_seconds) or max_age_seconds < 0): + raise ValueError("缓存容量和最长保留时间须为非负有限数值。") + async with self._transaction() as db: + removed = await self._prune(db, max_entries, max_age_seconds) + return removed + + async def cache_count(self) -> int: + async with self._lock: + async with self._connection().execute("SELECT COUNT(*) FROM cache") as cursor: + row = await cursor.fetchone() + return int(row[0]) + + async def _quota_usage(self, db: aiosqlite.Connection, day: str, actor: QuotaActor | None) -> dict: + usage = {"day": day, "global": 0, "user": 0 if actor else None, + "group": 0 if actor and actor.group else None} + platform, user, group = (actor.platform, actor.user, actor.group) if actor else ("", "", "") + async with db.execute( + "SELECT scope, used FROM request_quotas WHERE day = ? AND (" + "(scope = 'global' AND platform = '' AND subject = '') OR " + "(scope = 'user' AND platform = ? AND subject = ?) OR " + "(scope = 'group' AND platform = ? AND subject = ?))", + (day, platform, user, platform, group), + ) as cursor: + for scope, used in await cursor.fetchall(): + usage[scope] = int(used) + return usage + + async def quota_usage(self, actor: QuotaActor | None = None) -> dict: + """Read today's committed usage in a single snapshot; never reset it.""" + async with self._lock: + return await self._quota_usage(self._connection(), quota_day(self._clock()), actor) + + async def consume_request( + self, actor: QuotaActor | None = None, *, user_limit: int = 20, group_limit: int = 100, + ready: Callable[[], bool] | None = None, + ) -> dict: + """Reserve one request atomically across all applicable daily buckets. + + The global limit is fixed. Zero disables only the user/group limit, + never their accounting. No credentials or data-source namespace enter + these keys. Cancellation/errors before commit roll back every bucket. + """ + if any(type(value) is not int or value < 0 for value in (user_limit, group_limit)): + raise ValueError("用户和群每日额度必须为非负整数,0 表示不限。") + async with self._transaction() as db: + if ready is not None and not ready(): + raise AdmissionDeferred + # Evaluate the date AFTER obtaining the cross-connection write lock: + # a queued request can cross Beijing midnight. + day = quota_day(self._clock()) + usage = await self._quota_usage(db, day, actor) + for scope, limit in (("global", GLOBAL_DAILY_LIMIT), ("user", user_limit), + ("group", group_limit)): + if usage[scope] is not None and limit and usage[scope] >= limit: + raise QuotaExceededError(scope, limit, usage[scope]) + buckets = [(day, "global", "", "")] + if actor is not None: + buckets.append((day, "user", actor.platform, actor.user)) + if actor.group: + buckets.append((day, "group", actor.platform, actor.group)) + async with db.executemany( + "INSERT INTO request_quotas (day, scope, platform, subject, used) " + "VALUES (?, ?, ?, ?, 1) ON CONFLICT(day, scope, platform, subject) " + "DO UPDATE SET used = request_quotas.used + 1", buckets, + ): + pass + # Check again after SQLite awaits, while the write is uncommitted. + # Defer outside the transaction rather than waiting after charging. + if quota_day(self._clock()) != day or (ready is not None and not ready()): + raise AdmissionDeferred + for scope in ("global", "user", "group"): + if usage[scope] is not None: + usage[scope] += 1 + return usage diff --git a/templates/_macros.html b/templates/_macros.html new file mode 100644 index 0000000..ec8827a --- /dev/null +++ b/templates/_macros.html @@ -0,0 +1,9 @@ +{% macro exchange(metrics) %} +
+ {% for metric in metrics %} +

{{ metric.label }}

{{ metric.value }}{% if metric.unit %}{{ metric.unit }}{% endif %}

+ {% endfor %} +
+{% endmacro %} + +{% macro outcome(value) %}{{ value.label }}{% endmacro %} diff --git a/templates/base.html b/templates/base.html new file mode 100644 index 0000000..1641a91 --- /dev/null +++ b/templates/base.html @@ -0,0 +1,135 @@ + + + + + + + 断箭战报 · {{ view.title }} + + + +
+
断箭战报{{ view.title }}
+ {% if view.synthetic %}

合成样本 · 非真实玩家战绩

{% endif %} +
+ {% block identity %} +

{{ view.player.name }}

+

玩家 ID:{{ view.player.id }}

+ {% endblock %} +

统计范围:{{ view.scope }}

+
+ {% if view.pagination %}

{{ view.pagination }}

{% endif %} + {% if view.metrics %} +
+ {% for metric in view.metrics %} +
+

{{ metric.label }}

+

{{ metric.value }}{% if metric.unit %}{{ metric.unit }}{% endif %}

+ {% if metric.note %}

{{ metric.note }}

{% endif %} +
+ {% endfor %} +
+ {% elif view.kind == 'overview' %}

统计指标:暂无

{% endif %} + {% block content %}{% endblock %} + {% if view.notes %}{% endif %} + +
+ + diff --git a/templates/match.html b/templates/match.html new file mode 100644 index 0000000..871a0e6 --- /dev/null +++ b/templates/match.html @@ -0,0 +1,30 @@ +{% extends "base.html" %} +{% from "_macros.html" import exchange, outcome %} +{% block identity %} +

{{ view.match.map_name }}

+

对局 ID:{{ view.match.id }}

+ {% if view.player.id != '暂无' %}

{{ view.player.name }} · 玩家 ID:{{ view.player.id }}

{% endif %} +{% endblock %} +{% block content %} +
+

模式

{{ view.match.mode }}

+

胜方

{{ view.match.winner }}

+

时间

{{ view.match.started_at }}

+

时长

{{ view.match.duration }}

+
+{% for team in view.teams %} +
+

{{ team.name }}{{ team.players | length }} 人

{{ outcome(team.outcome) }}
+ {% if team.players %} + + {% else %}

队员:暂无

{% endif %} +
+{% else %}

分队与玩家:暂无

{% endfor %} +{% endblock %} diff --git a/templates/overview.html b/templates/overview.html new file mode 100644 index 0000000..a5daa6b --- /dev/null +++ b/templates/overview.html @@ -0,0 +1,13 @@ +{% extends "base.html" %} +{% block content %} +
+

常用单位 / 兵种

+ {% if view.common_units %} + + {% else %}

暂无

{% endif %} +
+{% endblock %} diff --git a/templates/recent.html b/templates/recent.html new file mode 100644 index 0000000..7d4eab0 --- /dev/null +++ b/templates/recent.html @@ -0,0 +1,16 @@ +{% extends "base.html" %} +{% from "_macros.html" import exchange, outcome %} +{% block content %} +{% if view.rows %} +
    + {% for row in view.rows %} +
  1. +

    {{ row.map_name }}

    {{ outcome(row.outcome) }}
    +
    时间:{{ row.started_at }}模式:{{ row.mode }}时长:{{ row.duration }}ELO 变化:{{ row.elo_delta }}
    + {{ exchange(row.exchange) }} +

    对局 ID:{{ row.id }}{% if row.source_url %} · 对局来源:{{ row.source_url }}{% endif %}

    +
  2. + {% endfor %} +
+{% else %}

近期对局:暂无

{% endif %} +{% endblock %} diff --git a/tests/test_client.py b/tests/test_client.py new file mode 100644 index 0000000..e4054d7 --- /dev/null +++ b/tests/test_client.py @@ -0,0 +1,704 @@ +"""SYNTHETIC fixtures and httpx.MockTransport only; no live BATrace requests.""" + +import asyncio +from dataclasses import replace +from datetime import datetime, timezone +import time + +import httpx +import pytest + +import client as client_module +from client import ( + AuthenticationError, BatraceClient, ClientClosedError, ClientConfig, + IdentityMismatchError, NoDataError, NotConfiguredError, QueueFullError, + RateLimitError, RequestTimeoutError, SchemaError, UpstreamError, +) +from storage import Storage +from quota import GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError + + +def config(**kwargs): + defaults = dict(enabled=True, base_url="https://synthetic.example.invalid", + client_id="synthetic-ba-stats", request_interval=0, retries=0, + request_timeout=0.2, wait_timeout=1) + defaults.update(kwargs) + return ClientConfig(**defaults) + + +def search_payload(id="001", name="Synthetic Player"): + return {"players": [{"id": id, "name": name}]} + + +def match_payload(*, complete=True, ended=None): + ended = time.time() - 1000 if ended is None else ended + player = {"Id": "001", "Name": "Synthetic", "OldRating": 1000, "NewRating": 1010} + if complete: + player["UnitData"] = {} + return {"matchInfo": {"StartTime": ended - 600, "EndTime": ended, + "TotalPlayTimeInSec": 600, "Data": {"a": player}}} + + +class MemoryStorage: + """Small test double implementing the real retained-cache contract.""" + def __init__(self): + self.entries = {} + self.ttls = [] + self.requests = 0 + + async def consume_request(self, actor=None, *, user_limit=20, group_limit=100, ready=None): + assert actor is None # Identified quota tests use real temporary SQLite. + if ready is not None and not ready(): + from quota import AdmissionDeferred + raise AdmissionDeferred + if self.requests >= GLOBAL_DAILY_LIMIT: + raise QuotaExceededError("global", GLOBAL_DAILY_LIMIT, self.requests) + self.requests += 1 + + async def quota_usage(self, actor=None): + assert actor is None + return {"global": self.requests, "user": None, "group": None} + + async def get_cache(self, key): + return self.entries.get(key) + + async def put_cache(self, key, payload, ttl): + now = time.time() + self.entries[key] = (payload, now, now + ttl) + self.ttls.append(ttl) + + async def clear_cache(self): + self.entries.clear() + + async def prune_cache(self, max_entries=1000, max_age_seconds=604800): + keys = sorted(self.entries, key=lambda k: self.entries[k][1], reverse=True) + for key in keys[max_entries:]: + self.entries.pop(key) + for key, (_, fetched, _) in list(self.entries.items()): + if time.time() - fetched >= max_age_seconds: + self.entries.pop(key) + + async def cache_count(self): + return len(self.entries) + + def expire(self, age=700): + now = time.time() + for key, (payload, _, _) in list(self.entries.items()): + self.entries[key] = (payload, now - age, now - 1) + + +@pytest.mark.asyncio +async def test_disabled_access_never_touches_http_or_cache(): + calls = [] + def handler(request): + calls.append(request) + raise AssertionError("disabled path reached transport") + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(http_client=http) + for operation in (lambda: client.search("Synthetic"), lambda: client.player("001"), + lambda: client.recent("001"), lambda: client.match("42")): + with pytest.raises(NotConfiguredError): + await operation() + await client.close() + assert calls == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("changes", [ + {"client_id": ""}, {"client_id": "ba-dragon-app"}, {"client_id": "ba-dragon-collector"}, + {"base_url": "http://synthetic.invalid"}, {"base_url": "https://name:secret@synthetic.invalid"}, + {"base_url": "https://synthetic.invalid/?secret=1"}, {"client_id": "test\r\nX: bad"}, +]) +async def test_invalid_or_impersonated_access_fails_closed(changes): + client = BatraceClient(config(**changes)) + with pytest.raises(NotConfiguredError): + await client.search("Synthetic") + assert client.status()["requests"] == 0 + await client.close() + + +def test_binding_namespace_survives_credentials_and_tracks_source(): + a = BatraceClient(config(api_token="first")) + b = BatraceClient(config(client_id="rotated", api_token="second")) + c = BatraceClient(config(base_url="https://different.example.invalid")) + assert a.namespace == b.namespace != c.namespace + assert a._namespace != b._namespace + status = str(a.status()) + assert "first" not in status and "synthetic.example" not in status + assert "first" not in repr(a.config) + + +@pytest.mark.asyncio +async def test_paths_query_encoding_and_plugin_identity(): + requests = [] + def handler(request): + requests.append(request) + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(api_token="synthetic-token"), http_client=http) + result = await client.search('Player 2 & "中文"') + assert result.data[0].id == "001" + assert result.fetched_at.tzinfo == timezone.utc + assert not result.stale + request = requests[0] + assert request.url.path == "/api/players/search" + assert dict(request.url.params) == {"q": 'Player 2 & "中文"', "limit": "20"} + assert request.headers["X-Client"] == "synthetic-ba-stats" + assert request.headers["User-Agent"] == "astrbot-plugin-ba-stats" + assert request.headers["Authorization"] == "Bearer synthetic-token" + assert request.extensions["timeout"]["read"] == 0.2 + await client.close() + assert not http.is_closed + + +@pytest.mark.asyncio +async def test_player_echo_verification_and_latest_elo(): + requests = [] + pid = "00098765432109876543210987654321" + def handler(request): + requests.append(request) + if request.url.path.endswith("search"): + return httpx.Response(200, json=search_payload(pid)) + assert request.url.path == "/api/analysis/player" + assert request.url.params["stbid"] == pid + return httpx.Response(200, json={"trend": {"points": [ + {"ratingAfter": 1100, "endTime": 1700000600}, + {"ratingAfter": 900, "endTime": 1700000000}, + ]}}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + result = await client.player(pid) + assert result.data.id == pid and result.data.elo == 1100 + assert result.data.steam_id is None + assert len(requests) == 2 + await client.close() + + +@pytest.mark.asyncio +async def test_identity_mismatch_is_not_a_fallback_or_a_new_binding(): + calls = [] + def handler(request): + calls.append(request) + return httpx.Response(200, json=search_payload("somebody-else")) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + with pytest.raises(IdentityMismatchError): + await client.player("001") + assert len(calls) == 1 # never continue analysis with the wrong identity + await client.close() + + +@pytest.mark.asyncio +async def test_recent_identity_limit_and_actual_request_parameters(): + seen = [] + def handler(request): + seen.append(dict(request.url.params)) + return httpx.Response(200, json={"matches": [ + {"matchId": "42", "data": match_payload()["matchInfo"]}, + ]}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + assert (await client.recent("001", 7)).data[0].id == "42" + assert seen[0] == {"stbid": "001", "limit": "7"} + with pytest.raises(IdentityMismatchError): + await client.recent("002", 7) + for limit in (0, 21, True, 1.5): + with pytest.raises(ValueError): + await client.recent("001", limit) + await client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("player_id", [None, "999"]) +async def test_recent_empty_roster_is_unknown_but_foreign_roster_cannot_use_old_cache(player_id): + store = MemoryStorage() + payload = {"matches": [{"matchId": "42", "data": match_payload()["matchInfo"]}]} + async with httpx.AsyncClient(transport=httpx.MockTransport( + lambda request: httpx.Response(200, json=payload) + )) as http: + client = BatraceClient(config(), storage=store, http_client=http) + try: + await client.recent("001") + store.expire() + payload = {"matches": [{"matchId": "42", "data": { + "Data": {} if player_id is None else {"a": {"Id": player_id}} + }}]} + if player_id is None: + result = await client.recent("001") + assert result.data[0].players == [] + assert not result.stale + else: + with pytest.raises(IdentityMismatchError, match="未参与") as error: + await client.recent("001") + assert error.value.code == "identity_mismatch" + assert client.status()["stale_hits"] == 0 + finally: + await client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("status,error", [ + (401, AuthenticationError), (403, AuthenticationError), (404, NoDataError), + (429, RateLimitError), (500, UpstreamError), (503, UpstreamError), +]) +async def test_http_failures_remain_distinct_without_unlimited_retries(status, error): + calls = [] + def handler(request): + calls.append(request) + return httpx.Response(status, json={"error": "SYNTHETIC secret, never display"}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + with pytest.raises(error) as caught: + await client.search("Synthetic") + assert "secret" not in str(caught.value) + assert len(calls) == 1 + assert client.status()["inflight"] == 0 + await client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("status,body,content_type,error", [ + (200, "{}", "application/json", SchemaError), + (200, "not json", "application/json", SchemaError), + (404, "

missing page

", "text/html", SchemaError), + (200, "Security Verification", "text/html", AuthenticationError), + (503, "EO-Bot-Captcha-Token", "text/html", AuthenticationError), + (200, "

maintenance

", "text/html", SchemaError), +]) +async def test_schema_changes_and_captcha_never_become_empty_results(status, body, content_type, error): + calls = [] + def handler(request): + calls.append(request) + return httpx.Response(status, text=body, headers={"Content-Type": content_type}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(retries=1), http_client=http) + with pytest.raises(error): + await client.search("Synthetic") + assert len(calls) == 1 + await client.close() + + +@pytest.mark.asyncio +async def test_retry_after_zero_retries_once_and_recovers(): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + if calls == 1: + return httpx.Response(429, json={}, headers={"Retry-After": "0"}) + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(retries=1), http_client=http) + assert (await client.search("Synthetic")).data[0].id == "001" + assert calls == 2 + await client.close() + + +@pytest.mark.asyncio +async def test_exhausted_retries_stop_after_configured_attempt_count(): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + return httpx.Response(429, json={}, headers={"Retry-After": "0"}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(retries=1), http_client=http) + with pytest.raises(RateLimitError): + await client.search("Synthetic") + assert calls == 2 + await client.close() + + +@pytest.mark.asyncio +async def test_long_retry_after_is_preserved_across_next_query(): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + return httpx.Response(429, json={}, headers={"Retry-After": "120"}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(retries=1, wait_timeout=0.03), http_client=http) + with pytest.raises(RateLimitError) as caught: + await client.search("Synthetic A") + assert caught.value.retry_after == 120 + with pytest.raises(RequestTimeoutError): + await client.search("Synthetic B") + assert calls == 1 + await client.close() + + +@pytest.mark.asyncio +async def test_retry_wait_is_part_of_overall_deadline(): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + return httpx.Response(503, json={}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(retries=1, wait_timeout=0.03), http_client=http) + start = time.monotonic() + with pytest.raises(RequestTimeoutError): + await client.search("Synthetic") + assert time.monotonic() - start < 0.5 and calls == 1 + await client.close() + + +@pytest.mark.asyncio +async def test_cache_hit_force_refresh_and_new_client_persistence(tmp_path): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + return httpx.Response(200, json=search_payload(name=f"Synthetic {calls}")) + store = Storage(tmp_path / "data") + await store.open() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + first = BatraceClient(config(), storage=store, http_client=http) + original = await first.search("Synthetic") + cached = await first.search("Synthetic") + assert calls == 1 and cached.data == original.data + assert not cached.stale + await first.close() + await store.close() + store = Storage(tmp_path / "data") + await store.open() + second = BatraceClient(config(), storage=store, http_client=http) + assert (await second.search("Synthetic")).data[0].name == "Synthetic 1" + assert calls == 1 + assert (await second.search("Synthetic", force=True)).data[0].name == "Synthetic 2" + assert calls == 2 + await second.close() + await store.close() + + +@pytest.mark.asyncio +async def test_stale_fallback_preserves_original_fetch_time_and_marks_reason(): + fail = False + def handler(request): + return httpx.Response(503, json={}) if fail else httpx.Response(200, json=search_payload()) + store = MemoryStorage() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), storage=store, http_client=http) + await client.search("Synthetic") + store.expire() + fetched = next(iter(store.entries.values()))[1] + fail = True + result = await client.search("Synthetic") + assert result.stale and result.stale_reason == "upstream" + assert result.fetched_at.timestamp() == pytest.approx(fetched, abs=0.000001, rel=0) + assert client.status()["stale_hits"] == 1 + await client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("status,payload,error", [ + (401, {}, AuthenticationError), (404, {}, NoDataError), (200, {}, SchemaError), +]) +async def test_nontransient_failures_never_hide_behind_stale_cache(status, payload, error): + fail = False + def handler(request): + return httpx.Response(status, json=payload) if fail else httpx.Response(200, json=search_payload()) + store = MemoryStorage() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), storage=store, http_client=http) + await client.search("Synthetic") + store.expire() + fail = True + with pytest.raises(error): + await client.search("Synthetic") + await client.close() + + +@pytest.mark.asyncio +async def test_stale_retention_limit_is_enforced(): + fail = False + def handler(request): + if fail: + raise httpx.ConnectError("SYNTHETIC", request=request) + return httpx.Response(200, json=search_payload()) + store = MemoryStorage() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(stale_hours=1), storage=store, http_client=http) + await client.search("Synthetic") + store.expire(age=3601) + fail = True + with pytest.raises(UpstreamError): + await client.search("Synthetic") + await client.close() + + +@pytest.mark.asyncio +async def test_identical_concurrent_misses_make_one_request(): + entered, release = asyncio.Event(), asyncio.Event() + calls = 0 + async def handler(request): + nonlocal calls + calls += 1 + entered.set() + await release.wait() + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(queue_size=0, concurrency=1), http_client=http) + tasks = [asyncio.create_task(client.search("Synthetic")) for _ in range(20)] + await entered.wait() + assert client.status()["inflight"] == 1 and calls == 1 + release.set() + results = await asyncio.gather(*tasks) + assert all(r.data[0].id == "001" for r in results) + assert client.status()["inflight"] == 0 + await client.close() + + +@pytest.mark.asyncio +async def test_queue_is_bounded_but_existing_request_can_join(): + entered, release = asyncio.Event(), asyncio.Event() + calls = 0 + async def handler(request): + nonlocal calls + calls += 1 + entered.set() + await release.wait() + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(concurrency=1, queue_size=1), http_client=http) + a = asyncio.create_task(client.search("A")) + await entered.wait() + b = asyncio.create_task(client.search("B")) + await asyncio.sleep(0) + with pytest.raises(QueueFullError): + await client.search("C") + joined = asyncio.create_task(client.search("A")) + release.set() + await asyncio.gather(a, b, joined) + assert calls == 2 + await client.close() + + +@pytest.mark.asyncio +async def test_global_request_spacing_and_max_concurrency(): + starts, active, peak = [], 0, 0 + async def handler(request): + nonlocal active, peak + starts.append(time.monotonic()) + active += 1 + peak = max(active, peak) + await asyncio.sleep(0.2) + active -= 1 + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(concurrency=2, request_interval=0.08), http_client=http) + await asyncio.gather(*(client.search(str(i)) for i in range(4))) + assert peak == 2 + assert all(b - a >= 0.07 for a, b in zip(starts, starts[1:])) + await client.close() + + +@pytest.mark.asyncio +async def test_queue_wait_and_transport_wait_share_one_deadline(): + calls = 0 + async def handler(request): + nonlocal calls + calls += 1 + await asyncio.Event().wait() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(concurrency=1, wait_timeout=0.03), http_client=http) + results = await asyncio.gather(client.search("A"), client.search("B"), return_exceptions=True) + assert all(isinstance(r, RequestTimeoutError) for r in results) + assert calls == 1 + assert client.status()["inflight"] == 0 + await client.close() + + +@pytest.mark.asyncio +async def test_cancelled_waiter_does_not_cancel_another_joined_waiter(): + entered, release = asyncio.Event(), asyncio.Event() + async def handler(request): + entered.set() + await release.wait() + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + a = asyncio.create_task(client.search("Synthetic")) + await entered.wait() + b = asyncio.create_task(client.search("Synthetic")) + await asyncio.sleep(0) + a.cancel() + with pytest.raises(asyncio.CancelledError): + await a + release.set() + assert (await b).data[0].id == "001" + await client.close() + + +@pytest.mark.asyncio +async def test_last_waiter_cancel_releases_request_and_allows_recovery(): + entered, stopped = asyncio.Event(), asyncio.Event() + calls = 0 + async def handler(request): + nonlocal calls + calls += 1 + if calls == 1: + entered.set() + try: + await asyncio.Event().wait() + finally: + stopped.set() + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + task = asyncio.create_task(client.search("Synthetic")) + await entered.wait() + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert stopped.is_set() and client.status()["inflight"] == 0 + assert (await client.search("Synthetic")).data[0].id == "001" + await client.close() + + +@pytest.mark.asyncio +async def test_close_cancels_and_awaits_active_and_queued_work(): + entered, stopped = asyncio.Event(), asyncio.Event() + async def handler(request): + entered.set() + try: + await asyncio.Event().wait() + finally: + stopped.set() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(concurrency=1), http_client=http) + a = asyncio.create_task(client.search("A")) + await entered.wait() + b = asyncio.create_task(client.search("B")) + await asyncio.sleep(0) + await client.close() + results = await asyncio.gather(a, b, return_exceptions=True) + assert all(isinstance(r, ClientClosedError) for r in results) + assert stopped.is_set() and client.status()["inflight"] == 0 + with pytest.raises(ClientClosedError): + await client.search("C") + await client.close() + assert not http.is_closed + + +@pytest.mark.asyncio +async def test_owned_http_client_is_closed(monkeypatch): + http = httpx.AsyncClient(transport=httpx.MockTransport(lambda r: httpx.Response(200, json=search_payload()))) + monkeypatch.setattr(client_module.httpx, "AsyncClient", lambda: http) + client = BatraceClient(config()) + await client.search("Synthetic") + await client.close() + assert http.is_closed + + +@pytest.mark.asyncio +async def test_cache_capacity_and_clear_during_refresh(): + entered, release = asyncio.Event(), asyncio.Event() + async def handler(request): + if request.url.params["q"] == "slow": + entered.set() + await release.wait() + return httpx.Response(200, json=search_payload()) + store = MemoryStorage() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(cache_max_entries=2), storage=store, http_client=http) + for q in ("A", "B", "C"): + await client.search(q) + assert await store.cache_count() == 2 + task = asyncio.create_task(client.search("slow")) + await entered.wait() + await client.clear_cache() + release.set() + await task + assert await store.cache_count() == 0 + await client.close() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("complete,ended,ttl", [ + (True, None, 86400), (False, None, 60), (True, "now", 60), +]) +async def test_complete_old_match_cache_is_long_but_fresh_or_partial_is_short(complete, ended, ttl): + payload = match_payload(complete=complete, ended=(time.time() if ended == "now" else ended)) + def handler(request): + assert request.url.path == "/api/match" and request.url.params["matchid"] == "42" + return httpx.Response(200, json=payload) + store = MemoryStorage() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), storage=store, http_client=http) + assert (await client.match("42")).data.id == "42" + assert store.ttls[-1] == ttl + await client.close() + + +@pytest.mark.asyncio +async def test_failed_request_does_not_leave_permanent_inflight_and_can_recover(): + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + if calls == 1: + raise httpx.ReadTimeout("SYNTHETIC", request=request) + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + with pytest.raises(RequestTimeoutError): + await client.search("Synthetic") + assert (await client.search("Synthetic")).data[0].id == "001" + await client.close() + + +@pytest.mark.asyncio +async def test_force_joining_fresh_cache_lookup_promotes_it_to_real_revalidation(): + class DelayedCache(MemoryStorage): + delay = False + entered = asyncio.Event() + release = asyncio.Event() + + async def get_cache(self, key): + if self.delay: + self.entered.set() + await self.release.wait() + return await super().get_cache(key) + + calls = 0 + def handler(request): + nonlocal calls + calls += 1 + return httpx.Response(200, json=search_payload(name=f"Synthetic {calls}")) + store = DelayedCache() + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), storage=store, http_client=http) + await client.search("Synthetic") + store.delay = True + normal = asyncio.create_task(client.search("Synthetic")) + await store.entered.wait() + forced = asyncio.create_task(client.search("Synthetic", force=True)) + await asyncio.sleep(0) + store.release.set() + results = await asyncio.gather(normal, forced) + assert calls == 2 # exactly one initial request plus one promoted refresh + assert all(r.data[0].name == "Synthetic 2" and not r.stale for r in results) + await client.close() + + +@pytest.mark.asyncio +async def test_force_joining_active_upstream_still_makes_one_request(): + entered, release = asyncio.Event(), asyncio.Event() + calls = 0 + async def handler(request): + nonlocal calls + calls += 1 + entered.set() + await release.wait() + return httpx.Response(200, json=search_payload()) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(config(), http_client=http) + normal = asyncio.create_task(client.search("Synthetic")) + await entered.wait() + forced = asyncio.create_task(client.search("Synthetic", force=True)) + await asyncio.sleep(0) + release.set() + await asyncio.gather(normal, forced) + assert calls == 1 + await client.close() diff --git a/tests/test_client_quota.py b/tests/test_client_quota.py new file mode 100644 index 0000000..538ec8c --- /dev/null +++ b/tests/test_client_quota.py @@ -0,0 +1,613 @@ +"""Client quota behavior using temporary SQLite and SYNTHETIC MockTransport data. + +No BATrace endpoint or real account is contacted. Storage atomicity and Beijing +midnight rollover have their own storage tests and are not duplicated here. +""" + +import asyncio +from contextlib import asynccontextmanager +from datetime import datetime + +import httpx +import pytest + +import client as client_module + +from client import ( + AuthenticationError, BatraceClient, ClientConfig, NoDataError, + RateLimitError, RequestTimeoutError, SchemaError, UpstreamError, +) +from quota import QuotaActor, QuotaExceededError +from quota import quota_day +from storage import Storage + + +def configuration(**overrides): + values = dict(enabled=True, base_url="https://synthetic.example.invalid", + client_id="synthetic-quota-client", request_interval=0, + retries=0, wait_timeout=5, request_timeout=1) + values.update(overrides) + return ClientConfig(**values) + + +def response(): + return httpx.Response(200, json={"players": [{"id": "001", "name": "Synthetic"}]}) + + +@asynccontextmanager +async def running_client(tmp_path, handler, **overrides): + storage = Storage(tmp_path / "plugin-data") + await storage.open() + try: + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = BatraceClient(configuration(**overrides), storage=storage, http_client=http) + try: + yield client, storage + finally: + await client.close() + finally: + await storage.close() + + +async def search(client, actor, query, *, force=False): + with client.request_scope(actor): + return await client.search(query, force=force) + + +async def counts(storage, actor): + usage = await storage.quota_usage(actor) + return usage["global"], usage["user"], usage["group"] + + +def assert_quota(error, scope, limit, used): + assert isinstance(error, QuotaExceededError) + assert (error.code, error.scope, error.limit, error.used) == ("daily_quota", scope, limit, used) + + +def expire_cache_reads(monkeypatch, storage): + """Expose retained data as one hour older, without changing daily quota time.""" + original = storage.get_cache + + async def expired(key): + hit = await original(key) + if hit is None: + return None + payload, fetched_at, expires_at = hit + return payload, fetched_at - 3600, expires_at - 3600 + + monkeypatch.setattr(storage, "get_cache", expired) + + +@pytest.mark.asyncio +async def test_100th_and_101st_http_attempts_race_at_fixed_global_limit(tmp_path): + calls = [] + def handler(request): + calls.append(request) + return response() + + async with running_client(tmp_path, handler) as (client, storage): + # Real adapter attempts establish 99; each sender stays below default 20. + for i in range(99): + actor = QuotaActor("onebot:a", f"sender-{i // 20}", "group-A") + await search(client, actor, f"Synthetic {i}", force=True) + actor = QuotaActor("onebot:a", "last-sender", "group-A") + results = await asyncio.gather( + search(client, actor, "Boundary A", force=True), + search(client, actor, "Boundary B", force=True), + return_exceptions=True, + ) + errors = [r for r in results if isinstance(r, BaseException)] + assert len(errors) == 1 + assert_quota(errors[0], "global", 100, 100) + assert len(calls) == client.status()["requests"] == 100 + assert await counts(storage, actor) == (100, 1, 100) + # Even a different user/group cannot bypass the fixed plugin-wide cap. + other = QuotaActor("onebot:b", "another", "group-B") + with pytest.raises(QuotaExceededError) as denied: + await search(client, other, "Other source caller", force=True) + assert_quota(denied.value, "global", 100, 100) + assert await counts(storage, other) == (100, 0, 0) + + +@pytest.mark.asyncio +async def test_default_user_20_counts_across_groups_and_private_chat(tmp_path): + calls = [] + def handler(request): + calls.append(request) + return response() + + async with running_client(tmp_path, handler) as (client, storage): + actors = [QuotaActor("onebot:a", "same-user", group) for group in ("A", "B", "")] + for i in range(20): + await search(client, actors[i % 3], f"Synthetic {i}", force=True) + for actor in actors: + with pytest.raises(QuotaExceededError) as denied: + await search(client, actor, "Beyond personal limit", force=True) + assert_quota(denied.value, "user", 20, 20) + assert await counts(storage, actors[0]) == (20, 20, 7) + assert await counts(storage, actors[1]) == (20, 20, 7) + assert await counts(storage, actors[2]) == (20, 20, None) + other = QuotaActor("onebot:a", "other-user", "A") + await search(client, other, "Other user", force=True) + assert await counts(storage, other) == (21, 1, 8) + assert len(calls) == 21 + + +@pytest.mark.asyncio +async def test_configured_group_limit_applies_to_all_senders_but_not_private_chat(tmp_path): + async with running_client(tmp_path, lambda r: response(), group_daily_limit=2) as (client, storage): + a = QuotaActor("onebot:a", "A", "limited-group") + b = QuotaActor("onebot:a", "B", "limited-group") + c = QuotaActor("onebot:a", "C", "limited-group") + await search(client, a, "First", force=True) + await search(client, b, "Second", force=True) + with pytest.raises(QuotaExceededError) as denied: + await search(client, c, "Third", force=True) + assert_quota(denied.value, "group", 2, 2) + assert await counts(storage, c) == (2, 0, 2) + private = QuotaActor("onebot:a", "C") + await search(client, private, "Private", force=True) + assert await counts(storage, private) == (3, 1, None) + + +@pytest.mark.asyncio +async def test_fresh_cache_costs_zero_at_limit_force_and_expired_cache_are_denied(tmp_path, monkeypatch): + calls = [] + def handler(request): + calls.append(request) + return response() + + async with running_client(tmp_path, handler, user_daily_limit=1) as (client, storage): + actor = QuotaActor("onebot:a", "A", "G") + await search(client, actor, "Synthetic") + assert not (await search(client, actor, "Synthetic")).stale + with pytest.raises(QuotaExceededError) as denied: + await search(client, actor, "Synthetic", force=True) + assert_quota(denied.value, "user", 1, 1) + expire_cache_reads(monkeypatch, storage) + with pytest.raises(QuotaExceededError): + await search(client, actor, "Synthetic") + assert await counts(storage, actor) == (1, 1, 1) + assert len(calls) == 1 + assert client.status()["stale_hits"] == 0 + assert client.status()["last_error"] == "daily_quota" + + +@pytest.mark.asyncio +async def test_each_submitted_failure_counts_and_is_not_refunded(tmp_path): + sequence = ["auth", "no_data", "server", "timeout", "network", "schema", "rate"] + errors = [AuthenticationError, NoDataError, UpstreamError, RequestTimeoutError, + UpstreamError, SchemaError, RateLimitError] + calls = [] + def handler(request): + kind = sequence[len(calls)] + calls.append(kind) + if kind == "timeout": + raise httpx.ReadTimeout("SYNTHETIC", request=request) + if kind == "network": + raise httpx.ConnectError("SYNTHETIC", request=request) + status = {"auth": 403, "no_data": 404, "server": 503, "schema": 200, "rate": 429}[kind] + return httpx.Response(status, json={}, headers={"Retry-After": "0"}) + + async with running_client(tmp_path, handler) as (client, storage): + actor = QuotaActor("onebot:a", "A", "G") + for i, error in enumerate(errors): + with pytest.raises(error): + await search(client, actor, f"Failure {i}") + assert await counts(storage, actor) == (i + 1, i + 1, i + 1) + assert len(calls) == client.status()["requests"] == len(errors) + assert await storage.cache_count() == 0 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("user_limit", [1, 2]) +async def test_retry_consumes_another_attempt_or_is_blocked_before_submission(tmp_path, user_limit): + calls = [] + def handler(request): + calls.append(request) + if len(calls) == 1: + return httpx.Response(429, json={}, headers={"Retry-After": "0"}) + return response() + + async with running_client(tmp_path, handler, retries=1, user_daily_limit=user_limit) as (client, storage): + actor = QuotaActor("onebot:a", "A", "G") + if user_limit == 1: + with pytest.raises(QuotaExceededError) as denied: + await search(client, actor, "Synthetic") + assert_quota(denied.value, "user", 1, 1) + else: + assert (await search(client, actor, "Synthetic")).data[0].id == "001" + assert len(calls) == user_limit + assert await counts(storage, actor) == (user_limit,) * 3 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("user_limit", [1, 2]) +async def test_player_two_http_calls_charge_twice_or_stop_between_endpoints(tmp_path, user_limit): + paths = [] + def handler(request): + paths.append(request.url.path) + if request.url.path.endswith("search"): + return response() + return httpx.Response(200, json={"matchCount": 0}) + + async with running_client(tmp_path, handler, user_daily_limit=user_limit) as (client, storage): + actor = QuotaActor("onebot:a", "A", "G") + with client.request_scope(actor): + if user_limit == 1: + with pytest.raises(QuotaExceededError) as denied: + await client.player("001", force=True) + assert_quota(denied.value, "user", 1, 1) + assert await storage.cache_count() == 0 + else: + assert (await client.player("001", force=True)).data.id == "001" + assert (await client.player("001")).data.id == "001" + assert paths == ["/api/players/search", "/api/analysis/player"][:user_limit] + assert await counts(storage, actor) == (user_limit,) * 3 + + +@pytest.mark.asyncio +async def test_same_actor_coalesces_different_callers_charge_separately_and_share_cache(tmp_path): + first_entered, all_entered, release = asyncio.Event(), asyncio.Event(), asyncio.Event() + calls = [] + async def handler(request): + calls.append(request) + first_entered.set() + if len(calls) == 3: + all_entered.set() + await release.wait() + return response() + + async with running_client(tmp_path, handler, concurrency=3) as (client, storage): + a = QuotaActor("onebot:a", "A", "G1") + a_other_group = QuotaActor("onebot:a", "A", "G2") + b = QuotaActor("onebot:a", "B", "G1") + tasks = [asyncio.create_task(search(client, a, "Same"))] + try: + await asyncio.wait_for(first_entered.wait(), 2) + tasks.extend([ + asyncio.create_task(search(client, a, "Same", force=True)), + asyncio.create_task(search(client, a_other_group, "Same", force=True)), + asyncio.create_task(search(client, b, "Same", force=True)), + ]) + await asyncio.wait_for(all_entered.wait(), 2) + assert len(calls) == 3 + release.set() + results = await asyncio.gather(*tasks) + assert all(r.data[0].id == "001" for r in results) + assert await counts(storage, a) == (3, 2, 2) + assert await counts(storage, a_other_group) == (3, 2, 1) + assert await counts(storage, b) == (3, 1, 2) + c = QuotaActor("onebot:a", "C", "G1") + assert not (await search(client, c, "Same")).stale + assert await counts(storage, c) == (3, 0, 2) + assert len(calls) == 3 + finally: + release.set() + await asyncio.gather(*tasks, return_exceptions=True) + + +@pytest.mark.asyncio +async def test_other_actor_force_cannot_join_owner_or_spend_owners_quota(tmp_path): + entered, release = asyncio.Event(), asyncio.Event() + calls = [] + async def handler(request): + calls.append(request) + if request.url.params["q"] == "Shared": + entered.set() + await release.wait() + return response() + + async with running_client(tmp_path, handler, user_daily_limit=1) as (client, storage): + owner = QuotaActor("onebot:a", "owner", "G") + other = QuotaActor("onebot:a", "other", "G") + await search(client, other, "Spend own limit") + task = asyncio.create_task(search(client, owner, "Shared")) + try: + await asyncio.wait_for(entered.wait(), 2) + with pytest.raises(QuotaExceededError) as denied: + await search(client, other, "Shared", force=True) + assert_quota(denied.value, "user", 1, 1) + assert len(calls) == 2 + finally: + release.set() + await task + assert await counts(storage, owner) == (2, 1, 2) + assert await counts(storage, other) == (2, 1, 2) + + +@pytest.mark.asyncio +async def test_cancelling_queued_costs_zero_submitted_attempt_remains_charged(tmp_path): + entered, stopped = asyncio.Event(), asyncio.Event() + calls = [] + async def handler(request): + calls.append(request) + if len(calls) == 1: + entered.set() + try: + await asyncio.Event().wait() + finally: + stopped.set() + return response() + + async with running_client(tmp_path, handler, concurrency=1) as (client, storage): + active_actor = QuotaActor("onebot:a", "active", "G") + queued_actor = QuotaActor("onebot:a", "queued", "G") + active = asyncio.create_task(search(client, active_actor, "Active")) + await asyncio.wait_for(entered.wait(), 2) + queued = asyncio.create_task(search(client, queued_actor, "Queued")) + async with asyncio.timeout(2): + while client.status()["inflight"] < 2: + await asyncio.sleep(0) + queued.cancel() + with pytest.raises(asyncio.CancelledError): + await queued + assert await counts(storage, queued_actor) == (1, 0, 1) + active.cancel() + with pytest.raises(asyncio.CancelledError): + await active + assert stopped.is_set() + assert await counts(storage, active_actor) == (1, 1, 1) + await search(client, active_actor, "After cancellation", force=True) + assert await counts(storage, active_actor) == (2, 2, 2) + assert len(calls) == 2 + + +@pytest.mark.asyncio +async def test_cancellation_after_durable_reservation_conservatively_keeps_count(tmp_path, monkeypatch): + reserved = asyncio.Event() + calls = [] + def handler(request): + calls.append(request) + return response() + + async with running_client(tmp_path, handler) as (client, storage): + consume = storage.consume_request + async def pause_after_commit(*args, **kwargs): + await consume(*args, **kwargs) + reserved.set() + await asyncio.Event().wait() + monkeypatch.setattr(storage, "consume_request", pause_after_commit) + actor = QuotaActor("onebot:a", "A", "G") + task = asyncio.create_task(search(client, actor, "Synthetic")) + await asyncio.wait_for(reserved.wait(), 2) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert await counts(storage, actor) == (1, 1, 1) + assert calls == [] + assert client.status()["inflight"] == 0 + + +@pytest.mark.asyncio +async def test_clear_rotation_and_reopen_never_reset_any_daily_bucket(tmp_path): + calls = [] + def handler(request): + calls.append(request) + return response() + + actor = QuotaActor("onebot:a", "A", "G") + async with running_client(tmp_path, handler, user_daily_limit=2) as (first, storage): + await search(first, actor, "Synthetic") + await first.clear_cache() + assert await counts(storage, actor) == (1, 1, 1) + async with running_client( + tmp_path, handler, user_daily_limit=2, client_id="rotated-synthetic", api_token="rotated-token", + ) as (second, storage): + await search(second, actor, "Synthetic", force=True) + assert await counts(storage, actor) == (2, 2, 2) + async with running_client(tmp_path, handler, user_daily_limit=2) as (third, storage): + with pytest.raises(QuotaExceededError) as denied: + await search(third, actor, "Synthetic", force=True) + assert_quota(denied.value, "user", 2, 2) + assert await counts(storage, actor) == (2, 2, 2) + assert len(calls) == 2 + + +@pytest.mark.asyncio +async def test_exhausted_actor_during_global_backoff_cannot_receive_stale(tmp_path, monkeypatch): + calls = [] + def handler(request): + calls.append(request) + if request.url.params["q"] == "Trigger backoff": + return httpx.Response(429, json={}, headers={"Retry-After": "120"}) + return response() + + async with running_client(tmp_path, handler, user_daily_limit=1, wait_timeout=0.1) as (client, storage): + exhausted = QuotaActor("onebot:a", "A", "G") + other = QuotaActor("onebot:a", "B", "G") + await search(client, exhausted, "Retained") + expire_cache_reads(monkeypatch, storage) + with pytest.raises(RateLimitError): + await search(client, other, "Trigger backoff") + with pytest.raises(QuotaExceededError) as denied: + await search(client, exhausted, "Retained") + assert_quota(denied.value, "user", 1, 1) + assert await counts(storage, exhausted) == (2, 1, 2) + assert len(calls) == 2 + assert client.status()["stale_hits"] == 0 + + +def test_identified_requests_require_persistent_storage(): + client = BatraceClient(configuration()) + with pytest.raises(RuntimeError, match="持久化"): + with client.request_scope(QuotaActor("onebot:a", "A")): + pytest.fail("actor scope must not silently fall back to local counters") + + +@pytest.mark.asyncio +async def test_cache_write_deadline_rolls_back_and_next_request_recovers(tmp_path, monkeypatch): + calls = [] + + def handler(request): + calls.append(request) + return response() + + async with running_client(tmp_path, handler, wait_timeout=0.1) as (client, storage): + actor = QuotaActor("p", "u", "g") + + async def paused_prune(*args): + await asyncio.Event().wait() + + with monkeypatch.context() as patch: + patch.setattr(storage, "_prune", paused_prune) + with pytest.raises(RequestTimeoutError): + await search(client, actor, "Interrupted cache write") + assert not storage._connection().in_transaction + assert await storage.cache_count() == 0 + assert await counts(storage, actor) == (1, 1, 1) + assert (await search(client, actor, "Recovery")).data[0].id == "001" + assert await counts(storage, actor) == (2, 2, 2) + assert len(calls) == 2 + + +@pytest.mark.asyncio +async def test_delayed_quota_keeps_send_spacing_without_serializing_responses(tmp_path, monkeypatch): + interval = 0.08 + reserving, release_quota = asyncio.Event(), asyncio.Event() + both_started, release_responses = asyncio.Event(), asyncio.Event() + starts = [] + loop = asyncio.get_running_loop() + + async def handler(request): + starts.append(loop.time()) + if len(starts) == 2: + both_started.set() + await release_responses.wait() + return response() + + async with running_client(tmp_path, handler, request_interval=interval, concurrency=2) as (client, storage): + consume = storage.consume_request + + async def delayed_consume(*args, **kwargs): + reserving.set() + await release_quota.wait() + return await consume(*args, **kwargs) + + monkeypatch.setattr(storage, "consume_request", delayed_consume) + actor = QuotaActor("p", "u", "g") + tasks = [asyncio.create_task(search(client, actor, query)) for query in ("First", "Second")] + try: + await asyncio.wait_for(reserving.wait(), 2) + await asyncio.sleep(interval * 2) + release_quota.set() + # Both HTTP calls must start while the first response is still blocked. + await asyncio.wait_for(both_started.wait(), 2) + assert starts[1] - starts[0] >= interval - 0.005 + assert await counts(storage, actor) == (2, 2, 2) + finally: + release_quota.set() + release_responses.set() + await asyncio.gather(*tasks, return_exceptions=True) + + +@pytest.mark.asyncio +async def test_backoff_received_during_quota_wait_is_checked_before_sending(tmp_path, monkeypatch): + first_started, reply_first = asyncio.Event(), asyncio.Event() + second_reserving, release_quota = asyncio.Event(), asyncio.Event() + starts = [] + loop = asyncio.get_running_loop() + backoff_started = None + + async def handler(request): + nonlocal backoff_started + starts.append(loop.time()) + if request.url.params["q"] == "First": + first_started.set() + await reply_first.wait() + backoff_started = loop.time() + return httpx.Response(429, json={}, headers={"Retry-After": "0.15"}) + return response() + + async with running_client(tmp_path, handler, concurrency=2) as (client, storage): + consume = storage.consume_request + reservations = 0 + + async def delayed_second(*args, **kwargs): + nonlocal reservations + reservations += 1 + if reservations == 2: + second_reserving.set() + await release_quota.wait() + return await consume(*args, **kwargs) + + monkeypatch.setattr(storage, "consume_request", delayed_second) + actor = QuotaActor("p", "u", "g") + tasks = [asyncio.create_task(search(client, actor, "First"))] + try: + await asyncio.wait_for(first_started.wait(), 2) + tasks.append(asyncio.create_task(search(client, actor, "Second"))) + await asyncio.wait_for(second_reserving.wait(), 2) + reply_first.set() + with pytest.raises(RateLimitError): + await tasks[0] + release_quota.set() + await asyncio.wait_for(tasks[1], 2) + assert len(starts) == 2 + assert starts[1] - backoff_started >= 0.145 + assert await counts(storage, actor) == (2, 2, 2) + finally: + reply_first.set() + release_quota.set() + await asyncio.gather(*tasks, return_exceptions=True) + + +@pytest.mark.asyncio +async def test_admission_backoff_crossing_midnight_cannot_send_101_new_day_attempts(tmp_path, monkeypatch): + clock = [datetime.fromisoformat("2026-11-17T15:59:59+00:00").timestamp()] + first_started, reply_first = asyncio.Event(), asyncio.Event() + second_reserved, release_reservation = asyncio.Event(), asyncio.Event() + days = [] + + async def handler(request): + days.append(quota_day(clock[0])) + if request.url.params["q"] == "First": + first_started.set() + await reply_first.wait() + return httpx.Response(429, json={}, headers={"Retry-After": "0.1"}) + return response() + + async with running_client(tmp_path, handler, user_daily_limit=0, group_daily_limit=0) as (client, storage): + monkeypatch.setattr(storage, "_clock", lambda: clock[0]) + monkeypatch.setattr(client_module, "quota_day", lambda _: quota_day(clock[0])) + consume = storage.consume_request + reservations = 0 + + async def pause_second_before_commit(*args, **kwargs): + nonlocal reservations + reservations += 1 + if reservations == 2: + second_reserved.set() + await release_reservation.wait() + return await consume(*args, **kwargs) + + monkeypatch.setattr(storage, "consume_request", pause_second_before_commit) + actor = QuotaActor("p", "u", "g") + tasks = [asyncio.create_task(search(client, actor, "First", force=True))] + try: + await asyncio.wait_for(first_started.wait(), 2) + tasks.append(asyncio.create_task(search(client, actor, "Second", force=True))) + await asyncio.wait_for(second_reserved.wait(), 2) + assert await counts(storage, actor) == (1, 1, 1) + reply_first.set() + with pytest.raises(RateLimitError): + await tasks[0] + release_reservation.set() + await asyncio.sleep(0.02) + clock[0] += 1 # Midnight while the new Retry-After is still active. + await asyncio.wait_for(tasks[1], 2) + assert await counts(storage, actor) == (1, 1, 1) + clock[0] -= 1 + assert await counts(storage, actor) == (1, 1, 1) + clock[0] += 1 + for index in range(99): + await search(client, actor, f"New day {index}", force=True) + with pytest.raises(QuotaExceededError) as denied: + await search(client, actor, "New day 101st", force=True) + assert_quota(denied.value, "global", 100, 100) + assert days.count("2026-11-18") == 100 + assert await counts(storage, actor) == (100, 100, 100) + finally: + reply_first.set() + release_reservation.set() + await asyncio.gather(*tasks, return_exceptions=True) diff --git a/tests/test_commands.py b/tests/test_commands.py new file mode 100644 index 0000000..f43f3b1 --- /dev/null +++ b/tests/test_commands.py @@ -0,0 +1,160 @@ +"""Command contract tests; no framework, network, or real account is used.""" + +import pytest + +from commands import Request, Target, mention_token, parse_command + + +@pytest.mark.parametrize(("text", "expected"), [ + ("", Request("help")), + ("help", Request("help")), + ("me", Request("stats", Target("me", ""))), + ("stats me", Request("stats", Target("me", ""))), + ("stats stb:0012345678901234567890", Request("stats", Target("stb", "0012345678901234567890"))), + ("stats steam:76561198012345678", Request("stats", Target("steam", "76561198012345678"))), + ("recent", Request("recent", Target("me", ""))), + ("recent 10", Request("recent", Target("me", ""), 10)), + ("recent10", Request("recent", Target("me", ""), 10)), + ("me recent 10", Request("recent", Target("me", ""), 10)), + ("me recent10", Request("recent", Target("me", ""), 10)), + ("recent steam:76561198012345678 --limit 10", + Request("recent", Target("steam", "76561198012345678"), 10)), + ("last", Request("last", Target("me", ""))), + ("me last", Request("last", Target("me", ""))), + ("last stb:001", Request("last", Target("stb", "001"))), + ("match 00098765432109876543210", Request("match", code="00098765432109876543210")), + ("search Player 2", Request("search", Target("name", "Player 2"))), + ("search 12345", Request("search", Target("name", "12345"))), + ("search me", Request("search", Target("name", "me"))), + ("bind name:Player", Request("bind", Target("name", "Player"))), + ("binding", Request("binding")), + ("unbind", Request("unbind")), + ("select AbC123 2", Request("select", code="AbC123", index=2)), + ("cancel AbC123", Request("cancel", code="AbC123")), + ("status", Request("status")), + ("quota", Request("quota")), + ("cache clear", Request("cache_clear")), +]) +def test_english_command_table(text, expected): + assert parse_command(text) == expected + + +@pytest.mark.parametrize("action", ["stats", "bind", "recent", "last"]) +@pytest.mark.parametrize(("argument", "name"), [ + ('"Player 2"', "Player 2"), + ('name:"Player 2"', "Player 2"), + ("name:Player 2", "Player 2"), + ("name:me", "me"), + ("name:recent", "recent"), + ("name:12345", "12345"), + ('name:" Player 2 "', " Player 2 "), + ('name:"欧阳 O\'Brien [x]&"', "欧阳 O'Brien [x]&"), + ("name:@user:123", "@user:123"), + ('name:"Player --limit 2"', "Player --limit 2"), +]) +def test_names_preserve_content(action, argument, name): + request = parse_command(f"{action} {argument}") + assert request.target == Target("name", name) + + +def test_trailing_number_belongs_to_target_unless_explicit_limit(): + assert parse_command("recent Player 2").target == Target("name", "Player 2") + request = parse_command('recent name:"Player 2" --limit 10') + assert request == Request("recent", Target("name", "Player 2"), 10) + assert parse_command("recent name:10").target == Target("name", "10") + + +def test_case_insensitive_keywords_do_not_change_names_or_ids(): + assert parse_command("STATS NAME:MiXeD Player").target == Target("name", "MiXeD Player") + assert parse_command("ME ReCeNt 10") == parse_command("recent 10") + assert parse_command("STATS STB:AbC-001").target == Target("stb", "AbC-001") + + +@pytest.mark.parametrize(("chinese", "english"), [ + ("帮助", "help"), ("我", "me"), ("战绩 我", "stats me"), + ("最近 10", "recent 10"), ("自己 近期 10", "me recent 10"), + ("上一场", "last"), ("我 上一场", "me last"), + ("单局 123", "match 123"), ("搜索 me", "search me"), + ("绑定 name:me", "bind name:me"), ("当前绑定", "binding"), + ("解绑", "unbind"), ("选择 ABC 1", "select ABC 1"), + ("取消 ABC", "cancel ABC"), ("状态", "status"), ("缓存 清理", "cache clear"), + ("额度", "quota"), +]) +def test_optional_chinese_aliases_share_requests(chinese, english): + assert parse_command(chinese) == parse_command(english) + with pytest.raises(ValueError, match="未知命令"): + parse_command(chinese, chinese_aliases=False) + + +def test_alias_switch_does_not_translate_explicit_names(): + assert parse_command("stats name:我").target == Target("name", "我") + assert parse_command("stats 我", chinese_aliases=False).target == Target("name", "我") + + +def test_structured_mentions_require_trusted_component_position(): + assert parse_command(f"stats {mention_token(0)}", mentions=["000123"]).target == Target("mention", "000123") + for text, mentions in [ + ("stats @user:123", []), ("stats @user:123", ["123"]), + (f"stats @user:123 {mention_token(0)}", ["123"]), + (f"stats {mention_token(1)}", ["123"]), + (f"stats {mention_token(0)}", []), + ("stats @user:123 @user:321", ["123", "321"]), + ("stats @群名片", []), ("stats", ["123"]), + ]: + with pytest.raises(ValueError): + parse_command(text, mentions=mentions) + + +@pytest.mark.parametrize("text", ["stats name:@user:123", "search @user:123"]) +def test_literal_marker_names_never_borrow_trusted_account_ids(text): + assert parse_command(text, mentions=["123"]).target == Target("name", "@user:123") + + +@pytest.mark.parametrize("text", ["search {}", "stats name:{}", "stats name:Player {}"]) +def test_real_mentions_are_not_converted_into_nickname_queries(text): + with pytest.raises(ValueError, match="提及"): + parse_command(text.format(mention_token(0)), mentions=["123"]) + + +@pytest.mark.parametrize("text", [ + "stats 12345", "bind 12345", "last 12345", "recent 123 --limit 5", +]) +def test_bare_numeric_player_is_ambiguous(text): + with pytest.raises(ValueError, match="stb:.*steam:.*name:"): + parse_command(text) + + +@pytest.mark.parametrize("text", [ + "stats", "bind", 'stats ""', 'stats " "', "stats name:", 'stats name:" "', "stats stb:", + "stats steam:abc", 'stats stb:"12 34"', 'stats "Player', + "recent 0", "recent 21", "recent10 --limit 5", "me recent 0", + "me recent player", "me recent 5 6", "me stats", "me last player", + "recent Player --limit 0", "recent Player --limit", "recent --limit 5", + "recent Player --limit 5 ignored", "recent Player --limit 5 --limit 10", + "recent Player --unknown 10", "match", "match a b", "match 'a b'", + "select code 0", "select code -1", "select code 1.5", "select code", + "cancel", "cancel code extra", "cache", "cache clear extra", "cache delete", + "search", 'search ""', "help extra", "binding extra", "unbind extra", "status extra", "quota extra", + "stats https://steamcommunity.com/id/player", "stats steamcommunity.com/id/player", + "unknown", "/ba help", +]) +def test_invalid_syntax_has_chinese_feedback(text): + with pytest.raises(ValueError) as error: + parse_command(text) + assert any("\u4e00" <= char <= "\u9fff" for char in str(error.value)) + + +def test_configured_limits_apply_to_defaults_and_both_self_spellings(): + assert parse_command("recent", default_limit=3, max_limit=10).limit == 3 + assert parse_command("recent 10", max_limit=10) == parse_command("me recent 10", max_limit=10) + with pytest.raises(ValueError): + parse_command("recent 11", max_limit=10) + for default, maximum in [(0, 20), (21, 20), (1, 0), (True, 20)]: + with pytest.raises(ValueError): + parse_command("help", default_limit=default, max_limit=maximum) + + +def test_excessively_long_integer_arguments_still_have_chinese_errors(): + for text in ["recent " + "9" * 5000, "select code " + "9" * 5000]: + with pytest.raises(ValueError, match="整数"): + parse_command(text) diff --git a/tests/test_main.py b/tests/test_main.py new file mode 100644 index 0000000..f62f040 --- /dev/null +++ b/tests/test_main.py @@ -0,0 +1,523 @@ +"""AstrBot adapter tests with test-local, fully restored module stubs. + +These exercise registered handler behavior, not a live QQ/AstrBot deployment. +Plain/At and event methods follow the adapter's actual framework interfaces. +""" + +import asyncio +from contextlib import nullcontext +from dataclasses import dataclass +import importlib +import inspect +import json +import logging +from pathlib import Path +import sys +from types import ModuleType, SimpleNamespace +from datetime import datetime, timezone +from unittest.mock import AsyncMock + +import pytest +import httpx + + +ROOT = Path(__file__).resolve().parents[1] + + +@dataclass +class Plain: + text: str + + +@dataclass +class At: + qq: str | int + + +class Event: + def __init__(self, messages, *, admin=False, normalized=None, session="onebot:test:group:1", + user="10001", group="1", platform="onebot:test"): + self.message_obj = SimpleNamespace(message=messages, self_id="999", sender=SimpleNamespace(user_id="10001")) + self.unified_msg_origin = session + self.admin = admin + self.stopped = False + self.normalized = normalized + self.message_obj.sender.user_id = user + self.group, self.platform = group, platform + + def get_messages(self): + return self.message_obj.message + + def get_message_str(self): + if self.normalized is not None: + return self.normalized + text = "".join(part.text if isinstance(part, Plain) else f"@{part.qq}" for part in self.get_messages()) + return " ".join(text.split()) + + def get_self_id(self): + return self.message_obj.self_id + + def get_sender_id(self): + return self.message_obj.sender.user_id + + def get_platform_id(self): + return self.platform + + def get_group_id(self): + return self.group + + def is_admin(self): + return self.admin + + def stop_event(self): + self.stopped = True + + def plain_result(self, text): + return "plain", text + + def image_result(self, path): + return "image", path + + +@pytest.fixture +def app_modules(monkeypatch, tmp_path): + registered = [] + + class Filters: + def command(self, command, **options): + def decorate(function): + registered.append((command, options, function)) + return function + return decorate + + def __getattr__(self, name): + raise AssertionError(f"Unexpected message-wide or extra filter registration: {name}") + + class Star: + def __init__(self, context): + self.context = context + self.logger = logging.getLogger("ba-stats-test") + + async def html_render(self, *args, **kwargs): + raise AssertionError("A real renderer must never be contacted by these tests") + + class StarTools: + @staticmethod + def get_data_dir(plugin_name): + assert plugin_name == "astrbot_plugin_ba_stats" + return tmp_path / "plugin-data" + + stubs = {key: ModuleType(key) for key in ( + "astrbot", "astrbot.api", "astrbot.api.event", "astrbot.api.message_components", "astrbot.api.star" + )} + stubs["astrbot"].__path__ = [] + stubs["astrbot.api"].__path__ = [] + stubs["astrbot"].api = stubs["astrbot.api"] + stubs["astrbot.api"].AstrBotConfig = dict + stubs["astrbot.api.event"].AstrMessageEvent = Event + stubs["astrbot.api.event"].filter = Filters() + stubs["astrbot.api.message_components"].Plain = Plain + stubs["astrbot.api.message_components"].At = At + stubs["astrbot.api.star"].Context = object + stubs["astrbot.api.star"].Star = Star + stubs["astrbot.api.star"].StarTools = StarTools + for key, module in stubs.items(): + monkeypatch.setitem(sys.modules, key, module) + name = "_ba_stats_main_contract" + package = ModuleType(name) + package.__path__ = [str(ROOT)] + monkeypatch.setitem(sys.modules, name, package) + try: + main = importlib.import_module(name + ".main") + yield SimpleNamespace( + main=main, registered=registered, + models=importlib.import_module(name + ".models"), + storage=importlib.import_module(name + ".storage"), + package=name, + ) + finally: + for key in tuple(sys.modules): + if key.startswith(name + "."): + sys.modules.pop(key, None) + + +@pytest.fixture +async def app(app_modules): + plugins = [] + + async def make(*, images=False, config=None, prefixes=None): + values = {"query": {"cooldown_seconds": 0}, "output": {"image_enabled": images}} + if config: + values.update(config) + context = SimpleNamespace(get_config=lambda umo: {"wake_prefix": prefixes or ["/"]}) + plugin = app_modules.main.BAStatsPlugin(context, values) + plugins.append(plugin) + await plugin.initialize() + return plugin + + try: + yield SimpleNamespace(make=make, **vars(app_modules)) + finally: + for plugin in plugins: + await plugin.terminate() + + +async def collect(plugin, event): + return [item async for item in plugin.ba(event)] + + +def test_only_framework_ba_command_is_registered(app_modules): + assert len(app_modules.registered) == 1 + command, options, function = app_modules.registered[0] + assert command == "ba" + assert options["alias"] == {"BA", "Ba", "bA"} + assert function is app_modules.main.BAStatsPlugin.ba + + +@pytest.mark.parametrize("messages", [ + [Plain('/ba recent name:"a b" --limit 10')], + [Plain('/ba recent name:"a '), Plain(' b" --limit 10')], + [At("999"), Plain(' /ba recent name:"a b" --limit 10')], + [Plain('!!BA recent name:"a b" --limit 10')], +]) +def test_real_style_plain_components_preserve_quotes_and_repeated_spaces(app_modules, messages): + event = Event(messages, normalized='ba recent name:"a b" --limit 10') + text, mentions = app_modules.main.extract_arguments(event, ["/", "!!"]) + assert 'name:"a b"' in text + request = app_modules.main.parse_command(text, mentions) + assert request.target.kind == "name" + assert request.target.value == "a b" + assert request.limit == 10 + + +def test_at_component_is_used_as_account_id_and_never_group_card(app_modules): + event = Event([At("999"), Plain(" /ba stats "), At(12345)]) + text, mentions = app_modules.main.extract_arguments(event, ["/"]) + assert mentions == ["12345"] + request = app_modules.main.parse_command(text, mentions) + assert (request.target.kind, request.target.value) == ("mention", "12345") + + +@pytest.mark.parametrize("messages", [ + [Plain("/ba stats @user:12345")], + [Plain("/ba stats @user:12345 "), At("12345")], + [Plain("/ba stats "), At("all")], +]) +def test_typed_internal_mentions_and_at_all_are_rejected(app_modules, messages): + with pytest.raises(ValueError, match="提及|全体"): + text, mentions = app_modules.main.extract_arguments(Event(messages), ["/"]) + app_modules.main.parse_command(text, mentions) + + +def test_plain_text_cannot_forge_component_position(app_modules): + with pytest.raises(ValueError, match="控制字符"): + app_modules.main.extract_arguments(Event([ + Plain("/ba stats \x00at:0\x00 "), At("12345") + ]), ["/"]) + + +@pytest.mark.parametrize("command", [ + "stats name:@user:12345", "bind name:@user:12345", + "recent name:@user:12345 --limit 2", "last name:@user:12345", + "search @user:12345", +]) +async def test_handler_preserves_marker_text_for_nickname_targets(app, monkeypatch, command): + plugin = await app.make() + execute = AsyncMock(return_value=SimpleNamespace(text="ok", view=None)) + monkeypatch.setattr(plugin.service, "execute", execute) + assert await collect(plugin, Event([Plain("/ba " + command)])) == [("plain", "ok")] + request, _ = execute.await_args.args + assert (request.target.kind, request.target.value) == ("name", "@user:12345") + + +@pytest.mark.parametrize("command", ["stats", "bind", "recent", "last"]) +def test_component_provenance_is_preserved_for_each_target_action(app_modules, command): + text, mentions = app_modules.main.extract_arguments( + Event([Plain(f"/ba {command} "), At("12345")]), ["/"]) + target = app_modules.main.parse_command(text, mentions).target + assert (target.kind, target.value) == ("mention", "12345") + + +async def test_unconfigured_plugin_help_works_and_online_command_explains_missing_access(app): + plugin = await app.make() + help_event = Event([Plain("/ba help")]) + replies = await collect(plugin, help_event) + assert help_event.stopped + assert replies[0][0] == "plain" + assert "首次使用" in replies[0][1] + replies = await collect(plugin, Event([Plain("/ba search Synthetic")])) + assert "接入未配置" in replies[0][1] + assert plugin.client.status()["requests"] == 0 + + +async def test_handler_passes_component_preserved_name_to_service(app, monkeypatch): + plugin = await app.make(prefixes=["!!"]) + execute = AsyncMock(return_value=SimpleNamespace(text="ok", view=None)) + monkeypatch.setattr(plugin.service, "execute", execute) + replies = await collect(plugin, Event( + [Plain('!!ba stats name:"a '), Plain(' b"')], normalized='ba stats name:"a b"' + )) + assert replies == [("plain", "ok")] + request, caller = execute.await_args.args + assert request.target.value == "a b" + assert caller.prefix == "!!ba" + + +@pytest.mark.parametrize("command", ["status", "状态", "cache clear", "缓存 清理"]) +async def test_admin_check_cannot_be_bypassed_by_english_or_chinese_commands(app, monkeypatch, command): + plugin = await app.make() + status = AsyncMock(wraps=plugin._status) + clear = AsyncMock(wraps=plugin.client.clear_cache) + execute = AsyncMock(wraps=plugin.service.execute) + monkeypatch.setattr(plugin, "_status", status) + monkeypatch.setattr(plugin.client, "clear_cache", clear) + monkeypatch.setattr(plugin.service, "execute", execute) + replies = await collect(plugin, Event([Plain("/ba " + command)], admin=False)) + assert "仅供 AstrBot 管理员" in replies[0][1] + status.assert_not_awaited() + clear.assert_not_awaited() + execute.assert_not_awaited() + + +async def test_admin_cache_clear_removes_api_and_images_but_preserves_binding(app): + plugin = await app.make() + old = app.storage.Binding(plugin.client.namespace, "001", "Synthetic") + await plugin.storage.set_binding("onebot:test", "10001", old) + await plugin.storage.put_cache("synthetic", {}, 60) + await plugin.storage.consume_request() + (plugin._images / "synthetic.jpg").write_bytes(b"synthetic image cache") + replies = await collect(plugin, Event([Plain("/ba cache clear")], admin=True)) + assert "已清理" in replies[0][1] + assert await plugin.storage.cache_count() == 0 + assert not list(plugin._images.glob("*.jpg")) + assert await plugin.storage.get_binding("onebot:test", "10001") == old + assert (await plugin.storage.quota_usage())["global"] == 1 + + +async def test_admin_status_does_not_expose_configured_credentials(app): + secret = "synthetic-token-never-display" + identity = "synthetic-private-client" + plugin = await app.make(config={"access": { + "enabled": True, "client_id": identity, "api_token": secret, + "base_url": "https://example.invalid", + }}) + replies = await collect(plugin, Event([Plain("/ba status")], admin=True)) + text = replies[0][1] + assert "已填写" in text + assert secret not in text and identity not in text and "example.invalid" not in text + assert plugin.client.status()["requests"] == 0 + assert "今日总请求:0/100(固定上限)" in text + + +async def test_image_failure_uses_same_result_as_text_without_second_fetch(app, monkeypatch): + plugin = await app.make(images=True) + m = app.models + at = datetime(2026, 11, 17, tzinfo=timezone.utc) + player = m.Player("001", "Synthetic a b", source_url="https://example.invalid/players/001") + client = SimpleNamespace( + namespace="batrace:synthetic", player=AsyncMock(return_value=m.FetchResult(player, at)), + recent=AsyncMock(return_value=m.FetchResult([], at)), close=AsyncMock(), + request_scope=lambda actor: nullcontext(), + ) + await plugin.client.close() + plugin.client = plugin.service.client = client + image = AsyncMock(side_effect=RuntimeError("synthetic render failure")) + monkeypatch.setattr(plugin, "_image", image) + original_execute = plugin.service.execute + responses = [] + + async def execute(*args): + response = await original_execute(*args) + responses.append(response) + return response + + monkeypatch.setattr(plugin.service, "execute", execute) + replies = await collect(plugin, Event([Plain("/ba stats stb:001")])) + assert len(responses) == 1 + expected = plugin.renderer.text(plugin.renderer.views(responses[0].view)[0]) + assert replies == [("plain", expected)] + assert "001" in expected and "Synthetic a b" in expected + image.assert_awaited_once() + client.player.assert_awaited_once_with("001") + client.recent.assert_awaited_once_with("001", plugin.settings.max_limit) + + +async def test_image_render_uses_mobile_jpeg_contract_and_fixed_outer_template(app, monkeypatch, tmp_path): + plugin = await app.make(images=True) + # Only exercise local file handoff/caching, not image validity or appearance. + source = tmp_path / "synthetic-render.jpg" + source.write_bytes(b"synthetic jpeg handoff") + render = AsyncMock(return_value=str(source)) + monkeypatch.setattr(plugin, "html_render", render) + view = { + "kind": "overview", "player": {"id": "001", "name": "Synthetic {{ 7 * 7 }} a b"}, + "scope": "合成测试样本", "fetched_at": datetime(2026, 11, 17, tzinfo=timezone.utc), + } + first = await plugin._image(view, "onebot:test:group:one") + assert Path(first).suffix == ".jpg" + assert Path(first).read_bytes() == source.read_bytes() + assert await plugin._image(view, "onebot:test:group:one") == first + render.assert_awaited_once() + positional, options = render.await_args + assert positional[0] == "{{ body | safe }}" + assert "{{ 7 * 7 }} a b" in positional[1]["body"] + assert options["return_url"] is False + assert options["umo"] == "onebot:test:group:one" + assert options["options"] == { + "type": "jpeg", "quality": 85, "full_page": True, + "viewport_width": 390, "device_scale_factor_level": "ultra", + } + second = await plugin._image(view, "onebot:test:group:two") + assert second != first + assert render.await_count == 2 + + +async def test_run_after_terminate_closes_coroutine_and_creates_no_task(app): + plugin = await app.make() + await plugin.terminate() + entered = False + + async def should_not_run(): + nonlocal entered + entered = True + + coroutine = should_not_run() + with pytest.raises(asyncio.CancelledError): + await plugin._run(coroutine) + assert inspect.getcoroutinestate(coroutine) == inspect.CORO_CLOSED + assert not entered + assert not plugin._tasks + + +async def test_terminate_cancels_and_awaits_active_work_then_closes_resources(app, monkeypatch): + plugin = await app.make() + started, cancelled = asyncio.Event(), asyncio.Event() + + async def blocked(*args): + started.set() + try: + await asyncio.Event().wait() + finally: + cancelled.set() + + monkeypatch.setattr(plugin.service, "execute", blocked) + close_client = AsyncMock(wraps=plugin.client.close) + close_storage = AsyncMock(wraps=plugin.storage.close) + monkeypatch.setattr(plugin.client, "close", close_client) + monkeypatch.setattr(plugin.storage, "close", close_storage) + scope = ("p", "s", "u") + generation = plugin.service.pending.begin(scope) + plugin.service.pending.publish(scope, generation, object(), [object()]) + task = asyncio.create_task(collect(plugin, Event([Plain("/ba search Synthetic")]))) + try: + await asyncio.wait_for(started.wait(), 2) + await plugin.terminate() + results = await asyncio.gather(task, return_exceptions=True) + assert isinstance(results[0], asyncio.CancelledError) + assert cancelled.is_set() + assert not plugin._tasks + assert not plugin.service.pending.is_current(scope, generation) + close_client.assert_awaited_once() + close_storage.assert_awaited_once() + with pytest.raises(RuntimeError, match="尚未打开"): + await plugin.storage.get_binding("p", "u") + assert await collect(plugin, Event([Plain("/ba help")])) == [] + finally: + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + +@pytest.mark.parametrize("command,group", [("quota", "1"), ("额度", "")]) +async def test_quota_is_local_and_available_without_access_or_admin(app, command, group): + plugin = await app.make() + replies = await collect(plugin, Event([Plain("/ba " + command)], group=group)) + text = replies[0][1] + assert "个人:已用 0/20 次" in text + assert "全插件:已用 0/100 次" in text + assert ("本群:已用 0/100 次" in text) == bool(group) + assert "北京时间每天 0 点重置" in text + assert plugin.client.status()["requests"] == 0 + + +async def test_handler_enforces_user_group_quota_and_preserves_cached_access(app): + plugin = await app.make(config={ + "access": {"enabled": True, "client_id": "synthetic-test", "base_url": "https://synthetic.invalid"}, + "query": {"cooldown_seconds": 0}, + "maintenance": {"request_interval": 0.1, "retries": 0}, + "limits": {"user_daily_limit": 2, "group_daily_limit": 3}, + }) + calls = [] + def handler(request): + calls.append(request) + return httpx.Response(200, json={"players": [{"id": "001", "name": "Synthetic"}]}) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + plugin.client._http, plugin.client._owns_http = http, False + async def search(query, user, group, admin=False): + return await collect(plugin, Event([Plain("/ba search " + query)], user=user, + group=group, admin=admin)) + await search("one", "u1", "g1") + await search("two", "u1", "g2") + blocked = await search("private", "u1", "") + assert "20" not in blocked[0][1] # Runtime override, not a hardcoded default. + assert "额度" in blocked[0][1] and "2" in blocked[0][1] + await search("three", "u2", "g1") + await search("four", "u3", "g1") + assert "额度" in (await search("five", "u4", "g1"))[0][1] + assert "额度" in (await search("six", "u1", "g2", admin=True))[0][1] + assert len(calls) == 4 + # A fresh cached response consumes no upstream request, even at the cap. + cached = await search("one", "u1", "g1") + assert "请选择" in cached[0][1] + assert len(calls) == 4 + actor = app.main.QuotaActor("onebot:test", "u1", "g1") + usage = await plugin.storage.quota_usage(actor) + assert (usage["global"], usage["user"], usage["group"]) == (4, 2, 3) + before = dict(usage) + for text in ["help", "binding", "unbind", "quota"]: + await collect(plugin, Event([Plain("/ba " + text)], user="u1", group="g1")) + assert await plugin.storage.quota_usage(actor) == before + + +async def test_mentions_charge_request_sender_not_queried_user(app): + plugin = await app.make(config={ + "access": {"enabled": True, "client_id": "synthetic-test", "base_url": "https://synthetic.invalid"}, + "query": {"cooldown_seconds": 0}, "maintenance": {"request_interval": 0.1, "retries": 0}, + }) + await plugin.storage.set_binding("onebot:test", "target", app.storage.Binding( + plugin.client.namespace, "001", "Synthetic")) + def handler(request): + if request.url.path.endswith("search"): + payload = {"players": [{"id": "001", "name": "Synthetic"}]} + elif request.url.path.endswith("player"): + payload = {"trend": {"points": []}} + else: + payload = {"matches": []} + return httpx.Response(200, json=payload) + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + plugin.client._http, plugin.client._owns_http = http, False + replies = await collect(plugin, Event([Plain("/ba stats "), At("target")], user="sender", group="g")) + assert "Synthetic" in replies[0][1] + sender = await plugin.storage.quota_usage(app.main.QuotaActor("onebot:test", "sender", "g")) + target = await plugin.storage.quota_usage(app.main.QuotaActor("onebot:test", "target", "g")) + assert (sender["global"], sender["user"], sender["group"], target["user"]) == (3, 3, 3, 0) + + +def test_quota_defaults_schema_and_fixed_total_are_consistent(app_modules): + settings = app_modules.main.Settings + schema = json.loads((ROOT / "_conf_schema.json").read_text(encoding="utf-8")) + limits = schema["limits"]["items"] + assert set(limits) == {"user_daily_limit", "group_daily_limit"} + defaults = settings.from_config({}) + assert defaults.user_daily_limit == limits["user_daily_limit"]["default"] == 20 + assert defaults.group_daily_limit == limits["group_daily_limit"]["default"] == 100 + configured = settings.from_config({"limits": { + "user_daily_limit": 0, "group_daily_limit": 1, "global_daily_limit": 10000, "timezone": "UTC", + }, "output": {"timezone": "UTC"}}) + assert configured.user_daily_limit == 0 and configured.group_daily_limit == 1 + assert not hasattr(configured, "global_daily_limit") + assert app_modules.main.GLOBAL_DAILY_LIMIT == 100 + for key in limits: + for invalid in [-1, 101, True, 2.5, "20", None]: + with pytest.raises(ValueError, match="0–100"): + settings.from_config({"limits": {key: invalid}}) diff --git a/tests/test_models.py b/tests/test_models.py new file mode 100644 index 0000000..3591304 --- /dev/null +++ b/tests/test_models.py @@ -0,0 +1,176 @@ +"""All payloads below are SYNTHETIC contract fixtures, not captured BATrace data.""" + +from datetime import datetime, timezone + +import pytest + +from models import ( + FetchResult, Match, Participant, Player, canonical_id, parse_match, + parse_player, parse_recent, parse_search, utc_datetime, +) + + +def raw_match(*, start=1700000000, end=1700000600): + return { + "StartTime": start, "EndTime": end, "TotalPlayTimeInSec": 600, + "MapId": 20, "Type": 99, + "Data": { + "a": {"Id": "001", "Name": "Synthetic ", "OldRating": 1000, + "NewRating": 1012, "Destruction": 2, "Losses": 1, + "DestructionScore": 500, "LossesScore": 100, "UnitData": {}}, + "b": {"Id": 2, "Name": "Synthetic B", "TeamId": 1, + "OldRating": 1000, "NewRating": 988, "UnitData": {}}, + }, + } + + +def test_dataclasses_do_not_share_mutable_lists(): + a, b = Match("a"), Match("b") + a.players.append(Participant("p", "Synthetic")) + assert b.players == [] + a.players[0].units.append({"id": "u"}) + assert Participant("q", "Another").units == [] + assert Player("001", "Synthetic").steam_id is None + assert FetchResult([], datetime.now(timezone.utc)).stale is False + + +@pytest.mark.parametrize("raw", [1.0, True, None, "", " 1", "1 "]) +def test_identity_does_not_guess_or_round(raw): + with pytest.raises(ValueError): + canonical_id(raw) + + +def test_large_ids_are_strings_and_names_are_never_identity_keys(): + payload = {"players": [ + {"id": "000765611980123456789012345", "name": "Same"}, + {"id": 98765432109876543210987654321, "name": "Same"}, + {"id": "000765611980123456789012345", "name": "Same"}, + ]} + players = parse_search(payload) + assert len(players) == 2 + assert players[0].id == "000765611980123456789012345" + assert players[1].id == "98765432109876543210987654321" + assert all(p.elo is None and p.steam_id is None for p in players) + + +def test_newer_search_duplicate_updates_name_without_moving_candidate(): + players = parse_search({"players": [ + {"id": "a", "name": "Old", "updated_at": "2023-01-01T00:00:00Z"}, + {"id": "b", "name": "Other"}, + {"id": "a", "name": "New", "updated_at": "2023-02-01T00:00:00Z"}, + ]}) + assert [(p.id, p.name) for p in players] == [("a", "New"), ("b", "Other")] + + +def test_links_use_reference_confirmed_routes_and_escape_external_id(): + player = parse_search({"players": [{"id": "x/#?", "name": "Synthetic"}]})[0] + assert player.source_url == "https://dash.batrace.top/player/x%2F%23%3F" + assert parse_match({"matchInfo": raw_match()}, "x/#?").source_url.endswith("/match/x%2F%23%3F") + + +def test_time_is_aware_utc_and_recent_can_derive_start_from_end(): + assert utc_datetime("2023-11-15T06:13:20+08:00") == utc_datetime(1700000000) + match = raw_match() + match.pop("StartTime") + normalized = parse_match({"matchInfo": match}, "a") + assert normalized.started_at == datetime.fromtimestamp(1700000000, timezone.utc) + + +@pytest.mark.parametrize("raw", ["2023-01-01T00:00:00", True, float("nan"), float("inf")]) +def test_time_does_not_guess_timezone_or_accept_nonfinite_values(raw): + with pytest.raises(ValueError): + utc_datetime(raw) + + +def test_player_uses_newest_dated_observation_not_array_order(): + player = parse_player({ + "search": {"players": [{"id": "001", "name": "Synthetic", "rating": 900}]}, + "analysis": {"matchCount": 2, "trend": {"points": [ + {"ratingAfter": 1200, "endTime": 1700000600}, + {"ratingAfter": 1100, "endTime": 1700000000}, + ]}}, + }, "001") + assert player.elo == 1200 + assert player.elo_observed_at == utc_datetime(1700000600) + assert player.updated_at is None # a match end is not a source update stamp + + +def test_search_snapshot_newer_than_trend_keeps_its_rating(): + player = parse_player({ + "search": {"players": [{"id": "001", "name": "Synthetic", "rating": 1300, + "updated_at": "2023-11-15T00:00:00Z"}]}, + "analysis": {"trend": {"points": [{"ratingAfter": 1200, "endTime": 1700000000}]}}, + }, "001") + assert player.elo == 1300 + assert player.elo_observed_at is None + + +def test_player_does_not_replace_requested_identity_or_invent_steam_mapping(): + with pytest.raises(ValueError, match="ID"): + parse_player({"search": {"players": [{"id": "other", "name": "Same"}]}, + "analysis": {"matchCount": 0}}, "001") + + +def test_protobuf_defaults_are_scoped_and_count_is_distinct_from_value(): + match = parse_match({"matchInfo": raw_match()}, "42") + a, b = match.players + assert (a.kills, a.losses, a.destroyed_value, a.lost_value) == (2, 1, 500, 100) + assert a.team == "0" + assert (b.kills, b.losses, b.destroyed_value, b.lost_value) == (0, 0, 0, 0) + assert parse_match({"matchInfo": {"Data": {"a": {"Id": "001"}}}}, "empty").players[0].elo is None + assert Participant("001", "Synthetic").kills is None # no universal zero filling + + +def test_rating_change_never_becomes_verified_outcome_or_mode(): + match = parse_match({"matchInfo": raw_match()}, "42") + assert match.winner_team is None + assert match.mode == "unknown" + assert [p.outcome for p in match.players] == ["unknown", "unknown"] + assert [p.elo_delta for p in match.players] == [12, -12] + + +def test_match_detail_and_recent_have_different_completeness(): + match = raw_match() + assert parse_match({"matchInfo": match}, "42").complete + assert not parse_match({"matchInfo": match}, "42", detail=False).complete + match["Data"]["a"].pop("UnitData") + assert not parse_match({"matchInfo": match}, "42").complete + + +def test_recent_deduplicates_ids_sorts_actual_start_and_retains_unknown_time(): + rows = [ + {"matchId": "old", "data": raw_match(start=1700000000)}, + {"matchId": "new", "data": raw_match(start=1700000500)}, + {"matchId": "new", "data": raw_match(start=1700000500)}, + {"matchId": "unknown", "data": {"Data": {}}}, + ] + assert [m.id for m in parse_recent({"matches": rows})] == ["new", "old", "unknown"] + assert parse_recent({"matches": []}) == [] + + +@pytest.mark.parametrize("payload", [{}, {"players": None}, {"players": {}}, {"error": "synthetic"}]) +def test_missing_response_array_is_not_a_successful_empty_search(payload): + with pytest.raises(ValueError): + parse_search(payload) + + +@pytest.mark.parametrize("mutate", [ + lambda m: m["Data"]["a"].update({"Id": 1.5}), + lambda m: m["Data"]["a"].update({"Destruction": -1}), + lambda m: m["Data"]["a"].update({"Losses": 1.5}), + lambda m: m["Data"]["a"].update({"NewRating": float("nan")}), + lambda m: m["Data"]["a"].update({"TeamId": None}), + lambda m: m["Data"]["a"].update({"UnitData": []}), + lambda m: m.update({"EndTime": 1600000000}), + lambda m: m.update({"TotalPlayTimeInSec": -1}), +]) +def test_structural_changes_and_invalid_numbers_are_rejected(mutate): + payload = raw_match() + mutate(payload) + with pytest.raises(ValueError): + parse_match({"matchInfo": payload}, "42") + + +def test_explicit_mismatching_match_id_is_rejected(): + with pytest.raises(ValueError, match="ID mismatch"): + parse_match({"matchId": "other", "matchInfo": raw_match()}, "42") diff --git a/tests/test_pending.py b/tests/test_pending.py new file mode 100644 index 0000000..c604adf --- /dev/null +++ b/tests/test_pending.py @@ -0,0 +1,219 @@ +"""Deterministic selection tests with opaque requests and fake time.""" + +from concurrent.futures import ThreadPoolExecutor + +import pytest + +from pending import PendingManager + + +SCOPE = ("onebot:instance-a", "group:one", "user:1") + + +class Clock: + now = 100.0 + + def __call__(self): + return self.now + + +def publish(manager, scope=SCOPE, request=None, candidates=None): + generation = manager.begin(scope) + pending = manager.publish(scope, generation, request if request is not None else object(), + candidates if candidates is not None else [object(), object()]) + assert pending is not None + return pending + + +def test_original_action_and_candidate_order_survive_one_time_choice(): + manager = PendingManager() + request = {"action": "recent", "limit": 10, "query": "Player"} + candidates = [object(), object()] + pending = publish(manager, request=request, candidates=candidates) + candidates.reverse() + chosen_request, chosen_candidate = manager.consume(SCOPE, pending.code, 2) + assert chosen_request is request + assert chosen_request["action"] == "recent" + assert chosen_candidate is candidates[0] + with pytest.raises(ValueError): + manager.consume(SCOPE, pending.code, 2) + assert manager.publish(SCOPE, pending.generation, request, candidates) is None + + +@pytest.mark.parametrize("scope", [ + ("onebot:instance-a", "group:one", "user:2"), + ("onebot:instance-a", "group:two", "user:1"), + ("onebot:instance-b", "group:one", "user:1"), +]) +def test_other_users_sessions_and_platforms_cannot_consume_or_cancel(scope): + manager = PendingManager() + first = publish(manager) + second = publish(manager, scope) + with pytest.raises(ValueError): + manager.consume(scope, first.code, 1) + assert not manager.cancel(scope, first.code) + assert manager.consume(SCOPE, first.code, 1)[0] is first.request + assert manager.consume(scope, second.code, 1)[0] is second.request + + +def test_begin_immediately_invalidates_old_list_before_network_finishes(): + manager = PendingManager() + old = publish(manager) + generation = manager.begin(SCOPE) + with pytest.raises(ValueError): + manager.consume(SCOPE, old.code, 1) + assert manager.publish(SCOPE, old.generation, old.request, old.candidates) is None + new = manager.publish(SCOPE, generation, {"action": "bind"}, ["new"]) + assert new is not None + assert manager.consume(SCOPE, new.code, 1) == ({"action": "bind"}, "new") + + +def test_old_network_result_cannot_replace_new_results(): + manager = PendingManager() + old_generation = manager.begin(SCOPE) + new_generation = manager.begin(SCOPE) + new = manager.publish(SCOPE, new_generation, "read-only", ["right"]) + assert manager.publish(SCOPE, old_generation, "bind", ["wrong"]) is None + assert manager.consume(SCOPE, new.code, 1) == ("read-only", "right") + + +def test_generation_can_publish_only_once_and_empty_results_invalidate_it(): + manager = PendingManager() + first = publish(manager) + assert manager.publish(SCOPE, first.generation, "bind", ["wrong"]) is None + assert manager.consume(SCOPE, first.code, 1)[0] is first.request + generation = manager.begin(SCOPE) + assert manager.publish(SCOPE, generation, "empty", []) is None + assert manager.publish(SCOPE, generation, "late", ["wrong"]) is None + + +@pytest.mark.parametrize("index", [0, -1, 3, "1", True, 1.5]) +def test_out_of_range_or_invalid_index_preserves_valid_request(index): + manager = PendingManager() + pending = publish(manager) + with pytest.raises(ValueError, match="序号"): + manager.consume(SCOPE, pending.code, index) + assert manager.consume(SCOPE, pending.code, 1)[0] is pending.request + + +def test_expiry_boundary_and_no_generation_reuse_after_cleanup(): + clock = Clock() + manager = PendingManager(ttl=120, clock=clock) + pending = publish(manager) + clock.now += 120 + with pytest.raises(ValueError): + manager.consume(SCOPE, pending.code, 1) + assert not manager.cancel(SCOPE, pending.code) + replacement = manager.begin(SCOPE) + assert replacement != pending.generation + assert manager.publish(SCOPE, pending.generation, "old", ["wrong"]) is None + assert manager.publish(SCOPE, replacement, "new", ["right"]) is not None + + +def test_unpublished_network_request_expires_and_publication_starts_selection_ttl(): + clock = Clock() + manager = PendingManager(ttl=120, clock=clock) + expired = manager.begin(SCOPE) + clock.now += 120 + assert manager.publish(SCOPE, expired, "old", ["wrong"]) is None + generation = manager.begin(SCOPE) + clock.now += 90 + pending = manager.publish(SCOPE, generation, "new", ["right"]) + clock.now += 119 + assert manager.consume(SCOPE, pending.code, 1) == ("new", "right") + + +def test_cancel_is_scoped_single_use_and_does_not_cancel_replacement(): + manager = PendingManager() + first = publish(manager) + second = publish(manager) + assert not manager.cancel(SCOPE, first.code) + assert manager.cancel(SCOPE, second.code) + assert not manager.cancel(SCOPE, second.code) + with pytest.raises(ValueError): + manager.consume(SCOPE, second.code, 1) + assert manager.publish(SCOPE, second.generation, "late", ["wrong"]) is None + + +def test_capacity_evicts_oldest_without_resurrecting_its_network_generation(): + manager = PendingManager(max_entries=2) + one = publish(manager) + two = publish(manager, ("p", "s", "2")) + three = publish(manager, ("p", "s", "3")) + with pytest.raises(ValueError): + manager.consume(SCOPE, one.code, 1) + assert manager.publish(SCOPE, one.generation, "late", ["wrong"]) is None + assert manager.consume(two.scope, two.code, 1)[0] is two.request + assert manager.consume(three.scope, three.code, 1)[0] is three.request + + +def test_simultaneous_consume_only_succeeds_once(): + manager = PendingManager() + pending = publish(manager) + + def choose(_): + try: + return manager.consume(SCOPE, pending.code, 1) + except ValueError: + return None + + with ThreadPoolExecutor(max_workers=4) as executor: + results = list(executor.map(choose, range(8))) + assert sum(result is not None for result in results) == 1 + + +def test_generation_check_does_not_consume_or_extend_and_expires_at_boundary(): + clock = Clock() + manager = PendingManager(ttl=120, clock=clock) + generation = manager.begin(SCOPE) + assert manager.is_current(SCOPE, generation) + assert not manager.is_current(("other", "session", "user"), generation) + pending = manager.publish(SCOPE, generation, "bind", ["player"]) + assert manager.is_current(SCOPE, generation) + assert manager.is_current(SCOPE, generation) + assert manager.consume(SCOPE, pending.code, 1) == ("bind", "player") + assert not manager.is_current(SCOPE, generation) + executing = manager.begin(SCOPE) + clock.now += 119 + assert manager.is_current(SCOPE, executing) + clock.now += 1 + assert not manager.is_current(SCOPE, executing) + + +def test_new_operation_invalidates_selected_execution_generation(): + manager = PendingManager() + pending = publish(manager, request="bind", candidates=["player"]) + manager.consume(SCOPE, pending.code, 1) + execution = manager.begin(SCOPE) + assert manager.is_current(SCOPE, execution) + replacement = manager.begin(SCOPE) + assert not manager.is_current(SCOPE, execution) + assert manager.is_current(SCOPE, replacement) + + +def test_clear_invalidates_all_scopes_and_prevents_late_publication(): + manager = PendingManager() + published = publish(manager) + other_scope = ("p", "s", "another") + network_generation = manager.begin(other_scope) + manager.clear() + manager.clear() + assert not manager.is_current(SCOPE, published.generation) + assert not manager.is_current(other_scope, network_generation) + with pytest.raises(ValueError): + manager.consume(SCOPE, published.code, 1) + assert not manager.cancel(SCOPE, published.code) + new_generation = manager.begin(other_scope) + assert new_generation > network_generation + assert manager.publish(other_scope, network_generation, "old", ["wrong"]) is None + assert manager.publish(SCOPE, published.generation, "old", ["wrong"]) is None + assert manager.publish(other_scope, new_generation, "new", ["right"]) is not None + + +def test_pending_configuration_requires_bounded_lifetime_and_capacity(): + for ttl in [0, -1, float("nan"), float("inf")]: + with pytest.raises(ValueError): + PendingManager(ttl=ttl) + for maximum in [0, -1, 1.5, True]: + with pytest.raises(ValueError): + PendingManager(max_entries=maximum) diff --git a/tests/test_quota_storage.py b/tests/test_quota_storage.py new file mode 100644 index 0000000..a941072 --- /dev/null +++ b/tests/test_quota_storage.py @@ -0,0 +1,402 @@ +"""Persistent quota accounting with real temporary SQLite connections. + +No API requests: all dates, contention, cancellation and failures are local. +""" + +import asyncio +from dataclasses import FrozenInstanceError +from datetime import datetime +import sqlite3 + +import pytest + +from quota import GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day +from storage import Binding, Storage + + +class Clock: + def __init__(self, value="2026-11-17T15:59:59+00:00"): + self.now = datetime.fromisoformat(value).timestamp() + + def __call__(self): + return self.now + + +@pytest.fixture +async def stores(tmp_path): + connections, tasks = [], [] + clock = Clock() + + async def connect(): + store = Storage(tmp_path / "plugin-data", clock=clock) + await store.open() + connections.append(store) + return store + + def spawn(coroutine): + task = asyncio.create_task(coroutine) + tasks.append(task) + return task + + try: + yield connect, clock, spawn + finally: + for task in tasks: + if not task.done(): + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + for store in connections: + await store.close() + + +def assert_exceeded(error, scope, limit, used): + assert isinstance(error, ValueError) + assert error.code == "daily_quota" + assert (error.scope, error.limit, error.used) == (scope, limit, used) + assert "北京时间 0 点重置" in str(error) + assert str(limit) in str(error) and str(used) in str(error) + + +def test_actor_is_immutable_and_preserves_identity_strings(): + actor = QuotaActor("onebot:001", "00012345678901234567890") + assert actor.group == "" + assert actor.user == "00012345678901234567890" + with pytest.raises(FrozenInstanceError): + actor.user = "another" + + +@pytest.mark.parametrize("args", [ + ("", "u"), ("p", ""), (" ", "u"), ("p", " \t"), + (None, "u"), ("p", 123), ("p", "u", None), ("p", "u", " "), +]) +def test_actor_rejects_missing_platform_or_user_and_invalid_group(args): + with pytest.raises(ValueError): + QuotaActor(*args) + + +@pytest.mark.parametrize(("iso", "expected"), [ + ("2026-11-17T15:59:59.999999+00:00", "2026-11-17"), + ("2026-11-17T16:00:00+00:00", "2026-11-18"), + ("2026-12-31T16:00:00+00:00", "2027-01-01"), +]) +def test_quota_day_uses_beijing_calendar_boundary(iso, expected): + assert quota_day(datetime.fromisoformat(iso).timestamp()) == expected + + +async def test_usage_is_read_only_and_actor_none_counts_global_only(stores): + connect, _, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "g") + before_changes = store._connection().total_changes + assert await store.quota_usage() == {"day": "2026-11-17", "global": 0, "user": None, "group": None} + assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 0, "user": 0, "group": 0} + assert store._connection().total_changes == before_changes + assert await store.consume_request() == {"day": "2026-11-17", "global": 1, "user": None, "group": None} + assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 1, "user": 0, "group": 0} + + +async def test_default_user_twenty_boundary_does_not_charge_other_buckets(stores): + connect, _, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "group-one") + for count in range(1, 21): + assert (await store.consume_request(actor))["user"] == count + another_group = QuotaActor("p", "u", "group-two") + with pytest.raises(QuotaExceededError) as error: + await store.consume_request(another_group) + assert_exceeded(error.value, "user", 20, 20) + assert await store.quota_usage(another_group) == { + "day": "2026-11-17", "global": 20, "user": 20, "group": 0, + } + assert (await store.quota_usage(actor))["group"] == 20 + assert (await store.consume_request(QuotaActor("p", "other", "group-two")))["global"] == 21 + + +async def test_group_accumulates_across_users_and_rejection_does_not_charge_new_user(stores): + connect, _, _ = stores + store = await connect() + for index in range(3): + result = await store.consume_request(QuotaActor("p", str(index), "g"), group_limit=3) + assert result["user"] == 1 + assert result["group"] == index + 1 + actor = QuotaActor("p", "new-user", "g") + with pytest.raises(QuotaExceededError) as error: + await store.consume_request(actor, group_limit=3) + assert_exceeded(error.value, "group", 3, 3) + assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 3, "user": 0, "group": 3} + assert await store.consume_request(QuotaActor("p", actor.user, "other"), group_limit=3) == { + "day": "2026-11-17", "global": 4, "user": 1, "group": 1, + } + + +async def test_user_shared_across_groups_and_private_but_platforms_are_isolated(stores): + connect, _, _ = stores + store = await connect() + for group in ("g1", "g2", ""): + await store.consume_request(QuotaActor("p1", "u", group), user_limit=3) + private = QuotaActor("p1", "u") + with pytest.raises(QuotaExceededError) as error: + await store.consume_request(private, user_limit=3) + assert_exceeded(error.value, "user", 3, 3) + assert await store.quota_usage(private) == {"day": "2026-11-17", "global": 3, "user": 3, "group": None} + assert (await store.quota_usage(QuotaActor("p1", "u", "g1")))["group"] == 1 + assert await store.consume_request(QuotaActor("p2", "u", "g1"), user_limit=3) == { + "day": "2026-11-17", "global": 4, "user": 1, "group": 1, + } + + +@pytest.mark.parametrize("unlimited", [False, True]) +async def test_fixed_global_hundred_and_default_group_hundred_boundaries(stores, unlimited): + connect, _, _ = stores + store = await connect() + assert GLOBAL_DAILY_LIMIT == 100 + for index in range(100): + actor = QuotaActor("p", "one-user" if unlimited else str(index // 20), "g") + result = await store.consume_request(actor, user_limit=0 if unlimited else 20, + group_limit=0 if unlimited else 100) + assert result["global"] == 100 and result["group"] == 100 + assert result["user"] == (100 if unlimited else 20) + rejected = QuotaActor("new-platform", "new-user", "new-group") + with pytest.raises(QuotaExceededError) as error: + await store.consume_request(rejected, user_limit=0, group_limit=0) + assert_exceeded(error.value, "global", 100, 100) + assert await store.quota_usage(rejected) == {"day": "2026-11-17", "global": 100, "user": 0, "group": 0} + with pytest.raises(QuotaExceededError) as error: + await store.consume_request() + assert_exceeded(error.value, "global", 100, 100) + + +@pytest.mark.parametrize("scope", ["user", "group"]) +async def test_lowered_limits_apply_to_already_recorded_unlimited_usage(stores, scope): + connect, _, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "g") + for _ in range(4): + await store.consume_request(actor, user_limit=0, group_limit=0) + limits = {"user_limit": 0, "group_limit": 0, f"{scope}_limit": 3} + with pytest.raises(QuotaExceededError) as error: + await store.consume_request(actor, **limits) + assert_exceeded(error.value, scope, 3, 4) + assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 4, "user": 4, "group": 4} + limits[f"{scope}_limit"] = 5 + assert await store.consume_request(actor, **limits) == { + "day": "2026-11-17", "global": 5, "user": 5, "group": 5, + } + + +@pytest.mark.parametrize(("scope", "limit", "kwargs"), [ + ("global", 100, {"user_limit": 0, "group_limit": 0}), + ("user", 20, {"user_limit": 20, "group_limit": 0}), + ("group", 30, {"user_limit": 0, "group_limit": 30}), +]) +async def test_multiple_connections_cannot_overdraw_any_bucket(stores, scope, limit, kwargs): + connect, _, spawn = stores + connections = [await connect() for _ in range(4)] + actor = QuotaActor("p", "u", "g") + tasks = [spawn(connections[index % 4].consume_request(actor, **kwargs)) + for index in range(limit + 20)] + results = await asyncio.gather(*tasks, return_exceptions=True) + successes = [result for result in results if isinstance(result, dict)] + failures = [result for result in results if isinstance(result, BaseException)] + assert len(successes) == limit + assert len(failures) == 20 + assert sorted(result["global"] for result in successes) == list(range(1, limit + 1)) + for error in failures: + assert isinstance(error, QuotaExceededError) + assert_exceeded(error, scope, limit, limit) + for store in connections: + assert await store.quota_usage(actor) == { + "day": "2026-11-17", "global": limit, "user": limit, "group": limit, + } + + +async def test_beijing_midnight_resets_all_daily_views_without_erasing_prior_day(stores): + connect, clock, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "g") + await store.consume_request(actor, user_limit=1) + with pytest.raises(QuotaExceededError): + await store.consume_request(actor, user_limit=1) + clock.now += 1 # Beijing 23:59:59 -> 00:00:00 + assert await store.quota_usage(actor) == {"day": "2026-11-18", "global": 0, "user": 0, "group": 0} + assert await store.consume_request(actor, user_limit=1) == { + "day": "2026-11-18", "global": 1, "user": 1, "group": 1, + } + clock.now -= 1 + assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 1, "user": 1, "group": 1} + + +async def test_date_is_evaluated_after_obtaining_cross_connection_write_lock(stores): + connect, clock, spawn = stores + locker, contender = await connect(), await connect() + actor = QuotaActor("p", "u", "g") + loop = asyncio.get_running_loop() + begin_started = asyncio.Event() + + def trace(sql): + if sql == "BEGIN IMMEDIATE": + loop.call_soon_threadsafe(begin_started.set) + + await contender._connection().set_trace_callback(trace) + async with locker._connection().execute("BEGIN IMMEDIATE"): + pass + try: + task = spawn(contender.consume_request(actor)) + await asyncio.wait_for(begin_started.wait(), 2) + clock.now += 1 + finally: + await locker._connection().rollback() + assert (await asyncio.wait_for(task, 2))["day"] == "2026-11-18" + clock.now -= 1 + assert (await locker.quota_usage())["global"] == 0 + + +async def test_reload_cache_clear_prune_and_binding_namespace_changes_keep_usage(stores): + connect, _, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "g") + expected = await store.consume_request(actor) + original = Binding("source:old-credentials", "001", "Synthetic") + await store.set_binding("p", "u", original) + await store.put_cache("source:old-credentials", {}, 10) + await store.clear_cache() + await store.prune_cache(max_entries=0, max_age_seconds=0) + assert await store.quota_usage(actor) == expected + assert await store.get_binding("p", "u") == original + await store.close() + reopened = await connect() + assert await reopened.quota_usage(actor) == expected + await reopened.set_binding("p", "u", Binding("source:new-credentials", "002", "Other")) + await reopened.put_cache("source:new-credentials", [], 10) + assert await reopened.quota_usage(actor) == expected + assert (await reopened.consume_request(actor))["global"] == 2 + + +async def test_sql_error_after_partial_bucket_updates_rolls_back_everything(stores): + connect, _, _ = stores + store, observer = await connect(), await connect() + actor = QuotaActor("p", "u", "g") + db = store._connection() + async with db.execute( + "CREATE TEMP TRIGGER reject_group BEFORE INSERT ON request_quotas " + "WHEN NEW.scope = 'group' BEGIN SELECT RAISE(ABORT, 'synthetic quota failure'); END" + ): + pass + with pytest.raises(sqlite3.IntegrityError, match="synthetic quota failure"): + await store.consume_request(actor) + assert not db.in_transaction + for connection in (store, observer): + assert await connection.quota_usage(actor) == { + "day": "2026-11-17", "global": 0, "user": 0, "group": 0, + } + async with db.execute("DROP TRIGGER reject_group"): + pass + assert (await store.consume_request(actor))["global"] == 1 + + +async def test_cancellation_before_commit_rolls_back_and_finishes_cleanup(stores, monkeypatch): + connect, _, spawn = stores + store, observer = await connect(), await connect() + actor = QuotaActor("p", "u", "g") + db = store._connection() + commit_started, rollback_started, allow_rollback = asyncio.Event(), asyncio.Event(), asyncio.Event() + original_rollback = db.rollback + + async def paused_commit(): + commit_started.set() + await asyncio.Event().wait() + + async def paused_rollback(): + rollback_started.set() + await allow_rollback.wait() + await original_rollback() + + with monkeypatch.context() as patch: + patch.setattr(db, "commit", paused_commit) + patch.setattr(db, "rollback", paused_rollback) + task = spawn(store.consume_request(actor)) + try: + await asyncio.wait_for(commit_started.wait(), 2) + task.cancel() + await asyncio.wait_for(rollback_started.wait(), 2) + task.cancel() # repeated cancellation must not abandon rollback + finally: + allow_rollback.set() + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(task, 2) + assert not db.in_transaction + assert await observer.quota_usage(actor) == {"day": "2026-11-17", "global": 0, "user": 0, "group": 0} + assert (await store.consume_request(actor))["global"] == 1 + + +async def test_cancelled_queued_begin_cannot_leave_an_open_transaction(stores): + connect, _, spawn = stores + locker, contender = await connect(), await connect() + loop = asyncio.get_running_loop() + begin_started = asyncio.Event() + + def trace(sql): + if sql == "BEGIN IMMEDIATE": + loop.call_soon_threadsafe(begin_started.set) + + await contender._connection().set_trace_callback(trace) + async with locker._connection().execute("BEGIN IMMEDIATE"): + pass + try: + task = spawn(contender.consume_request(QuotaActor("p", "u", "g"))) + await asyncio.wait_for(begin_started.wait(), 2) + task.cancel() + finally: + await locker._connection().rollback() + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(task, 2) + assert not contender._connection().in_transaction + assert (await locker.quota_usage())["global"] == 0 + assert (await contender.consume_request())["global"] == 1 + + +@pytest.mark.parametrize("invalid", [-1, 1.5, True, "20"]) +async def test_invalid_limits_are_rejected_without_charging(stores, invalid): + connect, _, _ = stores + store = await connect() + for field in ("user_limit", "group_limit"): + with pytest.raises(ValueError): + await store.consume_request(QuotaActor("p", "u", "g"), **{field: invalid}) + assert (await store.quota_usage())["global"] == 0 + + +@pytest.mark.parametrize("reject_at", [1, 2]) +async def test_changed_admission_rolls_back_all_buckets(stores, reject_at): + from quota import AdmissionDeferred + connect, _, _ = stores + store, observer = await connect(), await connect() + actor = QuotaActor("p", "u", "g") + calls = 0 + def ready(): + nonlocal calls + calls += 1 + return calls != reject_at + with pytest.raises(AdmissionDeferred): + await store.consume_request(actor, ready=ready) + assert not store._connection().in_transaction + assert (await observer.quota_usage(actor))["global"] == 0 + assert (await store.consume_request(actor))["global"] == 1 + + +async def test_midnight_during_reservation_rolls_back_before_retry(stores): + from quota import AdmissionDeferred + connect, clock, _ = stores + store = await connect() + actor = QuotaActor("p", "u", "g") + original = store._quota_usage + async def cross_midnight(*args): + usage = await original(*args) + clock.now += 1 + return usage + store._quota_usage = cross_midnight + with pytest.raises(AdmissionDeferred): + await store.consume_request(actor) + store._quota_usage = original + assert (await store.consume_request(actor))["day"] == "2026-11-18" + clock.now -= 1 + assert (await store.quota_usage(actor))["global"] == 0 diff --git a/tests/test_render.py b/tests/test_render.py new file mode 100644 index 0000000..453c538 --- /dev/null +++ b/tests/test_render.py @@ -0,0 +1,256 @@ +"""Presentation/security behavior; fixed synthetic values, no browser or API.""" + +from copy import deepcopy +from datetime import datetime, timezone +from html.parser import HTMLParser +import re + +from jinja2 import Environment +from markupsafe import Markup +import pytest + +from render import Renderer + + +class VisibleHTML(HTMLParser): + def __init__(self, html): + super().__init__(convert_charrefs=True) + self.in_body = False + self.parts = [] + self.tags = [] + self.feed(html) + + def handle_starttag(self, tag, attrs): + self.tags.append((tag, dict(attrs))) + if tag == "body": + self.in_body = True + + def handle_endtag(self, tag): + if tag == "body": + self.in_body = False + + def handle_data(self, data): + if self.in_body: + self.parts.append(data) + + @property + def text(self): + return " ".join(self.parts) + + +def compact(value): + return re.sub(r"\s+", "", value) + + +@pytest.fixture +def view(): + return { + "kind": "overview", + "player": {"id": "00076561198012345678", "name": "合成样本玩家"}, + "metrics": [ + {"label": "近期胜率", "value": 62.5, "format": "percent"}, + {"label": "实际样本", "value": 8, "format": "integer", "unit": "场"}, + {"label": "单位交换比", "value": 1.234}, + {"label": "价值交换比", "value": 2.789}, + ], + "scope": "已取得的 8 场排位样本 · 非完整历史", + "fetched_at": "2026-11-17T02:30:00Z", + "source_updated_at": "2026-11-17T02:20:00+00:00", + "source_url": "https://example.invalid/player/preview?scope=recent&n=8", + "synthetic": True, + } + + +@pytest.mark.parametrize("theme", ["dark", "light"]) +def test_identity_scope_precision_and_same_text_values(view, theme): + renderer = Renderer(theme=theme) + html = renderer.template(view) + visible = VisibleHTML(html).text + text = renderer.text(view) + for value in [ + "00076561198012345678", "合成样本玩家", view["scope"], + "62.50%", "8场", "1.23", "2.79", "2026-11-17 10:30 CST", + "2026-11-17 10:20 CST", "合成样本", view["source_url"], + ]: + assert compact(value) in compact(visible) + assert compact(value) in compact(text) + assert f'data-theme="{theme}"' in html + assert visible.index("合成样本玩家") < visible.index(view["scope"]) < visible.index("近期胜率") + + +@pytest.mark.parametrize("kind", ["overview", "recent", "match"]) +def test_external_text_is_escaped_in_every_card(view, kind): + attack = ' & "玩家"' + view.update( + kind=kind, title=attack, scope=attack, notes=[attack], + player={"id": attack, "name": Markup(attack)}, + metrics=[{"label": attack, "value": attack, "unit": attack, "note": attack}], + rows=[{"id": attack, "map_name": attack, "mode": attack}], + match={"id": attack, "map_name": attack, "winner": attack}, + teams=[{"name": attack, "players": [{"id": attack, "name": attack}]}], + common_units=[{"name": attack}], + ) + renderer = Renderer() + html = renderer.template(view) + visible = VisibleHTML(html) + assert "<img" in html + assert not any(tag in {"img", "script", "iframe"} for tag, _ in visible.tags) + assert attack in visible.text + assert attack in renderer.text(view) + + +def test_jinja_literal_nickname_survives_fixed_astrbot_wrapper(view): + nickname = '{{7*7}} {% if true %}字面昵称{% endif %} {#注释也保留#} <玩家>&' + view["player"]["name"] = nickname + renderer = Renderer() + html = renderer.template(view) + wrapped = Environment(autoescape=True).from_string("{{ body | safe }}").render(body=html) + assert nickname in VisibleHTML(wrapped).text + assert nickname in renderer.text(view) + assert "<玩家>" not in wrapped + assert "{{7*7}}" in wrapped + + +@pytest.mark.parametrize("url", [ + "javascript:alert(1)", "data:text/html,test", "file:///C:/secret", "//example.invalid", + "https://name:password@example.invalid/", "https://example.invalid\n/evil", + "https:\\example.invalid", "https://", "https://example.invalid:99999/", "https://[broken/", +]) +def test_unsafe_source_urls_are_omitted_everywhere(view, url): + view.update(source_url=url, player={"id": "id", "name": "name", "source_url": url}) + view["kind"] = "recent" + view["rows"] = [{"id": "match", "source_url": url}] + renderer = Renderer() + assert not any("href" in attrs for _, attrs in VisibleHTML(renderer.template(view)).tags) + assert url not in renderer.text(view) + assert "数据来源:暂无" in renderer.text(view) + + +def test_safe_http_links_are_escaped_not_loaded(view): + renderer = Renderer() + html = renderer.template(view) + parsed = VisibleHTML(html) + assert ("a", {"href": view["source_url"], "rel": "noreferrer noopener"}) in parsed.tags + assert "&n=8" in html + assert not any(tag in {"img", "iframe", "script", "link"} for tag, _ in parsed.tags) + assert "@import" not in html and "url(" not in html + + +@pytest.mark.parametrize("value", [None, "", " ", float("nan"), float("inf"), True]) +def test_missing_metric_is_unknown_without_fake_zero_or_unit(view, value): + view["metrics"] = [{"label": "ELO", "value": value, "unit": "分"}] + renderer = Renderer() + assert "ELO:暂无" in renderer.text(view) + assert "暂无分" not in compact(VisibleHTML(renderer.template(view)).text) + assert "0.00" not in renderer.text(view) + + +def test_real_zero_and_unknown_stay_distinct(view): + view.update(kind="recent", rows=[{ + "id": "zero", "kills": 0, "losses": None, "destroyed_value": 0, + "lost_value": None, "unit_exchange": None, "value_exchange": None, + "duration_seconds": 0, "elo_delta": 0, + }]) + text = Renderer().text(view) + assert "摧毁单位:0 个" in text + assert "损失单位:暂无" in text + assert "摧毁价值:0.00" in text + assert "损失价值:暂无" in text + assert "价值交换比:暂无" in text + assert "胜负暂无" in text + assert "时长:0分00秒" in text + assert "ELO 变化:+0.00" in text + + +def test_exchange_values_are_separate_and_not_recalculated(view): + view.update(kind="recent", rows=[{ + "id": "ratios", "kills": 8, "losses": 2, "unit_exchange": 4, + "destroyed_value": 2500.5, "lost_value": 2000.75, "value_exchange": 1.249, + }]) + renderer = Renderer() + html_text = compact(VisibleHTML(renderer.template(view)).text) + text = renderer.text(view) + for expected in ["摧毁单位:8 个", "损失单位:2 个", "单位交换比:4.00", + "摧毁价值:2500.50", "损失价值:2000.75", "价值交换比:1.25"]: + assert expected in text + assert compact(expected.replace(":", "")) in html_text + + +def test_stale_and_absent_timestamps_are_visible(view): + view.update(stale=True, fetched_at=None, source_updated_at="2026-11-17T02:20:00") + renderer = Renderer() + for output in [renderer.text(view), VisibleHTML(renderer.template(view)).text]: + assert "旧缓存" in output + assert "抓取时间:暂无" in compact(output) + assert "来源更新:暂无" in compact(output) + + +def test_timezone_aware_datetime_conversion(view): + view["fetched_at"] = datetime(2026, 11, 17, 2, 30, tzinfo=timezone.utc) + assert "2026-11-16 21:30 EST" in Renderer(timezone="America/New_York").text(view) + + +def test_recent_pagination_preserves_every_row_scope_and_input(view): + view.update(kind="recent", rows=[{"id": f"match-{i:03}"} for i in range(20)]) + before = deepcopy(view) + renderer = Renderer() + pages = renderer.views(view) + assert [len(page["rows"]) for page in pages] == [5, 5, 5, 5] + assert [row["id"] for page in pages for row in page["rows"]] == [row["id"] for row in view["rows"]] + assert "第 2/4 页 · 本页 6–10 场 / 共 20 场" in renderer.text(pages[1]) + assert "match-005" in renderer.text(pages[1]) + assert "match-000" not in renderer.text(pages[1]) + assert all(page["scope"] == view["scope"] and page["player"] == view["player"] for page in pages) + pages[0]["rows"][0]["id"] = "changed" + assert view == before + + +@pytest.mark.parametrize("kind,empty_label", [ + ("overview", "统计指标:暂无"), ("recent", "近期对局:暂无"), ("match", "分队与玩家:暂无"), +]) +def test_empty_card_has_explicit_unknown_state(kind, empty_label): + renderer = Renderer() + view = {"kind": kind} + assert empty_label in renderer.text(view) + assert compact(empty_label) in compact(VisibleHTML(renderer.template(view)).text) + assert len(renderer.views(view)) == 1 + + +def test_variable_team_sizes_keep_all_players_and_no_placeholder_opponents(view): + view.update(kind="match", match={"id": "000123", "map_name": "合成地图", "winner": "蓝队"}, teams=[ + {"name": "蓝队", "outcome": "win", "players": [{"id": f"a{i}", "name": f"蓝方{i}"} for i in range(3)]}, + {"name": "红队", "outcome": "loss", "players": [{"id": "b", "name": "红方0"}]}, + {"name": "未分配", "players": []}, + ]) + renderer = Renderer() + html = renderer.template(view) + assert html.count('class="participant"') == 4 + for expected in ["3 人", "1 人", "0 人", "队员:暂无", "蓝方2", "红方0", "000123"]: + assert compact(expected) in compact(VisibleHTML(html).text) + assert expected in renderer.text(view) + + +def test_long_nickname_is_not_truncated(view): + name = "中文非常长的合成昵称MixedNickname_" * 20 + view["player"]["name"] = name + renderer = Renderer() + assert name in VisibleHTML(renderer.template(view)).text + assert name in renderer.text(view) + + +def test_invalid_count_does_not_silently_round(view): + view["metrics"] = [{"label": "实际样本", "value": 1.5, "format": "integer", "unit": "场"}] + assert "实际样本:暂无" in Renderer().text(view) + + +@pytest.mark.parametrize("size", [0, 6, True, 2.5]) +def test_page_size_rejects_unbounded_cards(view, size): + with pytest.raises(ValueError): + Renderer().views(view, page_size=size) + + +def test_unknown_theme_and_kind_are_configuration_errors(): + with pytest.raises(ValueError): + Renderer(theme="other") + with pytest.raises(ValueError): + Renderer().template({"kind": "other"}) diff --git a/tests/test_service.py b/tests/test_service.py new file mode 100644 index 0000000..6644ceb --- /dev/null +++ b/tests/test_service.py @@ -0,0 +1,472 @@ +"""Synthetic integration scenarios against the real service and SQLite store. + +Network completions use explicit events, never timing-dependent sleeps. The +isolated package permits relative imports without importing AstrBot globally. +""" + +import asyncio +import importlib +from pathlib import Path +import re +import sys +from types import ModuleType, SimpleNamespace +from datetime import datetime, timezone +from unittest.mock import AsyncMock, call + +import httpx +import pytest + + +ROOT = Path(__file__).resolve().parents[1] +NOW = datetime(2026, 11, 17, tzinfo=timezone.utc) + + +@pytest.fixture +def modules(monkeypatch): + name = "_ba_stats_service_contract" + package = ModuleType(name) + package.__path__ = [str(ROOT)] + monkeypatch.setitem(sys.modules, name, package) + try: + yield SimpleNamespace(**{ + part: importlib.import_module(f"{name}.{part}") + for part in ("service", "models", "commands", "storage", "settings", "client") + }) + finally: + for key in tuple(sys.modules): + if key.startswith(name + "."): + sys.modules.pop(key, None) + + +@pytest.fixture +async def h(modules, tmp_path): + m = modules.models + + def result(data, **kwargs): + return m.FetchResult(data, NOW, **kwargs) + + player = m.Player("001", "Synthetic Player", source_url="https://example.invalid/players/001") + client = SimpleNamespace( + namespace="batrace:synthetic", player=AsyncMock(return_value=result(player)), + search=AsyncMock(return_value=result([player])), recent=AsyncMock(return_value=result([])), + match=AsyncMock(), + ) + storage = modules.storage.Storage(tmp_path / "service-data") + await storage.open() + settings = modules.settings.Settings(cooldown_seconds=0) + service = modules.service.StatsService(client, storage, settings) + caller = modules.service.Caller("onebot:test", "group:one", "10001") + tasks = [] + + async def run(text, who=None): + return await service.execute(modules.commands.parse_command(text), who or caller) + + def spawn(coro): + task = asyncio.create_task(coro) + tasks.append(task) + return task + + try: + yield SimpleNamespace( + m=m, modules=modules, client=client, storage=storage, service=service, + caller=caller, run=run, result=result, player=player, spawn=spawn, + Binding=modules.storage.Binding, + ) + finally: + for task in tasks: + if not task.done(): + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + service.close() + await storage.close() + + +def select_command(response): + match = re.search(r"/ba select ([^\s]+) ([0-9]+)", response.text) + assert match, response.text + return f"select {match[1]} {match[2]}" + + +async def seed(h, player_id="old", namespace=None): + binding = h.Binding(namespace or h.client.namespace, player_id, "Original", "https://example.invalid/original") + await h.storage.set_binding(h.caller.platform, h.caller.user, binding) + return binding + + +async def binding(h): + return await h.storage.get_binding(h.caller.platform, h.caller.user) + + +async def test_help_binding_unbind_work_with_real_unconfigured_client(h): + def forbidden_network(request): + raise AssertionError("Local commands must not contact the upstream") + + c = h.modules.client + async with httpx.AsyncClient(transport=httpx.MockTransport(forbidden_network)) as http: + real_client = c.BatraceClient(c.ClientConfig(), storage=h.storage, http_client=http) + h.service.client = real_client + try: + await seed(h, namespace=real_client.namespace) + assert "/ba help" in (await h.run("help")).text + assert "old" in (await h.run("binding")).text + assert "解除" in (await h.run("unbind")).text + assert await binding(h) is None + with pytest.raises(c.NotConfiguredError, match="未配置"): + await h.run("search Synthetic") + assert real_client.status()["requests"] == 0 + finally: + await real_client.close() + + +async def test_single_bind_requires_one_choice_and_forces_identity_revalidation(h): + old = await seed(h) + renamed = h.m.Player("001", "Renamed", source_url=h.player.source_url) + h.client.player.side_effect = [h.result(h.player), h.result(renamed)] + offered = await h.run("bind stb:001") + assert "选择后绑定" in offered.text + assert h.player.source_url in offered.text + assert await binding(h) == old + command = select_command(offered) + response = await h.run(command) + assert "已绑定默认账号:Renamed" in response.text + assert (await binding(h)).player_id == "001" + assert (await binding(h)).display_name == "Renamed" + assert (await binding(h)).namespace == h.client.namespace + assert h.client.player.await_args_list == [call("001"), call("001", force=True)] + with pytest.raises(ValueError, match="过期"): + await h.run(command) + assert h.client.player.await_count == 2 + + +@pytest.mark.parametrize("failure", ["wrong_id", "stale", "upstream"]) +async def test_failed_final_identity_check_preserves_original_binding(h, failure): + old = await seed(h) + offered = await h.run("bind stb:001") + if failure == "upstream": + h.client.player.side_effect = h.modules.client.AuthenticationError("鉴权失败") + expected = h.modules.client.AuthenticationError + else: + player = h.m.Player("wrong" if failure == "wrong_id" else "001", "Synthetic") + h.client.player.return_value = h.result(player, stale=failure == "stale") + expected = ValueError + with pytest.raises(expected): + await h.run(select_command(offered)) + assert await binding(h) == old + with pytest.raises(ValueError, match="过期"): + await h.run(select_command(offered)) + + +async def test_read_only_search_and_select_never_change_binding(h, monkeypatch): + old = await seed(h) + write = AsyncMock(wraps=h.storage.set_binding) + monkeypatch.setattr(h.storage, "set_binding", write) + offered = await h.run("search Synthetic Player") + assert "请选择要查询" in offered.text + assert await binding(h) == old + response = await h.run(select_command(offered)) + assert response.view["kind"] == "overview" + assert response.view["player"]["id"] == "001" + assert await binding(h) == old + write.assert_not_awaited() + assert h.client.player.await_args_list == [call("001")] + h.client.recent.assert_awaited_once_with("001", h.service.settings.max_limit) + + +async def test_late_search_cannot_publish_over_newer_candidates(h): + started, release = asyncio.Event(), asyncio.Event() + newer = h.m.Player("002", "New", source_url="https://example.invalid/players/002") + + async def search(query): + if query == "Old": + started.set() + await release.wait() + return h.result([h.player]) + return h.result([newer]) + + h.client.search.side_effect = search + old_task = h.spawn(h.run("search Old")) + await asyncio.wait_for(started.wait(), 2) + current = await h.run("search New") + release.set() + assert "覆盖" in (await old_task).text + h.client.player.return_value = h.result(newer) + response = await h.run(select_command(current)) + assert response.view["player"]["id"] == "002" + + +async def test_new_operation_during_selected_revalidation_prevents_binding(h): + old = await seed(h) + offered = await h.run("bind stb:001") + started, release = asyncio.Event(), asyncio.Event() + + async def revalidate(player_id, *, force=False): + assert force + started.set() + await release.wait() + return h.result(h.player) + + h.client.player.side_effect = revalidate + task = h.spawn(h.run(select_command(offered))) + await asyncio.wait_for(started.wait(), 2) + await h.run("help") + release.set() + assert "覆盖" in (await task).text + assert await binding(h) == old + + +async def test_cross_group_unbind_wins_over_older_selected_revalidation(h): + await seed(h) + offered = await h.run("bind stb:001") + started, release = asyncio.Event(), asyncio.Event() + + async def revalidate(player_id, *, force=False): + started.set() + await release.wait() + return h.result(h.player) + + h.client.player.side_effect = revalidate + task = h.spawn(h.run(select_command(offered))) + await asyncio.wait_for(started.wait(), 2) + other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user) + assert "解除" in (await h.run("unbind", other_group)).text + release.set() + assert "覆盖" in (await task).text + assert await binding(h) is None + + +async def test_cross_group_unbind_serializes_with_already_started_binding_write(h, monkeypatch): + await seed(h) + offered = await h.run("bind stb:001") + entered, release = asyncio.Event(), asyncio.Event() + original_set = h.storage.set_binding + + async def slow_set(*args): + entered.set() + await release.wait() + await original_set(*args) + + monkeypatch.setattr(h.storage, "set_binding", slow_set) + selecting = h.spawn(h.run(select_command(offered))) + await asyncio.wait_for(entered.wait(), 2) + other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user) + unbinding = h.spawn(h.run("unbind", other_group)) + await asyncio.sleep(0) # let the unbind enter the service's mutation lock + assert not unbinding.done() + release.set() + await asyncio.gather(selecting, unbinding) + assert await binding(h) is None + + +async def test_newer_cross_group_bind_cannot_be_overwritten_by_older_selection(h): + first = await h.run("bind stb:001") + second_player = h.m.Player("002", "Second", source_url="https://example.invalid/players/002") + h.client.player.return_value = h.result(second_player) + other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user) + second = await h.run("bind stb:002", other_group) + started, release = asyncio.Event(), asyncio.Event() + + async def revalidate(player_id, *, force=False): + if player_id == "001": + started.set() + await release.wait() + return h.result(h.player) + return h.result(second_player) + + h.client.player.side_effect = revalidate + older = h.spawn(h.run(select_command(first))) + await asyncio.wait_for(started.wait(), 2) + assert "已绑定" in (await h.run(select_command(second), other_group)).text + release.set() + assert "覆盖" in (await older).text + assert (await binding(h)).player_id == "002" + + +@pytest.mark.parametrize("target", ["me", "mention"]) +async def test_other_namespace_binding_is_rejected_before_upstream_query(h, target): + old = await seed(h, namespace="batrace:other-source") + request = h.modules.commands.Request("stats", h.modules.commands.Target(target, h.caller.user)) + with pytest.raises(ValueError, match="数据源.*不一致"): + await h.service.execute(request, h.caller) + h.client.player.assert_not_awaited() + h.client.recent.assert_not_awaited() + assert await binding(h) == old + + +async def test_last_skips_unrecorded_details_and_returns_next_available_match(h): + person = h.m.Participant("001", "Synthetic") + newest = h.m.Match("new", players=[person]) + available = h.m.Match("old", players=[person], complete=True) + h.client.recent.return_value = h.result([newest, available]) + h.client.match.side_effect = [h.modules.client.NoDataError("暂无收录"), h.result(available)] + response = await h.run("last stb:001") + assert response.view["match"]["id"] == "old" + assert h.client.match.await_args_list == [call("new"), call("old")] + assert response.view["player"]["id"] == "001" + + +async def test_last_does_not_describe_authentication_failure_as_missing_match(h): + h.client.recent.return_value = h.result([ + h.m.Match("new", players=[h.m.Participant("001", "Synthetic")]) + ]) + h.client.match.side_effect = h.modules.client.AuthenticationError("鉴权失败") + with pytest.raises(h.modules.client.AuthenticationError, match="鉴权失败"): + await h.run("last stb:001") + h.client.match.assert_awaited_once_with("new") + + +@pytest.mark.parametrize("action", ["stats", "recent", "last"]) +async def test_player_reports_reject_nonempty_foreign_rosters(h, action): + h.client.recent.return_value = h.result([ + h.m.Match("wrong", players=[h.m.Participant("999", "Other")]), + h.m.Match("valid", players=[h.m.Participant("001", "Synthetic")]), + ]) + with pytest.raises(h.modules.client.IdentityMismatchError, match="未参与"): + await h.run(f"{action} stb:001") + h.client.match.assert_not_awaited() + + +@pytest.mark.parametrize("detail_player_id", ["999", None, "001"]) +async def test_last_validates_real_client_detail_without_skipping_identity_errors(h, monkeypatch, detail_player_id): + c = h.modules.client + seen = [] + + def handler(request): + seen.append((request.url.path, dict(request.url.params))) + if request.url.path == "/api/players/matches": + return httpx.Response(200, json={"matches": [ + {"matchId": mid, "data": {"StartTime": start, "Data": {"a": {"Id": "001"}}}} + for mid, start in [("new", 1700000100), ("old", 1700000000)] + ]}) + assert request.url.path == "/api/match" + return httpx.Response(200, json={"matchInfo": { + "Data": {} if detail_player_id is None else {"a": {"Id": detail_player_id}} + }}) + + async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http: + client = c.BatraceClient(c.ClientConfig( + enabled=True, client_id="synthetic-test-client", base_url="https://example.invalid", + request_interval=0, retries=0, + ), storage=h.storage, http_client=http) + monkeypatch.setattr(client, "player", AsyncMock(return_value=h.result(h.player))) + h.service.client = client + try: + if detail_player_id == "999": + with pytest.raises(c.IdentityMismatchError, match="未参与") as error: + await h.run("last stb:001") + assert error.value.code == "identity_mismatch" + else: + view = (await h.run("last stb:001")).view + assert view["match"]["id"] == "new" + assert view["player"]["id"] == "001" + if detail_player_id is None: + assert view["teams"] == [] + assert view["match"]["winner"] is None + assert seen == [ + ("/api/players/matches", {"stbid": "001", "limit": "20"}), + ("/api/match", {"matchid": "new"}), + ] + finally: + await client.close() + + +async def test_empty_recent_rosters_remain_unavailable_without_identity_errors(h): + h.client.recent.return_value = h.result([h.m.Match("empty")]) + assert (await h.run("recent stb:001")).view["rows"] == [] + assert "暂无可用单局战报" in (await h.run("last stb:001")).text + h.client.match.assert_not_awaited() + + +@pytest.mark.parametrize("theme", ["dark", "light"]) +async def test_units_use_stable_ids_and_distinct_labels_in_image_and_text(h, theme): + from html import escape + from render import Renderer + + records = [ + [{"Id": "u1"}, {"Id": "u2", "Name": "Tank "}, {"Id": "u3"}], + [{"Id": "u1", "Name": "Tank "}], + [{"Id": "u1", "Name": "Old Name"}], + ] + h.client.recent.return_value = h.result(h.m.parse_recent({"matches": [ + {"matchId": str(index), "data": {"StartTime": 1700000200 - index * 100, "Data": { + "a": {"Id": "001", "UnitData": {str(i): unit for i, unit in enumerate(units)}}, + "b": {"Id": "999", "UnitData": {"x": {"Id": "other", "Name": "Other player's unit"}}}, + }}} + for index, units in enumerate(records) + ]})) + view = (await h.run("stats stb:001")).view + assert view["common_units"] == [ + {"id": "u1", "name": "Tank (ID:u1)", "count": 3}, + {"id": "u2", "name": "Tank (ID:u2)", "count": 1}, + {"id": "u3", "name": "单位#u3", "count": 1}, + ] + renderer = Renderer(theme=theme) + html, text = renderer.template(view), renderer.text(view) + for unit in view["common_units"]: + assert f"{unit['name']}:{unit['count']} 个" in text + assert (f'{escape(unit["name"])}' + f'{unit["count"]} 个') in html + assert "Old Name" not in html + text + assert "Other player's unit" not in html + text + + +async def test_recent_view_distinguishes_zero_unknown_and_lossless_ratios(h): + people = [ + h.m.Participant("001", "S", kills=0, losses=2, destroyed_value=0, lost_value=100), + h.m.Participant("001", "S", kills=2, losses=0, destroyed_value=500, lost_value=0), + h.m.Participant("001", "S", kills=None, losses=2, destroyed_value=None, lost_value=0), + h.m.Participant("001", "S", kills=0, losses=0, destroyed_value=0, lost_value=0), + h.m.Participant("001", "S", kills=2, losses=1, destroyed_value=1000, lost_value=100), + ] + h.client.recent.return_value = h.result([ + h.m.Match(str(index), players=[person]) for index, person in enumerate(people) + ]) + rows = (await h.run("recent stb:001 --limit 5")).view["rows"] + assert [row["unit_exchange"] for row in rows] == [0, "无损失", None, None, 2] + assert [row["value_exchange"] for row in rows] == [0, "无损失", None, None, 10] + assert rows[2]["kills"] is None + assert all(row["outcome"] == "unknown" for row in rows) + + +async def test_overview_uses_actual_sample_and_known_outcomes_only(h): + h.client.recent.return_value = h.result([ + h.m.Match(str(index), players=[h.m.Participant("001", "S", outcome=outcome)]) + for index, outcome in enumerate(["win", "loss", "unknown"]) + ], stale=True) + view = (await h.run("stats stb:001")).view + metrics = {item["label"]: item for item in view["metrics"]} + assert metrics["样本场数"]["value"] == 3 + assert metrics["胜 / 负 / 未知"]["value"] == "1 / 1 / 1" + assert metrics["已知结果胜率"]["value"] == 50 + assert "2 场" in metrics["已知结果胜率"]["note"] + assert "实际 3 场" in view["scope"] + assert "非完整历史" in view["scope"] + assert view["stale"] is True + + +async def test_service_real_client_pipeline_sorts_and_deduplicates_recent_samples(h, monkeypatch): + c = h.modules.client + client = c.BatraceClient(c.ClientConfig( + enabled=True, client_id="synthetic-test-client", base_url="https://example.invalid", + request_interval=0, retries=0, + ), storage=h.storage) + + def raw(start): + return {"StartTime": start, "EndTime": start + 60, "TotalPlayTimeInSec": 60, + "Data": {"a": {"Id": "001", "Name": "Synthetic", "UnitData": {}}}} + + payload = {"matches": [ + {"matchId": "old", "data": raw(1700000000)}, + {"matchId": "new", "data": raw(1700000100)}, + {"matchId": "new", "data": raw(1700000100)}, + ]} + request = AsyncMock(return_value=payload) + monkeypatch.setattr(client, "_request", request) + monkeypatch.setattr(client, "player", AsyncMock(return_value=h.result(h.player))) + h.service.client = client + try: + view = (await h.run("recent stb:001 --limit 5")).view + assert [row["id"] for row in view["rows"]] == ["new", "old"] + assert "实际 2 场" in view["scope"] + request.assert_awaited_once_with("/api/players/matches", {"stbid": "001", "limit": 5}) + finally: + await client.close() diff --git a/tests/test_storage.py b/tests/test_storage.py new file mode 100644 index 0000000..35e35a5 --- /dev/null +++ b/tests/test_storage.py @@ -0,0 +1,264 @@ +"""Use temporary SQLite databases, never production player data.""" + +import asyncio + +import pytest + +from storage import Binding, Storage + + +@pytest.mark.parametrize("operation", ["set_binding", "unbind", "put_cache", "clear_cache", "prune_cache"]) +@pytest.mark.parametrize("failure", ["error", "cancel"]) +async def test_failed_writes_roll_back_before_connection_reuse(tmp_path, monkeypatch, operation, failure): + store, observer = Storage(tmp_path), Storage(tmp_path) + await store.open() + await observer.open() + original = Binding("source", "001", "Original") + try: + await store.set_binding("p", "u", original) + await store.put_cache("existing", {"version": 1}, 60) + mutations = { + "set_binding": lambda: store.set_binding("p", "u", Binding("source", "002", "Replacement")), + "unbind": lambda: store.unbind("p", "u"), + "put_cache": lambda: store.put_cache("existing", {"version": 2}, 60), + "clear_cache": store.clear_cache, + "prune_cache": lambda: store.prune_cache(max_entries=0), + } + committing = asyncio.Event() + + async def fail_commit(): + committing.set() + if failure == "cancel": + await asyncio.Event().wait() + raise RuntimeError("synthetic commit failure") + + with monkeypatch.context() as patch: + patch.setattr(store._connection(), "commit", fail_commit) + task = asyncio.create_task(mutations[operation]()) + try: + await asyncio.wait_for(committing.wait(), 2) + if failure == "cancel": + task.cancel() + expected = asyncio.CancelledError if failure == "cancel" else RuntimeError + with pytest.raises(expected): + await asyncio.wait_for(task, 2) + finally: + if not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + + assert not store._connection().in_transaction + # A later successful write must neither commit the failed mutation nor + # encounter a transaction left open by it. + assert (await store.consume_request())["global"] == 1 + await store.put_cache("recovery", {}, 60) + for connection in (store, observer): + assert await connection.get_binding("p", "u") == original + assert (await connection.get_cache("existing"))[0] == {"version": 1} + assert await connection.cache_count() == 2 + finally: + await observer.close() + await store.close() + + +class Clock: + now = 1000.0 + + def __call__(self): + return self.now + + +def test_bindings_survive_restart_and_isolate_platform_and_user(tmp_path): + async def run(): + first = Binding("batrace", "000765611980123456789012345", "Player 2", "https://example.invalid/player", 10.5) + other = Binding("batrace", "2", "Other", updated_at=11.0) + db = Storage(tmp_path / "plugin-data") + await db.open() + await db.open() + try: + await db.set_binding("onebot:a", "001", first) + await db.set_binding("onebot:b", "001", other) + await db.set_binding("onebot:a", "002", other) + assert await db.get_binding("onebot:a", "missing") is None + finally: + await db.close() + await db.close() + restarted = Storage(tmp_path / "plugin-data") + await restarted.open() + try: + assert await restarted.get_binding("onebot:a", "001") == first + assert isinstance((await restarted.get_binding("onebot:a", "001")).player_id, str) + assert await restarted.get_binding("onebot:b", "001") == other + assert await restarted.get_binding("onebot:a", "002") == other + renamed = Binding(first.namespace, first.player_id, "Renamed", first.source_url, 20.0) + await restarted.set_binding("onebot:a", "001", renamed) + assert await restarted.get_binding("onebot:a", "001") == renamed + assert await restarted.unbind("onebot:a", "001") + assert not await restarted.unbind("onebot:a", "001") + assert await restarted.get_binding("onebot:a", "001") is None + assert await restarted.get_binding("onebot:b", "001") == other + finally: + await restarted.close() + await restarted.open() + try: + assert await restarted.get_binding("onebot:a", "001") is None + finally: + await restarted.close() + asyncio.run(run()) + + +def test_json_cache_timing_expiry_stale_read_and_restart(tmp_path): + async def run(): + clock = Clock() + db = Storage(tmp_path, clock=clock) + await db.open() + payload = {"id": "000765611980123456789012345", "name": "玩家", "unknown": None, + "nested": [{"win": False, "elo": 1234.5}]} + try: + assert await db.get_cache("missing") is None + await db.put_cache("batrace:player:001:recent:5", payload, 10) + clock.now = 1010.0 + assert await db.get_cache("batrace:player:001:recent:5") == (payload, 1000.0, 1010.0) + await db.put_cache("batrace:player:001:recent:10", [], 0) + assert await db.cache_count() == 2 + finally: + await db.close() + await db.open() + try: + assert await db.get_cache("batrace:player:001:recent:5") == (payload, 1000.0, 1010.0) + await db.put_cache("batrace:player:001:recent:5", [{"updated": True}], 60) + assert await db.get_cache("batrace:player:001:recent:5") == ([{"updated": True}], 1010.0, 1070.0) + assert await db.cache_count() == 2 + finally: + await db.close() + asyncio.run(run()) + + +def test_cache_clear_and_age_capacity_pruning_preserve_binding(tmp_path): + async def run(): + clock = Clock() + db = Storage(tmp_path, clock=clock) + await db.open() + binding = Binding("batrace", "001", "Player", updated_at=1.0) + try: + await db.set_binding("p", "u", binding) + for index in range(4): + clock.now = 1000.0 + index * 10 + await db.put_cache(str(index), {"i": index}, 1) + assert await db.prune_cache(max_entries=2) == 2 + assert await db.get_cache("0") is None + assert await db.get_cache("1") is None + assert await db.get_cache("2") is not None + clock.now = 1040 + assert await db.prune_cache(max_age_seconds=15) == 1 + assert await db.get_cache("2") is None + assert await db.get_cache("3") is not None + assert await db.get_binding("p", "u") == binding + await db.clear_cache() + assert await db.cache_count() == 0 + assert await db.get_binding("p", "u") == binding + await db.put_cache("new", [], 30) + assert await db.prune_cache(max_entries=0) == 1 + assert await db.get_binding("p", "u") == binding + finally: + await db.close() + asyncio.run(run()) + + +def test_default_retention_prunes_old_stale_entries_on_write(tmp_path): + async def run(): + clock = Clock() + db = Storage(tmp_path, clock=clock) + await db.open() + try: + await db.put_cache("old", {}, 10) + clock.now += 604800 + await db.put_cache("new", [], 10) + assert await db.get_cache("old") is None + assert await db.cache_count() == 1 + finally: + await db.close() + asyncio.run(run()) + + +def test_configured_cache_bounds_apply_on_write_and_manual_prune(tmp_path): + async def run(): + clock = Clock() + db = Storage(tmp_path, max_entries=2, max_age_seconds=10, clock=clock) + await db.open() + try: + for index in range(3): + clock.now += 1 + await db.put_cache(str(index), {}, 1) + assert await db.get_cache("0") is None + assert await db.cache_count() == 2 + assert await db.prune_cache() == 0 + clock.now += 10 + assert await db.prune_cache() == 2 + finally: + await db.close() + asyncio.run(run()) + + +def test_configured_cache_capacity_can_exceed_one_thousand(tmp_path): + async def run(): + db = Storage(tmp_path, max_entries=1002) + await db.open() + try: + for index in range(1001): + await db.put_cache(str(index), [], 60) + assert await db.cache_count() == 1001 + assert await db.prune_cache() == 0 + assert await db.cache_count() == 1001 + finally: + await db.close() + asyncio.run(run()) + + +def test_concurrent_writes_and_cache_maintenance_do_not_affect_bindings(tmp_path): + async def run(): + db = Storage(tmp_path) + await db.open() + try: + await asyncio.gather(*( + db.set_binding("p", str(index), Binding("ns", str(index), str(index))) + for index in range(20) + ), *(db.put_cache(str(index), {"i": index}, 30) for index in range(20))) + await asyncio.gather(db.clear_cache(), db.set_binding("p", "new", Binding("ns", "001", "New"))) + assert await db.cache_count() == 0 + for index in range(20): + assert (await db.get_binding("p", str(index))).player_id == str(index) + assert (await db.get_binding("p", "new")).player_id == "001" + finally: + await db.close() + asyncio.run(run()) + + +@pytest.mark.parametrize("player_id", [123, 123.5, None, ""]) +def test_bindings_never_convert_numeric_ids_to_float_or_integer(player_id): + with pytest.raises(ValueError): + Binding("batrace", player_id, "Player") + + +def test_invalid_cache_parameters_and_closed_lifecycle(tmp_path): + async def run(): + db = Storage(tmp_path) + with pytest.raises(RuntimeError, match="尚未打开"): + await db.get_binding("p", "u") + await db.open() + try: + for ttl in [-1, float("nan"), float("inf")]: + with pytest.raises(ValueError): + await db.put_cache("bad", {}, ttl) + with pytest.raises(ValueError): + await db.put_cache("bad", "text", 1) + for kwargs in [{"max_entries": -1}, {"max_entries": 1.5}, + {"max_age_seconds": -1}, {"max_age_seconds": float("nan")}]: + with pytest.raises(ValueError): + await db.prune_cache(**kwargs) + assert await db.cache_count() == 0 + finally: + await db.close() + with pytest.raises(RuntimeError): + await db.cache_count() + asyncio.run(run()) diff --git a/tools/build_delivery.py b/tools/build_delivery.py new file mode 100644 index 0000000..2693ac0 --- /dev/null +++ b/tools/build_delivery.py @@ -0,0 +1,254 @@ +"""Build an install ZIP, Gemini copywriting ZIP, and one final delivery ZIP. + +Reads only repository sources and the session's reviewed previews. No runtime +database, configuration, cache, credentials or virtual environment is included. +""" +from __future__ import annotations + +import argparse +import ast +import csv +import hashlib +import io +import json +from pathlib import Path +import re +import zipfile + +import yaml + +ROOT = Path(__file__).resolve().parents[1] +VERSION = "0.1.0" +CHINESE = re.compile(r"[\u3400-\u9fff]") + + +def digest(data): + return hashlib.sha256(data).hexdigest() + + +def repository_files(): + root_names = {"README.md", "LICENSE", "metadata.yaml", "_conf_schema.json", + "requirements.txt", "requirements-dev.txt", "pytest.ini", ".gitignore", ".gitattributes", "logo.png"} + files = [] + for p in ROOT.rglob("*"): + if not p.is_file(): + continue + rel = p.relative_to(ROOT) + if "__pycache__" in rel.parts or ".pytest_cache" in rel.parts: + continue + if len(rel.parts) == 1 and (p.suffix == ".py" or p.name in root_names): + files.append(p) + elif rel.parts[0] in {"templates", "assets", "docs", "tests", "tools", ".github"} and p.suffix in {".py", ".html", ".md", ".json", ".png", ".txt", ".yml", ".yaml"}: + files.append(p) + return sorted(files) + + +def archive(entries): + stream = io.BytesIO() + with zipfile.ZipFile(stream, "w", compression=zipfile.ZIP_DEFLATED) as z: + for name, data in sorted(entries.items()): + # Stable ZIP metadata keeps an unchanged export reproducible. + info = zipfile.ZipInfo(name, date_time=(2026, 11, 17, 0, 0, 0)) + info.compress_type = zipfile.ZIP_DEFLATED + info.external_attr = 0o644 << 16 + z.writestr(info, data) + data = stream.getvalue() + with zipfile.ZipFile(io.BytesIO(data)) as z: + assert z.testzip() is None + assert all(not name.startswith("/") and ".." not in Path(name).parts for name in z.namelist()) + return data + + +def text_catalog(files): + result = [] + for path in files: + rel = path.relative_to(ROOT).as_posix() + if path.parent != ROOT or path.suffix != ".py": + continue + source = path.read_text(encoding="utf-8") + tree = ast.parse(source) + parents = {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)} + docstrings = set() + for node in ast.walk(tree): + if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) and node.body: + first = node.body[0] + if isinstance(first, ast.Expr) and isinstance(first.value, ast.Constant) and isinstance(first.value.value, str): + docstrings.add(first.value) + for node in ast.walk(tree): + if isinstance(node, ast.JoinedStr): + text = "".join(v.value if isinstance(v, ast.Constant) else "{" + ast.unparse(v.value) + + ("!" + chr(v.conversion) if v.conversion != -1 else "") + + (":" + "".join(x.value if isinstance(x, ast.Constant) else "{" + ast.unparse(x.value) + "}" + for x in v.format_spec.values) if v.format_spec else "") + "}" + for v in node.values) + kind = "格式化提示(占位符必须原样保留)" + elif isinstance(node, ast.Constant) and isinstance(node.value, str) and node not in docstrings: + if isinstance(parents.get(node), ast.JoinedStr): + continue + text, kind = node.value, "文字常量(请结合上下文确认是否用户可见)" + else: + continue + ancestors, current = [], node + error_text = False + while current in parents: + current = parents[current] + if isinstance(current, ast.Raise): + error_text = True + if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): + ancestors.append(current.name) + if not CHINESE.search(text) and not error_text: + continue + line = node.lineno + result.append(dict(id=f"{rel}:{line}:{len(result)+1}", file=rel, line=line, + context=" / ".join(reversed(ancestors)), kind=kind, original=text, + source_literal=ast.get_source_segment(source, node), suggestion="")) + schema = json.loads((ROOT / "_conf_schema.json").read_text(encoding="utf-8")) + def walk(value, pointer=""): + if isinstance(value, dict): + for key, child in value.items(): + target = pointer + "/" + key + if key in {"description", "hint", "labels", "subtitles"}: + values = child if isinstance(child, list) else [child] + for i, text in enumerate(values): + result.append(dict(id="schema:" + target + (f"/{i}" if isinstance(child, list) else ""), + file="_conf_schema.json", line=None, context=pointer, kind="配置界面文案", + original=text, suggestion="")) + else: + walk(child, target) + walk(schema) + for number, line in enumerate((ROOT / "metadata.yaml").read_text(encoding="utf-8").splitlines(), 1): + if line.startswith(("display_name:", "desc:")): + key, text = line.split(":", 1) + result.append(dict(id="metadata:" + key, file="metadata.yaml", line=number, + context=key, kind="插件展示信息(名称需用户确认)", original=yaml.safe_load(text), suggestion="")) + # Keep complete Jinja/HTML lines so translators see tags and placeholders. + for path in sorted((ROOT / "templates").glob("*.html")): + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + if CHINESE.search(line): + result.append(dict(id=f"template:{path.name}:{number}", file=path.relative_to(ROOT).as_posix(), + line=number, context="保留 HTML 标签、Jinja 表达式和属性", kind="卡片模板行", + original=line, suggestion="")) + return result + + +PROMPT = """# 交给 Gemini 的文案优化任务 + +你将润色 AstrBot 插件「断箭战报」v0.1.0 的中文提示、配置说明、图片战报文字和 README。只提出文案修改,不执行代码、不调用服务、不改变功能或统计逻辑。 + +## 先读这些材料 +1. `事实与约束.md`:哪些能力已实现、哪些尚未验证。 +2. `文案清单.json` 或 `文案清单.csv`:带文件/行号/上下文的原文和待填写建议。 +3. `原文件/README.md`:全文润色对象。 +4. `原文件/` 中代码、配置和模板:确认实际触发条件及动态占位符。自动清单可能收录内部日志或数据标签,请标注「保持原样」,不要擅改程序标识。 +5. `参考预览/`:只用来理解呈现位置,全部是合成样本。 + +## 文风 +自然、准确、简洁的中文,像成熟工具的帮助信息;先告诉用户发生了什么及下一步。删重复说明和生硬技术用语,但保留影响操作的条件、范围、单位和后果。不要营销腔,不添加未经证实的能力、性能、兼容性或成功承诺。管理员诊断与普通玩家提示分别处理。 + +## 不可改动 +- `/ba`、英文子命令、现有中文别名、`stb:`、`steam:`、`name:`、`--limit`、示例 ID 的类型和参数顺序。 +- Python f-string 的所有占位符及格式说明,如 `{caller.prefix}`、`{remaining:.0f}`;JSON 键、枚举值、路径、URL、版本、默认值与数字边界。 +- Jinja 的 `{{ ... }}`、`{% ... %}`、HTML 标签属性、CSS、自动转义及安全规则。 +- STB ID 与 Steam ID 的区分;绑定不是所有权认证;一次选择即确认;查询不修改绑定;原绑定在失败时保留。 +- 缺失与零、未知胜负、近期样本与生涯、数量与价值、抓取时间与来源时间的区分。 +- 每用户默认 20 次、每群默认 100 次可调,全插件每日 100 次固定不可调;北京时间 0 点重置;按 HTTP 请求计数,失败与重试计入、缓存不扣额。不要将请求次数润色为战报查询次数。 +- 不把测试或合成截图写成已上线成果;README 保持简洁,详细接口边界和验证记录放在 docs。 +- 许可证、来源致谢与原 Logo。不要改变设计、代码或配置结构。 + +## 需要返回 +1. `README_润色建议.md`:完整 README,保留命令表、安装步骤、链接与必要限制。 +2. `文案修改建议.json`:数组,每条含 `id`、`original`、`suggestion`、`reason`;保持清单 id,不改键名。建议应为文案文本,不是自动执行补丁。 +3. `需确认事项.md`:仅列会改变含义、与代码不一致或无法确认的事项;不要自作假设。 + +请按文件分组核对整份清单。可保持已清晰的文案;对多条原文相同但触发条件不同的提示,不盲目合并。先给可回填的完整结果,再简述少量关键取舍。最终建议由用户审阅并交回开发者,不自动覆盖源文件。 +""" + +FACTS = """# 事实与约束 + +- 本包是文案审阅材料,非生产配置。源码、提示清单与 README 来自同一次交付快照;SHA256.json 用于核对回填基线。 +- 首版功能:英文主命令、可选中文子命令别名、玩家解析、候选请求码、默认绑定、玩家概览/近期/单局、图片失败文字回退、缓存/限流/管理员状态。 +- 接入默认关闭,客户端标识及令牌为空。需要本插件自己的 BATrace 许可;没有真实接口联调通过的结论,不借用其他项目身份。 +- SteamID64 权威映射尚未确认;语法识别后给出明确限制,不返回猜测映射。 +- API 字段来自固定参考源码研究及合成契约测试;未确认的胜负、模式、地图/单位名称保持未知或来源 ID。当前样本不代表全生涯。 +- 三类卡片已在本地 Chromium 用合成样本渲染并检查;实际 AstrBot 渲染服务与 QQ 收发仍待验收。 +- 配置保存后需重载。本地默认值不是上游许可额度。 +- 每用户默认 20 次、每群默认 100 次,均可在设置调整为 0–100;0 不单独限制。全插件每日 100 次为固定上限,不提供调整项或管理员豁免。所有额度北京时间每天 0 点重置,与显示时区无关。 +- 用户额度按同平台实例的实际发送者跨群及私聊累计,群额度由群内用户共享。按实际提交 HTTP 的尝试计数,重试、失败计入;一条战报命令可能耗多次。命中缓存、本地命令、图片渲染不计入。并发原子记账、重载/清缓存/改凭据不清零;发送前已记账的中断保守保留。 +- `/ba quota` 或 `/ba 额度` 可查看个人、本群、全插件用量;总额度固定 100,不得描述为可配置。达到额度仍可读取新鲜缓存,需要刷新则提示额度已用完,不使用旧缓存隐藏提示。 +- 用户偏好:界面简洁、主次清晰、必要解释靠近字段,普通小数两位、计数整数、精简冗余但保留口径和操作后果。 +- 交付源码保持 Apache-2.0;既有 Logo 原样保留。来源资料见原文件/docs。 +- 文案清单覆盖根目录 Python 中中文字符串及英文异常提示、配置展示字段、插件展示信息和含中文模板行;README 与文档全文随包。测试、工具、注释不作为用户文案润色目标。 +""" + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, default=ROOT.parent / "delivery") + args = parser.parse_args() + args.output.mkdir(parents=True, exist_ok=True) + files = repository_files() + entries = {p.relative_to(ROOT).as_posix(): p.read_bytes() for p in files} + install = {"astrbot_plugin_ba_stats/" + name: data for name, data in entries.items() + if name.split("/")[0] not in {"tests", "tools", ".github"} + and name not in {"requirements-dev.txt", "pytest.ini", ".gitignore", ".gitattributes"}} + for required in ("main.py", "metadata.yaml", "_conf_schema.json", "README.md", "logo.png", "LICENSE"): + assert "astrbot_plugin_ba_stats/" + required in install + for name in install: + assert not any(p in name for p in (".env", ".sqlite", "__pycache__", ".git/")) + plugin_name = f"astrbot_plugin_ba_stats_v{VERSION}.zip" + plugin = archive(install) + (args.output / plugin_name).write_bytes(plugin) + + catalog = text_catalog(files) + copy_entries = {"给Gemini的任务说明.md": PROMPT.encode(), "事实与约束.md": FACTS.encode(), + "文案清单.json": json.dumps(catalog, ensure_ascii=False, indent=2).encode()} + buffer = io.StringIO(newline="") + writer = csv.DictWriter(buffer, fieldnames=["id", "file", "line", "context", "kind", "original", "suggestion"], extrasaction="ignore") + writer.writeheader() + writer.writerows(catalog) + copy_entries["文案清单.csv"] = buffer.getvalue().encode("utf-8-sig") + for name, data in entries.items(): + if name == "README.md" or name == "metadata.yaml" or name == "_conf_schema.json" or ("/" not in name and name.endswith(".py")) or name.startswith(("templates/", "docs/")): + copy_entries["原文件/" + name] = data + previews = ROOT.parent / "previews" + for name in ["overview-normal-dark-mobile.png", "recent-normal-light-mobile.png", "match-missing-light-mobile.png"]: + path = previews / name + if path.is_file(): + copy_entries["参考预览/" + name] = path.read_bytes() + hashes = {name: digest(data) for name, data in entries.items()} + copy_entries["SHA256.json"] = json.dumps(hashes, indent=2).encode() + copy_name = f"断箭战报_Gemini文案优化包_v{VERSION}.zip" + copy_zip = archive(copy_entries) + (args.output / copy_name).write_bytes(copy_zip) + + bundle = {"安装包/" + plugin_name: plugin, "文案优化/" + copy_name: copy_zip} + bundle.update({"源码/astrbot_plugin_ba_stats/" + name: data for name, data in entries.items()}) + for p in previews.glob("*"): + if p.is_file() and p.suffix in {".png", ".html", ".txt", ".json"}: + bundle["验证/卡片预览/" + p.name] = p.read_bytes() + validation = ROOT / "docs" / "VALIDATION.md" + assert validation.is_file(), "Write final validation evidence before delivery." + bundle["验证/VALIDATION.md"] = validation.read_bytes() + log = ROOT.parent / "validation" / "pytest.txt" + if log.is_file(): + bundle["验证/pytest.txt"] = log.read_bytes() + bundle["开始使用.md"] = f"""# 断箭战报 v{VERSION} + +1. 导入 AstrBot:使用「安装包/{plugin_name}」,不要直接导入本总 ZIP。 +2. 真实在线查询还需独立获准的 BATrace 接入;详见源码目录 README 和 docs/API_NOTES.md。 +3. 「文案优化/{copy_name}」可单独交给 Gemini。先让 Gemini 阅读「给Gemini的任务说明.md」,润色提示、配置文字、卡片和 README;回填前仍需核对占位符及功能语义。 +4. 「验证」包含真实执行记录及标注为合成样本的预览。离线通过不代表真实 API 或 QQ 平台验收。 +5. 完整源码、测试和重建工具位于「源码/astrbot_plugin_ba_stats」。仓库审阅状态以 GitHub PR 为准;此包不表示已发布市场或部署生产。 +6. 每日默认额度:个人 20 次、每群 100 次可调,全插件固定 100 次。北京时间 0 点重置;发送 `/ba quota` 查看用量。按上游 HTTP 请求计数,重试及失败计入,命中缓存不计入。 +""".encode() + bundle["SHA256.json"] = json.dumps({name: digest(data) for name, data in bundle.items()}, ensure_ascii=False, indent=2).encode() + final_name = f"断箭战报_v{VERSION}_交付包.zip" + final = archive(bundle) + (args.output / final_name).write_bytes(final) + print(json.dumps({"delivery": str(args.output / final_name), "bytes": len(final), + "sha256": digest(final), "source_files": len(entries), "copy_items": len(catalog), + "plugin_entries": len(install), "bundle_entries": len(bundle)}, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/tools/render_previews.py b/tools/render_previews.py new file mode 100644 index 0000000..d0fd48b --- /dev/null +++ b/tools/render_previews.py @@ -0,0 +1,198 @@ +"""Build labelled synthetic card previews, with optional local-only Chromium. + +Run from the repository using the session's .venv/Scripts/python.exe -B: + tools/render_previews.py # HTML + matching text only + tools/render_previews.py --screenshots # desktop + 390px mobile PNGs + +Chromium must already be installed under the session's .playwright directory. +No installation, server, external page, account, or live API is used. Browser +contexts are offline and all requests are aborted as an additional boundary. +All outputs, browser temporary profiles and the manifest stay under the +session root's previews/. Images show synthetic samples, never real players. +""" + +from __future__ import annotations + +import argparse +import asyncio +from copy import deepcopy +import json +import os +from pathlib import Path +import sys +import tempfile + +sys.dont_write_bytecode = True +REPOSITORY = Path(__file__).resolve().parents[1] +SESSION = REPOSITORY.parent +OUTPUT = SESSION / "previews" +sys.path.insert(0, str(REPOSITORY)) + +from render import Renderer + + +def sample_views() -> dict[str, dict]: + """Deterministic synthetic data; deliberately unequal 3v2 team sizes.""" + base = { + "player": {"id": "sample-000001", "name": "蓝线观察员 · 合成样本"}, + "scope": "最近取得 5 场 · 其中排位样本 4 场 · 非完整历史", + "fetched_at": "2026-11-17T04:10:00Z", + "source_updated_at": "2026-11-17T04:00:00Z", + "source_url": "https://example.invalid/synthetic-preview", + "synthetic": True, + } + overview = deepcopy(base) + overview.update( + kind="overview", + metrics=[ + {"label": "ELO", "value": 1834.25, "note": "来源更新时点"}, + {"label": "样本胜率", "value": 75, "format": "percent", "note": "排位样本 4 场"}, + {"label": "单位交换比", "value": 150 / 96, "note": "摧毁单位 / 损失单位"}, + {"label": "价值交换比", "value": 39602 / 26081, "note": "摧毁价值 / 损失价值"}, + ], + common_units=[{"name": "合成装甲单位 A", "count": 12}, {"name": "合成支援兵种 B", "count": 8}], + ) + recent = deepcopy(base) + recent.update(kind="recent", rows=[ + { + "id": f"sample-match-{index + 1:03d}", "map_name": f"合成地图 {index + 1}", + "mode": "custom" if index == 4 else "ranked", "outcome": "loss" if index == 2 else "win", + "started_at": f"2026-11-{17 - index:02d}T02:20:00Z", "duration_seconds": 1327 + index * 53, + "elo_delta": -12.5 if index == 2 else 8.25, "kills": 36 + index, "losses": 24, + "unit_exchange": 1.5 + index / 24, "destroyed_value": 9750.5 + index * 100, + "lost_value": 6520.25, "value_exchange": (9750.5 + index * 100) / 6520.25, + } + for index in range(5) + ]) + match = deepcopy(base) + match.update( + kind="match", scope="单场完整记录 · 自定义 · 实际 3 对 2 人", + match={"id": "sample-match-001", "map_name": "合成港区", "mode": "custom", + "started_at": "2026-11-17T02:20:00Z", "duration_seconds": 1327, "winner": "蓝队"}, + teams=[ + {"name": name, "outcome": "win" if side == 0 else "loss", "players": [ + {"id": f"sample-{side}-{index}", "name": f"合成队员 {side + 1}-{index + 1}", + "elo": 1800 + index * 12.5, "elo_delta": 8.25 if side == 0 else -8.25, + "kills": 36, "losses": 24, "unit_exchange": 1.5, + "destroyed_value": 9750.5, "lost_value": 6520.25, "value_exchange": 9750.5 / 6520.25} + for index in range(size) + ]} + for side, (name, size) in enumerate([("蓝队", 3), ("红队", 2)]) + ], + ) + samples = {} + for kind, normal in [("overview", overview), ("recent", recent), ("match", match)]: + samples[f"{kind}-normal"] = normal + long = deepcopy(normal) + long["player"]["name"] = "合成长昵称_中文MixedPlayer_" * 7 + '{{7*7}} <昵称>&' + long["player"]["id"] = "sample-long-id-" + "0123456789" * 8 + if kind == "overview": + long["common_units"][0]["name"] = "合成长单位名称_" * 8 + elif kind == "recent": + long["rows"][0]["map_name"] = "合成长地图名称_" * 6 + else: + long["teams"][0]["name"] = "合成长分队名称_" * 7 + long["teams"][0]["players"][0]["name"] = long["player"]["name"] + samples[f"{kind}-long-name"] = long + missing = deepcopy(base) + missing.update(kind=kind, player={"id": "sample-missing", "name": None}, + source_url=None, source_updated_at=None, stale=True, scope="已取得样本 · 覆盖范围暂无") + if kind == "overview": + missing["metrics"] = [ + {"label": "ELO", "value": None}, {"label": "样本胜率", "value": None, "format": "percent"}, + {"label": "实际样本", "value": 0, "format": "integer", "unit": "场"}, + {"label": "价值交换比", "value": None}, + ] + elif kind == "recent": + missing["rows"] = [{"id": "sample-partial", "kills": 0, "duration_seconds": 0}] + else: + missing["match"] = {"id": "sample-partial"} + missing["teams"] = [{"name": "合成未完整分队", "players": [{"id": "sample-player", "name": None}]}, + {"name": "合成空分队", "players": []}] + samples[f"{kind}-missing"] = missing + return samples + + +async def screenshots(artifacts: list[dict]) -> list[dict]: + from playwright.async_api import async_playwright + + os.environ.setdefault("PLAYWRIGHT_BROWSERS_PATH", str(SESSION / ".playwright")) + temporary = OUTPUT / ".tmp" + temporary.mkdir(exist_ok=True) + os.environ["TMP"] = str(temporary) + os.environ["TEMP"] = str(temporary) + tempfile.tempdir = str(temporary) + checks = [] + async with async_playwright() as playwright: + browser = await playwright.chromium.launch(headless=True) + try: + for label, width in [("desktop", 980), ("mobile", 390)]: + context = await browser.new_context(viewport={"width": width, "height": 900}, + device_scale_factor=1, offline=True) + await context.route("**/*", lambda route: route.abort()) + try: + page = await context.new_page() + requests = [] + page.on("request", lambda request: requests.append(request.url)) + for item in artifacts: + requests.clear() + await page.set_content((OUTPUT / item["html"]).read_text(encoding="utf-8"), wait_until="load") + await page.evaluate("document.fonts.ready") + dimensions = await page.evaluate("""() => ({ + width: innerWidth, + documentWidth: document.documentElement.scrollWidth, + height: document.documentElement.scrollHeight, + reportHeight: document.querySelector('.report').getBoundingClientRect().height, + synthetic: document.querySelector('.synthetic')?.textContent, + font: getComputedStyle(document.body).fontFamily + })""") + name = f"{item['name']}-{label}.png" + await page.locator(".report").screenshot(path=str(OUTPUT / name), animations="disabled") + check = {"image": name, "viewport": label, **dimensions, + "external_requests": list(requests), + "passed": dimensions["documentWidth"] <= width and not requests + and bool(dimensions["synthetic"])} + checks.append(check) + finally: + await context.close() + finally: + await browser.close() + return checks + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--screenshots", action="store_true", help="use already installed local headless Chromium") + args = parser.parse_args() + OUTPUT.mkdir(parents=True, exist_ok=True) + artifacts = [] + for sample_name, view in sample_views().items(): + for theme in ("dark", "light"): + renderer = Renderer(theme=theme) + for page in renderer.views(view): + name = f"{sample_name}-{theme}" + if page.get("page_count", 1) > 1: + name += f"-page-{page['page']}" + html_name, text_name = name + ".html", name + ".txt" + (OUTPUT / html_name).write_text(renderer.template(page), encoding="utf-8") + (OUTPUT / text_name).write_text(renderer.text(page), encoding="utf-8") + artifacts.append({"name": name, "html": html_name, "text": text_name}) + checks = asyncio.run(screenshots(artifacts)) if args.screenshots else [] + manifest = { + "synthetic": True, "live_api_used": False, + "browser_mode": "local-only offline headless Chromium" if args.screenshots else "not launched", + "artifacts": artifacts, "screenshots": checks, + "visual_review": "Screenshots require manual image review; layout checks alone are not visual acceptance.", + } + (OUTPUT / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8") + failures = [check["image"] for check in checks if not check["passed"]] + print(f"Synthetic previews: {len(artifacts)} HTML/text pairs; {len(checks)} screenshots; {len(failures)} layout/network failures.") + print(f"Output: {OUTPUT}") + if failures: + print("Failed: " + ", ".join(failures)) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())