diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 8d965af..960dd29 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -769,6 +769,23 @@ message LookupResourcesRequest { // errors, with additional context being returned in error details, but this may be // extended in the future. bool with_debug = 8; + + // optional_response_batch_size, if non-zero, requests that the server return + // multiple resources per response message (up to this many) in + // LookupResourcesResponse.batched, instead of a single resource per message. + // Zero (the default) preserves one-resource-per-message streaming for + // backward compatibility. + // + // The batch size trades time-to-first-result against overall throughput: a + // larger batch size increases throughput (fewer, larger messages, less + // per-message overhead) but delays the first results, since the server + // accumulates more of them before sending a message; a smaller batch size + // returns initial results sooner. A value around 1000 is a good default. + // + // The maximum batch size is bounded by a server-side configuration flag; + // requesting more than the server allows is clamped to that maximum rather + // than rejected. + uint32 optional_response_batch_size = 9; } // LookupPermissionship represents whether a Lookup response was partially evaluated or not @@ -816,8 +833,55 @@ message LookupResourcesResponse { ]; // after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this - // result. + // result. Used only for the singular, one-resource-per-message form. Cursor after_result_cursor = 5; + + // batched, when set, holds multiple found resources in a single response + // message along with a single resume cursor for the batch. It is populated + // instead of the singular fields above when the request set + // optional_response_batch_size > 0. A response message uses either the + // singular fields or batched, never both. + LookupResourcesBatch batched = 6; +} + +// LookupResourcesBatch holds multiple found resources returned in a single +// LookupResourcesResponse, together with one cursor that resumes the stream +// after the last result in the batch. Grouping the results with a single cursor +// (rather than a cursor per result) keeps the response compact: a stream is +// consumed message-by-message, so only one resume point per message is ever +// needed. +message LookupResourcesBatch { + // results holds the found resources, in stream order. + repeated LookupResourcesResult results = 1; + + // after_cursor holds a cursor that can be used to resume the LookupResources + // stream after the last result in this batch. + Cursor after_cursor = 2; +} + +// LookupResourcesResult is a single found resource within a batched +// LookupResourcesResponse (see LookupResourcesBatch.results). +message LookupResourcesResult { + // resource_object_id is the object ID of the found resource. + string resource_object_id = 1; + + // permissionship indicates whether the result was partially evaluated or not. + LookupPermissionship permissionship = 2 [ + (validate.rules).enum = { + defined_only: true + not_in: [0] + }, + (buf.validate.field).enum = { + defined_only: true + not_in: [0] + } + ]; + + // partial_caveat_info holds information of a partially-evaluated caveated result. + PartialCaveatInfo partial_caveat_info = 3 [ + (validate.rules).message.required = false, + (buf.validate.field).required = false + ]; } // LookupSubjectsRequest performs a lookup of all subjects of a particular diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 6b19cc1..922436f 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -2263,6 +2263,24 @@ "description": "- LOOKUP_PERMISSIONSHIP_UNSPECIFIED: LOOKUP_PERMISSIONSHIP_UNSPECIFIED is the default value and should not be used or\nrelied upon. Servers should not return this value.\n - LOOKUP_PERMISSIONSHIP_HAS_PERMISSION: LOOKUP_PERMISSIONSHIP_HAS_PERMISSION indicates that the subject has permission\non the resource with no missing caveat context.\n - LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION: LOOKUP_PERMISSIONSHIP_CONDITIONAL_PERMISSION indicates that the subject has\npermission on the resource, but only if a caveat condition is met. The\n`partial_caveat_info` field in the response should contain the missing context\nfields that must be provided to fully evaluate the caveat.", "title": "LookupPermissionship represents whether a Lookup response was partially evaluated or not" }, + "LookupResourcesBatch": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/LookupResourcesResult" + }, + "description": "results holds the found resources, in stream order." + }, + "afterCursor": { + "$ref": "#/definitions/v1.Cursor", + "description": "after_cursor holds a cursor that can be used to resume the LookupResources\nstream after the last result in this batch." + } + }, + "description": "LookupResourcesBatch holds multiple found resources returned in a single\nLookupResourcesResponse, together with one cursor that resumes the stream\nafter the last result in the batch. Grouping the results with a single cursor\n(rather than a cursor per result) keeps the response compact: a stream is\nconsumed message-by-message, so only one resume point per message is ever\nneeded." + }, "LookupResourcesRequest": { "type": "object", "properties": { @@ -2297,6 +2315,11 @@ "withDebug": { "type": "boolean", "description": "with_debug, if true, indicates that the response should return debug information\nif present and available. For now, ONLY enables debugging of maximum recursion depth\nerrors, with additional context being returned in error details, but this may be\nextended in the future." + }, + "optionalResponseBatchSize": { + "type": "integer", + "format": "int64", + "description": "optional_response_batch_size, if non-zero, requests that the server return\nmultiple resources per response message (up to this many) in\nLookupResourcesResponse.batched, instead of a single resource per message.\nZero (the default) preserves one-resource-per-message streaming for\nbackward compatibility.\n\nThe batch size trades time-to-first-result against overall throughput: a\nlarger batch size increases throughput (fewer, larger messages, less\nper-message overhead) but delays the first results, since the server\naccumulates more of them before sending a message; a smaller batch size\nreturns initial results sooner. A value around 1000 is a good default.\n\nThe maximum batch size is bounded by a server-side configuration flag;\nrequesting more than the server allows is clamped to that maximum rather\nthan rejected." } }, "description": "LookupResourcesRequest performs a lookup of all resources of a particular\nkind on which the subject has the specified permission or the relation in\nwhich the subject exists, streaming back the IDs of those resources." @@ -2322,11 +2345,33 @@ }, "afterResultCursor": { "$ref": "#/definitions/v1.Cursor", - "description": "after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this\nresult." + "description": "after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this\nresult. Used only for the singular, one-resource-per-message form." + }, + "batched": { + "$ref": "#/definitions/LookupResourcesBatch", + "description": "batched, when set, holds multiple found resources in a single response\nmessage along with a single resume cursor for the batch. It is populated\ninstead of the singular fields above when the request set\noptional_response_batch_size \u003e 0. A response message uses either the\nsingular fields or batched, never both." } }, "description": "LookupResourcesResponse contains a single matching resource object ID for the\nrequested object type, permission, and subject." }, + "LookupResourcesResult": { + "type": "object", + "properties": { + "resourceObjectId": { + "type": "string", + "description": "resource_object_id is the object ID of the found resource." + }, + "permissionship": { + "$ref": "#/definitions/LookupPermissionship", + "description": "permissionship indicates whether the result was partially evaluated or not." + }, + "partialCaveatInfo": { + "$ref": "#/definitions/PartialCaveatInfo", + "description": "partial_caveat_info holds information of a partially-evaluated caveated result." + } + }, + "description": "LookupResourcesResult is a single found resource within a batched\nLookupResourcesResponse (see LookupResourcesBatch.results)." + }, "LookupSubjectsRequest": { "type": "object", "properties": { @@ -2436,7 +2481,7 @@ "NULL_VALUE" ], "default": "NULL_VALUE", - "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a Value with a `null_value` set\nas a JSON `null` regardless of the integer value, and so will round trip to\na `0` value.\n\n - NULL_VALUE: Null value." + "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a `Value` with a `null_value`\nset as a JSON `null` regardless of the integer value, and so will round trip\nto a `0` value.\n\n - NULL_VALUE: Null value." }, "ObjectReference": { "type": "object",