Add feed generator cursor specification at protocol level

[badlogic]

Apologies if opening an issue here is inapropriate. I was told to do so on the API touchers Discord, and it might make sense to consider this as atproto is still in its early stages.

I and quite a few others are trying our hands on writing alternative clients for BlueSky. One of the biggest problems we face is the under-specified nature of feed generator cursors.

We all would like to implement two features:

1. Resume viewing the feed from where you left
2. Fetch the next X "newer" items

However, given the current nature of feed generator cursors (and their result sets of items), this is currently not possible. I'm splitting this into two problems.

Problem 1: Resume viewing the feed from where you left

Let me illustrate the issues we have with cursors and resuming viewing of feeds where one has left off. The following assumes we are talking to the app.bsky.feed.getFeed endpoint. Similar things hold true for other cursor-based endpoints.

1. The user opens a feed in the app for the first time. The client app pulls the latest items from the feed by not providing a cursor to getFeed().
2. The client app receives a result containing an opaque cursor and a list of items. It displays the items.
3. The user scrolls down the rendered feed and hits the last item from the previous result. The client app fetches a new "page" (automatically or through user interaction) by providing the cursor from the previous result to getFeed()
4. The client app receives a new result containing another opaque cursor to the next page, and a list of items. It appends the new items to the bottom of the rendered list.
5. Rinse, repeat.
6. The user quits the app, or the app gets killed while being in the background on a mobile device. Before exiting, the app stores the pages that are currently in view locally, possibly caching the hydrated FeedViewPosts on device.
7. The user opens the app again and expects to continue where they left off.
8. The client app loads the saved pages and displays them, possibly pulling in new like/reply counts, optionally hiding deleted posts, and fixing up scroll offsets so things look just like before (or as close as possible)
9. The user continues to scroll down and hits the end of the known items.
10. The client app uses the cursor from the last saved page and pulls in older items for rendering.

Now, this works in theory. In practice, the cursor used in step 10 may have become invalid, point to somewhere wrong in the stream, or a myriad of other things that could go wrong. Feeds are not necessarily chronological, which often renders cursors unstable/not resumable.

A client app developer can not know if the cursor that was saved is still valid. Feed generators generally do not document whether their cursors are stable/resumable or not.

I believe a flag on the GeneratorView indicating whether cursors are stable/resumable would go a long way to help us.

If a generator can not provide stable/resumable cursors, client apps can tell the user to not expect resumable viewing of that feed, and avoid rendering possible errornous results, e.g. duplicate or incorrectly ordered feed items.

Problem 2: Fetch the next X newer items

Cursors get us into the past. There is no equivalent for going into the "future" so to speak. Let me illustrate with another user/client app flow:

1. The user happily scrolls down a feed, looking at ever "older" items.
2. The client app polls the feed in the background, checking whether there are newer items, e.g. by periodically calling getFeed() without a cursor, and with a limit of 1, checking if the returned feed item is part of the already known items or not. If it is not, we know there are new items. We do not know how many at this point.
3. New items have been detected, the client app tells the user about it, e.g. via a "Scroll up for newer items"
4. The user scrolls up, expecting new items to be rendered at the top of the list as they scroll.
5. The client app ... can't do it.

The reason for this "failure" is that we can not construct cursors for fetching newer items than the one's we've seen before, due to the opaque nature of the cursors, or simply because the feed generator can practically not support it, e.g. because they are not chronological.

One strategy we try to employ at the moment to fetch newer items goes like this:

1. Call getFeed() without a cursor
2. Assign unique keys to the returned items. That can be a post at-uri, or a post at-uri plus the did of a reposting actor.
3. Check whether we've seen the unique keys before
   • If we found overlap, we are done. We filter any overlapping items, and prepend the new items to the existing list.
   • If not, fetch more pages, this time using the returned cursors, until we find overlap between the new items and the old items. Stop after x pages and give up (happens when there are too many new posts since the user last checked the feed). Display a "Show more" button that will continue loading in newer posts.

This only works for chronological/ordered feeds, where we won't see the same item twice. Otherwise the overlap test will probably fail in some scenarios.

An alternative approach exploits the fact that many feeds use a <utc-timestamp>::<cid_of_last_seen_post> cursor format and allow constructing cursors into "the future". That way lies misery though: we can't be sure if a feed generator will actually honor the format properly, like the Following generator does (which isn't a generator like the others, but has its own endpoint getTimeline()).

I believe a flag on the GeneratorView indicating whether a feed is chronological/ordered and a cursor specification that allows client apps to construct cursors for queries like "give me 25 items that are newer than this item" would be a great addition on the protocol level

Again, sorry if this doesn't belong here. Figured I'd try my luck.

[imax9000]

(carrying over my thoughts from Discord)

FWIW, in general cursors are meant for short-term iteration over a list of results, so it might be worth to introduce a separate long-term token (as well as a feed flag to indicate the support for it). Given that the feed generators are opaque, and there's no contract for them even returning a stable set of posts, it doesn't make sense to require all of them to support this. So a client must be able to determine if a given feed supports this or not.

[bnewbold]

(migrated this from an issue on the proposals repo to here, where it gets more visibility)