Merge pull request #141 from authzed/mark-ls-cursors-as-unimplemented

Change documentation of lookupsubjects cursors

Author: tstirrat15

authzed/api/v1/permission_service.proto

@@ -841,35 +841,17 @@ message LookupSubjectsRequest {
     (buf.validate.field).required = false
   ];
 
-  // optional_concrete_limit, if non-zero, specifies the limit on the number of
-  // *concrete* (non-wildcard) subjects to return before the stream is closed on the
-  // server side. With the default value of zero, the stream will continue resolving
-  // concrete subjects until exhausted or the stream is closed due to the client or
-  // a network issue.
-  //
-  // NOTE: Wildcard subjects ("*") have special treatment when cursors and limits are used. Because
-  // wildcards can apply to *any* concrete subjects, if a wildcard subject is found within the dataset,
-  // a wildcard subject can be returned for *all* LookupSubjects calls, regardless of the cursor or
-  // limit.
-  //
-  // For example, if wildcards are requested, a wildcard subject exists, there is a specified limit
-  // of 10 concrete subjects, and at least 10 concrete subjects exist, the API will return 11 subjects
-  // in total: the 10 concrete + the wildcard
-  //
-  // Furthermore, if a wildcard has a set of exclusions generated by the dataset,
-  // the exclusions *will respect the cursor* and only a *partial* set of exclusions will be returned
-  // for each invocation of the API.
-  //
-  // ***IT IS UP TO THE CALLER IN THIS CASE TO COMBINE THE EXCLUSIONS IF DESIRED***
+  // optional_concrete_limit is currently unimplemented for LookupSubjects
+  // and will return an error as of SpiceDB version 1.40.1. This will
+  // be implemented in a future version of SpiceDB.
   uint32 optional_concrete_limit = 7 [
     (validate.rules).uint32 = {gte: 0},
     (buf.validate.field).uint32 = {gte: 0}
   ];
 
-  // optional_cursor, if specified, indicates the cursor after which results should resume being returned.
-  // The cursor can be found on the LookupSubjectsResponse object.
-  //
-  // NOTE: See above for notes about how cursors interact with wildcard subjects.
+  // optional_cursor is currently unimplemented for LookupSubjects
+  // and will be ignored as of SpiceDB version 1.40.1. This will
+  // be implemented in a future version of SpiceDB.
   Cursor optional_cursor = 8;
 
   // wildcard_option specifies whether wildcards should be returned by LookupSubjects.