1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
use crate::Incarnation;

/// The preamble of every datagram sent by Foca.
///
/// A foca packet is always:
///
/// - A Header. Optionally followed by:
/// - A `u16` in network byte order to signal how many updates are
///   expected;
/// - A sequence of said `u16` updates (`foca::Member`);
/// - And finally a tail of custom broadcasts, if at all used.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Header<T> {
    /// The identity of the sender
    pub src: T,
    /// The sender's incarnation, so that other cluster members
    /// may keep it up-to-date
    pub src_incarnation: Incarnation,
    /// The target of the message
    pub dst: T,
    /// The actual message
    pub message: Message<T>,
}

/// Messages are how members request interaction from each other.
///
/// There are a few different kind of interactions that may occur:
///
/// ## Direct Probe Cycle
///
/// Foca will periodically check if members are still active. It
/// sends a `Ping` to said member and expects an `Ack` in return.
///
/// If `B` takes too long to reply with an Ack, the indirect
/// probe cycle starts.
///
/// ## Indirect Probe Cycle
///
/// A previously pinged member may be too busy, its reply may have been
/// dropped by an unreliable network or maybe it's actually down.
///
/// The indirect probe cycle helps with getting more certainty about
/// its current state by asking other members to execute a ping
/// on our behalf.
///
/// Here, member `A` will ask member `C` to ping `B` on their
/// behalf:
///
/// ~~~txt
/// A ->[PingReq(B)]      C
/// C ->[IndirectPing(A)] B
/// B ->[IndirectAck(A)]  C
/// C ->[ForwardedAck(B)] A
/// ~~~
///
/// If by the end of the full probe cycle (direct and indirect) Foca
/// has received either an `Ack` or a `ForwardedAck`, the member is
/// considered active. Otherwise the member is declared `State::Suspect`
/// and will need to refute it before the configured deadline
/// else it will be declared `State::Down`.
///
/// ## "Join" sub-protocol
///
/// Foca instances can join a cluster by sending `Announce` messages
/// to one or more identities. If a recipient decides to accept it,
/// it replies with a `Feed` message, containing other active cluster
/// members.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum Message<T> {
    /// A Ping message. Replied with `Ack`.
    Ping(ProbeNumber),
    /// Acknowledment of a Ping. Reply to `Ping`.
    Ack(ProbeNumber),

    /// Receiver is being asked to Ping `target` on their behalf
    /// and should emit `IndirectPing(sender)` to `target`
    PingReq {
        /// The identity that failed to reply to the original
        /// `Ping` in a timely manner.
        target: T,
        /// See `foca::ProbeNumber`
        probe_number: ProbeNumber,
    },

    /// Analogous to `Ping`, with added metadata about the original
    /// requesting member.
    /// Recipient should reply `IndirectAck(origin)` to sender
    IndirectPing {
        /// The identity that started the indirect cycle. I.e.:
        /// whoever sent the unanswered `Ping`.
        origin: T,
        /// See `foca::ProbeNumber`
        probe_number: ProbeNumber,
    },

    /// Analogous to `Ack`, with added metadta about the final
    /// destination.
    /// Recipient should emit `ForwardedAck(sender)` to `target`
    IndirectAck {
        /// The identity that started the indirect cycle. I.e.:
        /// whoever sent the unanswered `Ping`.
        target: T,
        /// See `foca::ProbeNumber`
        probe_number: ProbeNumber,
    },

    /// The result of a successful indirect probe cycle. Sender
    /// is indicating that they've managed to ping and receive
    /// an ack from `origin`
    ForwardedAck {
        /// The identity that failed to reply to the original
        /// `Ping` in a timely manner.
        origin: T,
        /// See `foca::ProbeNumber`
        probe_number: ProbeNumber,
    },

    /// Request to join a cluster. Replied with `Feed`.
    Announce,
    /// Response to a Announce, signals that the remaining bytes in the
    /// payload will be a sequence of active members, instead of just
    /// cluster updates. Reply to `Announce`.
    Feed,

    /// Deliberate dissemination of cluster updates.
    /// Non-interactive, doesn't expect a reply.
    Gossip,

    /// Deliberate dissemination of custom broadcasts. Broadcast
    /// messages do not contain cluster updates.
    Broadcast,

    /// Indicates that the receiver is considered down by the sender
    ///
    /// This is an optional message that Foca sends whenever a member
    /// that's considered down sends a message.
    TurnUndead,
}

/// `ProbeNumber` is simply a bookkeeping mechanism to try and prevent
/// incorrect sequencing of protocol messages.
///
/// Similar in spirit to `foca::TimerToken`.
pub type ProbeNumber = u8;