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;