Validate pagination page-batch metadata bounds

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/client/polling.py

@@ -62,6 +62,38 @@ def _validate_max_wait_seconds(max_wait_seconds: Optional[float]) -> None:
         raise HyperbrowserError("max_wait_seconds must be non-negative")
 
 
+def _validate_page_batch_values(
+    *,
+    operation_name: str,
+    current_page_batch: int,
+    total_page_batches: int,
+) -> None:
+    if isinstance(current_page_batch, bool) or not isinstance(current_page_batch, int):
+        raise HyperbrowserPollingError(
+            f"Invalid current page batch for {operation_name}: expected integer"
+        )
+    if isinstance(total_page_batches, bool) or not isinstance(total_page_batches, int):
+        raise HyperbrowserPollingError(
+            f"Invalid total page batches for {operation_name}: expected integer"
+        )
+    if total_page_batches < 0:
+        raise HyperbrowserPollingError(
+            f"Invalid total page batches for {operation_name}: must be non-negative"
+        )
+    if current_page_batch < 0:
+        raise HyperbrowserPollingError(
+            f"Invalid current page batch for {operation_name}: must be non-negative"
+        )
+    if total_page_batches > 0 and current_page_batch < 1:
+        raise HyperbrowserPollingError(
+            f"Invalid current page batch for {operation_name}: must be at least 1 when total batches are positive"
+        )
+    if current_page_batch > total_page_batches:
+        raise HyperbrowserPollingError(
+            f"Invalid page batch state for {operation_name}: current page batch {current_page_batch} exceeds total page batches {total_page_batches}"
+        )
+
+
 def has_exceeded_max_wait(start_time: float, max_wait_seconds: Optional[float]) -> bool:
     return (
         max_wait_seconds is not None
@@ -241,6 +273,11 @@ def collect_paginated_results(
             on_page_success(page_response)
             current_page_batch = get_current_page_batch(page_response)
             total_page_batches = get_total_page_batches(page_response)
+            _validate_page_batch_values(
+                operation_name=operation_name,
+                current_page_batch=current_page_batch,
+                total_page_batches=total_page_batches,
+            )
             failures = 0
             first_check = False
             if (
@@ -303,6 +340,11 @@ async def collect_paginated_results_async(
             on_page_success(page_response)
             current_page_batch = get_current_page_batch(page_response)
             total_page_batches = get_total_page_batches(page_response)
+            _validate_page_batch_values(
+                operation_name=operation_name,
+                current_page_batch=current_page_batch,
+                total_page_batches=total_page_batches,
+            )
             failures = 0
             first_check = False
             if (

tests/test_polling.py

@@ -303,6 +303,20 @@ def test_collect_paginated_results_raises_when_page_batch_stagnates():
         )
 
 
+def test_collect_paginated_results_raises_on_invalid_page_batch_values():
+    with pytest.raises(HyperbrowserPollingError, match="Invalid page batch state"):
+        collect_paginated_results(
+            operation_name="sync paginated invalid batches",
+            get_next_page=lambda page: {"current": 3, "total": 2, "items": []},
+            get_current_page_batch=lambda response: response["current"],
+            get_total_page_batches=lambda response: response["total"],
+            on_page_success=lambda response: None,
+            max_wait_seconds=1.0,
+            max_attempts=2,
+            retry_delay_seconds=0.0001,
+        )
+
+
 def test_collect_paginated_results_async_times_out():
     async def run() -> None:
         with pytest.raises(
@@ -312,7 +326,7 @@ async def run() -> None:
             await collect_paginated_results_async(
                 operation_name="async paginated timeout",
                 get_next_page=lambda page: asyncio.sleep(
-                    0, result={"current": 0, "total": 1, "items": []}
+                    0, result={"current": 1, "total": 2, "items": []}
                 ),
                 get_current_page_batch=lambda response: response["current"],
                 get_total_page_batches=lambda response: response["total"],
@@ -344,6 +358,25 @@ async def run() -> None:
     asyncio.run(run())
 
 
+def test_collect_paginated_results_async_raises_on_invalid_page_batch_values():
+    async def run() -> None:
+        with pytest.raises(HyperbrowserPollingError, match="Invalid page batch state"):
+            await collect_paginated_results_async(
+                operation_name="async paginated invalid batches",
+                get_next_page=lambda page: asyncio.sleep(
+                    0, result={"current": 3, "total": 2, "items": []}
+                ),
+                get_current_page_batch=lambda response: response["current"],
+                get_total_page_batches=lambda response: response["total"],
+                on_page_success=lambda response: None,
+                max_wait_seconds=1.0,
+                max_attempts=2,
+                retry_delay_seconds=0.0001,
+            )
+
+    asyncio.run(run())
+
+
 def test_wait_for_job_result_returns_fetched_value():
     status_values = iter(["running", "completed"])