Tighten full scan polling and document it

Stop polling once the next attempt could not start before the deadline instead of sleeping out the budget, give each request the configured timeout rather than a fixed 30s cap, and document the polling parameters in the README.

Author: lelia

CHANGELOG.md

@@ -15,8 +15,9 @@
 - The polling budget defaults to the SDK's configured `timeout`. Callers can
   tune it with the new keyword-only arguments `poll_timeout_seconds`,
   `poll_initial_interval_seconds` and `poll_max_interval_seconds`. Each
-  individual request is capped at 30 seconds or the remaining budget,
-  whichever is shorter.
+  request is bounded by the configured `timeout` or the remaining budget,
+  whichever is shorter, and polling stops early once the next attempt could
+  not start before the budget runs out.
 - Transient failures (HTTP 408/502/503/504, timeouts, dropped connections) are
   retried within the budget. Authorization, not-found and quota errors still
   raise immediately.

README.rst

@@ -291,7 +291,11 @@ Stream a diff between two full scans. Returns a scan diff.
 
 fullscans.stream(org_slug, full_scan_id, use_types=False)
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""
-Stream all SBOM artifacts for a full scan.
+Stream all SBOM artifacts for a full scan. If the scan is still being analyzed, the SDK polls
+cached results until they are ready, backing off from 5 to 10 seconds between attempts, and
+raises ``APITimeout`` if they are not ready within the polling budget. Transient failures
+(HTTP 408/502/503/504, timeouts, dropped connections) are retried within the budget; other
+errors raise immediately.
 
 **Usage:**
 
@@ -304,11 +308,17 @@ Stream all SBOM artifacts for a full scan.
     # With typed response
     print(socket.fullscans.stream("org_slug", "full_scan_id", use_types=True))
 
+    # Wait up to 10 minutes for analysis to finish
+    print(socket.fullscans.stream("org_slug", "full_scan_id", poll_timeout_seconds=600))
+
 **PARAMETERS:**
 
 - **org_slug (str)** - The organization name
 - **full_scan_id (str)** - The ID of the full scan
 - **use_types (bool)** - Whether to return typed response objects (default: False)
+- **poll_timeout_seconds (float)** - Keyword-only. Total time to wait for results (default: the SDK's configured ``timeout``)
+- **poll_initial_interval_seconds (float)** - Keyword-only. Wait before the first retry (default: 5.0)
+- **poll_max_interval_seconds (float)** - Keyword-only. Longest wait between retries (default: 10.0)
 
 fullscans.metadata(org_slug, full_scan_id, use_types=False)
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""

socketdev/fullscans/__init__.py

@@ -994,33 +994,27 @@ def stream(
         deadline = time.monotonic() + timeout
         interval = poll_initial_interval_seconds
         while True:
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                raise APITimeout("Timed out waiting for full scan results")
+            retry_error = None
             try:
                 response = self.api.do_request(
                     path=path,
                     method="GET",
-                    request_timeout=min(30.0, float(request_timeout), remaining),
+                    request_timeout=min(float(request_timeout), max(deadline - time.monotonic(), 0.001)),
                 )
             except APIFailure as error:
                 if not error.is_transient_error():
                     raise
-                remaining = deadline - time.monotonic()
-                if remaining <= 0:
-                    raise APITimeout("Timed out waiting for full scan results") from error
-                time.sleep(min(interval, remaining))
-                interval = min(poll_max_interval_seconds, interval * 1.5)
-                continue
-            if response.status_code == 202:
+                retry_error = error
+            else:
+                if response.status_code != 202:
+                    break
                 response.close()
-                remaining = deadline - time.monotonic()
-                if remaining <= 0:
-                    raise APITimeout("Timed out waiting for full scan results")
-                time.sleep(min(interval, remaining))
-                interval = min(poll_max_interval_seconds, interval * 1.5)
-                continue
-            break
+            # Give up now if the next attempt could not start before the deadline,
+            # rather than sleeping out the rest of the budget and never polling again.
+            if deadline - time.monotonic() <= interval:
+                raise APITimeout("Timed out waiting for full scan results") from retry_error
+            time.sleep(interval)
+            interval = min(poll_max_interval_seconds, interval * 1.5)
 
         if response.status_code == 200:
             try:

tests/unit/test_full_scan_cached_polling_http.py

@@ -1,4 +1,5 @@
 import json
+import time
 
 import pytest
 
@@ -153,3 +154,29 @@ def test_invalid_configured_request_timeout_fails_before_request(api_fixture, va
     with pytest.raises(ValueError):
         sdk.fullscans.stream("org", "scan", poll_timeout_seconds=0.1)
     assert not api_fixture.requests
+
+
+def test_gives_up_without_sleeping_when_next_poll_cannot_start(api_fixture):
+    api_fixture.route("GET", "orgs/org/full-scans/scan", SocketResponse(202, {}))
+    start = time.monotonic()
+    with pytest.raises(APITimeout, match="full scan results"):
+        sdk_for(api_fixture).fullscans.stream(
+            "org", "scan", poll_timeout_seconds=0.5, poll_initial_interval_seconds=5,
+        )
+    assert time.monotonic() - start < 0.4
+    assert len(api_fixture.requests) == 1
+
+
+def test_first_request_uses_full_configured_timeout(api_fixture):
+    api_fixture.route("GET", "orgs/org/full-scans/scan", ndjson())
+    sdk = sdk_for(api_fixture, timeout=120)
+    do_request = sdk.api.do_request
+    timeouts = []
+
+    def spy(**kwargs):
+        timeouts.append(kwargs["request_timeout"])
+        return do_request(**kwargs)
+
+    sdk.api.do_request = spy
+    sdk.fullscans.stream("org", "scan")
+    assert timeouts and timeouts[0] > 100