Crate foca[−][src]
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
+alloc
crate by default. There’s an optionalstd
feature that simply brings compatibility with some types and thestd::error::Error
trait -
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
u16
to hostnames? Use that instead of a socket address! Bring your own type, implementIdentity
and enjoy. -
Write your own wire format by implementing
Codec
; Like serde? There isbincode-codec
andpostcard-codec
features, or just use theserde
feature 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
BroadcastHandler
and Foca will ship it. -
No runtime crashes: Apart from
alloc
-related aborts, Foca should only crash inside something you provided: aCodec
,Runtime
or aBroadcastHandler
- so long as those are solid, Foca is too. -
Doesn’t force you to choose between
sync
andasync
. 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.