diff options
author | Patrick Steinhardt <psteinhardt@gitlab.com> | 2022-06-07 15:31:07 +0300 |
---|---|---|
committer | Patrick Steinhardt <psteinhardt@gitlab.com> | 2022-06-07 15:50:47 +0300 |
commit | a78993a3de762d87d4a0c9152ab9a35e9c612c5b (patch) | |
tree | 46690ba8a49a8ce4065c8a840006950eb41780c8 | |
parent | f099614e635d05483055ba6fbebc74d961bf2ce5 (diff) |
proto: Document UserDeleteBranch RPC
The UserDeleteBranch RPC is missing documentation. Add it to document
its behaviour and expected error cases.
-rw-r--r-- | internal/gitaly/service/operations/branches.go | 3 | ||||
-rw-r--r-- | proto/go/gitalypb/operations.pb.go | 17 | ||||
-rw-r--r-- | proto/go/gitalypb/operations_grpc.pb.go | 20 | ||||
-rw-r--r-- | proto/operations.proto | 27 | ||||
-rw-r--r-- | ruby/proto/gitaly/operations_services_pb.rb | 10 |
5 files changed, 60 insertions, 17 deletions
diff --git a/internal/gitaly/service/operations/branches.go b/internal/gitaly/service/operations/branches.go index 8551ae9d7..a1bbb6d9c 100644 --- a/internal/gitaly/service/operations/branches.go +++ b/internal/gitaly/service/operations/branches.go @@ -143,7 +143,8 @@ func (s *Server) UserUpdateBranch(ctx context.Context, req *gitalypb.UserUpdateB return &gitalypb.UserUpdateBranchResponse{}, nil } -//nolint: revive,stylecheck // This is unintentionally missing documentation. +// UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes +// hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. func (s *Server) UserDeleteBranch(ctx context.Context, req *gitalypb.UserDeleteBranchRequest) (*gitalypb.UserDeleteBranchResponse, error) { // That we do the branch name & user check here first only in // UserDelete but not UserCreate is "intentional", i.e. it's diff --git a/proto/go/gitalypb/operations.pb.go b/proto/go/gitalypb/operations.pb.go index 65d40126f..cf7423868 100644 --- a/proto/go/gitalypb/operations.pb.go +++ b/proto/go/gitalypb/operations.pb.go @@ -465,17 +465,21 @@ func (x *UserUpdateBranchResponse) GetPreReceiveError() string { return "" } -// This comment is left unintentionally blank. +// UserDeleteBranchRequest is a request for the UserDeleteBranch RPC. type UserDeleteBranchRequest struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // This comment is left unintentionally blank. + // Repository is the repository to delete the branch in. Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - // This comment is left unintentionally blank. + // BranchName is the name of the branch that shall be deleted. This is expected to be the branch + // name only, e.g. in case you want to delete `refs/heads/main` the request needs to only contain + // `main` as the branch name. BranchName []byte `protobuf:"bytes,2,opt,name=branch_name,json=branchName,proto3" json:"branch_name,omitempty"` - // This comment is left unintentionally blank. + // User is the user on whose behalf we should delete the branch. This information is used to + // perform access checks against the Rails `/internal/allowed` API. This user is also exposed to + // any custom hooks executed as part of this RPC call. User *User `protobuf:"bytes,3,opt,name=user,proto3" json:"user,omitempty"` } @@ -532,13 +536,14 @@ func (x *UserDeleteBranchRequest) GetUser() *User { return nil } -// This comment is left unintentionally blank. +// UserDeleteBranchResponse is a response for the UserDeleteBranch RPC. type UserDeleteBranchResponse struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache unknownFields protoimpl.UnknownFields - // This comment is left unintentionally blank. + // PreReceiveError is an error that is returned in case deletion of the branch failed either + // because of failing access checks or because hooks have refused the update. PreReceiveError string `protobuf:"bytes,1,opt,name=pre_receive_error,json=preReceiveError,proto3" json:"pre_receive_error,omitempty"` } diff --git a/proto/go/gitalypb/operations_grpc.pb.go b/proto/go/gitalypb/operations_grpc.pb.go index a1db433bc..3ee7dabeb 100644 --- a/proto/go/gitalypb/operations_grpc.pb.go +++ b/proto/go/gitalypb/operations_grpc.pb.go @@ -22,7 +22,15 @@ type OperationServiceClient interface { UserCreateBranch(ctx context.Context, in *UserCreateBranchRequest, opts ...grpc.CallOption) (*UserCreateBranchResponse, error) // This comment is left unintentionally blank. UserUpdateBranch(ctx context.Context, in *UserUpdateBranchRequest, opts ...grpc.CallOption) (*UserUpdateBranchResponse, error) - // This comment is left unintentionally blank. + // UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes + // hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The + // following known error conditions may happen: + // + // - Returns `InvalidArgument` in case either the branch name or user are not set. + // - Returns `FailedPrecondition` in case the branch does not exist. + // - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update. + // - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent + // write to the same reference. UserDeleteBranch(ctx context.Context, in *UserDeleteBranchRequest, opts ...grpc.CallOption) (*UserDeleteBranchResponse, error) // UserCreateTag creates a new tag. UserCreateTag(ctx context.Context, in *UserCreateTagRequest, opts ...grpc.CallOption) (*UserCreateTagResponse, error) @@ -324,7 +332,15 @@ type OperationServiceServer interface { UserCreateBranch(context.Context, *UserCreateBranchRequest) (*UserCreateBranchResponse, error) // This comment is left unintentionally blank. UserUpdateBranch(context.Context, *UserUpdateBranchRequest) (*UserUpdateBranchResponse, error) - // This comment is left unintentionally blank. + // UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes + // hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The + // following known error conditions may happen: + // + // - Returns `InvalidArgument` in case either the branch name or user are not set. + // - Returns `FailedPrecondition` in case the branch does not exist. + // - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update. + // - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent + // write to the same reference. UserDeleteBranch(context.Context, *UserDeleteBranchRequest) (*UserDeleteBranchResponse, error) // UserCreateTag creates a new tag. UserCreateTag(context.Context, *UserCreateTagRequest) (*UserCreateTagResponse, error) diff --git a/proto/operations.proto b/proto/operations.proto index c8ac89350..48d71f0e3 100644 --- a/proto/operations.proto +++ b/proto/operations.proto @@ -29,7 +29,15 @@ service OperationService { }; } - // This comment is left unintentionally blank. + // UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes + // hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The + // following known error conditions may happen: + // + // - Returns `InvalidArgument` in case either the branch name or user are not set. + // - Returns `FailedPrecondition` in case the branch does not exist. + // - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update. + // - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent + // write to the same reference. rpc UserDeleteBranch(UserDeleteBranchRequest) returns (UserDeleteBranchResponse) { option (op_type) = { op: MUTATOR @@ -192,19 +200,24 @@ message UserUpdateBranchResponse { string pre_receive_error = 1; } -// This comment is left unintentionally blank. +// UserDeleteBranchRequest is a request for the UserDeleteBranch RPC. message UserDeleteBranchRequest { - // This comment is left unintentionally blank. + // Repository is the repository to delete the branch in. Repository repository = 1 [(target_repository)=true]; - // This comment is left unintentionally blank. + // BranchName is the name of the branch that shall be deleted. This is expected to be the branch + // name only, e.g. in case you want to delete `refs/heads/main` the request needs to only contain + // `main` as the branch name. bytes branch_name = 2; - // This comment is left unintentionally blank. + // User is the user on whose behalf we should delete the branch. This information is used to + // perform access checks against the Rails `/internal/allowed` API. This user is also exposed to + // any custom hooks executed as part of this RPC call. User user = 3; } -// This comment is left unintentionally blank. +// UserDeleteBranchResponse is a response for the UserDeleteBranch RPC. message UserDeleteBranchResponse { - // This comment is left unintentionally blank. + // PreReceiveError is an error that is returned in case deletion of the branch failed either + // because of failing access checks or because hooks have refused the update. string pre_receive_error = 1; } diff --git a/ruby/proto/gitaly/operations_services_pb.rb b/ruby/proto/gitaly/operations_services_pb.rb index 05f1184f4..b71684ee1 100644 --- a/ruby/proto/gitaly/operations_services_pb.rb +++ b/ruby/proto/gitaly/operations_services_pb.rb @@ -22,7 +22,15 @@ module Gitaly rpc :UserCreateBranch, ::Gitaly::UserCreateBranchRequest, ::Gitaly::UserCreateBranchResponse # This comment is left unintentionally blank. rpc :UserUpdateBranch, ::Gitaly::UserUpdateBranchRequest, ::Gitaly::UserUpdateBranchResponse - # This comment is left unintentionally blank. + # UserDeleteBranch force-deletes a single branch in the context of a specific user. It executes + # hooks and contacts Rails to verify that the user is indeed allowed to delete that branch. The + # following known error conditions may happen: + # + # - Returns `InvalidArgument` in case either the branch name or user are not set. + # - Returns `FailedPrecondition` in case the branch does not exist. + # - Returns `OK` with a `PreReceiveError` in case custom hooks refused the update. + # - Returns `FailedPrecondition` in case updating the reference fails because of a concurrent + # write to the same reference. rpc :UserDeleteBranch, ::Gitaly::UserDeleteBranchRequest, ::Gitaly::UserDeleteBranchResponse # UserCreateTag creates a new tag. rpc :UserCreateTag, ::Gitaly::UserCreateTagRequest, ::Gitaly::UserCreateTagResponse |