From 6f2d408dc300d8df52a0769c9597367638043926 Mon Sep 17 00:00:00 2001 From: Justin Tobler Date: Mon, 20 Nov 2023 22:33:28 -0600 Subject: proto: Add documentation for `SSHService` Some of the RPC definitions and protobuf message types in the `SSHService` lack documentation. Add the missing documentation. --- proto/go/gitalypb/ssh.pb.go | 57 +++++++++++++++++------------- proto/go/gitalypb/ssh_grpc.pb.go | 34 +++++++++++++----- proto/ssh.proto | 76 ++++++++++++++++++++++++---------------- 3 files changed, 103 insertions(+), 64 deletions(-) (limited to 'proto') 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. -- cgit v1.2.3