From d316b988feefa96e810e486245312eee5ee0a992 Mon Sep 17 00:00:00 2001 From: Stefano Scafiti Date: Tue, 10 Nov 2026 17:52:54 +0100 Subject: [PATCH 1/5] Add optional response batching to LookupResources Adds an opt-in way for LookupResources to return multiple resources per stream message instead of one message per resource: - LookupResourcesRequest.optional_response_batch_size (uint32, <= 1000): when non-zero, the server may return up to this many resources per response message. Zero (the default) preserves the existing one-resource-per-message behavior. - LookupResourcesResponse.batched_results (repeated LookupResourcesResult): populated instead of the singular fields when batching is requested. A response message uses either the singular fields or batched_results. - New LookupResourcesResult message mirroring the per-resource fields (resource_object_id, permissionship, partial_caveat_info, after_result_cursor). Fully backward compatible and opt-in; no behavior change unless the new request field is set. Batching reduces per-message overhead for high-cardinality lookups. --- authzed/api/v1/permission_service.proto | 46 +++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 8d965af..3a92da2 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -769,6 +769,17 @@ 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_results, instead of a single resource per + // message. Zero (the default) preserves one-resource-per-message streaming for + // backward compatibility. Batching reduces per-message overhead for + // high-cardinality lookups. + uint32 optional_response_batch_size = 9 [ + (validate.rules).uint32 = {lte: 1000}, + (buf.validate.field).uint32 = {lte: 1000} + ]; } // LookupPermissionship represents whether a Lookup response was partially evaluated or not @@ -818,6 +829,41 @@ message LookupResourcesResponse { // after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this // result. Cursor after_result_cursor = 5; + + // batched_results, when non-empty, holds multiple found resources in a single + // response message. 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_results, never both. + repeated LookupResourcesResult batched_results = 6; +} + +// LookupResourcesResult is a single found resource within a batched +// LookupResourcesResponse (see LookupResourcesResponse.batched_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 + ]; + + // after_result_cursor holds a cursor that can be used to resume the + // LookupResources stream after this result. + Cursor after_result_cursor = 4; } // LookupSubjectsRequest performs a lookup of all subjects of a particular From 64afdcd5dd71c4289a62257807c3442d8ab31a6f Mon Sep 17 00:00:00 2001 From: Stefano Scafiti Date: Wed, 11 Nov 2026 11:29:41 +0100 Subject: [PATCH 2/5] Regenerate OpenAPI docs for response batching --- docs/apidocs.swagger.json | 41 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 6b19cc1..8ca00fb 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -1022,11 +1022,11 @@ "properties": { "@type": { "type": "string", - "description": "Identifies the type of the serialized Protobuf message with a URI reference\nconsisting of a prefix ending in a slash and the fully-qualified type name.\n\nExample: type.googleapis.com/google.protobuf.StringValue\n\nThis string must contain at least one `/` character, and the content after\nthe last `/` must be the fully-qualified name of the type in canonical\nform, without a leading dot. Do not write a scheme on these URI references\nso that clients do not attempt to contact them.\n\nThe prefix is arbitrary and Protobuf implementations are expected to\nsimply strip off everything up to and including the last `/` to identify\nthe type. `type.googleapis.com/` is a common default prefix that some\nlegacy implementations require. This prefix does not indicate the origin of\nthe type, and URIs containing it are not expected to respond to any\nrequests.\n\nAll type URL strings must be legal URI references with the additional\nrestriction (for the text format) that the content of the reference\nmust consist only of alphanumeric characters, percent-encoded escapes, and\ncharacters in the following set (not including the outer backticks):\n`/-.~_!$\u0026()*+,;=`. Despite our allowing percent encodings, implementations\nshould not unescape them to prevent confusion with existing parsers. For\nexample, `type.googleapis.com%2FFoo` should be rejected.\n\nIn the original design of `Any`, the possibility of launching a type\nresolution service at these type URLs was considered but Protobuf never\nimplemented one and considers contacting these URLs to be problematic and\na potential security issue. Do not attempt to contact type URLs." + "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." } }, "additionalProperties": {}, - "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nIn its binary encoding, an `Any` is an ordinary message; but in other wire\nforms like JSON, it has a special encoding. The format of the type URL is\ndescribed on the `type_url` field.\n\nProtobuf APIs provide utilities to interact with `Any` values:\n\n- A 'pack' operation accepts a message and constructs a generic `Any` wrapper\n around it.\n- An 'unpack' operation reads the content of an `Any` message, either into an\n existing message or a new one. Unpack operations must check the type of the\n value they unpack against the declared `type_url`.\n- An 'is' operation decides whether an `Any` contains a message of the given\n type, i.e. whether it can 'unpack' that type.\n\nThe JSON format representation of an `Any` follows one of these cases:\n\n- For types without special-cased JSON encodings, the JSON format\n representation of the `Any` is the same as that of the message, with an\n additional `@type` field which contains the type URL.\n- For types with special-cased JSON encodings (typically called 'well-known'\n types, listed in https://protobuf.dev/programming-guides/json/#any), the\n JSON format representation has a key `@type` which contains the type URL\n and a key `value` which contains the JSON-serialized value.\n\nThe text format representation of an `Any` is like a message with one field\nwhose name is the type URL in brackets. For example, an `Any` containing a\n`foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`." + "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := \u0026pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" }, "BreakingSchemaChange": { "type": "object", @@ -2297,6 +2297,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_results, instead of a single resource per\nmessage. Zero (the default) preserves one-resource-per-message streaming for\nbackward compatibility. Batching reduces per-message overhead for\nhigh-cardinality lookups." } }, "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." @@ -2323,10 +2328,40 @@ "afterResultCursor": { "$ref": "#/definitions/v1.Cursor", "description": "after_result_cursor holds a cursor that can be used to resume the LookupResources stream after this\nresult." + }, + "batchedResults": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/LookupResourcesResult" + }, + "description": "batched_results, when non-empty, holds multiple found resources in a single\nresponse message. It is populated instead of the singular fields above when\nthe request set optional_response_batch_size \u003e 0. A response message uses\neither the singular fields or batched_results, 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." + }, + "afterResultCursor": { + "$ref": "#/definitions/v1.Cursor", + "description": "after_result_cursor holds a cursor that can be used to resume the\nLookupResources stream after this result." + } + }, + "description": "LookupResourcesResult is a single found resource within a batched\nLookupResourcesResponse (see LookupResourcesResponse.batched_results)." + }, "LookupSubjectsRequest": { "type": "object", "properties": { @@ -2436,7 +2471,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": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value." }, "ObjectReference": { "type": "object", From c4a605175362a787efc52d580c53de77925b2e09 Mon Sep 17 00:00:00 2001 From: Stefano Scafiti Date: Wed, 11 Nov 2026 11:56:24 +0100 Subject: [PATCH 3/5] Group batched LookupResources results with a single cursor Replace the repeated LookupResourcesResult batched_results field with a LookupResourcesBatch wrapper that holds the results plus one resume cursor for the whole batch, and drop the per-result cursor from LookupResourcesResult. A stream is consumed message-by-message, so only one resume point per message is ever needed; carrying a cursor per result made the cursor token dominate the response payload. --- authzed/api/v1/permission_service.proto | 38 ++++++++++++++++--------- docs/apidocs.swagger.json | 38 ++++++++++++++++--------- 2 files changed, 49 insertions(+), 27 deletions(-) diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 3a92da2..c727359 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -772,8 +772,8 @@ message LookupResourcesRequest { // optional_response_batch_size, if non-zero, requests that the server return // multiple resources per response message (up to this many) in - // LookupResourcesResponse.batched_results, instead of a single resource per - // message. Zero (the default) preserves one-resource-per-message streaming for + // LookupResourcesResponse.batched, instead of a single resource per message. + // Zero (the default) preserves one-resource-per-message streaming for // backward compatibility. Batching reduces per-message overhead for // high-cardinality lookups. uint32 optional_response_batch_size = 9 [ @@ -827,18 +827,34 @@ 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_results, when non-empty, holds multiple found resources in a single - // response message. 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_results, never both. - repeated LookupResourcesResult batched_results = 6; + // 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 LookupResourcesResponse.batched_results). +// LookupResourcesResponse (see LookupResourcesBatch.results). message LookupResourcesResult { // resource_object_id is the object ID of the found resource. string resource_object_id = 1; @@ -860,10 +876,6 @@ message LookupResourcesResult { (validate.rules).message.required = false, (buf.validate.field).required = false ]; - - // after_result_cursor holds a cursor that can be used to resume the - // LookupResources stream after this result. - Cursor after_result_cursor = 4; } // LookupSubjectsRequest performs a lookup of all subjects of a particular diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 8ca00fb..526b73f 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": { @@ -2301,7 +2319,7 @@ "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_results, instead of a single resource per\nmessage. Zero (the default) preserves one-resource-per-message streaming for\nbackward compatibility. Batching reduces per-message overhead for\nhigh-cardinality lookups." + "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. Batching reduces per-message overhead for\nhigh-cardinality lookups." } }, "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." @@ -2327,15 +2345,11 @@ }, "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." }, - "batchedResults": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/LookupResourcesResult" - }, - "description": "batched_results, when non-empty, holds multiple found resources in a single\nresponse message. It is populated instead of the singular fields above when\nthe request set optional_response_batch_size \u003e 0. A response message uses\neither the singular fields or batched_results, never both." + "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." @@ -2354,13 +2368,9 @@ "partialCaveatInfo": { "$ref": "#/definitions/PartialCaveatInfo", "description": "partial_caveat_info holds information of a partially-evaluated caveated result." - }, - "afterResultCursor": { - "$ref": "#/definitions/v1.Cursor", - "description": "after_result_cursor holds a cursor that can be used to resume the\nLookupResources stream after this result." } }, - "description": "LookupResourcesResult is a single found resource within a batched\nLookupResourcesResponse (see LookupResourcesResponse.batched_results)." + "description": "LookupResourcesResult is a single found resource within a batched\nLookupResourcesResponse (see LookupResourcesBatch.results)." }, "LookupSubjectsRequest": { "type": "object", From 2feb77720873f16ff18906691c3c8410b4e3440c Mon Sep 17 00:00:00 2001 From: Stefano Scafiti Date: Wed, 11 Nov 2026 12:18:20 +0100 Subject: [PATCH 4/5] Remove the response-batch-size cap; document the tradeoff optional_response_batch_size no longer validates lte:1000 (a uint32 is already non-negative). The maximum is now a server-side configuration flag, documented in the field: larger batches favor throughput, smaller batches favor time-to-first-result, ~1000 is a good default, and over-large requests are clamped to the server maximum rather than rejected. --- authzed/api/v1/permission_service.proto | 18 ++++++++++++------ docs/apidocs.swagger.json | 2 +- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index c727359..960dd29 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -774,12 +774,18 @@ message LookupResourcesRequest { // 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. Batching reduces per-message overhead for - // high-cardinality lookups. - uint32 optional_response_batch_size = 9 [ - (validate.rules).uint32 = {lte: 1000}, - (buf.validate.field).uint32 = {lte: 1000} - ]; + // 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 diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 526b73f..d3ae574 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -2319,7 +2319,7 @@ "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. Batching reduces per-message overhead for\nhigh-cardinality lookups." + "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." From 2d2999f9426d6d5184f39ac16beb0b800de4e828 Mon Sep 17 00:00:00 2001 From: Stefano Scafiti Date: Wed, 11 Nov 2026 12:21:21 +0100 Subject: [PATCH 5/5] Regenerate OpenAPI docs with current well-known type descriptions --- docs/apidocs.swagger.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index d3ae574..922436f 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -1022,11 +1022,11 @@ "properties": { "@type": { "type": "string", - "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." + "description": "Identifies the type of the serialized Protobuf message with a URI reference\nconsisting of a prefix ending in a slash and the fully-qualified type name.\n\nExample: type.googleapis.com/google.protobuf.StringValue\n\nThis string must contain at least one `/` character, and the content after\nthe last `/` must be the fully-qualified name of the type in canonical\nform, without a leading dot. Do not write a scheme on these URI references\nso that clients do not attempt to contact them.\n\nThe prefix is arbitrary and Protobuf implementations are expected to\nsimply strip off everything up to and including the last `/` to identify\nthe type. `type.googleapis.com/` is a common default prefix that some\nlegacy implementations require. This prefix does not indicate the origin of\nthe type, and URIs containing it are not expected to respond to any\nrequests.\n\nAll type URL strings must be legal URI references with the additional\nrestriction (for the text format) that the content of the reference\nmust consist only of alphanumeric characters, percent-encoded escapes, and\ncharacters in the following set (not including the outer backticks):\n`/-.~_!$\u0026()*+,;=`. Despite our allowing percent encodings, implementations\nshould not unescape them to prevent confusion with existing parsers. For\nexample, `type.googleapis.com%2FFoo` should be rejected.\n\nIn the original design of `Any`, the possibility of launching a type\nresolution service at these type URLs was considered but Protobuf never\nimplemented one and considers contacting these URLs to be problematic and\na potential security issue. Do not attempt to contact type URLs." } }, "additionalProperties": {}, - "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(\u0026foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := \u0026pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := \u0026pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": \u003cstring\u003e,\n \"lastName\": \u003cstring\u003e\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" + "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nIn its binary encoding, an `Any` is an ordinary message; but in other wire\nforms like JSON, it has a special encoding. The format of the type URL is\ndescribed on the `type_url` field.\n\nProtobuf APIs provide utilities to interact with `Any` values:\n\n- A 'pack' operation accepts a message and constructs a generic `Any` wrapper\n around it.\n- An 'unpack' operation reads the content of an `Any` message, either into an\n existing message or a new one. Unpack operations must check the type of the\n value they unpack against the declared `type_url`.\n- An 'is' operation decides whether an `Any` contains a message of the given\n type, i.e. whether it can 'unpack' that type.\n\nThe JSON format representation of an `Any` follows one of these cases:\n\n- For types without special-cased JSON encodings, the JSON format\n representation of the `Any` is the same as that of the message, with an\n additional `@type` field which contains the type URL.\n- For types with special-cased JSON encodings (typically called 'well-known'\n types, listed in https://protobuf.dev/programming-guides/json/#any), the\n JSON format representation has a key `@type` which contains the type URL\n and a key `value` which contains the JSON-serialized value.\n\nThe text format representation of an `Any` is like a message with one field\nwhose name is the type URL in brackets. For example, an `Any` containing a\n`foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`." }, "BreakingSchemaChange": { "type": "object", @@ -2481,7 +2481,7 @@ "NULL_VALUE" ], "default": "NULL_VALUE", - "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\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",