Repository navigation
Add optional response batching to LookupResources - #176
Merged
Merged
Conversation
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.
|
The latest Buf updates on your PR. Results from workflow Lint / lint (pull_request).
|
ostafen
marked this pull request as ready for review
November 11, 2026 10:31
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.
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.
vroldanbet
approved these changes
Nov 11, 2026
josephschorr
approved these changes
Nov 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an opt-in mechanism for
LookupResourcesto return multiple resources per stream message, instead of one message per resource, with a single resume cursor per batch.Changes
LookupResourcesRequest.optional_response_batch_size(uint32, field 9): when non-zero, the server may return up to this many resources per response message, inLookupResourcesResponse.batched. Zero (the default) preserves the existing one-resource-per-message behavior. The value trades time-to-first-result against throughput (~1000 is a good default); requests above the server-side maximum are clamped, not rejected.LookupResourcesResponse.batched(LookupResourcesBatch, field 6): populated instead of the singular fields when batching is requested. A response message uses either the singular fields orbatched, never both.LookupResourcesBatchmessage:repeated LookupResourcesResult resultsplus a singleafter_cursorfor the whole batch. One cursor per message (not per result) keeps responses compact — a stream is consumed message-by-message, so only one resume point per message is ever needed.LookupResourcesResultmessage: the per-resource fields (resource_object_id,permissionship,partial_caveat_info); it carries no cursor of its own, since the batch resumes as a unit.Recommended over non-batched going forward
New and existing integrations should prefer batched
LookupResources(setoptional_response_batch_size) over the one-resource-per-message form.For any lookup returning more than a handful of resources, batching is substantially more efficient: it collapses N stream messages into N/batch_size, and — because the resume cursor lives on the batch rather than on every result — it removes the dominant per-message payload (the cursor), rather than merely amortizing the gRPC framing. In practice this is a multi-x throughput win on high-cardinality lookups.
The non-batched form is retained for backward compatibility and remains the default so existing clients are unaffected, but it should be treated as the legacy path: prefer batched responses for all new work, and migrate throughput-sensitive callers.
Compatibility
Fully backward compatible and opt-in — no behavior change unless
optional_response_batch_sizeis set. Existing clients continue to receive one resource per message via the singular fields.