proto: Add documentation for `SSHService`

Some of the RPC definitions and protobuf message types in the
`SSHService` lack documentation. Add the missing documentation.

3 files changed, 103 insertions, 64 deletions

diff --git a/proto/go/gitalypb/ssh.pb.go b/proto/go/gitalypb/ssh.pb.go
index 8fad39755..9812e0cce 100644
--- a/proto/go/gitalypb/ssh.pb.go
+++ b/proto/go/gitalypb/ssh.pb.go
@@ -20,15 +20,17 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
-// SSHUploadPackRequest ...
+// SSHUploadPackRequest is a request for the SSHUploadPack RPC. The first request of the stream must
+// only contain repository, git_config_options, and git_protocol. All subsequent requests must only
+// contain stdin data.
 type SSHUploadPackRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository must be present in the first message.
+	// repository is the repository where git-upload-pack(1) is spawned.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// stdin is a chunk of raw data to be copied to 'git upload-pack' standard input.
+	// stdin is a chunk of raw data to be copied to git-upload-pack(1) standard input.
 	Stdin []byte `protobuf:"bytes,2,opt,name=stdin,proto3" json:"stdin,omitempty"`
 	// git_config_options are parameters to use with git -c (key=value pairs).
 	GitConfigOptions []string `protobuf:"bytes,4,rep,name=git_config_options,json=gitConfigOptions,proto3" json:"git_config_options,omitempty"`
@@ -96,15 +98,16 @@ func (x *SSHUploadPackRequest) GetGitProtocol() string {
 	return ""
 }
 
-// SSHUploadPackResponse ...
+// SSHUploadPackResponse is a response for the SSHUploadPack RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-upload-pack(1).
 type SSHUploadPackResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// stdout is a chunk of raw data from 'git upload-pack' standard output.
+	// stdout is a chunk of raw data from git-upload-pack(1) standard output.
 	Stdout []byte `protobuf:"bytes,1,opt,name=stdout,proto3" json:"stdout,omitempty"`
-	// stderr is a chunk of raw data from 'git upload-pack' standard error.
+	// stderr is a chunk of raw data from git-upload-pack(1) standard error.
 	Stderr []byte `protobuf:"bytes,2,opt,name=stderr,proto3" json:"stderr,omitempty"`
 	// exit_status is the exit status when the command has finished. This field
 	// may be nil. This is intentional.
@@ -164,13 +167,13 @@ func (x *SSHUploadPackResponse) GetExitStatus() *ExitStatus {
 	return nil
 }
 
-// SSHUploadPackWithSidechannelRequest ...
+// SSHUploadPackWithSidechannelRequest is a request for the SSHUploadPackWithSidechannel RPC.
 type SSHUploadPackWithSidechannelRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository must be present in the first message.
+	// repository is the repository where git-upload-pack(1) is spawned.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
 	// git_config_options 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"`
@@ -231,7 +234,7 @@ func (x *SSHUploadPackWithSidechannelRequest) GetGitProtocol() string {
 	return ""
 }
 
-// SSHUploadPackWithSidechannelResponse ...
+// SSHUploadPackWithSidechannelResponse is a response for the SSHUploadPackWithSidechannel RPC.
 type SSHUploadPackWithSidechannelResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -280,22 +283,23 @@ func (x *SSHUploadPackWithSidechannelResponse) GetPackfileNegotiationStatistics(
 	return nil
 }
 
-// SSHReceivePackRequest ...
+// SSHReceivePackRequest is a request for the SSHReceivePack RPC. All fields other than stdin must
+// be set in the first request message. Subsequent requests in the stream must only contain the
+// stdin field.
 type SSHReceivePackRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository must be present in the first message.
+	// repository is the repository where git-receive-pack(1) is spawned.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// stdin is a chunk of raw data to be copied to 'git upload-pack' standard input
+	// stdin is a chunk of raw data to be copied to git-receive-pack(1) standard input
 	Stdin []byte `protobuf:"bytes,2,opt,name=stdin,proto3" json:"stdin,omitempty"`
