fix: prevent hanging when calling get_groups with prefix and small page_size

[toph-allen]

Intent

get_groups(client, prefix = "prefix") would fail when the page_size required pagination — it would hang forever.

Fixes #319

Approach

• This hang occur because the v1/groups API only ever returns the first page of results when using prefix.
• Whereas v1/users returns no results when a subsequent page of a prefix request is called, v1/groups always returns the first page, which causes connectapi to just page eternally.
• So, we just don't call the pagination function when we're using a prefix!
• Updated documentation to clarify behavior of different parameters.

Checklist

• Does this change update NEWS.md (referencing the connected issue if necessary)?
• Does this change need documentation? Have you run `document()?

[tdstein]

This hang occur because the v1/groups API only ever returns the first page of results when using prefix.

Is this the rumored bug in Connect?

[tdstein]

Are there any unit tests that already verify this functionality?

[toph-allen]

This hang occur because the v1/groups API only ever returns the first page of results when using prefix.

Is this the rumored bug in Connect?

@tdstein I mean, it's an odd behavior, but the v1/groups endpoint works exactly as described in its documentation:

• For a prefix search, results are sorted based on similarity to the prefix. A prefix search ignores asc_order. The first page of results will always be returned.

So when calling v1/groups?prefix=c&page_size=2&page_number=2, the results returned are the same as for page 1. This behavior is kinda weird.

Aside: the v1/users endpoint docs say that it also behaves this way, but it does not. When calling it with a prefix with page_number > 1, no results are returned (which I feel like is the most sensible behavior.

I found Cole's original issue about this: https://github.com/rstudio/connect/issues/17543. Two notes on that: it (1) requests that the API return an error with prefix and page_number > 1, and (2) points to our docs on offset pagination, which I think point to a sensible answer.

The Cookbook docs on offset pagination are here. They recommend paging through results until you reach an empty page, which suggests that the behavior of the v1/users endpoint is the better approach and that the behavior of v1/groups endpoint is actually wrong.

Another option for this PR is to have the page_offset function check to see if the current result is zero or the same as the previous result, which would make it robust to current and future variations of Connect's API behavior.

---

[edit] another subtle bug with v1/groups is that the docs say that order is always based on similarity, but specifying page size does not just truncate the list, it seems to include the first list and then some number of results from the end. that's getting a connect bug too.

[toph-allen]

Two Connect bugs:

• https://github.com/rstudio/connect/issues/28774
• https://github.com/rstudio/connect/issues/28773