Merge pull request #90 from josephschorr/filtering-improvements

Add relationships filtering to bulk export, delete and watch APIs and expand the filtering support

authzed/api/v1/experimental_service.proto

@@ -123,6 +123,10 @@ message BulkExportRelationshipsRequest {
   // should resume being returned. The cursor can be found on the
   // BulkExportRelationshipsResponse object.
   Cursor optional_cursor = 3;
+
+  // optional_relationship_filter, if specified, indicates the
+  // filter to apply to each relationship to be exported.
+  RelationshipFilter optional_relationship_filter = 4;
 }
 
 // BulkExportRelationshipsResponse is one page in a stream of relationship

authzed/api/v1/permission_service.proto

@@ -122,24 +122,42 @@ message Consistency {
 // RelationshipFilter is a collection of filters which when applied to a
 // relationship will return relationships that have exactly matching fields.
 //
-// resource_type is required. All other fields are optional and if left
-// unspecified will not filter relationships.
+// All fields are optional and if left unspecified will not filter relationships,
+// but at least one field must be specified.
+//
+// NOTE: The performance of the API will be affected by the selection of fields
+// on which to filter. If a field is not indexed, the performance of the API
+// can be significantly slower.
 message RelationshipFilter {
+  // resource_type is the *optional* resource type of the relationship.
+  // NOTE: It is not prefixed with "optional_" for legacy compatibility.
   string resource_type = 1 [ (validate.rules).string = {
     pattern : "^([a-z][a-z0-9_]{1,61}[a-z0-9]/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$",
     max_bytes : 128,
   } ];
 
+  // optional_resource_id is the *optional* resource ID of the relationship.
+  // If specified, optional_resource_id_prefix cannot be specified.
   string optional_resource_id = 2 [ (validate.rules).string = {
     pattern : "^([a-zA-Z0-9/_|\\-=+]{1,})?$",
     max_bytes : 1024,
   } ];
 
+  // optional_resource_id_prefix is the *optional* prefix for the resource ID of the relationship.
+  // If specified, optional_resource_id cannot be specified.
+  string optional_resource_id_prefix = 5 [ (validate.rules).string = {
+    pattern : "^([a-zA-Z0-9/_|\\-=+]{1,})?$",
+    max_bytes : 1024,
+  } ];
+
+
+  // relation is the *optional* relation of the relationship.
   string optional_relation = 3 [ (validate.rules).string = {
     pattern : "^([a-z][a-z0-9_]{1,62}[a-z0-9])?$",
     max_bytes : 64,
   } ];
 
+  // optional_subject_filter is the optional filter for the subjects of the relationships.
   SubjectFilter optional_subject_filter = 4;
 }
 

authzed/api/v1/watch_service.proto

@@ -8,6 +8,7 @@ import "google/api/annotations.proto";
 import "validate/validate.proto";
 
 import "authzed/api/v1/core.proto";
+import "authzed/api/v1/permission_service.proto";
 
 service WatchService {
   rpc Watch(WatchRequest) returns (stream WatchResponse) {
@@ -22,6 +23,9 @@ service WatchService {
 // watching mutations, and an optional start snapshot for when to start
 // watching.
 message WatchRequest {
+  // optional_object_types is a filter of resource object types to watch for changes.
+  // If specified, only changes to the specified object types will be returned and
+  // optional_relationship_filters cannot be used.
   repeated string optional_object_types = 1 [
     (validate.rules).repeated .min_items = 0,
     (validate.rules).repeated .items.string = {
@@ -39,6 +43,11 @@ message WatchRequest {
   // Note that if this cursor references a point-in-time containing data
   // that has been garbage collected, an error will be returned.
   ZedToken optional_start_cursor = 2;
+
+  // optional_relationship_filters, if specified, indicates the
+  // filter(s) to apply to each relationship to be returned by watch.
+  // If specified, optional_object_types cannot be used.
+  repeated RelationshipFilter optional_relationship_filters = 3;
 }
 
 // WatchResponse contains all tuple modification events in ascending