Skip to content

fix(api): Keep per_page stable when listPage walks offset cursors - #149

Merged
BYK merged 1 commit into
mainfrom
fix/api-list-page-offset
Nov 13, 2026
Merged

fix(api): Keep per_page stable when listPage walks offset cursors#149
BYK merged 1 commit into
mainfrom
fix/api-list-page-offset

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Ported from getsentry/sentry#130518, per @BYK's request there: get the docs aligned here first, then move @sentry/api into getsentry/sentry. The commit applied cleanly on top of 2.0.0. Cursor Bugbot found the bug while reviewing the move (thread). It ships in the published @sentry/api 2.0.0.

Bug

listPage asked each later page for only the rows still missing: per_page = min(100, limit - items.length). listProjects, listTeams and listOrganizations are served by Sentry's OffsetPaginator. Its cursor is <page size>:<page>:<is_prev>. When per_page doesn't match the cursor's page size, it reads the cursor's window and keeps only the last per_page rows (src/sentry/api/paginator.py in getsentry/sentry). So 100:1:0 with per_page=50 returns rows 150–199, and rows 100–149 are lost. Any limit above 100 dropped rows without an error.

Fix

listPage now walks through the package's existing paginate, which:

  • uses one per_page for the whole walk. A fresh walk splits limit evenly: 150 becomes 2 × 75.
  • reuses the page size that an offset cursor encodes when resuming, whatever the new limit is.
  • returns a cursor that resumes at the first row not returned, including partway through a page.

listPage still validates each page with the schema, and still rejects a page with more rows than requested or a repeated cursor. One behavior changes: if a walk reaches MAX_LIST_PAGES, it now returns the rows it has and a resume cursor instead of throwing. Before this change, a stable page size couldn't hit that cap in a normal walk. Now a resumed small-page cursor can, for example 25:1:0 with limit: 5000.

Tests

  • test/api-client/core.test.ts models OffsetPaginator. It confirms that 100:1:0 with per_page=50 reads rows 150–199. Then it checks two things:
    • a 150-row walk and its resume return rows 0–299 in order, all with per_page=75;
    • resuming 100:1:0 with limit: 50 returns rows 100–149, then 150–199, both requested with per_page=100.
  • The listOrganizations test now expects per_page to stay at 3 on the second request. It was 1, which was the bug.

pnpm build, pnpm typecheck and pnpm test pass locally (53 files, 675 tests).

No UI change.

Co-Authored-By: BYK 126780+BYK@users.noreply.github.com

--

View Session [Sentry]

@sentry-junior @BYK
fix(api): Keep per_page stable when listPage walks offset cursors
3b56d96 
listPage asked each later page for only the rows still missing. Sentry's
OffsetPaginator reads a cursor's window with the page size the cursor
encodes, so pairing 100:1:0 with per_page=50 returned rows 150-199 and
dropped 100-149. listProjects, listTeams and listOrganizations lost rows
whenever limit was above 100.

