Improve ListObjects max-out behavior

[nediamond]

In the current state, there is no direct signal as to whether the result of ListObjects is complete or not, ie whether or not OPENFGA_LIST_OBJECTS_DEADLINE or OPENFGA_LIST_OBJECTS_MAX_RESULTS are hit. The latter could potentially be inferred by callers, but not actually with full-confidence (incorrect if real n=limit). This information gap could result in emergence of unsafe usage by assuming completeness of a response when it is not.

I believe the ideal solution for this would be to add pagination to the ListObjects api via a continuation_token pattern that is consistent with how it is done for Tuples/Read, though I am not sure if there are substantial technical blockers to that which I am unaware of.

A minimally viable solution could be something like an additional property on the ListObjects response incomplete_reason which can be null, 'OPENFGA_LIST_OBJECTS_DEADLINE', 'OPENFGA_LIST_OBJECTS_MAX_RESULTS' or a functional equivalent of that. Not sure what a technical blocker to that could be.

Design questions raised here may also be relevant to the upcoming ListUsers API.

[evansims]

Hey @nediamond 👋 Thanks for raising this! The team has recently been talking about this internally as well. We've been thinking through some different approaches to improving that experience. We really appreciate your feedback and will definitely add it to the conversation. We'll have more to share on this later.

[willvedd]

@nediamond You raise a good point. In practice, are you finding that you can't determine if the max results are hit or is this a matter of confidence? We'd like to understand your use case a bit more.

Technically speaking, the continuation_token pattern you suggested is unfortunately a non-starter for ListObjects and ListUsers provided how their algorithms work. However, an additional "reason" property in the response that indicates if the request timed-out or hit max results is feasible. Though no promises on delivery; we'll need to think through it a little more.

Thank you for the thoughtful suggestion!