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())