-	// gl_id is the contents of GL_ID, GL_REPOSITORY, and GL_USERNAME environment variables
-	// for 'git receive-pack'.
+	// gl_id is the GitLab ID of the user. This is used by Git {pre,post}-receive hooks.
 	GlId string `protobuf:"bytes,3,opt,name=gl_id,json=glId,proto3" json:"gl_id,omitempty"`
-	// gl_repository ...
+	// gl_repository refers to the GitLab repository. This is used by Git {pre,post}-receive hooks.
 	GlRepository string `protobuf:"bytes,4,opt,name=gl_repository,json=glRepository,proto3" json:"gl_repository,omitempty"`
-	// gl_username ...
+	// gl_username is the GitLab Username of the user. This is used by Git {pre,post}-receive hooks.
 	GlUsername string `protobuf:"bytes,5,opt,name=gl_username,json=glUsername,proto3" json:"gl_username,omitempty"`
 	// git_protocol is the git protocol version.
 	GitProtocol string `protobuf:"bytes,6,opt,name=git_protocol,json=gitProtocol,proto3" json:"git_protocol,omitempty"`
@@ -384,15 +388,16 @@ func (x *SSHReceivePackRequest) GetGitConfigOptions() []string {
 	return nil
 }
 
-// SSHReceivePackResponse ...
+// SSHReceivePackResponse is a response for the SSHReceivePack RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-receive-pack(1).
 type SSHReceivePackResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// stdout is a chunk of raw data from 'git receive-pack' standard output.
+	// stdout is a chunk of raw data from git-receive-pack(1) standard output.
 	Stdout []byte `protobuf:"bytes,1,opt,name=stdout,proto3" json:"stdout,omitempty"`
-	// stderr is a chunk of raw data from 'git receive-pack' standard error.
+	// stderr is a chunk of raw data from git-receive-pack(1) standard error.
 	Stderr []byte `protobuf:"bytes,2,opt,name=stderr,proto3" json:"stderr,omitempty"`
 	// exit_status is the exit status when the command has finished. This field
 	// may be nil. This is intentional.
@@ -452,15 +457,16 @@ func (x *SSHReceivePackResponse) GetExitStatus() *ExitStatus {
 	return nil
 }
 
-// SSHUploadArchiveRequest ...
+// SSHUploadArchiveRequest is a request for the SSHUploadArchive RPC. The first request of the
+// stream must only contain repository. All subsequent requests must only contain stdin data.
 type SSHUploadArchiveRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository must be present in the first message.
+	// repository is the repository where git-upload-archive(1) is spawned.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// stdin is a chunk of raw data to be copied to 'git upload-archive' standard input.
+	// stdin is a chunk of raw data to be copied to git-upload-archive(1) standard input.
 	Stdin []byte `protobuf:"bytes,2,opt,name=stdin,proto3" json:"stdin,omitempty"`
 }
 
@@ -510,15 +516,16 @@ func (x *SSHUploadArchiveRequest) GetStdin() []byte {
 	return nil
 }
 
-// SSHUploadArchiveResponse ...
+// SSHUploadArchiveResponse is a response for the SSHUploadArchive RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-upload-archive(1).
 type SSHUploadArchiveResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// stdout is a chunk of raw data from 'git upload-archive' standard output.
+	// stdout is a chunk of raw data from git-upload-archive(1) standard output.
 	Stdout []byte `protobuf:"bytes,1,opt,name=stdout,proto3" json:"stdout,omitempty"`
-	// stderr is a chunk of raw data from 'git upload-archive' standard error.
+	// stderr is a chunk of raw data from git-upload-archive(1) standard error.
 	Stderr []byte `protobuf:"bytes,2,opt,name=stderr,proto3" json:"stderr,omitempty"`
 	// exit_status is the exit status when the command has finished. This field
 	// may be nil. This is intentional.
