feat: add auto-pagination to `search_content()` function

[toph-allen]

The search_content() function currently exposes the page_number and page_size arguments, the latter of which maxes out at 500. Functionally, this means that it's not usable without wrapping it in a function that fetches all pages.

Considering two approaches.

Option 1: Use the current page_offset function for pagination. page_offset passes the page_number query param as a function argument, which demands that the endpoint is wrapped in a function that implements it (like the current search_content function).

With the current search_content function, this looks like so:

search_all_content <- function(client, q = NULL, include = "owner,vanity_url") {
  page_offset(client, req = search_content(client, q = q, page_number = 1, page_size = 500, include = include))
}

I don't actually propose the outer function be named search_all_content — it should be named search_content, and the inner wrapper should have a different name. Previously, those inner wrapping funcs have been methods on the Connect R6 class. We've been moving away from that. Maybe we want to name the inner function directly for the API path, e.g. v1_search_content().

Option 2: Use a different approach to paginating.

If we don't want to require an inner function wrapping the endpoint, we would need a different approach for pagination logic. If the pagination function didn't increment the page_number argument to an R call, but instead incremented that parameter in a list, we could iterate directly on the Connect$GET() call to the endpoint. This would be a little more work.

[toph-allen]

Alternatively, we may want to remove the page size limit for this endpoint (https://github.com/posit-dev/connect/issues/33764).

[jonkeane]

Does the first option basically just work now? I just tried myself, and page_offset(cl, search_content(cl, q="")) returns all the items I have access to on that server (dutifully going through each page). Is there something that is actually off or wrong subtly there (I know that this end point pages slightly differently, so it's possible something is funky about it!).

If that does just work, let's take that win and figure out how we want to wrap it into a package that makes it easy for users to use. I'm not sure there's much value exposing the unwrapped inner function, at the very least: not doing it yet and seeing if people ask for it (which also means we don't need to worry as much about naming since we don't also need to communicate that to users). We could do this in one of two ways:

(1) have the inner function simply be defined within the larger one:

search_content <- function(
  client,
  q = NULL,
  page_number = 1,
  page_size = 500,
  include = "owner,vanity_url",
  ...
) {
  error_if_less_than(client$version, "2024.04.0")

  inner_search <- function(...) {
    path <- v1_url("search", "content")

    query <- list(
      q = q,
      page_number = page_number,
      page_size = page_size,
      include = include
    )

    client$GET(path, query = query)
  }
  page_offset(client, inner_search(...))
}

Or, (re)name the current function to .search_content and have search_content be ~what you have in the description.

[toph-allen]

Yep! The first option works right now, and is the one I would like to do! And I agree that the inner function should not be exposed unless we actually see demand.

I think I prefer the first approach you propose, defining the inner function in the outer one! Thanks for that suggestion!!