From 749f12ca273c3f7c8adcd87cf77ae4559299c26d Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Thu, 12 Nov 2026 08:39:34 +0100 Subject: [PATCH] Group HLTB search context auth and results _SearchCtx holds the token, its issue time and renewal lock in an _AuthSlot, and the polls, extras, failures and dirty flag in _SearchResults. Lookup behaviour is unchanged. Todo: 9b9342ba Co-Authored-By: Claude Opus 5.5 --- steam_backlog_enforcer/_hltb_auth_refresh.py | 12 ++-- steam_backlog_enforcer/_hltb_search.py | 14 +++-- steam_backlog_enforcer/_hltb_search_one.py | 55 ++++++++++++------- .../tests/test_hltb_auth_refresh.py | 11 ++-- .../tests/test_hltb_pacing.py | 8 ++- .../tests/test_hltb_search.py | 2 +- .../test_hltb_search_failure_keeps_cache.py | 43 +++++++++++---- 7 files changed, 95 insertions(+), 50 deletions(-) diff --git a/steam_backlog_enforcer/_hltb_auth_refresh.py b/steam_backlog_enforcer/_hltb_auth_refresh.py index 3d20823..7881c53 100644 --- a/steam_backlog_enforcer/_hltb_auth_refresh.py +++ b/steam_backlog_enforcer/_hltb_auth_refresh.py @@ -39,15 +39,15 @@ def apply_auth(headers: dict[str, str], auth: _AuthInfo) -> None: async def ensure_fresh_auth(ctx: _SearchCtx) -> str | None: - """Renew ``ctx.auth`` once it is too old. + """Renew ``ctx.auth.info`` once it is too old. Returns ``None`` when the auth is usable, else the failure reason. A failed renewal trips the breaker: the stale token is never used again. """ - if _now() - ctx.auth_at < AUTH_MAX_AGE_S: + if _now() - ctx.auth.issued_at < AUTH_MAX_AGE_S: return None - async with ctx.auth_lock: - if _now() - ctx.auth_at < AUTH_MAX_AGE_S: + async with ctx.auth.lock: + if _now() - ctx.auth.issued_at < AUTH_MAX_AGE_S: return None # another lookup renewed it while we waited failures: list[str] = [] auth = await _get_auth_info(ctx.search_url, ctx.session, failures) @@ -55,8 +55,8 @@ async def ensure_fresh_auth(ctx: _SearchCtx) -> str | None: if auth is None: ctx.breaker.tripped = True return f"auth refresh {failures[0] if failures else 'no token'}" - ctx.auth = auth + ctx.auth.info = auth apply_auth(ctx.headers, auth) - ctx.auth_at = _now() + ctx.auth.issued_at = _now() logger.info("HLTB auth token refreshed.") return None diff --git a/steam_backlog_enforcer/_hltb_search.py b/steam_backlog_enforcer/_hltb_search.py index f960071..b1233f4 100644 --- a/steam_backlog_enforcer/_hltb_search.py +++ b/steam_backlog_enforcer/_hltb_search.py @@ -27,7 +27,12 @@ from steam_backlog_enforcer._hltb_search_api import ( _get_hltb_search_url, forget_hltb_search_url, ) -from steam_backlog_enforcer._hltb_search_one import _search_one, _SearchCtx +from steam_backlog_enforcer._hltb_search_one import ( + _AuthSlot, + _search_one, + _SearchCtx, + _SearchResults, +) from steam_backlog_enforcer._hltb_types import ( MAX_CONCURRENT, HLTBResult, @@ -71,7 +76,7 @@ def _check_batch(ctx: _SearchCtx) -> None: ctx.total, ) if ctx.breaker.tripped: - record_breaker(ctx.failed_ids) + record_breaker(ctx.results.failed_ids) if failed == ctx.total: msg = f"HLTB: all {failed} lookups failed, nothing refreshed" raise _fail_batch(msg) @@ -155,9 +160,8 @@ async def _search_batch( search_url=search_url, headers=_search_headers(auth), cache=cache, - polls=polls, - extras=extras, - auth=auth, + results=_SearchResults(polls=polls, extras=extras), + auth=_AuthSlot(auth), counter={"done": 0, "found": 0, "failed": 0}, total=len(games), progress_cb=progress_cb, diff --git a/steam_backlog_enforcer/_hltb_search_one.py b/steam_backlog_enforcer/_hltb_search_one.py index a7aa262..44b2b7e 100644 --- a/steam_backlog_enforcer/_hltb_search_one.py +++ b/steam_backlog_enforcer/_hltb_search_one.py @@ -47,6 +47,27 @@ from steam_backlog_enforcer._hltb_types import ( logger = logging.getLogger(__name__) +@dataclass +class _AuthSlot: + """The search token, when it was issued (monotonic), its renewal lock.""" + + info: _AuthInfo | None = None + issued_at: float = field(default_factory=time.monotonic) + lock: asyncio.Lock = field(default_factory=asyncio.Lock) + + +@dataclass +class _SearchResults: + """What the lookups record besides hours: polls, extras and failures.""" + + polls: dict[int, int] = field(default_factory=dict) + extras: _HLTBExtras = field(default_factory=_HLTBExtras) + failed_ids: set[int] = field(default_factory=set) + """Games whose lookup failed (the breaker reports them by id).""" + dirty: bool = False + """Only flush incrementally once something was actually written.""" + + @dataclass class _SearchCtx: """Shared context for HLTB search requests.""" @@ -55,20 +76,12 @@ class _SearchCtx: search_url: str headers: dict[str, str] cache: dict[int, float] - polls: dict[int, int] = field(default_factory=dict) - extras: _HLTBExtras = field(default_factory=_HLTBExtras) - auth: _AuthInfo | None = None + results: _SearchResults = field(default_factory=_SearchResults) + auth: _AuthSlot = field(default_factory=_AuthSlot) counter: dict[str, int] = field(default_factory=dict) total: int = 0 progress_cb: ProgressCb | None = None breaker: Breaker = field(default_factory=Breaker) - # When ``auth`` was issued (monotonic) and the lock for renewing it. - auth_at: float = field(default_factory=time.monotonic) - auth_lock: asyncio.Lock = field(default_factory=asyncio.Lock) - # Games whose lookup failed (the breaker reports them by id). - failed_ids: set[int] = field(default_factory=set) - # Only flush incrementally once something was actually written. - dirty: bool = False _Best = tuple[dict[str, Any], float] @@ -107,7 +120,7 @@ async def _query_variant( Returns ``(best, None)`` on a match, ``(None, None)`` on a clean 200 with no usable entry, and ``(None, reason)`` when the request itself failed. """ - payload = _build_search_payload(query_name, ctx.auth) + payload = _build_search_payload(query_name, ctx.auth.info) try: async with ctx.session.post( ctx.search_url, headers=ctx.headers, data=payload @@ -135,23 +148,23 @@ def _record_outcome( """Write a match or a clean miss; a failed lookup keeps the old entry.""" if result is not None: ctx.cache[app_id] = result.completionist_hours - ctx.polls[app_id] = result.comp_100_count - ctx.extras.count_comp[app_id] = result.count_comp + ctx.results.polls[app_id] = result.comp_100_count + ctx.results.extras.count_comp[app_id] = result.count_comp if result.hltb_game_id > 0: - ctx.extras.hltb_game_id[app_id] = result.hltb_game_id + ctx.results.extras.hltb_game_id[app_id] = result.hltb_game_id ctx.counter["found"] += 1 - ctx.dirty = True + ctx.results.dirty = True record_success() elif failure is not None: ctx.counter["failed"] += 1 - ctx.failed_ids.add(app_id) + ctx.results.failed_ids.add(app_id) record_failure(failure) else: # Every variant answered cleanly with nothing usable: a real miss. ctx.cache[app_id] = -1 - ctx.polls[app_id] = 0 - ctx.extras.count_comp[app_id] = 0 - ctx.dirty = True + ctx.results.polls[app_id] = 0 + ctx.results.extras.count_comp[app_id] = 0 + ctx.results.dirty = True record_success() @@ -188,8 +201,8 @@ async def _search_one( done = ctx.counter["done"] # Incremental save every _SAVE_INTERVAL lookups. - if ctx.dirty and not done % _SAVE_INTERVAL: - save_hltb_cache(ctx.cache, ctx.polls, ctx.extras) + if ctx.results.dirty and not done % _SAVE_INTERVAL: + save_hltb_cache(ctx.cache, ctx.results.polls, ctx.results.extras) # Report progress. if ctx.progress_cb is not None: diff --git a/steam_backlog_enforcer/tests/test_hltb_auth_refresh.py b/steam_backlog_enforcer/tests/test_hltb_auth_refresh.py index 150caee..102f51a 100644 --- a/steam_backlog_enforcer/tests/test_hltb_auth_refresh.py +++ b/steam_backlog_enforcer/tests/test_hltb_auth_refresh.py @@ -19,7 +19,11 @@ from steam_backlog_enforcer._hltb_failures import ( Breaker, failure_summary_lines, ) -from steam_backlog_enforcer._hltb_search_one import _search_one, _SearchCtx +from steam_backlog_enforcer._hltb_search_one import ( + _AuthSlot, + _search_one, + _SearchCtx, +) from steam_backlog_enforcer._hltb_types import _AuthInfo from steam_backlog_enforcer.tests._hltb_fake_transport import MATCH, FakeResp @@ -84,10 +88,9 @@ def _ctx(session: _RotatingSession, clock: _Clock) -> _SearchCtx: search_url="https://example.invalid/api/finder", headers={"x-auth-token": "tok0", "x-hp-key": "hp", "x-hp-val": "v0"}, cache={}, - auth=_AuthInfo("tok0", "hp", "v0"), + auth=_AuthSlot(_AuthInfo("tok0", "hp", "v0"), issued_at=clock.t), counter={"done": 0, "found": 0, "failed": 0}, breaker=Breaker(), - auth_at=clock.t, ) @@ -119,7 +122,7 @@ def test_aged_token_is_refreshed_into_headers_and_body() -> None: _lookups(ctx, clock, [0, _AGE + 1]) assert session.gets == 1 assert session.posts == [("tok0", "v0"), ("tok1", "v1")] - assert ctx.auth == _AuthInfo("tok1", "hp", "v1") + assert ctx.auth.info == _AuthInfo("tok1", "hp", "v1") def test_one_refresh_per_elapsed_interval() -> None: diff --git a/steam_backlog_enforcer/tests/test_hltb_pacing.py b/steam_backlog_enforcer/tests/test_hltb_pacing.py index e53308c..5714985 100644 --- a/steam_backlog_enforcer/tests/test_hltb_pacing.py +++ b/steam_backlog_enforcer/tests/test_hltb_pacing.py @@ -15,7 +15,11 @@ import pytest from steam_backlog_enforcer import _hltb_pacing from steam_backlog_enforcer._hltb_comp_extract import _fetch_detail_one from steam_backlog_enforcer._hltb_failures import BREAKER_LIMIT, shared_breaker -from steam_backlog_enforcer._hltb_search_one import _search_one, _SearchCtx +from steam_backlog_enforcer._hltb_search_one import ( + _AuthSlot, + _search_one, + _SearchCtx, +) from steam_backlog_enforcer._hltb_types import MAX_CONCURRENT, _AuthInfo from steam_backlog_enforcer.tests._hltb_fake_transport import ( MATCH, @@ -49,7 +53,7 @@ def _ctx(session: FakeSession) -> _SearchCtx: search_url="https://example.invalid/api/finder", headers={}, cache={}, - auth=_AuthInfo("t"), + auth=_AuthSlot(_AuthInfo("t")), counter={"done": 0, "found": 0, "failed": 0}, ) diff --git a/steam_backlog_enforcer/tests/test_hltb_search.py b/steam_backlog_enforcer/tests/test_hltb_search.py index 0941619..052ebbc 100644 --- a/steam_backlog_enforcer/tests/test_hltb_search.py +++ b/steam_backlog_enforcer/tests/test_hltb_search.py @@ -47,7 +47,7 @@ class TestSearchOne: ctx = _ctx(make_session(FakeResponse(200, hit("TF2", 180000, 0)))) result = run_search(ctx) assert result is not None - assert 440 not in ctx.extras.hltb_game_id + assert 440 not in ctx.results.extras.hltb_game_id def test_not_found(self) -> None: """Test not found.""" diff --git a/steam_backlog_enforcer/tests/test_hltb_search_failure_keeps_cache.py b/steam_backlog_enforcer/tests/test_hltb_search_failure_keeps_cache.py index adb80b6..2f7fac6 100644 --- a/steam_backlog_enforcer/tests/test_hltb_search_failure_keeps_cache.py +++ b/steam_backlog_enforcer/tests/test_hltb_search_failure_keeps_cache.py @@ -15,7 +15,12 @@ from steam_backlog_enforcer._hltb_failures import ( failure_summary_lines, reset_failures, ) -from steam_backlog_enforcer._hltb_search_one import _search_one, _SearchCtx +from steam_backlog_enforcer._hltb_search_one import ( + _AuthSlot, + _search_one, + _SearchCtx, + _SearchResults, +) from steam_backlog_enforcer._hltb_types import _AuthInfo, _HLTBExtras from steam_backlog_enforcer.tests._hltb_fake_transport import ( MATCH, @@ -25,15 +30,19 @@ from steam_backlog_enforcer.tests._hltb_fake_transport import ( ) +def _saved(ctx: _SearchCtx) -> tuple[float, int, int]: + """Game 1's cached hours, poll count and completionist count.""" + return ctx.cache[1], ctx.results.polls[1], ctx.results.extras.count_comp[1] + + def _ctx(session: FakeSession, total: int = 1) -> _SearchCtx: return _SearchCtx( session=cast("aiohttp.ClientSession", session), search_url="https://example.invalid/api/finder", headers={}, cache={1: 50.0}, - polls={1: 120}, - extras=_HLTBExtras(count_comp={1: 900}), - auth=_AuthInfo("t"), + results=_SearchResults(polls={1: 120}, extras=_HLTBExtras(count_comp={1: 900})), + auth=_AuthSlot(_AuthInfo("t")), counter={"done": 0, "found": 0, "failed": 0}, total=total, ) @@ -64,8 +73,8 @@ def test_failed_search_keeps_prior_entry(kind: str) -> None: ctx = _ctx(FakeSession({"*": _FAILURES[kind]})) _run(ctx, 1, "Celeste") assert ctx.cache[1] == 50.0 - assert ctx.polls[1] == 120 - assert ctx.extras.count_comp[1] == 900 + assert ctx.results.polls[1] == 120 + assert ctx.results.extras.count_comp[1] == 900 assert ctx.counter["failed"] == 1 assert ctx.counter["found"] == 0 @@ -75,7 +84,11 @@ def test_failed_variant_blocks_a_miss() -> None: routes = {"Vox Populi Poland 2023": FakeResp(200, NO_MATCH), "*": FakeResp(429)} ctx = _ctx(FakeSession(routes)) _run(ctx, 1, "Vox Populi: Poland 2023") - assert (ctx.cache[1], ctx.polls[1], ctx.extras.count_comp[1]) == (50.0, 120, 900) + assert _saved(ctx) == ( + 50.0, + 120, + 900, + ) assert ctx.counter["failed"] == 1 @@ -84,7 +97,11 @@ def test_match_beats_failed_sibling_variant() -> None: routes = {"Vox Populi Poland 2023": FakeResp(429), "*": FakeResp(200, MATCH)} ctx = _ctx(FakeSession(routes)) _run(ctx, 1, "Vox Populi: Poland 2023") - assert (ctx.cache[1], ctx.polls[1], ctx.extras.count_comp[1]) == (10.0, 42, 300) + assert _saved(ctx) == ( + 10.0, + 42, + 300, + ) assert ctx.counter == {"done": 1, "found": 1, "failed": 0} @@ -92,7 +109,11 @@ def test_clean_no_match_still_writes_a_miss() -> None: """Every variant answered 200 with nothing usable: that is a real miss.""" ctx = _ctx(FakeSession({"*": FakeResp(200, NO_MATCH)})) _run(ctx, 1, "Vox Populi: Poland 2023") - assert (ctx.cache[1], ctx.polls[1], ctx.extras.count_comp[1]) == (-1, 0, 0) + assert _saved(ctx) == ( + -1, + 0, + 0, + ) assert ctx.counter["failed"] == 0 @@ -101,8 +122,8 @@ def test_failure_without_prior_entry_writes_nothing() -> None: ctx = _ctx(FakeSession({"*": FakeResp(429)})) _run(ctx, 2, "Celeste") assert 2 not in ctx.cache - assert 2 not in ctx.polls - assert 2 not in ctx.extras.count_comp + assert 2 not in ctx.results.polls + assert 2 not in ctx.results.extras.count_comp assert ctx.counter == {"done": 1, "found": 0, "failed": 1}