diff --git a/proto/go/gitalypb/ssh_grpc.pb.go b/proto/go/gitalypb/ssh_grpc.pb.go
index 27343b9ac..80ccdc879 100644
--- a/proto/go/gitalypb/ssh_grpc.pb.go
+++ b/proto/go/gitalypb/ssh_grpc.pb.go
@@ -22,13 +22,22 @@ 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 SSHServiceClient interface {
-	// SSHUploadPack is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions.
+	// SSHUploadPack is an RPC to forward git-upload-pack(1) to Gitaly for SSH sessions. The RPC uses
+	// bidirectional streaming so the client can stream stdin and the server can stream stdout and
+	// stderr for git-upload-pack(1).
 	SSHUploadPack(ctx context.Context, opts ...grpc.CallOption) (SSHService_SSHUploadPackClient, error)
-	// SSHUploadPackWithSidechannel is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions, via sidechannels.
+	// SSHUploadPackWithSidechannel is an RPC to forward git-upload-pack(1) to Gitaly for SSH
+	// sessions, via sidechannels. Sidechannel connections sidestep gRPC Protobuf message overhead and
+	// allow higher throughput of bulk data transfers. The stdin, stdout, and stderr for the
+	// git-upload-pack(1) are streamed through the sidechannel connection.
 	SSHUploadPackWithSidechannel(ctx context.Context, in *SSHUploadPackWithSidechannelRequest, opts ...grpc.CallOption) (*SSHUploadPackWithSidechannelResponse, error)
-	// SSHReceivePack is an RPC to forward 'git receive-pack' to Gitaly for SSH sessions.
+	// SSHReceivePack is an RPC to forward git-receive-pack(1) to Gitaly for SSH sessions. The RPC uses
+	// bidirectional streaming so the client can stream stdin and the server can stream stdout and
+	// stderr for git-receive-pack(1).
 	SSHReceivePack(ctx context.Context, opts ...grpc.CallOption) (SSHService_SSHReceivePackClient, error)
-	// SSHUploadArchive is an RPC to forward 'git upload-archive' to Gitaly for SSH sessions.
+	// SSHUploadArchive is an RPC to forward git-upload-archive(1) to Gitaly for SSH sessions. The RPC
+	// uses bidirectional streaming so the client can stream stdin and the server can stream stdout
+	// and stderr for git-upload-archive(1).
 	SSHUploadArchive(ctx context.Context, opts ...grpc.CallOption) (SSHService_SSHUploadArchiveClient, error)
 }
 
