Handle Steam rate limits with bounded cooldown and safe status

Keep existing Space access settings and simulator binaries. Fix required Id, Stats and Snapshots in exported game networks. Add optional read-only Steam comparison, run-wide best lap and bounded request admission. Formula remains the only hosted vehicle.

RELEASE_MANIFEST.json

@@ -60,8 +60,8 @@
     "hf_identity.py": "6993d0238ada835606dbdc3275c17a3fe5a5cac5ad2156ab78230acf2d051eba",
     "index.html": "713496757a5fa796cf35eb9fba7a4f29b0eb2f8abdd6c8e3a6fdfd8036a3a30f",
     "requirements.txt": "9b532747e51bd052e82090ece860d6dafe027407f4512dc74272c148ea104c22",
-    "server.py": "af567a30347bbcb75dda324408c47bc2fa8b519693d95c450403fd3012eb8fc5",
-    "steam_leaderboard.py": "0f2dbe9615f1bcda2e8f4399a2fa4257ef86a751887dd0b41e0f65034ed3138b",
+    "server.py": "679a5f36997a2c3c2808e71402588789b8fd3e246b4da4ed0a5f6f5621d138c3",
+    "steam_leaderboard.py": "d76397c39cae58f636ddf9a9be1a46ae3d77fefd6b7269feac73d34d97165481",
     "track-library.js": "351ec4c026b49420ce963f4310cb000d9e987fd28e6dac5ecd0176509340f6e6",
     "track-map.js": "ab5374aa49c7ccec90a787ee8c56cd71beb56b903bf2bbc322783e6f43c009f0",
     "training_config.py": "a0dd095e0de8c5a964ace66954f346e5d7b861db3d34cd2feaceedc5ecb80bad",

server.py

