Allow pagination for FindAllLocalBranches

Pagination has always been ad hoc within Gitaly, and there was no
convergence to a standard. This change creates a structure around this,
which an implementation for one RPC to try it.

The structure uses a page token, as proposed in:
https://gitlab.com/gitlab-org/gitaly/-/issues/2704#note_349733942.
This allows a generic field to hold what's usually a numeric `offset`
field. Where `offset` can be unstable over a series of requests due to
race conditions, the page token could prevent that.

The change does alter the implementation for `lines.Send()` a little,
which create a situation where for other RPCs there's been slight
normalization on their input to `lines.Send()` to make this change
backward as well as forward compatible.

Helps with: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/48097#note_354316835
Part of: https://gitlab.com/gitlab-org/gitaly/-/issues/2704

1 files changed, 16 insertions, 0 deletions

diff --git a/proto/shared.proto b/proto/shared.proto
index 59076a441..9f843ee68 100644
--- a/proto/shared.proto
+++ b/proto/shared.proto
@@ -103,3 +103,19 @@ message User {
 message ObjectPool {
   Repository repository = 1 [(gitaly.repository)=true];
 }
+
+message PaginationParameter {
+	// Instructs pagination to start sending results after the provided page
+	// token appears. A page token allows for a generic pattern to uniquely
+	// identify a result or 'page'. Each paginated RPC may interpret a page
+	// token differently.
+	string page_token = 1;
+	// When fully consuming the response the client will receive _at most_
+	// `limit` number of resulting objects. Note that the number of response
+	// messages might be much lower, as some response messages already send
+	// multiple objects per message.
+	// When the limit is smaller than 0, it will be normalized to 2147483647
+	// on the server side. When limit is not set, it defaults to 0, and no
+	// results are send in the response.
+	int32 limit = 2;
+}