Expand description
Foca is a building block for your gossip-based cluster discovery. It’s
a small library-first crate that implements the SWIM protocol along
with its useful extensions (SWIM+Inf.+Susp.).
-
It’s a
no_std+alloccrate by default. There’s an optionalstdfeature that simply brings compatibility with some types and thestd::error::Errortrait -
Bring Your Own Everything: Foca doesn’t care about anything that isn’t part of the cluster membership functionality:
-
Pluggable, renewable identities: Using a fixed port number? No need to send it all the time. Want to attach extra crucial information (shard id, deployment version, etc)? Easy. Always have a lookup table mapping
u16to hostnames? Use that instead of a socket address! Bring your own type, implementIdentityand enjoy. -
Write your own wire format by implementing
Codec; Like serde? There isbincode-codecandpostcard-codecfeatures, or just use theserdefeature and pick your favorite format. -
Use any transport you want, it’s up to you how messages reach each member: Foca will tell you “Send these bytes to member M”, how that happens is not its business.
-
-
Custom Broadcasts: Foca can attach arbitrary data to its messages and disseminate them the same way it distributes cluster updates. Send CRDT operations, take a stab at implementing metadata-heavy service discovery system, anything really. Give it something that implements
BroadcastHandlerand Foca will ship it. -
No runtime crashes: Apart from
alloc-related aborts, Foca should only crash inside something you provided: aCodec,Runtimeor aBroadcastHandler- so long as those are solid, Foca is too. -
Doesn’t force you to choose between
syncandasync. It’s as easy to plug it in an evented runtime as it is to go old-school.
Structs
BincodeCodec encodes/decodes messages using bincode.
Error emitted by NoCustomBroadcast when any trailing byte is
found. Will be wrapped by Error
A Config specifies the parameters Foca will use for the SWIM protocol.
Foca is the main interaction point of this crate.
The preamble of every datagram sent by Foca.
A Cluster Member. Also often called “cluster update”.
A Broadcast Handler that rejects any form of custom broadcast.
PostcardCodec encodes/decodes packets using postcard.
Enums
This type represents all possible errors operating a Foca instance.
Messages are how members request interaction from each other.
A Notification contains information about high-level relevant state changes in the cluster or Foca itself.
State describes how a Foca instance perceives a member of the cluster.
Traits
A type capable of decoding a (associated) broadcast from a buffer and deciding whether to keep disseminating it for other members of the cluster (when it’s new information) or to discard it (when its outdated/stale).
A Codec is responsible to encoding and decoding the data that is sent between cluster members.
Identity is a cluster-global identifier. It qualifies a cluster member and there must not be multiple members sharing the same identity.
A type that’s able to look at another and decide wether it’s newer/fresher (i.e. invalidates) than it.
A Runtime is Foca’s gateway to the real world: here is where implementations decide how to interact with the network, the hardware timer and the user.
Type Definitions
Incarnation is a member-controlled cluster-global number attached to a member identity. A member M’s incarnation starts with zero and can only be incremented by said member M when refuting suspicion.
ProbeNumber is simply a bookkeeping mechanism to try and prevent incorrect sequencing of protocol messages.
TimerToken is simply a bookkeeping mechanism to try and prevent reacting to events dispatched that aren’t relevant anymore.