listPage now walks through paginate, which keeps one page size per walk,
reuses the size an offset cursor encodes, and returns a cursor that resumes
mid-page.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
@sentry-junior sentry-junior Bot mentioned this pull request Nov 13, 2026
Merged
@sentry-junior
sentry-junior Bot added this pull request to stack #151 November 13, 2026 14:26
@sentry-junior sentry-junior Bot mentioned this pull request Nov 13, 2026
Closed
@BYK
BYK merged commit c08ef49 into main Nov 13, 2026
13 of 14 checks passed
@BYK
BYK deleted the fix/api-list-page-offset branch November 13, 2026 14:32
@sentry-release-bot sentry-release-bot Bot mentioned this pull request Nov 13, 2026
Closed
2 tasks done
BYK added a commit that referenced this pull request Nov 13, 2026
@sentry-junior @BYK
feat(api): Export API reference data as @sentry/api/docs (#150)
7871887 
Stacked on #149. Ported from getsentry/sentry#130538, per @BYK's request
there: get the docs aligned here first, then move `@sentry/api` into
getsentry/sentry.

This adds the data sentry-docs needs to build the API reference from the
`@sentry/api` version it pins, so it no longer has to read
`openapi-derefed.json` from a pinned commit of this repository. The
sentry-docs adapter is getsentry/sentry-docs#20679.

## Changes from the sentry version

2.0.0 (#148) made every path relative to the API base path and trimmed
server URLs to their origin. The export now follows the same contract:
- operation `path`s are relative, such as `/organizations/`, the same as
`@sentry/api/operations`;
- the base path ships as `API_BASE_PATH` (`/api/0`) and as `apiBasePath`
in `extractDocs()` output, so a page builds the full path as
`${API_BASE_PATH}${operation.path}`;
- per-operation `servers` are origins.

`extractDocs()` applies `splitApiBasePath` to a copy of the spec it
gets, so the published data and a preview of a local spec have the same
shape. It accepts both the current spec and one that declares the base
path in `servers`.

**sentry-docs#20679 needs a follow-up for this:** its adapter has to
prepend `API_BASE_PATH` to paths, like sentry-docs#20787 does for 2.0.0.
I'll push that once this shape is settled.

## What it adds

- **`scripts/generate-docs.mjs`**, next to the `operations` generator.
It runs `lib/docs-catalog.mjs` `extractDocs(spec)` on the original
`openapi-derefed.json` and emits `src/docs.ts`. That file holds the data
as a JSON string literal, so tsc doesn't infer a type for 3.7 MB of
data. It ships as **`@sentry/api/docs`** (`dist/docs.js` plus `.d.ts`).
- **Shape** (`lib/docs-types.ts`):
  - `apiBasePath` / `API_BASE_PATH`.
- `tags`: name, description, `sidebarName` (`x-sidebar-name`) and
`displayDescription` (`x-display-description`).
- `operations`, in spec order: `operationId`, method and relative path,
with summary and description copied as written. Also tags, `deprecated`,
`experimental` (`x-sentry-experimental`), server origins, security
requirements, and parameters (path-level merged with operation
overrides) with `in`, `required`, description, `experimental` and
schema. The request body comes from its first content type (content
type, `required`, schema, example), and every response has its status,
description, content type, schema and `example`/`examples`.
- **`extractDocs` is exported too**, so sentry-docs'
`OPENAPI_LOCAL_PATH` preview of an unreleased local spec goes through
the same projection as the published data.
- `lib/http-methods.mjs` holds the HTTP method set that both catalogs
use.

## The export's shape is now a semver contract

sentry-docs, and anything else that imports `@sentry/api/docs`, depends
on these field names and types. Removing or renaming a field, or
changing its type, is a **major** release. Adding fields is a minor
release. The README says so.

## Size

Measured with `npm pack --dry-run` from clean builds of #149 and this
branch, using the spec in this repository:

| | tgz | unpacked | files |
|---|---|---|---|
| #149 | 3,385,825 B | 35,812,862 B | 80 |
| this PR | 3,828,867 B | 39,660,930 B | 86 |
| change | **+443 KB (+13%)** | **+3.85 MB (+11%)** | +6 |

Almost all of it is `dist/docs.js` (3,840,561 B). It's a separate entry
point, so `@sentry/api` and `@sentry/api/client` users like toolkit
don't load it unless they import `./docs`. They only pay for the
download.

## Tests

- `test/docs.test.ts`:
- A fixture test pins the exact output shape. Its spec declares `/api/0`
in `servers` and an operation server override under it, so the test also
covers the relative paths, `apiBasePath` and origin-only servers. It
also covers path-level parameter overrides, experimental flags, multiple
content types, responses without content, named examples and security.
- Drift tests compare the published `@sentry/api/docs` with
`openapi-derefed.json`:
- the export equals `extractDocs(spec)`, and `API_BASE_PATH` is
`/api/0`;
- tag and operation order matches the spec, with `API_BASE_PATH` plus
each relative path equal to the spec's path;
- for every operation, the text, parameters, request schema and example,
and response schemas and examples match the spec directly.
- `test/package.test.ts`: the packed-tarball smoke test imports
`@sentry/api/docs`.

`pnpm build`, `pnpm typecheck` and `pnpm test` pass locally (54 files,
679 tests).

No UI change here. The sentry-docs PR carries the API reference
screenshots.

## Merge order

#149, this PR, the normal release of an `@sentry/api` version with
`./docs`, then getsentry/sentry-docs#20679 with its `API_BASE_PATH`
follow-up. That PR's dependency bump is its last step.

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3A69da19b385017e68b7f9eace56e9477f -->

--

[View
Session](https://junior-prod.sentry.dev/conversations/agent%3A69da19b385017e68b7f9eace56e9477f)
[[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A69da19b385017e68b7f9eace56e9477f/?project=4510944073809921)

<!-- junior-session-footer:end -->

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
@sentry-junior sentry-junior Bot mentioned this pull request Nov 13, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@BYK BYK BYK approved these changes
@betegon betegon Awaiting requested review from betegon betegon is a code owner
@MathurAditya724 MathurAditya724 Awaiting requested review from MathurAditya724 MathurAditya724 is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@BYK