Proposal: Reflection APIs for SpiceDB

[josephschorr]

A number of issues have been filed within SpiceDB around the ability to reflect upon schema and its types:
#613
#439
#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: #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: #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: #735