Merge branch 'kn-smarthttp-docs' into 'master'

proto: Add documentation to `smarthttp.proto`

Closes #5120

See merge request https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5858

Merged-by: Quang-Minh Nguyen <qmnguyen@gitlab.com>
Approved-by: Quang-Minh Nguyen <qmnguyen@gitlab.com>
Approved-by: Toon Claes <toon@gitlab.com>
Reviewed-by: Toon Claes <toon@gitlab.com>
Reviewed-by: Quang-Minh Nguyen <qmnguyen@gitlab.com>
Reviewed-by: karthik nayak <knayak@gitlab.com>
Co-authored-by: Karthik Nayak <knayak@gitlab.com>

3 files changed, 114 insertions, 70 deletions

diff --git a/proto/go/gitalypb/smarthttp.pb.go b/proto/go/gitalypb/smarthttp.pb.go
index acb010fd4..358c2c6b6 100644
--- a/proto/go/gitalypb/smarthttp.pb.go
+++ b/proto/go/gitalypb/smarthttp.pb.go
@@ -20,17 +20,17 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
-// This comment is left unintentionally blank.
+// InfoRefsRequest is a request for the InfoRefsUploadPack and InfoRefsUploadPack rpcs.
 type InfoRefsRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Repository is the repository on which to operate.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// Parameters to use with git -c (key=value pairs)
+	// GitConfigOptions are parameters to use with git -c (key=value pairs).
 	GitConfigOptions []string `protobuf:"bytes,2,rep,name=git_config_options,json=gitConfigOptions,proto3" json:"git_config_options,omitempty"`
-	// Git protocol version
+	// GitProtocol is the git protocol version.
 	GitProtocol string `protobuf:"bytes,3,opt,name=git_protocol,json=gitProtocol,proto3" json:"git_protocol,omitempty"`
 }
 
@@ -87,13 +87,15 @@ func (x *InfoRefsRequest) GetGitProtocol() string {
 	return ""
 }
 
-// This comment is left unintentionally blank.
+// InfoRefsResponse is the response of InfoRefsUploadPack and InfoRefsUploadPack rpcs.
+// It is used to provide the client with the servers advertised refs.
 type InfoRefsResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// This comment is left unintentionally blank.
+	// Data is the raw data copied from the stdout of git-upload-pack(1) or
+	// git-receive-pack(1) when used with the `--advertise-refs` flag.
 	Data []byte `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
 }
 
@@ -136,17 +138,17 @@ func (x *InfoRefsResponse) GetData() []byte {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelRequest is the request for the PostUploadPackWithSidechannel rpc.
 type PostUploadPackWithSidechannelRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository should only be present in the first message of the stream
+	// Repository is the repository on which to operate.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// Parameters to use with git -c (key=value pairs)
+	// GitConfigOptions are parameters to use with git -c (key=value pairs).
 	GitConfigOptions []string `protobuf:"bytes,2,rep,name=git_config_options,json=gitConfigOptions,proto3" json:"git_config_options,omitempty"`
-	// Git protocol version
+	// GitProtocol is the git protocol version.
 	GitProtocol string `protobuf:"bytes,3,opt,name=git_protocol,json=gitProtocol,proto3" json:"git_protocol,omitempty"`
 }
 
@@ -203,7 +205,9 @@ func (x *PostUploadPackWithSidechannelRequest) GetGitProtocol() string {
 	return ""
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelResponse is the response for the PostUploadPackWithSidechannel rpc.
+// This is an empty response since the raw data is transferred to the client via the sidechannel
+// exclusively.
 type PostUploadPackWithSidechannelResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -242,26 +246,30 @@ func (*PostUploadPackWithSidechannelResponse) Descriptor() ([]byte, []int) {
 	return file_smarthttp_proto_rawDescGZIP(), []int{3}
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackRequest is the request for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the client to the servers stdin of git-receive-pack(1) process.
 type PostReceivePackRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository should only be present in the first message of the stream
+	// Repository is the repository on which to operate.
+	// It should only be present in the first message of the stream.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// Raw data to be copied to stdin of 'git receive-pack'
+	// Data is the raw data to be copied to stdin of 'git receive-pack'.
 	Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"`
