LookupResources optional_limit pagination: strict maximum or advisory limit

Question

When using LookupResources to paginate a large set of resources that grant a permission to a subject, the goal is to receive each page with a predictable maximum number of entries so that client‑side buffering and latency budgets can be fixed in advance.
The SpiceDB v1 API accepts an optional_limit field and returns an opaque after_result_cursor, but the documentation notes that the server may apply its own default or maximum page size, treating the request limit as advisory. It is unclear whether the limit is enforced as a strict upper bound, whether the server can return fewer items without signaling end‑of‑stream, and what guarantees exist for callers that need a hard cap on page size.

Does the server guarantee that each LookupResources page contains no more than the requested optional_limit items?
If the server can return fewer items, how should a client determine that the stream has ended versus merely receiving a partially filled page?
If the server can exceed the requested limit, what mechanism (if any) enforces a hard bound on page size?

Siddharth · Answer

LookupResources optional_limit: strict cap or advisory floor
When calling LookupResources with an optional_limit, the SpiceDB v1 API does not enforce the requested number as a strict upper bound. The server may apply its own default or maximum page size, treating the client's limit as advisory.
What the protocol guarantees

The server may silently cap the effective page size at a configured maximum, downgrading requests that exceed it.
  End-of-stream is signaled by a null or unchanged after_result_cursor, or by returning fewer items than requested.

Detecting end-of-stream vs partial page
If the returned item count is strictly less than the requested optional_limit, the server likely reached the end of the available result set or applied a hard cap. If the count equals the limit and after_result_cursor is present, more pages probably exist.
Enforcing a hard page-bound
No protocol-level guarantee exists that the server will never exceed or fall short of the requested limit. Clients requiring a deterministic page size must either query the server's maximum page-size configuration or enforce pagination bounds client-side.
Note: To determine whether your deployment enforces a hard cap, please confirm the SpiceDB server version and any configured maximum page-size settings, as behavior varies across releases.

Inspect the after_result_cursor field: null or empty indicates stream termination.
  Compare the returned item count to the original optional_limit.
  If a hard cap is non-negotiable, implement client-side pagination throttling or contact the service operator for the configured maximum page size.

LookupResources optional_limit pagination: strict maximum or advisory limit

1 answer

LookupResources optional_limit: strict cap or advisory floor

What the protocol guarantees

Detecting end-of-stream vs partial page

Enforcing a hard page-bound

Your perspective belongs here.

0 question comments