@@ -50,8 +50,14 @@ def create_app(worker=run_reported,store=None,gpu_worker=None,track_library=None
             return {'status':'busy','message':'Another Steam check is in progress. The completed result is unaffected.'}
         try:
             return await run_in_threadpool(compare_public_best_lap,entry,body['lap_seconds'])
-        except SteamUnavailable:
-            return {'status':'unavailable','message':'Steam could not provide a complete public leaderboard. The completed result is unaffected.'}
+        except SteamUnavailable as error:
+            result={'status':'unavailable','failure_category':error.failure_category,
+                'message':'Steam could not provide a complete public leaderboard. The completed result is unaffected.'}
+            if error.failure_category == 'rate_limited':
+                result['message']='Steam is limiting leaderboard requests. Checks pause for one minute; your completed result is unaffected.'
+            if error.upstream_http_status is not None:
+                result['upstream_http_status']=error.upstream_http_status
+            return result
         finally:
             leaderboard_admission.release()
     @app.get('/api/tracks/{identifier}/file')

steam_leaderboard.py

@@ -4,8 +4,10 @@ from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
 from html.parser import HTMLParser
 import hashlib
 import re
+import socket
 import threading
 import time
+from urllib.error import HTTPError, URLError
 from urllib.parse import urlparse
 from urllib.request import Request, urlopen
 import xml.etree.ElementTree as ET
@@ -17,15 +19,28 @@ TIMEOUT_SECONDS = 4
 TOTAL_TIMEOUT_SECONDS = 10
 INDEX_TTL_SECONDS = 300
 BOARD_TTL_SECONDS = 60
+RATE_LIMIT_COOLDOWN_SECONDS = 60
+FAILURE_CATEGORIES = frozenset({
+    'rate_limited', 'upstream_http_error', 'timeout', 'network_error', 'invalid_response',
+})
 
 _cache_lock = threading.Lock()
+_rate_limit_lock = threading.Lock()
 _index_cache = None
 _board_cache = {}
+_rate_limited_until = 0.0
 
 
 class SteamUnavailable(Exception):
     """The public Community endpoint could not provide a validated board."""
 
+    def __init__(self, message, *, failure_category='invalid_response', upstream_http_status=None):
+        if failure_category not in FAILURE_CATEGORIES:
+            raise ValueError('Unknown Steam failure category')
+        self.failure_category = failure_category
+        self.upstream_http_status = upstream_http_status
+        super().__init__(message)
+
 
 class BoardOptions(HTMLParser):
     def __init__(self):
@@ -55,29 +70,57 @@ class BoardOptions(HTMLParser):
 def _read(url):
     # Callers pass only INDEX_URL or a URL assembled from a numeric ID in that
     # verified public index. No request data is placed in a Steam URL.
+    global _rate_limited_until
+    now = time.monotonic()
+    with _rate_limit_lock:
+        if now < _rate_limited_until:
+            raise SteamUnavailable(
+                'Steam public leaderboard is cooling down after rate limiting',
+                failure_category='rate_limited', upstream_http_status=429,
+            )
+        if _rate_limited_until:
+            _rate_limited_until = 0.0
     request = Request(url, headers={'User-Agent': 'ALD-hosted-public-board-check/1.0'})
     started = time.monotonic()
     try:
         with urlopen(request, timeout=TIMEOUT_SECONDS) as response:
             final = urlparse(response.geturl())
             if final.scheme != 'https' or final.hostname != 'steamcommunity.com':
-                raise SteamUnavailable('Steam public leaderboard redirected outside its fixed host')
+                raise SteamUnavailable('Steam public leaderboard redirected outside its fixed host', failure_category='invalid_response')
             chunks, size = [], 0
             while True:
                 if time.monotonic() - started >= TOTAL_TIMEOUT_SECONDS:
-                    raise SteamUnavailable('Steam public leaderboard request exceeded its time limit')
+                    raise SteamUnavailable('Steam public leaderboard request exceeded its time limit', failure_category='timeout')
                 chunk = response.read(min(65536, MAX_BYTES + 1 - size))
                 if not chunk:
                     break
                 chunks.append(chunk)
                 size += len(chunk)
                 if size > MAX_BYTES:
-                    raise SteamUnavailable('Steam public leaderboard response exceeded the size limit')
+                    raise SteamUnavailable('Steam public leaderboard response exceeded the size limit', failure_category='invalid_response')
             return b''.join(chunks)
     except SteamUnavailable:
         raise
+    except HTTPError as error:
+        if error.code == 429:
+            with _rate_limit_lock:
+                _rate_limited_until = max(_rate_limited_until, time.monotonic() + RATE_LIMIT_COOLDOWN_SECONDS)
+            raise SteamUnavailable(
+                'Steam public leaderboard is rate limited',
+                failure_category='rate_limited', upstream_http_status=429,
+            ) from error
+        raise SteamUnavailable(
+            'Steam public leaderboard returned an HTTP error',
+            failure_category='upstream_http_error', upstream_http_status=error.code,
+        ) from error
+    except (socket.timeout, TimeoutError) as error:
+        raise SteamUnavailable('Steam public leaderboard request timed out', failure_category='timeout') from error
+    except URLError as error:
+        if isinstance(error.reason, (socket.timeout, TimeoutError)):
+            raise SteamUnavailable('Steam public leaderboard request timed out', failure_category='timeout') from error
+        raise SteamUnavailable('Steam public leaderboard network request failed', failure_category='network_error') from error
     except Exception as error:
-        raise SteamUnavailable('Steam public leaderboard is temporarily unavailable') from error
+        raise SteamUnavailable('Steam public leaderboard network request failed', failure_category='network_error') from error
 
 
 def _index():
@@ -91,14 +134,14 @@ def _index():
         try:
             parser.feed(raw.decode('utf-8'))
         except (UnicodeDecodeError, ValueError) as error:
-            raise SteamUnavailable('Steam public leaderboard index was invalid') from error
+            raise SteamUnavailable('Steam public leaderboard index was invalid', failure_category='invalid_response') from error
         if parser.duplicate:
-            raise SteamUnavailable('Steam public leaderboard index had duplicate IDs')
+            raise SteamUnavailable('Steam public leaderboard index had duplicate IDs', failure_category='invalid_response')
         boards = {}
         for identifier, label in parser.options.items():
             if identifier.isdecimal() and label:
                 if label in boards:
-                    raise SteamUnavailable('Steam public leaderboard index had ambiguous track labels')
+                    raise SteamUnavailable('Steam public leaderboard index had ambiguous track labels', failure_category='invalid_response')
                 boards[label] = (int(identifier), label)
         fetched = datetime.now(timezone.utc).isoformat()
         _index_cache = (now, {'boards': boards, 'sha256': hashlib.sha256(raw).hexdigest(), 'fetched_at_utc': fetched})
@@ -126,7 +169,7 @@ def _parse_board(raw, board_id):
         if count < 1 or received != count or len(entries) != count:
             raise ValueError()
     except (ET.ParseError, TypeError, ValueError, OverflowError) as error:
-        raise SteamUnavailable('Steam returned an incomplete or mismatched leaderboard') from error
+        raise SteamUnavailable('Steam returned an incomplete or mismatched leaderboard', failure_category='invalid_response') from error
     return entries
 
 
@@ -222,7 +265,9 @@ def compare_public_best_lap(track, lap_seconds):
 
 
 def _reset_cache_for_tests():
-    global _index_cache
+    global _index_cache, _rate_limited_until
     with _cache_lock:
         _index_cache = None
         _board_cache.clear()
+    with _rate_limit_lock:
+        _rate_limited_until = 0.0