-	// gl_id, gl_repository, and gl_username become env variables, used by the Git {pre,post}-receive
-	// hooks. They should only be present in the first message of the stream.
+	// GlID is the GitLab ID of the user. This is used by Git {pre,post}-receive hooks.
+	// It should only be present in the first message of the stream.
 	GlId string `protobuf:"bytes,3,opt,name=gl_id,json=glId,proto3" json:"gl_id,omitempty"`
-	// This comment is left unintentionally blank.
+	// GlRepository refers to the GitLab repository. This is used by Git {pre,post}-receive hooks.
+	// It should only be present in the first message of the stream.
 	GlRepository string `protobuf:"bytes,4,opt,name=gl_repository,json=glRepository,proto3" json:"gl_repository,omitempty"`
-	// This comment is left unintentionally blank.
+	// GlID is the GitLab Username of the user. This is used by Git {pre,post}-receive hooks.
+	// It should only be present in the first message of the stream.
 	GlUsername string `protobuf:"bytes,5,opt,name=gl_username,json=glUsername,proto3" json:"gl_username,omitempty"`
-	// Git protocol version
+	// GitProtocol is the git protocol version.
 	GitProtocol string `protobuf:"bytes,6,opt,name=git_protocol,json=gitProtocol,proto3" json:"git_protocol,omitempty"`
-	// Parameters to use with git -c (key=value pairs)
+	// GitConfigOptions are parameters to use with git -c (key=value pairs).
 	GitConfigOptions []string `protobuf:"bytes,7,rep,name=git_config_options,json=gitConfigOptions,proto3" json:"git_config_options,omitempty"`
 }
 
