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 adds compatibility with socket address types and exposes helpers to generate a configuration based on cluster size -
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§
- Accumulating
Runtime - A
Runtime
implementation that’s good enough for simple use-cases. - Bincode
Codec BincodeCodec
encodes/decodes messages usingbincode
.- Broadcasts
Disabled Error - Error emitted by
NoCustomBroadcast
when any trailing byte is found. Will be wrapped byError
- Config
- A Config specifies the parameters Foca will use for the SWIM protocol.
- Foca
- Foca is the main interaction point of this crate.
- Header
- The preamble of every datagram sent by Foca.
- Member
- A Cluster Member. Also often called “cluster update”.
- NoCustom
Broadcast - A Broadcast Handler that rejects any form of custom broadcast.
- Periodic
Params - Configuration for a task that should happen periodically
- Postcard
Codec PostcardCodec
encodes/decodes packets usingpostcard
.
Enums§
- Error
- This type represents all possible errors operating a Foca instance.
- Message
- Messages are how members request interaction from each other.
- Notification
- A Notification contains information about high-level relevant state changes in the cluster or Foca itself.
- Owned
Notification - An owned
Notification
, for convenience. - State
- State describes how a Foca instance perceives a member of the cluster.
- Timer
- Timer is an event that’s scheduled by a
Runtime
. You won’t need to construct or understand these, just ensure a timely delivery.
Traits§
- Broadcast
Handler - 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).
- Codec
- A Codec is responsible to encoding and decoding the data that is sent between cluster members.
- Identity
- Identity is a cluster-global identifier. It qualifies a cluster member and there must not be multiple members sharing the same identity.
- Invalidates
- A type that’s able to look at another and decide wether it’s newer/fresher (i.e. invalidates) than it.
- Runtime
- 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 Aliases§
- Incarnation
- 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.
- Probe
Number ProbeNumber
is simply a bookkeeping mechanism to try and prevent incorrect sequencing of protocol messages.- Timer
Token TimerToken
is simply a bookkeeping mechanism to try and prevent reacting to events dispatched that aren’t relevant anymore.