use std::{
future::{Future, IntoFuture},
pin::Pin,
task::{Context, Poll},
};
use crate::{Client, ClusterResponseHeader, MemberId, client::ClientInner, pb::etcdserverpb};
impl Client {
pub fn member_list(&self) -> MemberList<Self> {
MemberList::new().with_client(self.clone())
}
pub fn member_add(&self, peer_urls: impl IntoIterator<Item = impl Into<String>>) -> MemberAdd<Self> {
MemberAdd::new(peer_urls).with_client(self.clone())
}
pub fn member_remove(&self, member_id: MemberId) -> MemberRemove<Self> {
MemberRemove::new(member_id).with_client(self.clone())
}
pub fn member_update(
&self,
member_id: MemberId,
peer_urls: impl IntoIterator<Item = impl Into<String>>,
) -> MemberUpdate<Self> {
MemberUpdate::new(member_id, peer_urls).with_client(self.clone())
}
pub fn member_promote(&self, member_id: MemberId) -> MemberPromote<Self> {
MemberPromote::new(member_id).with_client(self.clone())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Member {
id: MemberId,
name: String,
peer_urls: Vec<String>,
client_urls: Vec<String>,
is_learner: bool,
}
impl Member {
pub(crate) fn from_pb(pb: etcdserverpb::Member) -> Self {
Self {
id: MemberId::new(pb.id).expect("Member should have a non-zero ID"),
name: pb.name,
peer_urls: pb.peer_ur_ls,
client_urls: pb.client_ur_ls,
is_learner: pb.is_learner,
}
}
pub fn id(&self) -> MemberId {
self.id
}
pub fn name(&self) -> &str {
&self.name
}
pub fn peer_urls(&self) -> &[String] {
&self.peer_urls
}
pub fn client_urls(&self) -> &[String] {
&self.client_urls
}
pub fn is_learner(&self) -> bool {
self.is_learner
}
}
#[derive(Clone)]
#[must_use = "MemberList does nothing unless you `await` it"]
pub struct MemberList<C> {
client: C,
pub(crate) request: etcdserverpb::MemberListRequest,
}
impl MemberList<()> {
#[allow(clippy::new_without_default)]
pub fn new() -> Self {
Self {
client: (),
request: etcdserverpb::MemberListRequest::default(),
}
}
}
impl<C> MemberList<C> {
pub fn with_client<C2>(self, client: C2) -> MemberList<C2> {
MemberList {
client,
request: self.request,
}
}
pub fn linearizable(mut self) -> Self {
self.request.linearizable = true;
self
}
pub fn is_linearizable(&self) -> bool {
self.request.linearizable
}
pub(crate) fn into_parts(self) -> (C, MemberList<()>) {
(
self.client,
MemberList {
client: (),
request: self.request,
},
)
}
}
pub struct MemberListFuture(Pin<Box<dyn Future<Output = Result<MemberListResponse, ClusterError>> + Send>>);
impl MemberListFuture {
pub(crate) fn new(future: impl Future<Output = Result<MemberListResponse, ClusterError>> + Send + 'static) -> Self {
Self(Box::pin(future))
}
}
impl Future for MemberListFuture {
type Output = Result<MemberListResponse, ClusterError>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.get_mut().0.as_mut().poll(cx)
}
}
impl<C: crate::driver::ClusterDriver> IntoFuture for MemberList<C> {
type Output = Result<MemberListResponse, ClusterError>;
type IntoFuture = C::MemberListFuture;
fn into_future(self) -> Self::IntoFuture {
let (client, detached) = self.into_parts();
client.execute_member_list(detached)
}
}
#[derive(Clone, Debug)]
pub struct MemberListResponse {
header: ClusterResponseHeader,
members: Vec<Member>,
}
impl MemberListResponse {
pub(crate) fn new(header: ClusterResponseHeader, members: Vec<Member>) -> Self {
Self { header, members }
}
pub fn header(&self) -> &ClusterResponseHeader {
&self.header
}
pub fn members(&self) -> &[Member] {
&self.members
}
pub fn into_members(self) -> Vec<Member> {
self.members
}
}
#[derive(Clone)]
#[must_use = "MemberAdd does nothing unless you `await` it"]
pub struct MemberAdd<C> {
client: C,
pub(crate) request: etcdserverpb::MemberAddRequest,
}
impl MemberAdd<()> {
pub fn new(peer_urls: impl IntoIterator<Item = impl Into<String>>) -> Self {
Self {
client: (),
request: etcdserverpb::MemberAddRequest {
peer_ur_ls: peer_urls.into_iter().map(Into::into).collect(),
is_learner: false,
},
}
}
}
impl<C> MemberAdd<C> {
pub fn with_client<C2>(self, client: C2) -> MemberAdd<C2> {
MemberAdd {
client,
request: self.request,
}
}
pub fn is_learner(mut self, is_learner: bool) -> Self {
self.request.is_learner = is_learner;
self
}
pub fn peer_urls(&self) -> &[String] {
&self.request.peer_ur_ls
}
pub fn is_learner_member(&self) -> bool {
self.request.is_learner
}
pub(crate) fn into_parts(self) -> (C, MemberAdd<()>) {
(
self.client,
MemberAdd {
client: (),
request: self.request,
},
)
}
}
pub struct MemberAddFuture(Pin<Box<dyn Future<Output = Result<MemberAddResponse, ClusterError>> + Send>>);
impl MemberAddFuture {
pub(crate) fn new(future: impl Future<Output = Result<MemberAddResponse, ClusterError>> + Send + 'static) -> Self {
Self(Box::pin(future))
}
}
impl Future for MemberAddFuture {
type Output = Result<MemberAddResponse, ClusterError>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.get_mut().0.as_mut().poll(cx)
}
}
impl<C: crate::driver::ClusterDriver> IntoFuture for MemberAdd<C> {
type Output = Result<MemberAddResponse, ClusterError>;
type IntoFuture = C::MemberAddFuture;
fn into_future(self) -> Self::IntoFuture {
let (client, detached) = self.into_parts();
client.execute_member_add(detached)
}
}
#[derive(Clone, Debug)]
pub struct MemberAddResponse {
header: ClusterResponseHeader,
member: Member,
members: Vec<Member>,
}
impl MemberAddResponse {
pub(crate) fn new(header: ClusterResponseHeader, member: Member, members: Vec<Member>) -> Self {
Self {
header,
member,
members,
}
}
pub fn header(&self) -> &ClusterResponseHeader {
&self.header
}
pub fn member(&self) -> &Member {
&self.member
}
pub fn members(&self) -> &[Member] {
&self.members
}
}
#[derive(Clone)]
#[must_use = "MemberRemove does nothing unless you `await` it"]
pub struct MemberRemove<C> {
client: C,
pub(crate) request: etcdserverpb::MemberRemoveRequest,
}
impl MemberRemove<()> {
pub fn new(member_id: MemberId) -> Self {
Self {
client: (),
request: etcdserverpb::MemberRemoveRequest { id: member_id.get() },
}
}
}
impl<C> MemberRemove<C> {
pub fn with_client<C2>(self, client: C2) -> MemberRemove<C2> {
MemberRemove {
client,
request: self.request,
}
}
pub fn member_id(&self) -> MemberId {
MemberId::new(self.request.id).expect("member remove request should have a member ID")
}
pub(crate) fn into_parts(self) -> (C, MemberRemove<()>) {
(
self.client,
MemberRemove {
client: (),
request: self.request,
},
)
}
}
pub struct MemberRemoveFuture(Pin<Box<dyn Future<Output = Result<MemberRemoveResponse, ClusterError>> + Send>>);
impl MemberRemoveFuture {
pub(crate) fn new(
future: impl Future<Output = Result<MemberRemoveResponse, ClusterError>> + Send + 'static,
) -> Self {
Self(Box::pin(future))
}
}
impl Future for MemberRemoveFuture {
type Output = Result<MemberRemoveResponse, ClusterError>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.get_mut().0.as_mut().poll(cx)
}
}
impl<C: crate::driver::ClusterDriver> IntoFuture for MemberRemove<C> {
type Output = Result<MemberRemoveResponse, ClusterError>;
type IntoFuture = C::MemberRemoveFuture;
fn into_future(self) -> Self::IntoFuture {
let (client, detached) = self.into_parts();
client.execute_member_remove(detached)
}
}
#[derive(Clone)]
#[must_use = "MemberUpdate does nothing unless you `await` it"]
pub struct MemberUpdate<C> {
client: C,
pub(crate) request: etcdserverpb::MemberUpdateRequest,
}
impl MemberUpdate<()> {
pub fn new(member_id: MemberId, peer_urls: impl IntoIterator<Item = impl Into<String>>) -> Self {
Self {
client: (),
request: etcdserverpb::MemberUpdateRequest {
id: member_id.get(),
peer_ur_ls: peer_urls.into_iter().map(Into::into).collect(),
},
}
}
}
impl<C> MemberUpdate<C> {
pub fn with_client<C2>(self, client: C2) -> MemberUpdate<C2> {
MemberUpdate {
client,
request: self.request,
}
}
pub fn member_id(&self) -> MemberId {
MemberId::new(self.request.id).expect("member update request should have a member ID")
}
pub fn peer_urls(&self) -> &[String] {
&self.request.peer_ur_ls
}
pub(crate) fn into_parts(self) -> (C, MemberUpdate<()>) {
(
self.client,
MemberUpdate {
client: (),
request: self.request,
},
)
}
}
pub struct MemberUpdateFuture(Pin<Box<dyn Future<Output = Result<MemberUpdateResponse, ClusterError>> + Send>>);
impl MemberUpdateFuture {
pub(crate) fn new(
future: impl Future<Output = Result<MemberUpdateResponse, ClusterError>> + Send + 'static,
) -> Self {
Self(Box::pin(future))
}
}
impl Future for MemberUpdateFuture {
type Output = Result<MemberUpdateResponse, ClusterError>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.get_mut().0.as_mut().poll(cx)
}
}
impl<C: crate::driver::ClusterDriver> IntoFuture for MemberUpdate<C> {
type Output = Result<MemberUpdateResponse, ClusterError>;
type IntoFuture = C::MemberUpdateFuture;
fn into_future(self) -> Self::IntoFuture {
let (client, detached) = self.into_parts();
client.execute_member_update(detached)
}
}
#[derive(Clone)]
#[must_use = "MemberPromote does nothing unless you `await` it"]
pub struct MemberPromote<C> {
client: C,
pub(crate) request: etcdserverpb::MemberPromoteRequest,
}
impl MemberPromote<()> {
pub fn new(member_id: MemberId) -> Self {
Self {
client: (),
request: etcdserverpb::MemberPromoteRequest { id: member_id.get() },
}
}
}
impl<C> MemberPromote<C> {
pub fn with_client<C2>(self, client: C2) -> MemberPromote<C2> {
MemberPromote {
client,
request: self.request,
}
}
pub fn member_id(&self) -> MemberId {
MemberId::new(self.request.id).expect("member promote request should have a member ID")
}
pub(crate) fn into_parts(self) -> (C, MemberPromote<()>) {
(
self.client,
MemberPromote {
client: (),
request: self.request,
},
)
}
}
pub struct MemberPromoteFuture(Pin<Box<dyn Future<Output = Result<MemberPromoteResponse, ClusterError>> + Send>>);
impl MemberPromoteFuture {
pub(crate) fn new(
future: impl Future<Output = Result<MemberPromoteResponse, ClusterError>> + Send + 'static,
) -> Self {
Self(Box::pin(future))
}
}
impl Future for MemberPromoteFuture {
type Output = Result<MemberPromoteResponse, ClusterError>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.get_mut().0.as_mut().poll(cx)
}
}
impl<C: crate::driver::ClusterDriver> IntoFuture for MemberPromote<C> {
type Output = Result<MemberPromoteResponse, ClusterError>;
type IntoFuture = C::MemberPromoteFuture;
fn into_future(self) -> Self::IntoFuture {
let (client, detached) = self.into_parts();
client.execute_member_promote(detached)
}
}
#[derive(Clone, Debug)]
pub struct MemberRemoveResponse {
header: ClusterResponseHeader,
members: Vec<Member>,
}
impl MemberRemoveResponse {
pub(crate) fn new(header: ClusterResponseHeader, members: Vec<Member>) -> Self {
Self { header, members }
}
pub fn header(&self) -> &ClusterResponseHeader {
&self.header
}
pub fn members(&self) -> &[Member] {
&self.members
}
}
#[derive(Clone, Debug)]
pub struct MemberUpdateResponse {
header: ClusterResponseHeader,
members: Vec<Member>,
}
impl MemberUpdateResponse {
pub(crate) fn new(header: ClusterResponseHeader, members: Vec<Member>) -> Self {
Self { header, members }
}
pub fn header(&self) -> &ClusterResponseHeader {
&self.header
}
pub fn members(&self) -> &[Member] {
&self.members
}
}
#[derive(Clone, Debug)]
pub struct MemberPromoteResponse {
header: ClusterResponseHeader,
members: Vec<Member>,
}
impl MemberPromoteResponse {
pub(crate) fn new(header: ClusterResponseHeader, members: Vec<Member>) -> Self {
Self { header, members }
}
pub fn header(&self) -> &ClusterResponseHeader {
&self.header
}
pub fn members(&self) -> &[Member] {
&self.members
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ClusterErrorKind {
MemberNotFound,
MemberAlreadyExists,
PeerUrlExists,
MemberNotLearner,
LearnerNotReady,
UnhealthyCluster,
Authentication,
Exhausted,
DataLoss,
Unavailable,
Timeout,
Unknown,
}
define_op_error! {
pub struct ClusterError(ClusterErrorKind);
}
impl ClusterError {
pub(crate) fn from_status(status: tonic::Status) -> Self {
let kind = match (status.code(), status.message()) {
(tonic::Code::NotFound, _) => ClusterErrorKind::MemberNotFound,
(tonic::Code::FailedPrecondition | tonic::Code::Unknown, message) => match message {
"etcdserver: member ID already exist" => ClusterErrorKind::MemberAlreadyExists,
"etcdserver: Peer URLs already exists" => ClusterErrorKind::PeerUrlExists,
"etcdserver: can only promote a learner member" => ClusterErrorKind::MemberNotLearner,
"etcdserver: can only promote a learner member which is in sync with leader" => {
ClusterErrorKind::LearnerNotReady
}
"etcdserver: re-configuration failed due to not enough started members" => {
ClusterErrorKind::UnhealthyCluster
}
_ => ClusterErrorKind::Unknown,
},
(tonic::Code::Unauthenticated, _) => ClusterErrorKind::Authentication,
(tonic::Code::PermissionDenied, _) => ClusterErrorKind::Authentication,
(tonic::Code::InvalidArgument, _) if ClientInner::is_stale_token_error(&status) => {
ClusterErrorKind::Authentication
}
(tonic::Code::ResourceExhausted, _) => ClusterErrorKind::Exhausted,
(tonic::Code::DataLoss, _) => ClusterErrorKind::DataLoss,
(tonic::Code::Unavailable, "etcdserver: unhealthy cluster") => ClusterErrorKind::UnhealthyCluster,
(tonic::Code::Unavailable, _) => ClusterErrorKind::Unavailable,
(tonic::Code::Cancelled | tonic::Code::DeadlineExceeded, _) => ClusterErrorKind::Timeout,
_ => ClusterErrorKind::Unknown,
};
Self::new(kind, "", Some(status))
}
}
const _: () = {
fn _assert_send<T: Send>() {}
fn _check() {
_assert_send::<MemberListFuture>();
_assert_send::<MemberAddFuture>();
}
};
#[cfg(test)]
mod test {
use super::*;
fn kind_of(code: tonic::Code, message: &str) -> ClusterErrorKind {
ClusterError::from_status(tonic::Status::new(code, message)).kind()
}
#[test]
fn etcd_membership_rejections_are_classified() {
use ClusterErrorKind::*;
use tonic::Code;
for (code, message, expected) in [
(Code::NotFound, "etcdserver: member not found", MemberNotFound),
(
Code::FailedPrecondition,
"etcdserver: member ID already exist",
MemberAlreadyExists,
),
(
Code::FailedPrecondition,
"etcdserver: Peer URLs already exists",
PeerUrlExists,
),
(
Code::FailedPrecondition,
"etcdserver: can only promote a learner member",
MemberNotLearner,
),
(
Code::FailedPrecondition,
"etcdserver: can only promote a learner member which is in sync with leader",
LearnerNotReady,
),
(Code::Unavailable, "etcdserver: unhealthy cluster", UnhealthyCluster),
(
Code::Unknown,
"etcdserver: re-configuration failed due to not enough started members",
UnhealthyCluster,
),
] {
assert_eq!(kind_of(code, message), expected, "{code:?} {message:?}");
}
}
#[test]
fn too_many_learners_has_no_kind_of_its_own_yet() {
assert_eq!(
kind_of(
tonic::Code::FailedPrecondition,
"etcdserver: too many learner members in cluster"
),
ClusterErrorKind::Unknown
);
}
#[test]
fn invalid_argument_is_authentication_only_for_token_messages() {
use ClusterErrorKind::*;
for (message, expected) in [
("etcdserver: user name is empty", Authentication),
("etcdserver: revision of auth store is old", Authentication),
("etcdserver: invalid auth management", Unknown),
("etcdserver: given member URLs are invalid", Unknown),
("etcdserver: request is too large", Unknown),
("etcdserver: invalid client api version", Unknown),
] {
assert_eq!(kind_of(tonic::Code::InvalidArgument, message), expected, "{message:?}");
}
}
#[test]
fn not_enough_started_members_is_accepted_under_either_code() {
let message = "etcdserver: re-configuration failed due to not enough started members";
assert_eq!(
kind_of(tonic::Code::FailedPrecondition, message),
ClusterErrorKind::UnhealthyCluster
);
}
#[test]
fn unrelated_unknown_stays_unknown() {
assert_eq!(
kind_of(tonic::Code::Unknown, "transport error"),
ClusterErrorKind::Unknown
);
}
#[test]
fn unrelated_unavailable_stays_unavailable() {
for message in ["transport error", "etcdserver: no leader"] {
assert_eq!(
kind_of(tonic::Code::Unavailable, message),
ClusterErrorKind::Unavailable,
"{message:?}"
);
}
}
#[test]
fn messages_etcd_never_sends_are_unknown() {
for message in [
"etcdserver: ID exists",
"etcdserver: ID removed",
"etcdserver: peerURL exists",
"etcdserver: learner not ready",
"etcdserver: not a learner",
] {
assert_eq!(
kind_of(tonic::Code::FailedPrecondition, message),
ClusterErrorKind::Unknown,
"{message:?}"
);
}
}
#[test]
fn code_only_classifications() {
use ClusterErrorKind::*;
use tonic::Code;
for (code, expected) in [
(Code::Unauthenticated, Authentication),
(Code::PermissionDenied, Authentication),
(Code::ResourceExhausted, Exhausted),
(Code::DataLoss, DataLoss),
(Code::Cancelled, Timeout),
(Code::DeadlineExceeded, Timeout),
(Code::Internal, Unknown),
] {
assert_eq!(kind_of(code, "etcdserver: unhealthy cluster"), expected, "{code:?}");
}
}
}