Merge pull request #144 from ecordell/downloadapi

add download api definition to materialize v0

Author: ecordell

authzed/api/materialize/v0/watchpermissionsets.proto

@@ -54,6 +54,12 @@ service WatchPermissionSetsService {
   // cursor received. Once completed, the consumer may start streaming permission set changes using WatchPermissionSets
   // and the revision token from the last LookupPermissionSets response.
   rpc LookupPermissionSets(LookupPermissionSetsRequest) returns (stream LookupPermissionSetsResponse) {}
+
+  // DownloadPermissionSets returns URLs to download permission sets data as Avro files.
+  // This provides an alternative to LookupPermissionSets for customers who need to download
+  // large datasets efficiently. The returned URLs point to compressed Avro files containing
+  // the permission sets data in a normalized format.
+  rpc DownloadPermissionSets(DownloadPermissionSetsRequest) returns (DownloadPermissionSetsResponse) {}
 }
 
 message WatchPermissionSetsRequest {
@@ -186,3 +192,21 @@ message BreakingSchemaChange {
   // change_at is the revision at which a breaking schema event has happened.
   authzed.api.v1.ZedToken change_at = 1;
 }
+
+message DownloadPermissionSetsRequest {
+  // optional_at_revision is a specific revision to download; for now this will
+  // just validate that it matches the backing store if provided.
+  authzed.api.v1.ZedToken optional_at_revision = 1;
+}
+
+message File {
+  // name is the filename of the downloadable file
+  string name = 1;
+  // url is the download URL for the file (typically a signed S3 URL)
+  string url = 2;
+}
+
+message DownloadPermissionSetsResponse {
+  // files contains the list of downloadable files with their URLs
+  repeated File files = 1;
+}

authzed/api/v1/watch_service.proto

@@ -74,6 +74,8 @@ message WatchRequest {
   repeated RelationshipFilter optional_relationship_filters = 3;
 
   // optional_update_kinds, if specified, indicates what kinds of mutations to include.
+  // If your SpiceDB instance is running behind a proxy that aborts idle connections,
+  // we recommend including Checkpoints to keep the stream alive even when there are no changes.
   repeated WatchKind optional_update_kinds = 4;
 }
 

docs/apidocs.swagger.json

@@ -1618,6 +1618,19 @@
       },
       "description": "DirectSubjectSet is a subject set which is simply a collection of subjects."
     },
+    "DownloadPermissionSetsResponse": {
+      "type": "object",
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/File"
+          },
+          "title": "files contains the list of downloadable files with their URLs"
+        }
+      }
+    },
     "ExpCaveat": {
       "type": "object",
       "properties": {
@@ -2119,6 +2132,19 @@
       },
       "description": "ExportBulkRelationshipsResponse is one page in a stream of relationship\ngroups that meet the criteria specified by the originating request. The\nserver will continue to stream back relationship groups as quickly as it can\nuntil all relationships have been transmitted back."
     },
+    "File": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "title": "name is the filename of the downloadable file"
+        },
+        "url": {
+          "type": "string",
+          "title": "url is the download URL for the file (typically a signed S3 URL)"
+        }
+      }
+    },
     "ImportBulkRelationshipsRequest": {
       "type": "object",
       "properties": {
@@ -2264,11 +2290,11 @@
         "optionalConcreteLimit": {
           "type": "integer",
           "format": "int64",
-          "description": "optional_concrete_limit, if non-zero, specifies the limit on the number of\n*concrete* (non-wildcard) subjects to return before the stream is closed on the\nserver side. With the default value of zero, the stream will continue resolving\nconcrete subjects until exhausted or the stream is closed due to the client or\na network issue.\n\nNOTE: Wildcard subjects (\"*\") have special treatment when cursors and limits are used. Because\nwildcards can apply to *any* concrete subjects, if a wildcard subject is found within the dataset,\na wildcard subject can be returned for *all* LookupSubjects calls, regardless of the cursor or\nlimit.\n\nFor example, if wildcards are requested, a wildcard subject exists, there is a specified limit\nof 10 concrete subjects, and at least 10 concrete subjects exist, the API will return 11 subjects\nin total: the 10 concrete + the wildcard\n\nFurthermore, if a wildcard has a set of exclusions generated by the dataset,\nthe exclusions *will respect the cursor* and only a *partial* set of exclusions will be returned\nfor each invocation of the API.\n\n***IT IS UP TO THE CALLER IN THIS CASE TO COMBINE THE EXCLUSIONS IF DESIRED***"
+          "description": "optional_concrete_limit is currently unimplemented for LookupSubjects\nand will return an error as of SpiceDB version 1.40.1. This will\nbe implemented in a future version of SpiceDB."
         },
         "optionalCursor": {
           "$ref": "#/definitions/v1.Cursor",
-          "description": "optional_cursor, if specified, indicates the cursor after which results should resume being returned.\nThe cursor can be found on the LookupSubjectsResponse object.\n\nNOTE: See above for notes about how cursors interact with wildcard subjects."
+          "description": "optional_cursor is currently unimplemented for LookupSubjects\nand will be ignored as of SpiceDB version 1.40.1. This will\nbe implemented in a future version of SpiceDB."
         },
         "wildcardOption": {
           "$ref": "#/definitions/WildcardOption",
@@ -3116,7 +3142,7 @@
           "items": {
             "$ref": "#/definitions/WatchKind"
           },
-          "description": "optional_update_kinds, if specified, indicates what kinds of mutations to include."
+          "description": "optional_update_kinds, if specified, indicates what kinds of mutations to include.\nIf your SpiceDB instance is running behind a proxy that aborts idle connections,\nwe recommend including Checkpoints to keep the stream alive even when there are no changes."
         }
       },
       "description": "WatchRequest specifies what mutations to watch for, and an optional start snapshot for when to start\nwatching."