Skip to content

Commit 17e637e

Browse files
committed
fix: list commands fetch every page by default
Six list commands (zone/record/tsig/messages/report problematic-zones/ acme list-challenges) previously truncated at the first API page (50 rows, 100 for ACME) with exit code 0 and no warning. A zone with 50 RRsets and a zone with thousands looked identical on screen, which caused an operational incident where records were declared absent because they had been silently paginated off the first page. Default behavior now fetches every page. `--all` is kept as an accepted no-op for script compatibility. `--page N` remains the explicit single-page path and now prints a stderr warning when more rows exist (envelope shape) or may exist (bare-array shape); `-q` / `--quiet` suppresses it. JSON/YAML stdout stays clean — warnings are stderr-only. Adds `PageInfo` + `fetch_page()` to the paginator for the single-page path, `_warn_if_truncated()` helper in commands, and 15 new tests (9 integration regressions + 6 paginator unit tests). Rewrites the pagination topic doc.
1 parent db6b425 commit 17e637e

24 files changed

Lines changed: 1023 additions & 117 deletions

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Changed
11+
- List commands (`zone list`, `record list`, `tsig list`, `messages list`,
12+
`report problematic-zones`, `acme list-challenges`) now fetch all pages by
13+
default. Previously they silently truncated at 50 rows (100 for ACME) with
14+
no indication that more results existed, causing an operational incident
15+
where records were declared absent because they had been paginated off the
16+
first page. `--all` remains accepted for script compatibility. `--page N`
17+
still selects a single page and now prints a stderr warning when more rows
18+
exist; pass `-q` / `--quiet` to suppress it.
19+
1020
## [1.0.8] — 2026-04-24
1121

1222
### Added

‎src/rc0/api/acme.py‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,11 @@
44

55
from typing import TYPE_CHECKING, Any
66

7-
from rc0.client.pagination import iter_all, iter_pages
7+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
88

99
if TYPE_CHECKING:
1010
from rc0.client.http import Client
11+
from rc0.client.pagination import PageInfo
1112

1213

1314
def zone_exists(client: Client, zone: str) -> list[str]:
@@ -23,12 +24,33 @@ def list_challenges(
2324
*,
2425
page: int | None = None,
2526
page_size: int | None = None,
26-
fetch_all: bool = False,
27+
fetch_all: bool = True,
2728
) -> list[dict[str, Any]]:
28-
"""GET /api/v1/acme/zones/{zone}/rrsets — return TXT challenge records."""
29+
"""GET /api/v1/acme/zones/{zone}/rrsets — TXT challenge records.
30+
31+
Defaults to fetching every page (``page_size`` defaults to 100, matching
32+
the v1 ACME endpoint's own default).
33+
"""
2934
effective_page_size = page_size or 100
3035
path = f"/api/v1/acme/zones/{zone}/rrsets"
3136
if fetch_all:
3237
return [dict(row) for row in iter_all(client, path, page_size=effective_page_size)]
3338
page_iter = iter_pages(client, path, page_size=effective_page_size, start_page=page or 1)
3439
return [dict(row) for row in next(iter(page_iter), [])]
40+
41+
42+
def list_challenges_page(
43+
client: Client,
44+
zone: str,
45+
*,
46+
page: int,
47+
page_size: int | None = None,
48+
) -> tuple[list[dict[str, Any]], PageInfo]:
49+
"""Fetch exactly one page of ACME challenges with pagination metadata."""
50+
rows, info = fetch_page(
51+
client,
52+
f"/api/v1/acme/zones/{zone}/rrsets",
53+
page=page,
54+
page_size=page_size or 100,
55+
)
56+
return [dict(row) for row in rows], info

‎src/rc0/api/messages.py‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@
44

55
from typing import TYPE_CHECKING
66

7-
from rc0.client.pagination import iter_all, iter_pages
7+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
88
from rc0.models.messages import Message
99

1010
if TYPE_CHECKING:
1111
from rc0.client.http import Client
12+
from rc0.client.pagination import PageInfo
1213

1314

