docs(616): scope the pageSize cap per endpoint — it is not one number
Self-review of the previous commit caught an overclaim I introduced. I wrote the paging docs as if the pageSize cap were uniformly 100. It is not: most reads (collections, library browse, logs, playouts) Math.Clamp(.., 1, 100) GetAutoTuneChannelMembers pageSize <= 0 ? 100 : Min(.., 200) GET /api/v1/search/all-items default 500, cap 1000 That made a concrete example in docs/mcp.md simply false. It claimed `pageSize=500&pageNum=1` returns items 101-200 "not 501-1000" — but ersatztv_search_all_items also takes Page(), and 500 is UNDER its cap, so there page 1 really is items 501-1000. A caller following that example on the one tool most likely to be paged hard would have mis-derived its offsets, which is the same class of silent-short-set error this issue is about. The invariant that actually holds everywhere is the derivation, not any single cap: the offset comes from the EFFECTIVE (bounded) page size, never the requested one. Reworded to say that, in docs/mcp.md, the api.paging-zero-based record (rule + mechanics + body), and the ToolCatalog Page() comment. Catalog regenerated. The record's mechanics line no longer claims every controller uses Math.Clamp — ChannelController does not. No behaviour change; MCP suite still 59/59. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -240,8 +240,9 @@ public static class ToolCatalog
|
||||
// so a caller that trusted it silently skipped the first page and read the result as data loss.
|
||||
// Documented rather than translated: a 1-based MCP over a 0-based API would make the same
|
||||
// parameter name mean two different things depending on which surface you were reading.
|
||||
// pageSize is clamped server-side (100 on most endpoints), so an over-large value yields
|
||||
// clamped-width pages — it does not widen the offset.
|
||||
// pageSize is clamped server-side and the cap is PER-ENDPOINT (100 for most reads, 200 for
|
||||
// auto-tune members, 1000 for search/all-items). The invariant is not a single number: the
|
||||
// offset always derives from the EFFECTIVE page size, never the requested one.
|
||||
private static Arg[] Page() =>
|
||||
[
|
||||
Int("pageNum", "0-based page number; the first page is 0 (optional, default 0).", arg: In.Query),
|
||||
|
||||
@@ -19,7 +19,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
|
||||
| `api.logs-sort-params` | `GET /api/logs` takes allow-listed `sortField` (`timestamp`\|`level`) and `sortDirection` (`asc`\|`desc`) query params, normalized (not rejected) on an unrecognized value. | 2026-07-11 | [link](records/api/logs-sort-params.md) |
|
||||
| `api.mediatr-passthrough` | The REST API is thin controllers over existing MediatR handlers, with no new service/business-logic layer. | 2026-06 | [link](records/api/mediatr-passthrough.md) |
|
||||
| `api.openapi-mirrors-runtime` | The generated OpenAPI spec is made to match the runtime Newtonsoft wire contract (via `NewtonsoftSchemaNamingTransformer`), not the reverse. | 2026-07-09 | [link](records/api/openapi-mirrors-runtime.md) |
|
||||
| `api.paging-zero-based` | `pageNum` is 0-based across the entire `/api/v1` surface and every wrapper of it (MCP tool catalog, SPA hooks, docs); the page offset is always derived from the CLAMPED `pageSize`, so an over-large `pageSize` narrows the page without widening the offset. A paging parameter description that omits or contradicts "0-based" is a defect. | 2026-07-25 | [link](records/api/paging-zero-based.md) |
|
||||
| `api.paging-zero-based` | `pageNum` is 0-based across the entire `/api/v1` surface and every wrapper of it (MCP tool catalog, SPA hooks, docs); the page offset is always derived from the EFFECTIVE (bounded) `pageSize`, never the requested one, so a `pageSize` above an endpoint's cap narrows the page without widening the offset. The cap itself is per-endpoint (100 typical, 200 auto-tune members, 1000 search/all-items) and must not be documented as one number. A paging parameter description that omits or contradicts "0-based" is a defect. | 2026-07-25 | [link](records/api/paging-zero-based.md) |
|
||||
| `api.parentid-drillin` | Media drill-in (season/episode/artist/music-video) is served by an optional `parentId` query param on library-browse, not dedicated per-kind child-listing endpoints. | 2026-07-07 | [link](records/api/parentid-drillin.md) |
|
||||
| `api.playout-build-lock-409` | Every id-keyed playout/channel mutation endpoint checks `IEntityLocker.IsPlayoutLocked(id)` and returns 409 Conflict while a build is in-flight, mirroring Blazor's disabled-buttons behavior; reset-all stays 202 and silently skips locked playouts. | 2026-07-10 | [link](records/api/playout-build-lock-409.md) |
|
||||
| `api.postcommit-cancellation-none` | Once a mutation commits, its entire compensating side effect (enqueues, publishes, reindexes, cache refresh, and any post-commit lookup gating one of those) runs on `CancellationToken.None` so a late client disconnect can't half-abort an already-committed change. | 2026-07-11 | [link](records/api/postcommit-cancellation-none.md) |
|
||||
|
||||
@@ -5,15 +5,22 @@ status: active
|
||||
since: '2026-07-25'
|
||||
supersedes: none
|
||||
superseded-by: none
|
||||
rule: '`pageNum` is 0-based across the entire `/api/v1` surface and every wrapper of it (MCP tool catalog, SPA hooks, docs); the page offset is always derived from the CLAMPED `pageSize`, so an over-large `pageSize` narrows the page without widening the offset. A paging parameter description that omits or contradicts "0-based" is a defect.'
|
||||
rule: '`pageNum` is 0-based across the entire `/api/v1` surface and every wrapper of it (MCP tool catalog, SPA hooks, docs); the page offset is always derived from the EFFECTIVE (bounded) `pageSize`, never the requested one, so a `pageSize` above an endpoint''s cap narrows the page without widening the offset. The cap itself is per-endpoint (100 typical, 200 auto-tune members, 1000 search/all-items) and must not be documented as one number. A paging parameter description that omits or contradicts "0-based" is a defect.'
|
||||
signals: '`pageNum`, `pageSize`, `Math.Clamp(pageSize`, `Skip(pageNum * pageSize)`, "1-based", off-by-one paging, short result set, MCP `Page()` · paths: `ErsatzTV.Mcp/ToolCatalog.cs`, `ErsatzTV/Controllers/Api/*Controller.cs` · issues: #616, #487, #58'
|
||||
mechanics: '`Math.Max(0, pageNum)` + `Math.Clamp(pageSize, 1, MaxPageSize)` in the controller, `Skip(PageNum * PageSize)` in the handler'
|
||||
mechanics: '`Math.Max(0, pageNum)` + a per-endpoint upper bound on `pageSize` (`Math.Clamp(pageSize, 1, MaxPageSize)` in most controllers) then `Skip(PageNum * PageSize)` in the handler'
|
||||
---
|
||||
|
||||
Every paged controller on `/api/v1` defaults `pageNum` to `0`, floors it with `Math.Max(0, pageNum)`,
|
||||
clamps `pageSize` with `Math.Clamp(pageSize, 1, MaxPageSize)`, and passes **both clamped values** to a
|
||||
handler that skips `PageNum * PageSize`. That makes paging uniformly 0-based, and makes the offset a
|
||||
function of the clamped size rather than the requested one.
|
||||
bounds `pageSize` above by a per-endpoint maximum, and passes **both bounded values** to a handler
|
||||
that skips `PageNum * PageSize`. That makes paging uniformly 0-based, and makes the offset a function
|
||||
of the effective size rather than the requested one.
|
||||
|
||||
The *maximum* is deliberately not uniform and must not be documented as if it were: most reads clamp
|
||||
`Math.Clamp(pageSize, 1, MaxPageSize)` with `MaxPageSize = 100`, `GetAutoTuneChannelMembers` uses
|
||||
`pageSize <= 0 ? 100 : Math.Min(pageSize, 200)`, and `GET /api/v1/search/all-items` defaults to 500
|
||||
and caps at 1000. So `pageSize=500` is narrowed to 100 on a collection listing and honored verbatim
|
||||
on all-items. The invariant that holds everywhere is the *derivation* (offset from the effective
|
||||
size), not any single cap.
|
||||
|
||||
The convention was correct in code and unwritten everywhere else, which is how it produced a bug
|
||||
report. The MCP tool catalog described `pageNum` as "1-based page number", so a caller that started
|
||||
|
||||
+7
-3
@@ -92,9 +92,13 @@ translate them, so they mean exactly what they mean on `/api/v1`:
|
||||
- **`pageNum` is 0-based.** The first page is `0`. Starting at `1` silently skips a page and returns a
|
||||
short set with no error, which is easy to misread as missing data (ersatztv#616 — the catalog used
|
||||
to describe it as 1-based, and #487 lost a verification pass to it).
|
||||
- **`pageSize` is clamped server-side** (100 on most endpoints, 200 on a few). An over-large value
|
||||
gives you narrower pages, not a wider offset: `pageSize=500&pageNum=1` returns items 101–200, not
|
||||
501–1000. Page to completeness against `totalCount` rather than assuming your requested size held.
|
||||
- **`pageSize` is clamped server-side, and the cap is per-endpoint** — 100 for most reads
|
||||
(collections, library browse, logs, playouts), 200 for auto-tune channel members, 1000 for
|
||||
`ersatztv_search_all_items` (whose *default* is 500). The invariant is not a single number: it is
|
||||
that the offset is derived from the **effective** page size, never the requested one. So
|
||||
`pageSize=500` on a 100-capped tool gives 100-wide pages (page 1 = items 101–200), while the same
|
||||
value on `search_all_items` is under its cap and is honored (page 1 = items 501–1000). Don't assume
|
||||
your requested size held — page to completeness against `totalCount`.
|
||||
|
||||
Rows that reference another entity carry that entity's id, not just its display fields — take the
|
||||
channel id for `ersatztv_reset_channel_playout` from a playout row's `channelId`, never from its `id`
|
||||
|
||||
Reference in New Issue
Block a user