@@ -346,13 +354,14 @@ func (x *PostReceivePackRequest) GetGitConfigOptions() []string {
 	return nil
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackResponse is the response for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the stdout of git-receive-pack(1) from the server to the client.
 type PostReceivePackResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// Raw data from stdout of 'git receive-pack'
+	// Data is the raw data from the stdout of 'git receive-pack'.
 	Data []byte `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
 }
 
diff --git a/proto/go/gitalypb/smarthttp_grpc.pb.go b/proto/go/gitalypb/smarthttp_grpc.pb.go
index 66c8d6b60..1ea24a47b 100644
--- a/proto/go/gitalypb/smarthttp_grpc.pb.go
+++ b/proto/go/gitalypb/smarthttp_grpc.pb.go
@@ -22,17 +22,26 @@ const _ = grpc.SupportPackageIsVersion7
 //
 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
 type SmartHTTPServiceClient interface {
-	// The response body for GET /info/refs?service=git-upload-pack
-	// Will be invoked when the user executes a `git fetch`, meaning the server
-	// will upload the packs to that user. The user doesn't upload new objects.
+	// InfoRefsUploadPack provides the response for GET /info/refs?service=git-upload-pack.
+	// It is invoked when the client fetches packs from the server, meaning the server will
+	// upload the packs to that client. The client doesn't upload new objects. This is used
+	// to advertise the references available on the server to the client via
+	// git-upload-pack(1)'s `--advertise-refs` option.
 	InfoRefsUploadPack(ctx context.Context, in *InfoRefsRequest, opts ...grpc.CallOption) (SmartHTTPService_InfoRefsUploadPackClient, error)
-	// The response body for GET /info/refs?service=git-receive-pack
-	// Will be invoked when the user executes a `git push`, but only advertises
-	// references to the user.
+	// InfoRefsReceivePack provides the response for GET /info/refs?service=git-receive-pack.
+	// It is invoked when the client pushes packs to the server, meaning the server
+	// will fetch the packs from the client. This is used to advertise the references
+	// available on the server to the client via git-receive-pack(1)'s `--advertise-refs`
+	// option.
 	InfoRefsReceivePack(ctx context.Context, in *InfoRefsRequest, opts ...grpc.CallOption) (SmartHTTPService_InfoRefsReceivePackClient, error)
-	// Request and response body for POST /upload-pack using sidechannel protocol
+	// PostUploadPackWithSidechannel provides the response for POST /upload-pack. It
+	// used to transfer pack files from the server to the client via sidechannels. This
+	// is invoked when the client executes `git fetch`.
+	//
+	// More info on sidechannels: https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/sidechannel.md
 	PostUploadPackWithSidechannel(ctx context.Context, in *PostUploadPackWithSidechannelRequest, opts ...grpc.CallOption) (*PostUploadPackWithSidechannelResponse, error)
-	// Request and response body for POST /receive-pack
+	// PostReceivePack provides the response for POST /receive-pack. It used to transfer
+	// pack files from the client to the server. This is invoked when the client executes `git push`.
 	PostReceivePack(ctx context.Context, opts ...grpc.CallOption) (SmartHTTPService_PostReceivePackClient, error)
 }
 
@@ -152,17 +161,26 @@ func (x *smartHTTPServicePostReceivePackClient) Recv() (*PostReceivePackResponse
 // All implementations must embed UnimplementedSmartHTTPServiceServer
 // for forward compatibility
 type SmartHTTPServiceServer interface {
-	// The response body for GET /info/refs?service=git-upload-pack
-	// Will be invoked when the user executes a `git fetch`, meaning the server
-	// will upload the packs to that user. The user doesn't upload new objects.
+	// InfoRefsUploadPack provides the response for GET /info/refs?service=git-upload-pack.
+	// It is invoked when the client fetches packs from the server, meaning the server will
+	// upload the packs to that client. The client doesn't upload new objects. This is used
+	// to advertise the references available on the server to the client via
+	// git-upload-pack(1)'s `--advertise-refs` option.
 	InfoRefsUploadPack(*InfoRefsRequest, SmartHTTPService_InfoRefsUploadPackServer) error
-	// The response body for GET /info/refs?service=git-receive-pack
-	// Will be invoked when the user executes a `git push`, but only advertises
-	// references to the user.
+	// InfoRefsReceivePack provides the response for GET /info/refs?service=git-receive-pack.
+	// It is invoked when the client pushes packs to the server, meaning the server
+	// will fetch the packs from the client. This is used to advertise the references
+	// available on the server to the client via git-receive-pack(1)'s `--advertise-refs`
+	// option.
 	InfoRefsReceivePack(*InfoRefsRequest, SmartHTTPService_InfoRefsReceivePackServer) error
-	// Request and response body for POST /upload-pack using sidechannel protocol
+	// PostUploadPackWithSidechannel provides the response for POST /upload-pack. It
+	// used to transfer pack files from the server to the client via sidechannels. This
+	// is invoked when the client executes `git fetch`.
+	//
+	// More info on sidechannels: https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/sidechannel.md
 	PostUploadPackWithSidechannel(context.Context, *PostUploadPackWithSidechannelRequest) (*PostUploadPackWithSidechannelResponse, error)
-	// Request and response body for POST /receive-pack
+	// PostReceivePack provides the response for POST /receive-pack. It used to transfer
+	// pack files from the client to the server. This is invoked when the client executes `git push`.
 	PostReceivePack(SmartHTTPService_PostReceivePackServer) error
 	mustEmbedUnimplementedSmartHTTPServiceServer()
 }
diff --git a/proto/smarthttp.proto b/proto/smarthttp.proto
index d54d123e5..3094bfb23 100644
--- a/proto/smarthttp.proto
+++ b/proto/smarthttp.proto
@@ -10,32 +10,42 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";
 // SmartHTTPService is a service that provides RPCs required for HTTP-based Git
 // clones via the smart HTTP protocol.
 service SmartHTTPService {
-  // The response body for GET /info/refs?service=git-upload-pack
-  // Will be invoked when the user executes a `git fetch`, meaning the server
-  // will upload the packs to that user. The user doesn't upload new objects.
+  // InfoRefsUploadPack provides the response for GET /info/refs?service=git-upload-pack.
+  // It is invoked when the client fetches packs from the server, meaning the server will
+  // upload the packs to that client. The client doesn't upload new objects. This is used
+  // to advertise the references available on the server to the client via
+  // git-upload-pack(1)'s `--advertise-refs` option.
   rpc InfoRefsUploadPack(InfoRefsRequest) returns (stream InfoRefsResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // The response body for GET /info/refs?service=git-receive-pack
-  // Will be invoked when the user executes a `git push`, but only advertises
-  // references to the user.
+  // InfoRefsReceivePack provides the response for GET /info/refs?service=git-receive-pack.
+  // It is invoked when the client pushes packs to the server, meaning the server
+  // will fetch the packs from the client. This is used to advertise the references
+  // available on the server to the client via git-receive-pack(1)'s `--advertise-refs`
+  // option.
   rpc InfoRefsReceivePack(InfoRefsRequest) returns (stream InfoRefsResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // Request and response body for POST /upload-pack using sidechannel protocol
+
+  // PostUploadPackWithSidechannel provides the response for POST /upload-pack. It
+  // used to transfer pack files from the server to the client via sidechannels. This
+  // is invoked when the client executes `git fetch`.
+  //
+  // More info on sidechannels: https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/sidechannel.md
   rpc PostUploadPackWithSidechannel(PostUploadPackWithSidechannelRequest) returns (PostUploadPackWithSidechannelResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // Request and response body for POST /receive-pack
+  // PostReceivePack provides the response for POST /receive-pack. It used to transfer
+  // pack files from the client to the server. This is invoked when the client executes `git push`.
   rpc PostReceivePack(stream PostReceivePackRequest) returns (stream PostReceivePackResponse) {
     option (op_type) = {
       op: MUTATOR
@@ -43,59 +53,66 @@ service SmartHTTPService {
   }
 }
 
-// This comment is left unintentionally blank.
+// InfoRefsRequest is a request for the InfoRefsUploadPack and InfoRefsUploadPack rpcs.
 message InfoRefsRequest {
-  // This comment is left unintentionally blank.
+  // Repository is the repository on which to operate.
   Repository repository = 1 [(target_repository)=true];
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 2;
-
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 3;
 }
 
-// This comment is left unintentionally blank.
+// InfoRefsResponse is the response of InfoRefsUploadPack and InfoRefsUploadPack rpcs.
+// It is used to provide the client with the servers advertised refs.
 message InfoRefsResponse {
-  // This comment is left unintentionally blank.
+  // Data is the raw data copied from the stdout of git-upload-pack(1) or
+  // git-receive-pack(1) when used with the `--advertise-refs` flag.
   bytes data = 1;
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelRequest is the request for the PostUploadPackWithSidechannel rpc.
 message PostUploadPackWithSidechannelRequest {
-  // repository should only be present in the first message of the stream
+  // Repository is the repository on which to operate.
   Repository repository = 1 [(target_repository)=true];
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 2;
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 3;
 }
 
-// This comment is left unintentionally blank.
+// PostUploadPackWithSidechannelResponse is the response for the PostUploadPackWithSidechannel rpc.
+// This is an empty response since the raw data is transferred to the client via the sidechannel
+// exclusively.
 message PostUploadPackWithSidechannelResponse {
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackRequest is the request for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the client to the servers stdin of git-receive-pack(1) process.
 message PostReceivePackRequest {
-  // repository should only be present in the first message of the stream
+  // Repository is the repository on which to operate.
+  // It should only be present in the first message of the stream.
   Repository repository = 1 [(target_repository)=true];
-  // Raw data to be copied to stdin of 'git receive-pack'
+  // Data is the raw data to be copied to stdin of 'git receive-pack'.
   bytes data = 2;
-  // gl_id, gl_repository, and gl_username become env variables, used by the Git {pre,post}-receive
-  // hooks. They should only be present in the first message of the stream.
+  // GlID is the GitLab ID of the user. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_id = 3;
-  // This comment is left unintentionally blank.
+  // GlRepository refers to the GitLab repository. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_repository = 4;
-  // This comment is left unintentionally blank.
+  // GlID is the GitLab Username of the user. This is used by Git {pre,post}-receive hooks.
+  // It should only be present in the first message of the stream.
   string gl_username = 5;
-  // Git protocol version
+  // GitProtocol is the git protocol version.
   string git_protocol = 6;
-
-  // Parameters to use with git -c (key=value pairs)
+  // GitConfigOptions are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 7;
 }
 
-// This comment is left unintentionally blank.
+// PostReceivePackResponse is the response for the PostReceivePack rpc. It is a stream used to
+// transfer the raw data from the stdout of git-receive-pack(1) from the server to the client.
 message PostReceivePackResponse {
-  // Raw data from stdout of 'git receive-pack'
+  // Data is the raw data from the stdout of 'git receive-pack'.
   bytes data = 1;
 }