paxakos/
append.rs

1//! Defines [`AppendError`], [`AppendArgs`] and related types.
2
3use std::ops::RangeInclusive;
4
5use num_traits::Bounded;
6use num_traits::Zero;
7use thiserror::Error;
8
9use crate::error::ShutDownOr;
10use crate::invocation::AbstainOf;
11use crate::invocation::CommunicationErrorOf;
12use crate::invocation::Invocation;
13use crate::invocation::NayOf;
14use crate::invocation::RoundNumOf;
15use crate::retry::DoNotRetry;
16use crate::retry::RetryPolicy;
17
18/// Options that determine how an append is performed.
19#[derive(Debug)]
20pub struct AppendArgs<I: Invocation, R = DoNotRetry<I>> {
21    /// The round(s) in which the entry should be appended. The append won't be
22    /// started until the round(s) can be settled and will fail if they already
23    /// are.
24    pub round: RangeInclusive<RoundNumOf<I>>,
25    /// The append's [importance][Importance].
26    pub importance: Importance,
27    /// The [retry policy][crate::retry::RetryPolicy] with which to perform the
28    /// append.
29    pub retry_policy: R,
30}
31
32impl<I: Invocation, R: RetryPolicy<Invocation = I> + Default> Default for AppendArgs<I, R> {
33    fn default() -> Self {
34        R::default().into()
35    }
36}
37
38impl<I: Invocation, R: Clone> Clone for AppendArgs<I, R> {
39    fn clone(&self) -> Self {
40        Self {
41            round: self.round.clone(),
42            importance: self.importance,
43            retry_policy: self.retry_policy.clone(),
44        }
45    }
46}
47
48impl<I, R> From<R> for AppendArgs<I, R>
49where
50    I: Invocation,
51    R: RetryPolicy<Invocation = I>,
52{
53    fn from(retry_policy: R) -> Self {
54        Self {
55            round: Zero::zero()..=Bounded::max_value(),
56            importance: Importance::GainLeadership,
57            retry_policy,
58        }
59    }
60}
61
62impl<I: Invocation> From<()> for AppendArgs<I> {
63    fn from(_: ()) -> Self {
64        Default::default()
65    }
66}
67
68/// Describes the importance of an append operation.
69#[derive(Clone, Copy, Debug, Eq, PartialEq)]
70pub enum Importance {
71    /// If necessary, leadership should be gained.
72    ///
73    /// Note: Just because leadership _should_ be gained does not imply that it
74    /// can or will be gained. It merely implies that the node will not
75    /// immediately give up when it doesn't have leadership.
76    GainLeadership,
77
78    /// Leadership should only be maintained.
79    ///
80    /// Using this mode implies that the given append is of low importance. We
81    /// wish only to go through with it if it does not require an election
82    /// cycle.
83    MaintainLeadership(Peeryness),
84}
85
86impl Default for Importance {
87    fn default() -> Self {
88        Self::GainLeadership
89    }
90}
91
92/// Whether to inquire with other nodes about the round in question.
93///
94/// If a node has to abandon an append due to [lack of status][Maintain] it may
95/// still wish to inquire with other nodes whether the round in question has
96/// converged. This can be achieved by indicating an inquisitiveness of "peery".
97///
98/// [Maintain]: Importance::MaintainLeadership
99#[derive(Clone, Copy, Debug, Eq, PartialEq)]
100pub enum Peeryness {
101    /// Inquire with up to a quorum of other nodes.
102    ///
103    /// By inquiring about a round with (up to) a quorum of other nodes one
104    /// learns whether the round has already converged or not. This can be a
105    /// convenient mechanism for keeping up with the distributed log without
106    /// upsetting the status quo.
107    Peery,
108
109    /// Immediately abandon an append if status is insufficient.
110    Unpeery,
111}
112
113/// Reason an append failed.
114#[derive(Error)]
115#[non_exhaustive]
116pub enum AppendError<I: Invocation> {
117    /// The chosen round had already converged.
118    #[error("round had already converged")]
119    Converged {
120        /// Whether this node has already learned the converged on value for
121        /// this round.
122        caught_up: bool,
123    },
124
125    /// A decoration failed the append.
126    #[error("a node decoration raised an error")]
127    Decoration(#[source] Box<dyn std::error::Error + Send + Sync + 'static>),
128
129    /// Node does not currently know the shared state.
130    #[error("node is disoriented")]
131    Disoriented,
132
133    /// Node was removed from the cluster.
134    #[error("node was removed from the cluster")]
135    Exiled,
136
137    /// Node either lost its mandate or failed in acquiring one.
138    #[error("node lost its mandate or failed in acquiring one")]
139    Lost,
140
141    /// Failed in achieving a quorum.
142    #[error("node could not achieve a quorum")]
143    NoQuorum {
144        /// All abstentions received.
145        abstentions: Vec<AbstainOf<I>>,
146        /// All encountered errors.
147        communication_errors: Vec<CommunicationErrorOf<I>>,
148        /// All discards due to unacceptable conditions.
149        discards: Vec<NayOf<I>>,
150        /// All rejections received.
151        rejections: Vec<NayOf<I>>,
152    },
153
154    /// Node is in passive mode.
155    #[error("node is passive")]
156    Passive,
157
158    /// Node was forced to append a different entry for the chosen round.
159    #[error("node was forced to append a different entry")]
160    Railroaded,
161
162    /// Node is shut down.
163    #[error("node is shut down")]
164    ShutDown,
165
166    /// The entry was unaccepable to this node.
167    #[error("entry is unacceptable")]
168    Unacceptable(NayOf<I>),
169}
170
171// TODO any way to implement this genericly as `impl From<ShutDownOr<E>> for E`?
172impl<I: Invocation> From<ShutDownOr<AppendError<I>>> for AppendError<I> {
173    fn from(e: ShutDownOr<AppendError<I>>) -> Self {
174        match e {
175            ShutDownOr::Other(e) => e,
176            ShutDownOr::ShutDown => AppendError::ShutDown,
177        }
178    }
179}
180
181impl<I: Invocation> std::fmt::Debug for AppendError<I> {
182    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
183        match self {
184            AppendError::Converged { caught_up } => f
185                .debug_struct("AppendError::Converged")
186                .field("caught_up", caught_up)
187                .finish(),
188            AppendError::Decoration(err) => {
189                f.debug_tuple("AppendError::Decoration").field(err).finish()
190            }
191            AppendError::Disoriented => f.debug_tuple("AppendError::Disoriented").finish(),
192            AppendError::Exiled => f.debug_tuple("AppendError::Exiled").finish(),
193            AppendError::Lost => f.debug_tuple("AppendError::Lost").finish(),
194            AppendError::NoQuorum {
195                abstentions,
196                communication_errors,
197                discards,
198                rejections,
199            } => f
200                .debug_struct("AppendError::NoQuorum")
201                .field("abstentions", abstentions)
202                .field("communication_errors", communication_errors)
203                .field("discards", discards)
204                .field("rejections", rejections)
205                .finish(),
206            AppendError::Passive => f.debug_tuple("AppendError::Passive").finish(),
207            AppendError::Railroaded => f.debug_tuple("AppendError::Railroaded").finish(),
208            AppendError::ShutDown => f.debug_tuple("AppendError::ShutDown").finish(),
209            AppendError::Unacceptable(reason) => f
210                .debug_tuple("AppendError::Unacceptable")
211                .field(reason)
212                .finish(),
213        }
214    }
215}
paxakos/append.rs

paxakos/
append.rs
