Proposal: Reflection APIs for SpiceDB

[josephschorr]

trafficstars

A number of issues have been filed within SpiceDB around the ability to reflect upon schema and its types: https://github.com/authzed/spicedb/issues/613 https://github.com/authzed/spicedb/issues/439 https://github.com/authzed/spicedb/issues/1173

The following is a proposal for a series of new APIs to provide these reflection capabilities over schema, to be added to the v1.schema package.

[!IMPORTANT]
These APIs will operate solely over the structure of schema and not over any data; computation of data-based answers is done via APIs such as CheckPermission, LookupResources, etc

Schema Reflection API

schema.ReflectSchema will provide a means for basic structural reflection of the entire schema, including metadata such as comments

See: https://github.com/authzed/spicedb/issues/439

message SchemaFilter {
  enum Kind {
    DEFINITION = 1;
    CAVEAT = 2;
    RELATION = 3;
    PERMISSION = 4;
  }

  // optional_definition_name_match is a regular expression matching
  // the definition name
  optional optional_definition_name_match = 1;
  optional optional_relation_or_permission_name_match = 2;
  repeated Kind kind_filters = 3;
}

message ReflectSchemaRequest {
  Consistency consistency = 1;
 
  // optional_filters defines optional filters that are applied in
  // an OR fashion to the schema, before being returned
  repeated SchemaFilter optional_filters = 2;
}

message ReflectSchemaResponse {
  repeated Definition definitions = 1;
  repeated Caveat caveats = 2;

  // read_at is the ZedToken at which the schema was read.
  ZedToken read_at = 3;
}

message Definition {
  string name = 1;
  string comment = 2;
  
  repeated Relation relations = 3;
  repeated Permission permissions = 4;
}

message Caveat {
  string name = 1;
  string comment = 2;

  repeated CaveatParameter = 3;
  string expression = 4;
}

message CaveatParameter {
  string name = 1;
  string type = 2;
}

message Relation {
  string name = 1;
  string comment = 2;
  repeated TypeReference subject_types = 3;
}

message TypeReference {
  string type_name = 1;
  string optional_caveat_name = 2;

  oneof {
    boolean is_terminal_subject = 3;
    string optional_relation_name = 4;
    boolean is_public_wildcard  = 5;
  }
}

message Permission {
  string name = 1;
  string comment = 2;
}

ComputablePermissions API

schema.ComputablePermissions provides a means for accessing the reachability graph and determining all permissions which are reachable from one (or more) relations. This walks from relations->permissions, upward through the schema.

This + batch check can resolve: #1173

message ComputablePermissionsRequest {
  Consistency consistency = 1;
  repeated RelationReference relations = 3;
}

message RelationReference {
  string definition_name = 1;
  string relation_name = 2;
}

message PermissionReference {
  string definition_name = 1;
  string relation_name = 2;
}

message ComputablePermissionsResponse {
  repeated PermissionReference permissions = 1;

  // read_at is the ZedToken at which the schema was read.
  ZedToken read_at = 2;
}

DependentRelations API

schema.DependentRelations will provides a means for accessing the reachability graph and determining all relations which are reachable from a permission. This walks downward from permissions->relations.

See: https://github.com/authzed/spicedb/issues/613

message DependentRelationsRequest {
  Consistency consistency = 1;
  PermissionReference permission = 2;
}

message DependentRelationsResponse {
  repeated RelationReference relations = 1;

  // read_at is the ZedToken at which the schema was read.
  ZedToken read_at = 2;
}

[josephschorr]

Related issue: https://github.com/authzed/spicedb/issues/735

[josephschorr]

Fixed in #1885, #1891, #1894