blob: Implement ListLFSPointers() RPC

We currently have three different functions to retrieve LFS pointers:
one which checks object IDs directly, one which retrieves all reachable
LFS pointers and a third one which does a limited graph walk. In short,
all three of these search LFS pointers by iterating a set of revisions.
The current interface is thus unnecessarily complex given that it has
three limited ways to do the same thing instead of providing one general
implementation which allows both our own API to be more concise as well
as allowing users of the API to be more flexible.

This commit thus implements a replacement interface `ListLFSPointers`.
Instead of restricting users, we simply accept a set of revisions which
we traverse in order to find LFS pointers. Because `GetNewLFSPointers`
allowed users to restrict the graph walk via a set of negative refs, we
also accept the pseudo-revisions `--not` and `--all`.

With this new and simple interface, we can replace all existing usecases
and thus mark the three other RPCs as deprecated.

1 files changed, 39 insertions, 0 deletions

diff --git a/proto/blob.proto b/proto/blob.proto
index 5798a04fe..db7eda834 100644
--- a/proto/blob.proto
+++ b/proto/blob.proto
@@ -25,6 +25,8 @@ service BlobService {
   // GetLFSPointers retrieves LFS pointers from a given set of object IDs.
   // This RPC filters all requested objects and only returns those which refer
   // to a valid LFS pointer.
+  //
+  // Deprecated in favor of `ListLFSPointers`, passing object IDs as revisions.
   rpc GetLFSPointers(GetLFSPointersRequest) returns (stream GetLFSPointersResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -34,6 +36,10 @@ service BlobService {
   // GetNewLFSPointers retrieves LFS pointers for a limited subset of the
   // commit graph. It will return all LFS pointers which are reachable by the
   // provided revision, but not reachable by any of the limiting references.
+  //
+  // Deprecated in favor of `ListLFSPointers`. `NotInAll` can be replaced with
+  // `REVISION` `--not` `--all`, while `NotInRefs` can be replaced with
+  // `REVISION` `--not` `NotInRevs...`.
   rpc GetNewLFSPointers(GetNewLFSPointersRequest) returns (stream GetNewLFSPointersResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -41,11 +47,26 @@ service BlobService {
   }
 
   // GetAllLFSPointers retrieves all LFS pointers of the given repository.
+  //
+  // Deprecated in favor of `ListLFSPointers`, passing `--all` as revision.
   rpc GetAllLFSPointers(GetAllLFSPointersRequest) returns (stream GetAllLFSPointersResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
+
+  // ListLFSPointers retrieves LFS pointers reachable from a given set of
+  // revisions by doing a graph walk. This includes both normal revisions like
+  // an object ID or branch, but also the pseudo-revisions "--all" and "--not"
+  // as documented in git-rev-parse(1). Revisions which don't directly or
+  // transitively reference any LFS pointers are ignored. It is not valid to
+  // pass revisions which do not resolve to an existing object.
+  rpc ListLFSPointers(ListLFSPointersRequest) returns (stream ListLFSPointersResponse) {
+    option (op_type) = {
+      op: ACCESSOR
+    };
+  }
+
 }
 
 message GetBlobRequest {
@@ -166,3 +187,21 @@ message GetAllLFSPointersResponse {
   // LfsPointers is the list of LFS pointers.
   repeated LFSPointer lfs_pointers = 1;
 }
+
+// ListLFSPointersRequest is a request for the ListLFSPointers RPC.
+message ListLFSPointersRequest {
+  // Repository is the repository for which LFS pointers should be retrieved
+  // from.
+  Repository repository = 1[(target_repository)=true];
+  // Revisions is the list of revisions to retrieve LFS pointers from. Must be
+  // a non-empty list.
+  repeated string revisions = 2;
+  // Limit limits the number of LFS pointers returned.
+  int32 limit = 3;
+}
+
+// ListLFSPointersResponse is a response for the ListLFSPointers RPC.
+message ListLFSPointersResponse {
+  // LfsPointers is the list of LFS pointers which were requested.
+  repeated LFSPointer lfs_pointers = 1;
+}