Crate foca

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 brings compatibility with some types and the std::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, 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.
• 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.