Struct Serf

pub struct Serf<T, D = DefaultDelegate<T>>
where
    D: Delegate<Id = T::Id, Address = T::ResolvedAddress>,
    T: Transport,
{ /* private fields */ }

Serf is a single node that is part of a single cluster that gets events about joins/leaves/failures/etc. It is created with the Create method.

All functions on the Serf structure are safe to call concurrently.

Implementations

impl<T> Serf<T>

where T: Transport,

pub async fn new( transport: T::Options, opts: Options, ) -> Result<Self, Error<T, DefaultDelegate<T>>>

Creates a new Serf instance with the given transport and options.

pub async fn with_event_producer( transport: T::Options, opts: Options, ev: EventProducer<T, DefaultDelegate<T>>, ) -> Result<Self, Error<T, DefaultDelegate<T>>>

Creates a new Serf instance with the given transport and options.

impl<T, D> Serf<T, D>

where D: Delegate<Id = T::Id, Address = T::ResolvedAddress>, T: Transport,

pub async fn with_delegate( transport: T::Options, opts: Options, delegate: D, ) -> Result<Self, Error<T, D>>

Creates a new Serf instance with the given transport and options.

pub async fn with_event_producer_and_delegate( transport: T::Options, opts: Options, ev: EventProducer<T, D>, delegate: D, ) -> Result<Self, Error<T, D>>

Creates a new Serf instance with the given transport, options, event sender, and delegate.

pub fn local_id(&self) -> &T::Id

Returns the local node’s ID

pub fn advertise_node(&self) -> Node<T::Id, T::ResolvedAddress>

Returns the local node’s ID and the advertised address

pub fn encryption_enabled(&self) -> bool

Available on crate feature encryption only.

A predicate that determines whether or not encryption is enabled, which can be possible in one of 2 cases:

• Single encryption key passed at agent start (no persistence)
• Keyring file provided at agent start

pub fn shutdown_rx(&self) -> Receiver<()>

Returns a receiver that can be used to wait for Serf to shutdown.

pub fn state(&self) -> SerfState

The current state of this Serf instance.

pub async fn members(&self) -> OneOrMore<Member<T::Id, T::ResolvedAddress>>

Returns a point-in-time snapshot of the members of this cluster.

pub async fn stats(&self) -> Stats

Used to provide operator debugging information

pub async fn num_members(&self) -> usize

Returns the number of nodes in the serf cluster, regardless of their health or status.

pub fn key_manager(&self) -> &KeyManager<T, D>

Available on crate feature encryption only.

Returns the key manager for the current serf instance

pub async fn local_member(&self) -> Member<T::Id, T::ResolvedAddress>

Returns the Member information for the local node

pub async fn set_tags(&self, tags: Tags) -> Result<(), Error<T, D>>

Used to dynamically update the tags associated with the local node. This will propagate the change to the rest of the cluster. Blocks until a the message is broadcast out.

pub async fn user_event( &self, name: impl Into<SmolStr>, payload: impl Into<Bytes>, coalesce: bool, ) -> Result<(), Error<T, D>>

Used to broadcast a custom user event with a given name and payload. If the configured size limit is exceeded and error will be returned. If coalesce is enabled, nodes are allowed to coalesce this event.

pub async fn query( &self, name: impl Into<SmolStr>, payload: impl Into<Bytes>, params: Option<QueryParam<T::Id>>, ) -> Result<QueryResponse<T::Id, T::ResolvedAddress>, Error<T, D>>

Used to broadcast a new query. The query must be fairly small, and an error will be returned if the size limit is exceeded. Query parameters are optional, and if not provided, a sane set of defaults will be used.

pub async fn join( &self, node: Node<T::Id, MaybeResolvedAddress<T::Address, T::ResolvedAddress>>, ignore_old: bool, ) -> Result<Node<T::Id, T::ResolvedAddress>, Error<T, D>>

Joins an existing Serf cluster. Returns the id of node successfully contacted. If ignore_old is true, then any user messages sent prior to the join will be ignored.

pub async fn join_many( &self, existing: impl Iterator<Item = Node<T::Id, MaybeResolvedAddress<T::Address, T::ResolvedAddress>>>, ignore_old: bool, ) -> Result<SmallVec<Node<T::Id, T::ResolvedAddress>>, (SmallVec<Node<T::Id, T::ResolvedAddress>>, Error<T, D>)>

Joins an existing Serf cluster. Returns the id of nodes successfully contacted. If ignore_old is true, then any user messages sent prior to the join will be ignored.

pub async fn leave(&self) -> Result<(), Error<T, D>>

Gracefully exits the cluster. It is safe to call this multiple times. If the Leave broadcast timeout, Leave() will try to finish the sequence as best effort.

pub async fn remove_failed_node(&self, id: T::Id) -> Result<(), Error<T, D>>

Forcibly removes a failed node from the cluster immediately, instead of waiting for the reaper to eventually reclaim it. This also has the effect that Serf will no longer attempt to reconnect to this node.

pub async fn remove_failed_node_prune( &self, id: T::Id, ) -> Result<(), Error<T, D>>

Forcibly removes a failed node from the cluster immediately, instead of waiting for the reaper to eventually reclaim it. This also has the effect that Serf will no longer attempt to reconnect to this node.

pub async fn shutdown(&self) -> Result<(), Error<T, D>>

Forcefully shuts down the Serf instance, stopping all network activity and background maintenance associated with the instance.

This is not a graceful shutdown, and should be preceded by a call to Leave. Otherwise, other nodes in the cluster will detect this node’s exit as a node failure.

It is safe to call this method multiple times.

pub fn cooridate(&self) -> Result<Coordinate, Error<T, D>>

Returns the network coordinate of the local node.

pub fn cached_coordinate( &self, id: &T::Id, ) -> Result<Option<Coordinate>, Error<T, D>>

Returns the network coordinate for the node with the given name. This will only be valid if disable_coordinates is set to false.

pub fn memberlist(&self) -> &Memberlist<T, SerfDelegate<T, D>>

Returns the underlying Memberlist instance

impl<T, D> Serf<T, D>

where D: Delegate<Id = T::Id, Address = T::ResolvedAddress>, T: Transport,

pub async fn default_query_timeout(&self) -> Duration

Returns the default timeout value for a query Computed as

gossip_interval * query_timeout_mult * log(N+1)

pub async fn default_query_param(&self) -> QueryParam<T::Id>

Used to return the default query parameters

Trait Implementations

impl<T, D> Clone for Serf<T, D>

where D: Delegate<Id = T::Id, Address = T::ResolvedAddress> + Delegate, T: Transport,

fn clone(&self) -> Self

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.