ListUsers API

[willvedd]

Description

Introducing the ListUsers API which answers the question "what users are related to a specific object?". To learn more about this feature, refer to the ListUsers RFC.

A ListUsers request is composed of three main properties:

• user_filter – the type of user (subject) targeted for the response. This can either be a terminal type (e.g. user) or a userset (e.g. group#member). Only one user filter can be provided at this time.
• relation – the target relation that subjects need to the specified object
• object – the target resource that subjects need to be related to

Example:
Consider this model and tuples:

model
  schema 1.1

type user

type group
  relations
    define member: [user]

type document
  relations
    define viewer: [user, group#member]
    
#   document:1, viewer, user:maria
#   document:1, viewer, user:will
#   document:2, viewer, user:jon
#   group:A, member, user:christy
#   document:1, viewer, group:A#member

If we want to return all subjects of type user that have the viewer relation on document:1 we would call
ListUsers(user_filter=user, viewer, document:1) which would return the following:

{
    "users": [ "user:maria", "user:will", "user:christy" ]
    "excluded_users": []
}

Note: This API will initially be released in an experimental capacity. It can be enabled by setting OPENFGA_EXPERIMENTALS=enable-list-users

References

• ListUsers API Docs
• ListUsers RFC
• ListUsers Roadmap Item
• API Protobuf Definitions
• Related Issues:
  • Support for reverse queries for  #1215
  • Will the List Users API be an optional API? #406

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

[willvedd]

Not sure we should be treating this like a user. It's a string of format type#relation where #relation is optional. Treating it as a user is a hack. It should have a unique representation and converters to/from proto. Not sure that belongs in this package listusers either, but we can revisit that later. We're probably missing a pkg/types package where human readable helpers can convert to/from protos?

Lets not look too much into the argument name. We're just using an established convention to specify type and optional relation, why would we create a whole new system for this? It's only to facilitate our integration testing too.