1415
def poll_message(client: Client) -> Message | None:
@@ -24,9 +25,9 @@ def list_messages(
2425
*,
2526
page: int | None = None,
2627
page_size: int | None = None,
27-
fetch_all: bool = False,
28+
fetch_all: bool = True,
2829
) -> list[Message]:
29-
"""GET /api/v2/messages/list — Laravel envelope."""
30+
"""GET /api/v2/messages/list — Laravel envelope. Defaults to all pages."""
3031
effective_page_size = page_size or 50
3132
if fetch_all:
3233
rows = list(
@@ -41,3 +42,19 @@ def list_messages(
4142
)
4243
rows = next(iter(page_iterator), [])
4344
return [Message.model_validate(r) for r in rows]
45+
46+
47+
def list_messages_page(
48+
client: Client,
49+
*,
50+
page: int,
51+
page_size: int | None = None,
52+
) -> tuple[list[Message], PageInfo]:
53+
"""Fetch exactly one page of messages with pagination metadata."""
54+
rows, info = fetch_page(
55+
client,
56+
"/api/v2/messages/list",
57+
page=page,
58+
page_size=page_size or 50,
59+
)
60+
return [Message.model_validate(r) for r in rows], info

‎src/rc0/api/reports.py‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
from datetime import date, timedelta
1515
from typing import TYPE_CHECKING, Any
1616

17-
from rc0.client.pagination import iter_all, iter_pages
17+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
1818
from rc0.models.reports import (
1919
AccountingRow,
2020
DomainListRow,
@@ -25,6 +25,7 @@
2525

2626
if TYPE_CHECKING:
2727
from rc0.client.http import Client
28+
from rc0.client.pagination import PageInfo
2829

2930

3031
def _resolve_day(day: str | None) -> str | None:
@@ -41,9 +42,9 @@ def list_problematic_zones(
4142
*,
4243
page: int | None = None,
4344
page_size: int | None = None,
44-
fetch_all: bool = False,
45+
fetch_all: bool = True,
4546
) -> list[ProblematicZone]:
46-
"""Return problematic-zone rows. With ``fetch_all=True`` iterate every page."""
47+
"""Return problematic-zone rows. Defaults to fetching every page."""
4748
effective_page_size = page_size or 50
4849
path = "/api/v2/reports/problematiczones"
4950
if fetch_all:
@@ -61,6 +62,22 @@ def list_problematic_zones(
6162
return [ProblematicZone.model_validate(row) for row in first]
6263

6364

65+
def list_problematic_zones_page(
66+
client: Client,
67+
*,
68+
page: int,
69+
page_size: int | None = None,
70+
) -> tuple[list[ProblematicZone], PageInfo]:
71+
"""Fetch exactly one page of problematic zones with pagination metadata."""
72+
rows, info = fetch_page(
73+
client,
74+
"/api/v2/reports/problematiczones",
75+
page=page,
76+
page_size=page_size or 50,
77+
)
78+
return [ProblematicZone.model_validate(row) for row in rows], info
79+
80+
6481
def list_nxdomains(client: Client, *, day: str | None = None) -> list[NxdomainRow]:
6582
"""GET /api/v2/reports/nxdomains — bare array.
6683

‎src/rc0/api/rrsets.py‎

Lines changed: 42 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,21 @@
44

55
from typing import TYPE_CHECKING
66

7-
from rc0.client.pagination import iter_all, iter_pages
7+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
88
from rc0.models.rrset import RRset
99

1010
if TYPE_CHECKING:
1111
from rc0.client.http import Client
12+
from rc0.client.pagination import PageInfo
13+
14+
15+
def _filters(name: str | None, type_: str | None) -> dict[str, str]:
16+
out: dict[str, str] = {}
17+
if name is not None:
18+
out["names"] = name
19+
if type_ is not None:
20+
out["types"] = type_
21+
return out
1222

1323

1424
def list_rrsets(
@@ -19,20 +29,19 @@ def list_rrsets(
1929
type: str | None = None,
2030
page: int | None = None,
2131
page_size: int | None = None,
22-
fetch_all: bool = False,
32+
fetch_all: bool = True,
2333
) -> list[RRset]:
24-
"""GET /api/v2/zones/{zone}/rrsets — Laravel envelope."""
25-
filters: dict[str, str] = {}
26-
if name is not None:
27-
filters["names"] = name
28-
if type is not None:
29-
filters["types"] = type
34+
"""GET /api/v2/zones/{zone}/rrsets — Laravel envelope.
35+
36+
``fetch_all`` defaults to ``True`` so the caller receives every RRset.
37+
Pass ``fetch_all=False`` (or use :func:`list_rrsets_page`) to get one
38+
explicit page.
39+
"""
40+
filters = _filters(name, type)
3041
path = f"/api/v2/zones/{zone}/rrsets"
3142
effective_page_size = page_size or 50
3243
if fetch_all:
33-
rows = list(
34-
iter_all(client, path, page_size=effective_page_size, params=filters),
35-
)
44+
rows = list(iter_all(client, path, page_size=effective_page_size, params=filters))
3645
else:
3746
page_iterator = iter_pages(
3847
client,
@@ -43,3 +52,25 @@ def list_rrsets(
4352
)
4453
rows = next(iter(page_iterator), [])
4554
return [RRset.model_validate(r) for r in rows]
55+
56+
57+
def list_rrsets_page(
58+
client: Client,
59+
zone: str,
60+
*,
61+
name: str | None = None,
62+
type: str | None = None,
63+
page: int,
64+
page_size: int | None = None,
65+
) -> tuple[list[RRset], PageInfo]:
66+
"""Fetch exactly one page and return rows plus pagination metadata."""
67+
filters = _filters(name, type)
68+
path = f"/api/v2/zones/{zone}/rrsets"
69+
rows, info = fetch_page(
70+
client,
71+
path,
72+
page=page,
73+
page_size=page_size or 50,
74+
params=filters,
75+
)
76+
return [RRset.model_validate(r) for r in rows], info

‎src/rc0/api/tsig.py‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,22 @@
44

55
from typing import TYPE_CHECKING, Any
66

7-
from rc0.client.pagination import iter_all, iter_pages
7+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
88
from rc0.models.tsig import TsigKey
99

1010
if TYPE_CHECKING:
1111
from rc0.client.http import Client
12+
from rc0.client.pagination import PageInfo
1213

1314

1415
def list_tsig(
1516
client: Client,
1617
*,
1718
page: int | None = None,
1819
page_size: int | None = None,
19-
fetch_all: bool = False,
20+
fetch_all: bool = True,
2021
) -> list[TsigKey]:
21-
"""GET /api/v2/tsig — bare array."""
22+
"""GET /api/v2/tsig — bare array. Defaults to fetching every page."""
2223
effective_page_size = page_size or 50
2324
if fetch_all:
2425
rows = list(iter_all(client, "/api/v2/tsig", page_size=effective_page_size))
@@ -33,6 +34,22 @@ def list_tsig(
3334
return [TsigKey.model_validate(r) for r in rows]
3435

3536

37+
def list_tsig_page(
38+
client: Client,
39+
*,
40+
page: int,
41+
page_size: int | None = None,
42+
) -> tuple[list[TsigKey], PageInfo]:
43+
"""Fetch exactly one page of TSIG keys with pagination metadata."""
44+
rows, info = fetch_page(
45+
client,
46+
"/api/v2/tsig",
47+
page=page,
48+
page_size=page_size or 50,
49+
)
50+
return [TsigKey.model_validate(r) for r in rows], info
51+
52+
3653
def show_tsig(client: Client, name: str) -> TsigKey:
3754
"""GET /api/v2/tsig/{keyname}."""
3855
response = client.get(f"/api/v2/tsig/{name}")

‎src/rc0/api/zones.py‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,25 @@
44

55
from typing import TYPE_CHECKING, Any
66

7-
from rc0.client.pagination import iter_all, iter_pages
7+
from rc0.client.pagination import fetch_page, iter_all, iter_pages
88
from rc0.models.zone import Zone, ZoneStatus
99

1010
if TYPE_CHECKING:
1111
from collections.abc import Mapping
1212

1313
from rc0.client.http import Client
14+
from rc0.client.pagination import PageInfo
1415

1516

1617
def list_zones(
1718
client: Client,
1819
*,
1920
page: int | None = None,
2021
page_size: int | None = None,
21-
fetch_all: bool = False,
22+
fetch_all: bool = True,
2223
filters: Mapping[str, Any] | None = None,
2324
) -> list[Zone]:
24-
"""Return zones. With ``fetch_all=True`` iterate every page."""
25+
"""Return zones. Defaults to fetching every page."""
2526
effective_page_size = page_size or 50
2627
if fetch_all:
2728
return [
@@ -44,6 +45,24 @@ def list_zones(
4445
return [Zone.model_validate(row) for row in first]
4546

4647

48+
def list_zones_page(
49+
client: Client,
50+
*,
51+
page: int,
52+
page_size: int | None = None,
53+
filters: Mapping[str, Any] | None = None,
54+
) -> tuple[list[Zone], PageInfo]:
55+
"""Fetch exactly one page of zones with pagination metadata."""
56+
rows, info = fetch_page(
57+
client,
58+
"/api/v2/zones",
59+
page=page,
60+
page_size=page_size or 50,
61+
params=filters,
62+
)
63+
return [Zone.model_validate(row) for row in rows], info
64+
65+
4766
def show_zone(client: Client, zone: str) -> Zone:
4867
response = client.get(f"/api/v2/zones/{zone}")
4968
return Zone.model_validate(response.json())

0 commit comments

Comments
 (0)