fix: follow offset cursors in either direction

Author: meliaj

src/kernel/pagination.py

@@ -133,11 +133,10 @@ def next_page_info(self) -> Optional[PageInfo]:
         if next_offset == 0:
             return None
 
-        # A next offset at or before the one this page was requested at means no
-        # progress (e.g. an empty page after rows vanished mid-request); stop
-        # instead of re-requesting the same page.
+        # Cursors can move in either direction. Stop only when the server repeats
+        # the cursor and would re-request the same page.
         request_offset = self._options.params.get("offset")
-        if isinstance(request_offset, int) and next_offset <= request_offset:
+        if isinstance(request_offset, int) and next_offset == request_offset:
             return None
 
         return PageInfo(params={"offset": next_offset})
@@ -191,11 +190,10 @@ def next_page_info(self) -> Optional[PageInfo]:
         if next_offset == 0:
             return None
 
-        # A next offset at or before the one this page was requested at means no
-        # progress (e.g. an empty page after rows vanished mid-request); stop
-        # instead of re-requesting the same page.
+        # Cursors can move in either direction. Stop only when the server repeats
+        # the cursor and would re-request the same page.
         request_offset = self._options.params.get("offset")
-        if isinstance(request_offset, int) and next_offset <= request_offset:
+        if isinstance(request_offset, int) and next_offset == request_offset:
             return None
 
         return PageInfo(params={"offset": next_offset})

tests/test_pagination.py

@@ -89,12 +89,21 @@ def test_stops_on_empty_page_when_x_has_more_false(cls: PageClass) -> None:
 
 
 @both_classes
-def test_stops_when_next_offset_does_not_advance(cls: PageClass) -> None:
+def test_stops_when_next_offset_repeats_requested_offset(cls: PageClass) -> None:
     page = _page(cls, items=[], next_offset=200, has_more=True, request_offset=200)
     assert page.next_page_info() is None
     assert page.has_next_page() is False
 
 
+@both_classes
+def test_continues_past_empty_page_with_descending_cursor(cls: PageClass) -> None:
+    page = _page(cls, items=[], next_offset=200, has_more=True, request_offset=300)
+    assert page.has_next_page() is True
+    info = page.next_page_info()
+    assert info is not None
+    assert info.params == {"offset": 200}
+
+
 @both_classes
 def test_stops_on_empty_first_page_without_pagination_headers(cls: PageClass) -> None:
     page = _page(cls, items=[], next_offset=None, has_more=None)