API version 20240415 removed race-free flag enumeration: offset pagination can skip/duplicate flags under concurrent archival

[keeely]

Regression

Before 20240415, GET /api/v2/flags/{projectKey} returned the full set in a
single atomic response — a race-free enumeration. 20240415 switched it to
offset pagination (limit/offset, default 20) with no race-free
alternative.

LD-API-Version	GET /flags behaviour
20191212, 20210729, 20220603	Full set in one response, no _links.next — atomic snapshot
20240415 (current)	Paginated, limit=20 default, _links.next present — not race-free

_links.next is not a cursor. Its href is just …&limit=20&offset=20 —
offset pagination re-encoded as a link, so following it is identical to
incrementing offset and inherits the same race. A real cursor would carry an
opaque, position-stable token ("resume after key X"), not a numeric offset.
Quick test: if next.href contains offset=, it's position-based and races.

Offset pagination isn't a consistent enumeration: archiving a flag mid-walk
removes it from the archived:false set, shifting all later offsets down by one,
so a flag present for the entire walk can be skipped (unarchive → duplicate).
The unpaged behaviour now only survives on the deprecated versions above, so
once those are enforced, no supported version offers race-free enumeration at all.

Reproduction

# pre-20240415: one atomic page, no next link
curl -s -H "Authorization: $LD_TOKEN" -H "LD-API-Version: 20220603" \
  ".../flags/$PROJECT?filter=archived:false" \
  | jq '{count:(.items|length), hasNext:(._links|has("next")), total:.totalCount}'
# count == totalCount, hasNext == false

# 20240415: paginated, and next.href is offset-based
curl -s -H "Authorization: $LD_TOKEN" -H "LD-API-Version: 20240415" \
  ".../flags/$PROJECT?filter=archived:false" \
  | jq '{count:(.items|length), next:._links.next.href, total:.totalCount}'
# count == 20, next ends in "&offset=20"

Skip race on 20240415: page through ?filter=archived:false; archive any flag
behind the current offset; subsequent offsets shift down and the flag at the next
page boundary is never returned.

Request

Restore race-free complete enumeration on a supported version. Not asking to
revert to unpaged — cursor/keyset pagination keeps the paging model while
being immune to offset shift. (For dotted keys, an S3-style prefix+delimiter
listing would also give bounded, atomic per-subtree pages.)

[monsagri]

Thanks for getting in touch @keeely.

Could you give some detail on the actual issue you've encountered as a result of these changes?
You can increase the page size to 100 and are able to query by archived flag specifically, so I'm trying to understand the ask here

[keeely]

@monsagri

In this case we're talking ~4k active flags, and that's significant because it's much higher than even the max page size. I will try to show this with a concrete example, and just illustrate the point with max page size of 3. Let's assume we have just 6 flags, and max page size is 3. (Yeah, I know I can have 100 but to save me typing :))

Old interface: retrieves flags A, B, C, D, E, F all in a single call. No paging.

New Interface has to return the same values:
Page 1: Flags A, B, C
Page 2: Flags D, E, F

So I make the call for Page 1, and I get A, B, C
Then (the race) someone archives flag B before I get a chance to query for page 2.
Next I make the call for Page 2. But page 2 is now no longer D, E, F. Everything is shifted. Since B is missing (archived) we get reordering, the pages are now laid out like this:

Page 1: Flags A, C, D
Page 2: Flags E, F

Now I ask for page 2 and I get just two items. D disappeared from the enumeration thanks to removal of B 'just in time'.

Most interfaces solve this problem with a cursor. The ID for 'D' is returned in the first page, and that's supplied with the query for the second page, instead of using the number '2' (page number). Then there is no race because each time we query it's for a specific key, not a page offset.