"""ProtonDB integration for Linux compatibility ratings. Fetches game compatibility tiers from ProtonDB's public API to filter out games that don't work well on Linux. Ratings are cached locally so repeated lookups are free. Tier hierarchy (best → worst): native, platinum, gold, silver, bronze, borked. """ from __future__ import annotations import asyncio from dataclasses import dataclass import json import logging from typing import Any import aiohttp from steam_backlog_enforcer.config import CONFIG_DIR, _atomic_write logger = logging.getLogger(__name__) PROTONDB_CACHE_FILE = CONFIG_DIR / "protondb_cache.json" _PROTONDB_API = "https://www.protondb.com/api/v1/reports/summaries/{app_id}.json" MAX_CONCURRENT = 30 # parallel requests - be polite to the CDN HTTP_NOT_FOUND = 404 # Tier ordering from best to worst. TIER_ORDER: dict[str, int] = { "native": 0, "platinum": 1, "gold": 2, "silver": 3, "bronze": 4, "borked": 5, "pending": 6, } # Games at or below this tier are skipped. MIN_PLAYABLE_TIER = "gold" @dataclass class ProtonDBRating: """ProtonDB compatibility rating for a game.""" app_id: int tier: str = "" trending_tier: str = "" score: float = 0.0 confidence: str = "" total_reports: int = 0 @property def is_playable(self) -> bool: """True if the game has at least gold-tier compatibility. A game is considered unplayable when: - Its tier is silver, bronze, or borked. - Both reported ratings are available, but one is below silver. - Both reported ratings are available, but neither reaches gold. If both ``tier`` and ``trending_tier`` exist, the acceptance rule is: at least one rating must be gold-or-better and the other must be silver-or-better. """ if not self.tier or self.tier == "pending": return True # No data / pending → don't block; user can skip manually. tier_rank = TIER_ORDER.get(self.tier, 99) min_rank = TIER_ORDER[MIN_PLAYABLE_TIER] silver_rank = TIER_ORDER["silver"] if not self.trending_tier: return tier_rank <= min_rank trend_rank = TIER_ORDER.get(self.trending_tier, 99) if tier_rank > silver_rank or trend_rank > silver_rank: # Bronze, borked, unknown tier in either field → skip. return False # At least one rating must still be gold-or-better. return not (tier_rank > min_rank and trend_rank > min_rank) @property def unplayable_reason(self) -> str: """Return a human-readable reason when ``is_playable`` is false.""" if self.is_playable: return "" tier_rank = TIER_ORDER.get(self.tier, 99) TIER_ORDER[MIN_PLAYABLE_TIER] silver_rank = TIER_ORDER["silver"] if not self.trending_tier: return f"tier<{MIN_PLAYABLE_TIER} ({self.tier})" trend_rank = TIER_ORDER.get(self.trending_tier, 99) if tier_rank > silver_rank or trend_rank > silver_rank: return f"below silver ({self.tier}/{self.trending_tier})" return f"no gold tier ({self.tier}/{self.trending_tier})" def _load_cache() -> dict[str, Any]: """Load the on-disk ProtonDB cache.""" if PROTONDB_CACHE_FILE.exists(): data: dict[str, Any] = json.loads( PROTONDB_CACHE_FILE.read_text(encoding="utf-8"), ) return data return {} def _save_cache(cache: dict[str, Any]) -> None: """Persist the ProtonDB cache.""" _atomic_write( PROTONDB_CACHE_FILE, json.dumps(cache, indent=2) + "\n", ) async def _fetch_one( session: aiohttp.ClientSession, sem: asyncio.Semaphore, app_id: int, ) -> ProtonDBRating | None: """Fetch a single game's ProtonDB rating. Returns None on network/server errors (not cached, will retry next run). Returns ProtonDBRating with empty tier on HTTP 404 (no ProtonDB data). """ url = _PROTONDB_API.format(app_id=app_id) async with sem: try: async with session.get(url, timeout=aiohttp.ClientTimeout(total=15)) as r: if r.status == HTTP_NOT_FOUND: return ProtonDBRating(app_id=app_id) r.raise_for_status() data = await r.json(content_type=None) return ProtonDBRating( app_id=app_id, tier=data.get("tier", ""), trending_tier=data.get("trendingTier", ""), score=data.get("score", 0.0), confidence=data.get("confidence", ""), total_reports=data.get("total", 0), ) except (aiohttp.ClientError, asyncio.TimeoutError, OSError) as e: logger.warning("ProtonDB fetch failed for AppID=%d: %s", app_id, e) return None # Don't cache transient failures — retry next run. async def _fetch_batch(app_ids: list[int]) -> list[ProtonDBRating]: """Fetch ProtonDB ratings for a batch of app IDs concurrently.""" sem = asyncio.Semaphore(MAX_CONCURRENT) async with aiohttp.ClientSession() as session: tasks = [_fetch_one(session, sem, aid) for aid in app_ids] results = await asyncio.gather(*tasks) return [r for r in results if r is not None] def _rating_to_dict(r: ProtonDBRating) -> dict[str, Any]: """Serialize a rating to a cache-friendly dict.""" return { "tier": r.tier, "trending_tier": r.trending_tier, "score": r.score, "confidence": r.confidence, "total_reports": r.total_reports, } def _rating_from_cache(app_id: int, data: dict[str, Any]) -> ProtonDBRating: """Deserialize a rating from cached data.""" return ProtonDBRating( app_id=app_id, tier=data.get("tier", ""), trending_tier=data.get("trending_tier", ""), score=data.get("score", 0.0), confidence=data.get("confidence", ""), total_reports=data.get("total_reports", 0), ) def fetch_protondb_ratings( app_ids: list[int], ) -> dict[int, ProtonDBRating]: """Fetch ProtonDB ratings with local caching. Returns a dict mapping app_id → ProtonDBRating for every requested ID. Cached results are reused; only missing IDs are fetched from the network. """ cache = _load_cache() # Separate cached vs. uncached. results: dict[int, ProtonDBRating] = {} to_fetch: list[int] = [] for aid in app_ids: key = str(aid) if key in cache: results[aid] = _rating_from_cache(aid, cache[key]) else: to_fetch.append(aid) if to_fetch: logger.info( "Fetching ProtonDB ratings for %d games (%d cached)...", len(to_fetch), len(results), ) fetched = asyncio.run(_fetch_batch(to_fetch)) for r in fetched: results[r.app_id] = r cache[str(r.app_id)] = _rating_to_dict(r) _save_cache(cache) logger.info("ProtonDB: fetched %d, total cached %d", len(fetched), len(cache)) else: logger.info("All %d ProtonDB ratings found in cache.", len(results)) return results