Crate foca

Source
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 optional std 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, implement Identity and enjoy.

    • Write your own wire format by implementing Codec; Like serde? There is bincode-codec and postcard-codec features, or just use the serde 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: a Codec, Runtime or a BroadcastHandler- so long as those are solid, Foca is too.

  • Doesn’t force you to choose between sync and async. It’s as easy to plug it in an evented runtime as it is to go old-school.

Structs§

AccumulatingRuntime
A Runtime implementation that’s good enough for simple use-cases.
BincodeCodec
BincodeCodec encodes/decodes messages using bincode.
BroadcastsDisabledError
Error emitted by NoCustomBroadcast when any trailing byte is found. Will be wrapped by Error
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”.
NoCustomBroadcast
A Broadcast Handler that rejects any form of custom broadcast.
PeriodicParams
Configuration for a task that should happen periodically
PostcardCodec
PostcardCodec encodes/decodes packets using postcard.

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.
OwnedNotification
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§

BroadcastHandler
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.
ProbeNumber
ProbeNumber is simply a bookkeeping mechanism to try and prevent incorrect sequencing of protocol messages.
TimerToken
TimerToken is simply a bookkeeping mechanism to try and prevent reacting to events dispatched that aren’t relevant anymore.