From 358b8c6e2be0b5f224ac9725aedf75d4a419fa54 Mon Sep 17 00:00:00 2001 From: Injun Song Date: Mon, 22 Jan 2024 00:33:51 +0900 Subject: [PATCH] docs(metarepos): add specification to management RPCs This PR adds specifications to "proto/mrpb/management.proto". This helps us establish agreements for the contracts of the metadata repository's management RPCs. Update: #658 --- proto/mrpb/management.pb.go | 58 +++++++++++++++++++++++++++++++++++++ proto/mrpb/management.proto | 35 ++++++++++++++++++++++ 2 files changed, 93 insertions(+) diff --git a/proto/mrpb/management.pb.go b/proto/mrpb/management.pb.go index 92a6542d8..c9683738f 100644 --- a/proto/mrpb/management.pb.go +++ b/proto/mrpb/management.pb.go @@ -31,6 +31,12 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.GoGoProtoPackageIsVersion3 // please upgrade the proto package +// AddPeerRequest is a request message for AddPeer RPC. +// +// TODO: TODO: Define a new message representing a new peer, such as "Peer" or +// "PeerInfo" and use it rather than primitive-type fields. +// See: +// - https://protobuf.dev/programming-guides/api/#dont-include-primitive-types type AddPeerRequest struct { ClusterID github_com_kakao_varlog_pkg_types.ClusterID `protobuf:"varint,1,opt,name=cluster_id,json=clusterId,proto3,casttype=github.com/kakao/varlog/pkg/types.ClusterID" json:"cluster_id,omitempty"` NodeID github_com_kakao_varlog_pkg_types.NodeID `protobuf:"varint,2,opt,name=node_id,json=nodeId,proto3,casttype=github.com/kakao/varlog/pkg/types.NodeID" json:"node_id,omitempty"` @@ -91,6 +97,7 @@ func (m *AddPeerRequest) GetUrl() string { return "" } +// RemovePeerRequest is a request message for RemovePeer RPC. type RemovePeerRequest struct { ClusterID github_com_kakao_varlog_pkg_types.ClusterID `protobuf:"varint,1,opt,name=cluster_id,json=clusterId,proto3,casttype=github.com/kakao/varlog/pkg/types.ClusterID" json:"cluster_id,omitempty"` NodeID github_com_kakao_varlog_pkg_types.NodeID `protobuf:"varint,2,opt,name=node_id,json=nodeId,proto3,casttype=github.com/kakao/varlog/pkg/types.NodeID" json:"node_id,omitempty"` @@ -143,6 +150,7 @@ func (m *RemovePeerRequest) GetNodeID() github_com_kakao_varlog_pkg_types.NodeID return 0 } +// GetClusterInfoRequest is a request message for GetClusterInfo RPC. type GetClusterInfoRequest struct { ClusterID github_com_kakao_varlog_pkg_types.ClusterID `protobuf:"varint,1,opt,name=cluster_id,json=clusterId,proto3,casttype=github.com/kakao/varlog/pkg/types.ClusterID" json:"cluster_id,omitempty"` } @@ -187,6 +195,7 @@ func (m *GetClusterInfoRequest) GetClusterID() github_com_kakao_varlog_pkg_types return 0 } +// ClusterInfo is a metadata representing the Raft cluster. type ClusterInfo struct { ClusterID github_com_kakao_varlog_pkg_types.ClusterID `protobuf:"varint,1,opt,name=cluster_id,json=clusterId,proto3,casttype=github.com/kakao/varlog/pkg/types.ClusterID" json:"clusterId"` NodeID github_com_kakao_varlog_pkg_types.NodeID `protobuf:"varint,2,opt,name=node_id,json=nodeId,proto3,casttype=github.com/kakao/varlog/pkg/types.NodeID" json:"nodeId"` @@ -334,6 +343,7 @@ func (m *ClusterInfo_Member) GetLearner() bool { return false } +// GetClusterInfoResponse is a response message for GetClusterInfo RPC. type GetClusterInfoResponse struct { ClusterInfo *ClusterInfo `protobuf:"bytes,1,opt,name=cluster_info,json=clusterInfo,proto3" json:"cluster_info,omitempty"` } @@ -448,8 +458,32 @@ const _ = grpc.SupportPackageIsVersion4 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type ManagementClient interface { + // AddPeer is a remote procedure to add a new node to the Raft cluster. If the + // node is already a member or learner, it fails and returns the gRPC status + // code "AlreadyExists". Users can cancel this RPC, but it doesn't guarantee + // that adding a new peer is not handled. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. AddPeer(ctx context.Context, in *AddPeerRequest, opts ...grpc.CallOption) (*types.Empty, error) + // RemovePeer is a remote procedure to remove a node from the Raft cluster. If + // the node is neither a member nor a learner of the cluster, it fails and + // returns the gRPC status code "NotFound". Users can cancel this RPC, but it + // doesn't guarantee that the node will not be removed. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. RemovePeer(ctx context.Context, in *RemovePeerRequest, opts ...grpc.CallOption) (*types.Empty, error) + // GetClusterInfo is a remote procedure used to retrieve information about the + // Raft cluster, specifically the ClusterInfo. If the current node is not a + // member of the cluster, it will fail and return the gRPC status code + // "codes.Unavailable". + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. + // + // TODO: Define ClusterInfo, which should contain the Raft cluster metadata. + // Some fields will be removed due to unmatched semantics. GetClusterInfo(ctx context.Context, in *GetClusterInfoRequest, opts ...grpc.CallOption) (*GetClusterInfoResponse, error) } @@ -490,8 +524,32 @@ func (c *managementClient) GetClusterInfo(ctx context.Context, in *GetClusterInf // ManagementServer is the server API for Management service. type ManagementServer interface { + // AddPeer is a remote procedure to add a new node to the Raft cluster. If the + // node is already a member or learner, it fails and returns the gRPC status + // code "AlreadyExists". Users can cancel this RPC, but it doesn't guarantee + // that adding a new peer is not handled. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. AddPeer(context.Context, *AddPeerRequest) (*types.Empty, error) + // RemovePeer is a remote procedure to remove a node from the Raft cluster. If + // the node is neither a member nor a learner of the cluster, it fails and + // returns the gRPC status code "NotFound". Users can cancel this RPC, but it + // doesn't guarantee that the node will not be removed. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. RemovePeer(context.Context, *RemovePeerRequest) (*types.Empty, error) + // GetClusterInfo is a remote procedure used to retrieve information about the + // Raft cluster, specifically the ClusterInfo. If the current node is not a + // member of the cluster, it will fail and return the gRPC status code + // "codes.Unavailable". + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. + // + // TODO: Define ClusterInfo, which should contain the Raft cluster metadata. + // Some fields will be removed due to unmatched semantics. GetClusterInfo(context.Context, *GetClusterInfoRequest) (*GetClusterInfoResponse, error) } diff --git a/proto/mrpb/management.proto b/proto/mrpb/management.proto index c0358f862..651df504a 100644 --- a/proto/mrpb/management.proto +++ b/proto/mrpb/management.proto @@ -14,6 +14,12 @@ option (gogoproto.goproto_unkeyed_all) = false; option (gogoproto.goproto_unrecognized_all) = false; option (gogoproto.goproto_sizecache_all) = false; +// AddPeerRequest is a request message for AddPeer RPC. +// +// TODO: TODO: Define a new message representing a new peer, such as "Peer" or +// "PeerInfo" and use it rather than primitive-type fields. +// See: +// - https://protobuf.dev/programming-guides/api/#dont-include-primitive-types message AddPeerRequest { int32 cluster_id = 1 [ (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.ClusterID", @@ -28,6 +34,7 @@ message AddPeerRequest { string url = 3; } +// RemovePeerRequest is a request message for RemovePeer RPC. message RemovePeerRequest { int32 cluster_id = 1 [ (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.ClusterID", @@ -40,6 +47,7 @@ message RemovePeerRequest { ]; } +// GetClusterInfoRequest is a request message for GetClusterInfo RPC. message GetClusterInfoRequest { int32 cluster_id = 1 [ (gogoproto.casttype) = "github.com/kakao/varlog/pkg/types.ClusterID", @@ -47,6 +55,7 @@ message GetClusterInfoRequest { ]; } +// ClusterInfo is a metadata representing the Raft cluster. message ClusterInfo { message Member { string peer = 1; @@ -80,12 +89,38 @@ message ClusterInfo { uint64 applied_index = 6 [(gogoproto.jsontag) = "appliedIndex"]; } +// GetClusterInfoResponse is a response message for GetClusterInfo RPC. message GetClusterInfoResponse { ClusterInfo cluster_info = 1; } +// Management service manages the Raft cluster of the Metadata Repository. service Management { + // AddPeer is a remote procedure to add a new node to the Raft cluster. If the + // node is already a member or learner, it fails and returns the gRPC status + // code "AlreadyExists". Users can cancel this RPC, but it doesn't guarantee + // that adding a new peer is not handled. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. rpc AddPeer(AddPeerRequest) returns (google.protobuf.Empty) {} + // RemovePeer is a remote procedure to remove a node from the Raft cluster. If + // the node is neither a member nor a learner of the cluster, it fails and + // returns the gRPC status code "NotFound". Users can cancel this RPC, but it + // doesn't guarantee that the node will not be removed. + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. rpc RemovePeer(RemovePeerRequest) returns (google.protobuf.Empty) {} + // GetClusterInfo is a remote procedure used to retrieve information about the + // Raft cluster, specifically the ClusterInfo. If the current node is not a + // member of the cluster, it will fail and return the gRPC status code + // "codes.Unavailable". + // + // TODO: Check if the cluster ID is the same as the current node's. If they + // are not the same, return a proper gRPC status code. + // + // TODO: Define ClusterInfo, which should contain the Raft cluster metadata. + // Some fields will be removed due to unmatched semantics. rpc GetClusterInfo(GetClusterInfoRequest) returns (GetClusterInfoResponse) {} }