diff --git a/steam_backlog_enforcer/_appinfo_cache.py b/steam_backlog_enforcer/_appinfo_cache.py new file mode 100644 index 0000000..9224cde --- /dev/null +++ b/steam_backlog_enforcer/_appinfo_cache.py @@ -0,0 +1,111 @@ +"""Selected apps from the Steam client's own cache, ``appcache/appinfo.vdf``. + +The same v29 layout steam-game-installer's ``appinfo_cache`` reads (magic +0x07564429): u32 magic, u32 universe, i64 offset of a string table; then per +app: u32 appid, u32 size, ``size`` bytes made of a 60-byte header and binary +key-values whose keys are u32 indexes into the string table. Appid 0 ends the +list. The table is a u32 count followed by NUL-terminated strings. + +Only the apps asked for are decoded; the rest are skipped by their size, so a +tool-step check stays cheap on the ~12 MB file. Every scalar comes back as a +string, as Steam's text VDF prints it. Reads only. +""" + +from __future__ import annotations + +import struct +from typing import TYPE_CHECKING, Final + +if TYPE_CHECKING: + from collections.abc import Iterable + from pathlib import Path + + from steam_backlog_enforcer._vdf_text import VdfNode + +MAGIC: Final = 0x07564429 +# "SteamPlay 2.0 Manifests": its extended/app_mappings is Valve's per-game +# tool pick (e.g. a broken native port sent to Proton). +STEAM_PLAY_APP: Final = 891390 +_HEADER: Final = 60 +# KV type bytes: a nested block, a NUL-terminated string, end of block. +_BLOCK: Final = 0 +_STRING: Final = 1 +_END: Final = 8 +# Fixed-width value types: KV type byte -> struct format. +_SCALARS: Final = {2: " Path: + """Where Steam keeps the cache under *steam_root*.""" + return steam_root / "appcache" / "appinfo.vdf" + + +def read_apps(path: Path, wanted: Iterable[int]) -> dict[int, dict[str, VdfNode]]: + """The ``appinfo`` block of each of *wanted* the cache holds. + + Raises: + OSError: The file cannot be read. + ValueError: It is not a v29 cache, or it is cut short or damaged. + """ + buf = path.read_bytes() + try: + return _parse(buf, set(wanted)) + except (struct.error, IndexError) as exc: + msg = "appinfo.vdf is cut short or damaged" + raise ValueError(msg) from exc + + +def _parse(buf: bytes, wanted: set[int]) -> dict[int, dict[str, VdfNode]]: + magic, _universe, table_offset = struct.unpack_from(" list[str]: + (count,) = struct.unpack_from(" tuple[dict[str, VdfNode], int]: + out: dict[str, VdfNode] = {} + while True: + kind = buf[pos] + pos += 1 + if kind == _END: + return out, pos + (index,) = struct.unpack_from(" list[Path] | ToolNeed: return found -def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | int: - """The reason to keep the tools, or how many installed games are mapped.""" +@dataclass(frozen=True) +class _Games: + """How many installed games are covered, and which of them by Valve.""" + + count: int + native: set[int] + + +def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | _Games: + """The reason to keep the tools, or the installed games they may go for.""" libraries = _libraries(steamapps) if isinstance(libraries, ToolNeed): return libraries @@ -124,6 +139,7 @@ def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | int: return manifests # A library listed twice (the default is usually key "0") counts once. games: set[str] = set() + native: set[int] = set() for manifest in manifests: try: tree = parse_vdf(manifest.read_text(encoding="utf-8")) @@ -134,10 +150,49 @@ def _unmapped(steamapps: Path, mapping: dict[str, VdfNode]) -> ToolNeed | int: return _keep(f"{manifest.name} has no appid") if int(app_id) in PROTECTED_APP_IDS: continue - if lookup(mapping, app_id, "name") != NATIVE_TOOL: + entry = lookup(mapping, app_id) + if entry is None or lookup(entry, "name") == "": + native.add(int(app_id)) # no pick of kuhy's: Valve's default runs it + elif lookup(entry, "name") != NATIVE_TOOL: return _keep(f"AppID={app_id} has no {NATIVE_TOOL} mapping") games.add(app_id) - return len(games) + return _Games(count=len(games), native=native) + + +def _cache( + steam_root: Path, app_ids: set[int] +) -> tuple[dict[int, dict[str, VdfNode]], dict[str, VdfNode]] | ToolNeed: + """The games' appinfo blocks and Valve's pick list, or why they are unusable.""" + try: + apps = read_apps(default_path(steam_root), {STEAM_PLAY_APP, *app_ids}) + except OSError: + return _keep("appinfo.vdf unreadable") + except ValueError: + return _keep("appinfo.vdf malformed") + picks = lookup(apps.get(STEAM_PLAY_APP), "extended", "app_mappings") + if not isinstance(picks, dict): + return _keep(f"app {STEAM_PLAY_APP} has no app_mappings") + return apps, picks + + +def _not_native(steam_root: Path, app_ids: set[int]) -> ToolNeed | None: + """None when Valve runs each of *app_ids* natively, else why it may not.""" + cache = _cache(steam_root, app_ids) + if isinstance(cache, ToolNeed): + return cache + apps, picks = cache + for app_id in sorted(app_ids): + block = apps.get(app_id) + if block is None: + return _keep(f"AppID={app_id} not in appinfo.vdf") + oslist = lookup(block, "common", "oslist") + if not isinstance(oslist, str) or "linux" not in oslist.split(","): + return _keep(f"AppID={app_id} has no {NATIVE_TOOL} mapping") + # A tool pick (a runtime such as Steam Linux Runtime 4.0, or Proton + # for a broken port) may need the very tools this would remove. + if str(app_id) in picks or lookup(block, "config", "app_mappings"): + return _keep(f"AppID={app_id} has a Valve tool mapping") + return None def _busy() -> ToolNeed | None: @@ -165,14 +220,16 @@ def _decide(steamapps: Path) -> ToolNeed: games = _unmapped(steamapps, mapping) if isinstance(games, ToolNeed): return games + if games.native and (not_native := _not_native(steam_root, games.native)): + return not_native toolmanifest = steam_root / "compatibilitytools.d" / NATIVE_TOOL if not (toolmanifest / "toolmanifest.vdf").is_file(): return _keep(f"{NATIVE_TOOL} toolmanifest.vdf missing") # No game installed means no game needs them; the reason says so in the log. - reason = ( - f"every installed game runs on {NATIVE_TOOL}" if games else "no game installed" - ) - return ToolNeed(needed=False, reason=reason) + reason = f"every installed game runs on {NATIVE_TOOL}" + if games.native: + reason += " or natively" + return ToolNeed(needed=False, reason=reason if games.count else "no game installed") def tool_need(steamapps: Path | None = None) -> ToolNeed: diff --git a/steam_backlog_enforcer/tests/_appinfo_home.py b/steam_backlog_enforcer/tests/_appinfo_home.py new file mode 100644 index 0000000..8b16850 --- /dev/null +++ b/steam_backlog_enforcer/tests/_appinfo_home.py @@ -0,0 +1,73 @@ +"""Fixture ``appcache/appinfo.vdf`` files in Steam's binary v29 layout. + +Mirrors what :mod:`steam_backlog_enforcer._appinfo_cache` reads: a 16-byte +head (magic, universe, string-table offset), one record per app (appid, size, +60-byte header, binary key-values keyed by string-table index), appid 0, then +the string table. A Python ``int`` becomes a 32-bit int value (type 2). +""" + +from __future__ import annotations + +import struct +from typing import TYPE_CHECKING + +from steam_backlog_enforcer._appinfo_cache import MAGIC, STEAM_PLAY_APP + +if TYPE_CHECKING: + from pathlib import Path + +type Node = str | int | dict[str, Node] + + +def _encode(node: dict[str, Node], strings: list[str]) -> bytes: + out = b"" + for key, value in node.items(): + if key not in strings: + strings.append(key) + index = struct.pack(" bytes: + """The binary cache holding *apps* (appid -> its ``appinfo`` block).""" + strings: list[str] = [] + body = b"" + for app_id, block in apps.items(): + data = b"\0" * 60 + _encode({"appinfo": block}, strings) + body += struct.pack(" dict[str, Node]: + """A game's appinfo block with *oslist* and an optional ``config``.""" + return {"common": {"name": "G", "oslist": oslist}, "config": dict(config)} + + +def steam_play(mapped: tuple[int, ...] = ()) -> dict[str, Node]: + """App 891390's block; *mapped* games get a Valve tool pick.""" + mappings: dict[str, Node] = { + str(a): {"appid": str(a), "tool": "proton-experimental"} for a in mapped + } + return {"extended": {"app_mappings": mappings}} + + +def write_appinfo( + root: Path, apps: dict[int, dict[str, Node]], *, steam_play_app: bool = True +) -> Path: + """Write ``/appcache/appinfo.vdf``; 891390 is added unless told not.""" + if steam_play_app: + apps = {STEAM_PLAY_APP: steam_play()} | apps + path = root / "appcache" / "appinfo.vdf" + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(appinfo_bytes(apps)) + return path diff --git a/steam_backlog_enforcer/tests/test_game_uninstall_tools.py b/steam_backlog_enforcer/tests/test_game_uninstall_tools.py index 317e7f8..05af9c7 100644 --- a/steam_backlog_enforcer/tests/test_game_uninstall_tools.py +++ b/steam_backlog_enforcer/tests/test_game_uninstall_tools.py @@ -13,6 +13,7 @@ from steam_backlog_enforcer.game_uninstall import ( remove_unneeded_tools, uninstall_other_games, ) +from steam_backlog_enforcer.tests._appinfo_home import game, write_appinfo from steam_backlog_enforcer.tests._tool_home import make_home if TYPE_CHECKING: @@ -67,8 +68,9 @@ def test_mapped_games_remove_the_tools( def test_unmapped_game_keeps_the_tools( home: Path, caplog: pytest.LogCaptureFixture ) -> None: - """An unmapped game keeps them with one line naming it.""" + """An unmapped Windows game keeps them with one line naming it.""" steamapps = make_home(home, {10: NATIVE_TOOL, 20: None}) + write_appinfo(home, {20: game("windows")}) with caplog.at_level(logging.INFO, logger=PKG): assert remove_unneeded_tools() == 0 assert _tools_left(steamapps) == set(STEAM_TOOLS) @@ -77,6 +79,21 @@ def test_unmapped_game_keeps_the_tools( ] +def test_native_game_lets_the_tools_go( + home: Path, caplog: pytest.LogCaptureFixture +) -> None: + """C12: an unmapped native game (DUSK) beside a mapped one: all three go.""" + steamapps = make_home(home, {10: NATIVE_TOOL, 20: None}) + write_appinfo(home, {20: game("windows,linux")}) + with caplog.at_level(logging.INFO, logger=PKG): + assert remove_unneeded_tools() == 3 + assert _tools_left(steamapps) == set() + assert (steamapps / "appmanifest_20.acf").exists() + assert _messages(caplog)[0] == ( + f"removing Steam tools: every installed game runs on {NATIVE_TOOL} or natively" + ) + + def test_steam_running_defers(home: Path, caplog: pytest.LogCaptureFixture) -> None: """A running Steam defers the decision.""" steamapps = make_home(home, {10: NATIVE_TOOL}) diff --git a/steam_backlog_enforcer/tests/test_tool_need.py b/steam_backlog_enforcer/tests/test_tool_need.py index e1badc3..8882199 100644 --- a/steam_backlog_enforcer/tests/test_tool_need.py +++ b/steam_backlog_enforcer/tests/test_tool_need.py @@ -9,6 +9,7 @@ from unittest.mock import patch import pytest from steam_backlog_enforcer._tool_need import NATIVE_TOOL, ToolNeed, tool_need +from steam_backlog_enforcer.tests._appinfo_home import game, write_appinfo from steam_backlog_enforcer.tests._tool_home import make_home if TYPE_CHECKING: @@ -41,8 +42,9 @@ def test_all_mapped_means_not_needed(root: Path) -> None: def test_one_unmapped_game_keeps(root: Path) -> None: - """One game with no mapping entry keeps them.""" + """One Windows game with no mapping entry keeps them.""" steamapps = make_home(root, {10: NATIVE_TOOL, 20: None}) + write_appinfo(root, {20: game("windows")}) assert tool_need(steamapps) == KEEP_UNMAPPED diff --git a/steam_backlog_enforcer/tests/test_tool_need_libraries.py b/steam_backlog_enforcer/tests/test_tool_need_libraries.py index 6f4142a..c311b66 100644 --- a/steam_backlog_enforcer/tests/test_tool_need_libraries.py +++ b/steam_backlog_enforcer/tests/test_tool_need_libraries.py @@ -8,6 +8,7 @@ from unittest.mock import patch import pytest from steam_backlog_enforcer._tool_need import NATIVE_TOOL, ToolNeed, tool_need +from steam_backlog_enforcer.tests._appinfo_home import game, write_appinfo from steam_backlog_enforcer.tests._tool_home import add_library, make_home if TYPE_CHECKING: @@ -43,6 +44,7 @@ def test_mapped_game_in_a_second_library(root: Path, tmp_path: Path) -> None: def test_unmapped_game_in_a_second_library_keeps(root: Path, tmp_path: Path) -> None: """An unmapped game in another library keeps them.""" steamapps = make_home(root, {10: NATIVE_TOOL, 50: None}) + write_appinfo(root, {50: game("windows")}) add_library(steamapps, {"0": root, "1": tmp_path / "lib"}, {50: tmp_path / "lib"}) assert tool_need(steamapps) == ToolNeed( needed=True, reason=f"AppID=50 has no {NATIVE_TOOL} mapping" @@ -52,6 +54,7 @@ def test_unmapped_game_in_a_second_library_keeps(root: Path, tmp_path: Path) -> def test_legacy_string_entries_are_scanned(root: Path, tmp_path: Path) -> None: """Old Steam wrote ``"1" ""``; that library is scanned too.""" steamapps = make_home(root, {10: NATIVE_TOOL, 50: None}) + write_appinfo(root, {50: game("windows")}) add_library(steamapps, {}, {50: tmp_path / "lib"}) (steamapps / "libraryfolders.vdf").write_text( f'"LibraryFolders" {{ "TimeNextStatsReport" "1" "1" "{tmp_path / "lib"}" }}' diff --git a/steam_backlog_enforcer/tests/test_tool_need_native.py b/steam_backlog_enforcer/tests/test_tool_need_native.py new file mode 100644 index 0000000..f2924ed --- /dev/null +++ b/steam_backlog_enforcer/tests/test_tool_need_native.py @@ -0,0 +1,173 @@ +"""Tests for _tool_need: a game Valve runs natively needs none of the tools. + +Native means: no CompatToolMapping entry of kuhy's (or an empty one), ``linux`` +in the app cache's ``common/oslist``, and no Valve tool pick for it (neither the +game's own ``config/app_mappings`` nor app 891390's). Any doubt keeps them. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING +from unittest.mock import patch + +import pytest + +from steam_backlog_enforcer._appinfo_cache import STEAM_PLAY_APP, read_apps +from steam_backlog_enforcer._tool_need import NATIVE_TOOL, ToolNeed, tool_need +from steam_backlog_enforcer.tests._appinfo_home import ( + Node, + appinfo_bytes, + game, + steam_play, + write_appinfo, +) +from steam_backlog_enforcer.tests._tool_home import config_vdf, make_home + +if TYPE_CHECKING: + from collections.abc import Iterator + from pathlib import Path + +PKG = "steam_backlog_enforcer._tool_need" +NATIVE = "windows,macos,linux" +COVERED = ToolNeed( + needed=False, reason=f"every installed game runs on {NATIVE_TOOL} or natively" +) + + +def _keep(reason: str) -> ToolNeed: + return ToolNeed(needed=True, reason=reason) + + +@pytest.fixture(name="root") +def fixture_root(tmp_path: Path) -> Path: + """A fixture Steam root (conftest already owns tmp_path/steamapps).""" + return tmp_path / "Steam" + + +@pytest.fixture(autouse=True) +def _steam_closed() -> Iterator[None]: + with patch(f"{PKG}.steam_client_running", return_value=False): + yield + + +def test_native_unmapped_game_beside_a_mapped_one_is_covered(root: Path) -> None: + """C12: DUSK (native, unmapped) next to Princess Remedy (mapped).""" + steamapps = make_home(root, {10: NATIVE_TOOL, 20: None}) + write_appinfo(root, {10: game("windows"), 20: game(NATIVE), 99: game("linux")}) + assert tool_need(steamapps) == COVERED + + +def test_empty_mapping_entry_counts_as_unmapped(root: Path) -> None: + """An entry Steam left with name "" is no pick of kuhy's.""" + steamapps = make_home(root, {20: None}) + (root / "config" / "config.vdf").write_text(config_vdf({20: ""})) + write_appinfo(root, {20: game(NATIVE, contenttype=3)}) + assert tool_need(steamapps) == COVERED + + +def test_native_game_forced_onto_another_tool_keeps(root: Path) -> None: + """kuhy's own pick of Valve Proton for a native game keeps them.""" + steamapps = make_home(root, {20: "proton_experimental"}) + write_appinfo(root, {20: game(NATIVE)}) + assert tool_need(steamapps) == _keep(f"AppID=20 has no {NATIVE_TOOL} mapping") + + +def test_windows_only_unmapped_game_keeps(root: Path) -> None: + """An unmapped Windows game runs on Valve's Proton: keep.""" + steamapps = make_home(root, {20: None}) + write_appinfo(root, {20: game("windows")}) + assert tool_need(steamapps) == _keep(f"AppID=20 has no {NATIVE_TOOL} mapping") + + +@pytest.mark.parametrize("block", [{"config": {}}, {"common": "x"}, {"common": {}}]) +def test_no_os_list_keeps(root: Path, block: dict[str, Node]) -> None: + """No readable OS list is no proof of a Linux build.""" + steamapps = make_home(root, {20: None}) + write_appinfo(root, {20: block}) + assert tool_need(steamapps) == _keep(f"AppID=20 has no {NATIVE_TOOL} mapping") + + +def test_game_own_tool_pick_keeps(root: Path) -> None: + """A native game whose appinfo picks a runtime (240 picks sniper) keeps.""" + steamapps = make_home(root, {20: None}) + pick: dict[str, Node] = {"0": {"tool": "steamlinuxruntime_4"}} + write_appinfo(root, {20: game(NATIVE, app_mappings=pick)}) + assert tool_need(steamapps) == _keep("AppID=20 has a Valve tool mapping") + + +def test_valve_steam_play_pick_keeps(root: Path) -> None: + """A native game app 891390 sends to Proton keeps them.""" + steamapps = make_home(root, {20: None}) + write_appinfo(root, {STEAM_PLAY_APP: steam_play((20,)), 20: game(NATIVE)}) + assert tool_need(steamapps) == _keep("AppID=20 has a Valve tool mapping") + + +@pytest.mark.parametrize("block", [{}, {"extended": {}}, {"extended": "x"}]) +def test_unusable_steam_play_app_keeps(root: Path, block: dict[str, Node]) -> None: + """Without Valve's pick list no game can be called native.""" + steamapps = make_home(root, {20: None}) + apps = {STEAM_PLAY_APP: block, 20: game(NATIVE)} + write_appinfo(root, apps, steam_play_app=False) + assert tool_need(steamapps) == _keep("app 891390 has no app_mappings") + + +def test_missing_steam_play_app_keeps(root: Path) -> None: + """No app 891390 in the cache keeps them.""" + steamapps = make_home(root, {20: None}) + write_appinfo(root, {20: game(NATIVE)}, steam_play_app=False) + assert tool_need(steamapps) == _keep("app 891390 has no app_mappings") + + +def test_game_missing_from_cache_keeps(root: Path) -> None: + """A game the cache does not hold keeps them.""" + steamapps = make_home(root, {20: None}) + write_appinfo(root, {}) + assert tool_need(steamapps) == _keep("AppID=20 not in appinfo.vdf") + + +def test_missing_cache_keeps(root: Path) -> None: + """No appinfo.vdf keeps them.""" + steamapps = make_home(root, {20: None}) + assert tool_need(steamapps) == _keep("appinfo.vdf unreadable") + + +def test_mapped_games_never_read_the_cache(root: Path) -> None: + """All mapped: no cache needed, the old reason stands.""" + steamapps = make_home(root, {10: NATIVE_TOOL}) + assert tool_need(steamapps) == ToolNeed( + needed=False, reason=f"every installed game runs on {NATIVE_TOOL}" + ) + + +@pytest.mark.parametrize( + "damage", + [ + appinfo_bytes({20: game(NATIVE)}, magic=0x07564428), + appinfo_bytes({20: game(NATIVE)})[:40], + b"\x29\x44", + ], + ids=["old-format", "truncated", "short"], +) +def test_malformed_cache_keeps(root: Path, damage: bytes) -> None: + """An old-format, cut-short or tiny cache keeps them.""" + steamapps = make_home(root, {20: None}) + (root / "appcache").mkdir() + (root / "appcache" / "appinfo.vdf").write_bytes(damage) + assert tool_need(steamapps) == _keep("appinfo.vdf malformed") + + +def test_unknown_value_type_is_malformed(tmp_path: Path) -> None: + """A value type the reader does not know is an error, not a guess.""" + good = appinfo_bytes({20: {"common": {"oslist": "linux"}}}) + bad = good.replace(b"\x01\x02\x00\x00\x00linux", b"\x09\x02\x00\x00\x00linux") + path = tmp_path / "appinfo.vdf" + path.write_bytes(bad) + with pytest.raises(ValueError, match="value type 9"): + read_apps(path, {20}) + + +def test_read_apps_decodes_only_what_is_asked(tmp_path: Path) -> None: + """Other apps are skipped by size; ints decode as strings.""" + path = tmp_path / "appinfo.vdf" + path.write_bytes(appinfo_bytes({20: {"a": 1}, 30: {"b": "x"}})) + assert read_apps(path, {20, 40}) == {20: {"a": "1"}}