From 5648f8e92e72c8ae4b3d5224144b41fd2b60a5f4 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 25 Jul 2026 23:24:40 +0200 Subject: [PATCH] =?UTF-8?q?docs(616):=20scope=20the=20pageSize=20cap=20per?= =?UTF-8?q?=20endpoint=20=E2=80=94=20it=20is=20not=20one=20number?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- ErsatzTV.Mcp/ToolCatalog.cs | 5 +++-- docs/decisions/README.md | 2 +- docs/decisions/records/api/paging-zero-based.md | 17 ++++++++++++----- docs/mcp.md | 10 +++++++--- 4 files changed, 23 insertions(+), 11 deletions(-) diff --git a/ErsatzTV.Mcp/ToolCatalog.cs b/ErsatzTV.Mcp/ToolCatalog.cs index 93fa059be..e3765393d 100644 --- a/ErsatzTV.Mcp/ToolCatalog.cs +++ b/ErsatzTV.Mcp/ToolCatalog.cs @@ -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), diff --git a/docs/decisions/README.md b/docs/decisions/README.md index fe7e19d72..7ee6fde6d 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -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) | diff --git a/docs/decisions/records/api/paging-zero-based.md b/docs/decisions/records/api/paging-zero-based.md index a232d6138..19dcd27f6 100644 --- a/docs/decisions/records/api/paging-zero-based.md +++ b/docs/decisions/records/api/paging-zero-based.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 diff --git a/docs/mcp.md b/docs/mcp.md index dcb760b18..0cbd39962 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -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`