@@ -146,13 +155,22 @@ func (x *sSHServiceSSHUploadArchiveClient) Recv() (*SSHUploadArchiveResponse, er
 // All implementations must embed UnimplementedSSHServiceServer
 // for forward compatibility
 type SSHServiceServer interface {
-	// SSHUploadPack is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions.
+	// SSHUploadPack is an RPC to forward git-upload-pack(1) to Gitaly for SSH sessions. The RPC uses
+	// bidirectional streaming so the client can stream stdin and the server can stream stdout and
+	// stderr for git-upload-pack(1).
 	SSHUploadPack(SSHService_SSHUploadPackServer) error
-	// SSHUploadPackWithSidechannel is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions, via sidechannels.
+	// SSHUploadPackWithSidechannel is an RPC to forward git-upload-pack(1) to Gitaly for SSH
+	// sessions, via sidechannels. Sidechannel connections sidestep gRPC Protobuf message overhead and
+	// allow higher throughput of bulk data transfers. The stdin, stdout, and stderr for the
+	// git-upload-pack(1) are streamed through the sidechannel connection.
 	SSHUploadPackWithSidechannel(context.Context, *SSHUploadPackWithSidechannelRequest) (*SSHUploadPackWithSidechannelResponse, error)
-	// SSHReceivePack is an RPC to forward 'git receive-pack' to Gitaly for SSH sessions.
+	// SSHReceivePack is an RPC to forward git-receive-pack(1) to Gitaly for SSH sessions. The RPC uses
+	// bidirectional streaming so the client can stream stdin and the server can stream stdout and
+	// stderr for git-receive-pack(1).
 	SSHReceivePack(SSHService_SSHReceivePackServer) error
-	// SSHUploadArchive is an RPC to forward 'git upload-archive' to Gitaly for SSH sessions.
+	// SSHUploadArchive is an RPC to forward git-upload-archive(1) to Gitaly for SSH sessions. The RPC
+	// uses bidirectional streaming so the client can stream stdin and the server can stream stdout
+	// and stderr for git-upload-archive(1).
 	SSHUploadArchive(SSHService_SSHUploadArchiveServer) error
 	mustEmbedUnimplementedSSHServiceServer()
 }
diff --git a/proto/ssh.proto b/proto/ssh.proto
index 08a9f4b12..95a1db249 100644
--- a/proto/ssh.proto
+++ b/proto/ssh.proto
@@ -10,28 +10,37 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";
 
 // SSHService is a service that provides RPCs required for SSH-based Git clones.
 service SSHService {
-  // SSHUploadPack is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions.
+  // SSHUploadPack is an RPC to forward git-upload-pack(1) to Gitaly for SSH sessions. The RPC uses
+  // bidirectional streaming so the client can stream stdin and the server can stream stdout and
+  // stderr for git-upload-pack(1).
   rpc SSHUploadPack(stream SSHUploadPackRequest) returns (stream SSHUploadPackResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // SSHUploadPackWithSidechannel is an RPC to forward 'git upload-pack' to Gitaly for SSH sessions, via sidechannels.
+  // SSHUploadPackWithSidechannel is an RPC to forward git-upload-pack(1) to Gitaly for SSH
+  // sessions, via sidechannels. Sidechannel connections sidestep gRPC Protobuf message overhead and
+  // allow higher throughput of bulk data transfers. The stdin, stdout, and stderr for the
+  // git-upload-pack(1) are streamed through the sidechannel connection.
   rpc SSHUploadPackWithSidechannel(SSHUploadPackWithSidechannelRequest) returns (SSHUploadPackWithSidechannelResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // SSHReceivePack is an RPC to forward 'git receive-pack' to Gitaly for SSH sessions.
+  // SSHReceivePack is an RPC to forward git-receive-pack(1) to Gitaly for SSH sessions. The RPC uses
+  // bidirectional streaming so the client can stream stdin and the server can stream stdout and
+  // stderr for git-receive-pack(1).
   rpc SSHReceivePack(stream SSHReceivePackRequest) returns (stream SSHReceivePackResponse) {
     option (op_type) = {
       op: MUTATOR
     };
   }
 
-  // SSHUploadArchive is an RPC to forward 'git upload-archive' to Gitaly for SSH sessions.
+  // SSHUploadArchive is an RPC to forward git-upload-archive(1) to Gitaly for SSH sessions. The RPC
+  // uses bidirectional streaming so the client can stream stdin and the server can stream stdout
+  // and stderr for git-upload-archive(1).
   rpc SSHUploadArchive(stream SSHUploadArchiveRequest) returns (stream SSHUploadArchiveResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -39,62 +48,64 @@ service SSHService {
   }
 }
 
-// SSHUploadPackRequest ...
+// SSHUploadPackRequest is a request for the SSHUploadPack RPC. The first request of the stream must
+// only contain repository, git_config_options, and git_protocol. All subsequent requests must only
+// contain stdin data.
 message SSHUploadPackRequest {
-  // repository must be present in the first message.
+  // repository is the repository where git-upload-pack(1) is spawned.
   Repository repository = 1 [(target_repository)=true];
-  // stdin is a chunk of raw data to be copied to 'git upload-pack' standard input.
+  // stdin is a chunk of raw data to be copied to git-upload-pack(1) standard input.
   bytes stdin = 2;
   // Prevent re-use of field id 3 and/or the "git_config_parameters" name.
   reserved 3;
   reserved "git_config_parameters";
   // git_config_options are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 4;
-
   // git_protocol is the git protocol version.
   string git_protocol = 5;
 }
 
-// SSHUploadPackResponse ...
+// SSHUploadPackResponse is a response for the SSHUploadPack RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-upload-pack(1).
 message SSHUploadPackResponse {
-  // stdout is a chunk of raw data from 'git upload-pack' standard output.
+  // stdout is a chunk of raw data from git-upload-pack(1) standard output.
   bytes stdout = 1;
-  // stderr is a chunk of raw data from 'git upload-pack' standard error.
+  // stderr is a chunk of raw data from git-upload-pack(1) standard error.
   bytes stderr = 2;
   // exit_status is the exit status when the command has finished. This field
   // may be nil. This is intentional.
   ExitStatus exit_status = 3;
 }
 
-// SSHUploadPackWithSidechannelRequest ...
+// SSHUploadPackWithSidechannelRequest is a request for the SSHUploadPackWithSidechannel RPC.
 message SSHUploadPackWithSidechannelRequest {
-  // repository must be present in the first message.
+  // repository is the repository where git-upload-pack(1) is spawned.
   Repository repository = 1 [(target_repository)=true];
   // git_config_options are parameters to use with git -c (key=value pairs).
   repeated string git_config_options = 2;
-
   // git_protocol is the git protocol version.
   string git_protocol = 3;
 }
 
-// SSHUploadPackWithSidechannelResponse ...
+// SSHUploadPackWithSidechannelResponse is a response for the SSHUploadPackWithSidechannel RPC.
 message SSHUploadPackWithSidechannelResponse {
   // packfile_negotiation_statistics is the packfile negotiation statistics.
   PackfileNegotiationStatistics packfile_negotiation_statistics = 1;
 }
 
-// SSHReceivePackRequest ...
+// SSHReceivePackRequest is a request for the SSHReceivePack RPC. All fields other than stdin must
+// be set in the first request message. Subsequent requests in the stream must only contain the
+// stdin field.
 message SSHReceivePackRequest {
-  // repository must be present in the first message.
+  // repository is the repository where git-receive-pack(1) is spawned.
   Repository repository = 1 [(target_repository)=true];
-  // stdin is a chunk of raw data to be copied to 'git upload-pack' standard input
+  // stdin is a chunk of raw data to be copied to git-receive-pack(1) standard input
   bytes stdin = 2;
-  // gl_id is the contents of GL_ID, GL_REPOSITORY, and GL_USERNAME environment variables
-  // for 'git receive-pack'.
+  // gl_id is the GitLab ID of the user. This is used by Git {pre,post}-receive hooks.
   string gl_id = 3;
-  // gl_repository ...
+  // gl_repository refers to the GitLab repository. This is used by Git {pre,post}-receive hooks.
   string gl_repository = 4;
-  // gl_username ...
+  // gl_username is the GitLab Username of the user. This is used by Git {pre,post}-receive hooks.
   string gl_username = 5;
   // git_protocol is the git protocol version.
   string git_protocol = 6;
@@ -102,30 +113,33 @@ message SSHReceivePackRequest {
   repeated string git_config_options = 7;
 }
 
-// SSHReceivePackResponse ...
+// SSHReceivePackResponse is a response for the SSHReceivePack RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-receive-pack(1).
 message SSHReceivePackResponse {
-  // stdout is a chunk of raw data from 'git receive-pack' standard output.
+  // stdout is a chunk of raw data from git-receive-pack(1) standard output.
   bytes stdout = 1;
-  // stderr is a chunk of raw data from 'git receive-pack' standard error.
+  // stderr is a chunk of raw data from git-receive-pack(1) standard error.
   bytes stderr = 2;
   // exit_status is the exit status when the command has finished. This field
   // may be nil. This is intentional.
   ExitStatus exit_status = 3;
 }
 
-// SSHUploadArchiveRequest ...
+// SSHUploadArchiveRequest is a request for the SSHUploadArchive RPC. The first request of the
+// stream must only contain repository. All subsequent requests must only contain stdin data.
 message SSHUploadArchiveRequest {
-  // repository must be present in the first message.
+  // repository is the repository where git-upload-archive(1) is spawned.
   Repository repository = 1 [(target_repository)=true];
-  // stdin is a chunk of raw data to be copied to 'git upload-archive' standard input.
+  // stdin is a chunk of raw data to be copied to git-upload-archive(1) standard input.
   bytes stdin = 2;
 }
 
-// SSHUploadArchiveResponse ...
+// SSHUploadArchiveResponse is a response for the SSHUploadArchive RPC. Responses are stream back to
+// clients in chunks containing the stdout and stderr from git-upload-archive(1).
 message SSHUploadArchiveResponse {
-  // stdout is a chunk of raw data from 'git upload-archive' standard output.
+  // stdout is a chunk of raw data from git-upload-archive(1) standard output.
   bytes stdout = 1;
-  // stderr is a chunk of raw data from 'git upload-archive' standard error.
+  // stderr is a chunk of raw data from git-upload-archive(1) standard error.
   bytes stderr = 2;
   // exit_status is the exit status when the command has finished. This field
   // may be nil. This is intentional.