Class RaftCluster<TMember>

Represents transport-independent implementation of Raft protocol.

Inheritance
object
Disposable
RaftCluster<TMember>
RaftCluster
Implements
Inherited Members
Namespace: DotNext.Net.Cluster.Consensus.Raft
Assembly: DotNext.Net.Cluster.dll
Syntax
public abstract class RaftCluster<TMember> : Disposable, IDisposable, IUnresponsiveClusterMemberRemovalSupport, IStandbyModeSupport, IRaftCluster, IReplicationCluster<IRaftLogEntry>, IReplicationCluster, ICluster, IPeerMesh<IClusterMember>, IPeerMesh<IRaftClusterMember>, IPeerMesh, IAsyncDisposable where TMember : class, IRaftClusterMember, IDisposable
Type Parameters
Name Description
TMember

The type implementing communication details with remote nodes.

Constructors

| Edit this page View Source

RaftCluster(IClusterMemberConfiguration)

Initializes a new cluster manager for the local node.

Declaration
protected RaftCluster(IClusterMemberConfiguration config)
Parameters
Type Name Description
IClusterMemberConfiguration config

The configuration of the local node.
| Edit this page View Source

RaftCluster(IClusterMemberConfiguration, in TagList)

Initializes a new cluster manager for the local node.

Declaration
[CLSCompliant(false)]
protected RaftCluster(IClusterMemberConfiguration config, in TagList measurementTags)
Parameters
Type Name Description
IClusterMemberConfiguration config

The configuration of the local node.
TagList measurementTags

A tags to be attached to each performance measurement.

Properties

| Edit this page View Source

AuditTrail

Associates audit trail with the current instance.

Declaration
public IPersistentState AuditTrail { get; set; }
Property Value
Type Description
IPersistentState
Exceptions
Type Condition
ArgumentNullException

value is null.
| Edit this page View Source

ConfigurationStorage

Gets configuration storage.

Declaration
protected abstract IClusterConfigurationStorage ConfigurationStorage { get; }
Property Value
Type Description
IClusterConfigurationStorage
| Edit this page View Source

ConsensusToken

Gets a token that remains non-canceled while the local node is a part of the majority of the cluster and has communication with the leader.

Declaration
public CancellationToken ConsensusToken { get; }
Property Value
Type Description
CancellationToken
Remarks

The token moves to canceled state if the current node upgrades to the candidate state or loses connection with the leader.

| Edit this page View Source

ElectionTimeout

Gets election timeout used by the local member.

Declaration
public TimeSpan ElectionTimeout { get; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

EndPointComparer

Gets the comparer for EndPoint type.

Declaration
protected IEqualityComparer<EndPoint> EndPointComparer { get; }
Property Value
Type Description
IEqualityComparer<EndPoint>
| Edit this page View Source

FailureDetectorFactory

Gets or sets failure detector to be used by the leader node to detect and remove unresponsive followers.

Declaration
public Func<TimeSpan, TMember, IFailureDetector>? FailureDetectorFactory { get; init; }
Property Value
Type Description
Func<TimeSpan, TMember, IFailureDetector>
| Edit this page View Source

Leader

Gets leader of the cluster.

Declaration
public TMember? Leader { get; }
Property Value
Type Description
TMember
| Edit this page View Source

LeadershipToken

Gets the token that can be used to track leader state.

Declaration
public CancellationToken LeadershipToken { get; }
Property Value
Type Description
CancellationToken
Remarks

The token moves to canceled state if the current node downgrades to the follower state.

| Edit this page View Source

LifecycleToken

Gets token that can be used for all internal asynchronous operations.

Declaration
protected CancellationToken LifecycleToken { get; }
Property Value
Type Description
CancellationToken
| Edit this page View Source

Logger

Gets logger used by this object.

Declaration
[CLSCompliant(false)]
protected virtual ILogger Logger { get; }
Property Value
Type Description
ILogger
| Edit this page View Source

Members

Gets members of Raft-based cluster.

Declaration
public IReadOnlyCollection<TMember> Members { get; }
Property Value
Type Description
IReadOnlyCollection<TMember>

A collection of cluster member.
| Edit this page View Source

Readiness

Represents a task indicating that the current node is ready to serve requests.

Declaration
public Task Readiness { get; }
Property Value
Type Description
Task
| Edit this page View Source

Standby

Gets a value indicating that the local member cannot be elected as cluster leader.

Declaration
public bool Standby { get; }
Property Value
Type Description
bool
| Edit this page View Source

Term

Gets Term value maintained by local member.

Declaration
public long Term { get; }
Property Value
Type Description
long

Methods

| Edit this page View Source

AddMemberAsync(TMember, CancellationToken)

Adds a new member to the collection of members visible by the current node.

Declaration
public ValueTask<bool> AddMemberAsync(TMember member, CancellationToken token)
Parameters
Type Name Description
TMember member

The member to add.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true if the member is added successfully; false if the member is already in the list.
Remarks

This method is exposed to be called by ActiveConfigurationChanged handler.

| Edit this page View Source

AddMemberAsync<TAddress>(TMember, int, IClusterConfigurationStorage<TAddress>, Func<TMember, TAddress>, CancellationToken)

Announces a new member in the cluster.

Declaration
protected Task<bool> AddMemberAsync<TAddress>(TMember member, int rounds, IClusterConfigurationStorage<TAddress> configurationStorage, Func<TMember, TAddress> addressProvider, CancellationToken token = default) where TAddress : notnull
Parameters
Type Name Description
TMember member

The cluster member client used to catch up its state.
int rounds

The number of warmup rounds.
IClusterConfigurationStorage<TAddress> configurationStorage

The configuration storage.
Func<TMember, TAddress> addressProvider

The delegate that allows to get the address of the member.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
Task<bool>

true if the node has been added to the cluster successfully; false if the node rejects the replication or the address of the node cannot be committed.
Type Parameters
Name Description
TAddress

The type of the member address.
Exceptions
Type Condition
ArgumentOutOfRangeException

rounds is less than or equal to zero.
OperationCanceledException

The operation has been canceled or the cluster elects a new leader.
NotLeaderException

The current node is not a leader.
RaftCluster<TMember>.ConcurrentMembershipModificationException

The method is called concurrently.
| Edit this page View Source

AppendEntriesAsync<TEntry>(ClusterMemberId, long, ILogEntryProducer<TEntry>, long, long, long, IClusterConfiguration, bool, CancellationToken)

Handles AppendEntries message received from remote cluster member.

Declaration
protected ValueTask<Result<HeartbeatResult>> AppendEntriesAsync<TEntry>(ClusterMemberId sender, long senderTerm, ILogEntryProducer<TEntry> entries, long prevLogIndex, long prevLogTerm, long commitIndex, IClusterConfiguration config, bool applyConfig, CancellationToken token) where TEntry : IRaftLogEntry
Parameters
Type Name Description
ClusterMemberId sender

The sender of the replica message.
long senderTerm

Term value provided by Heartbeat message sender.
ILogEntryProducer<TEntry> entries

The stateful function that provides entries to be committed locally.
long prevLogIndex

Index of log entry immediately preceding new ones.
long prevLogTerm

Term of prevLogIndex entry.
long commitIndex

The last entry known to be committed on the sender side.
IClusterConfiguration config

The list of cluster members.
bool applyConfig

true to inform that the receiver must apply previously proposed configuration; false to propose a new configuration.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<Result<HeartbeatResult>>

The processing result.
Type Parameters
Name Description
TEntry

The actual type of the log entry returned by the supplier.
| Edit this page View Source

ApplyReadBarrierAsync(CancellationToken)

Ensures linearizable read from underlying state machine.

Declaration
public ValueTask ApplyReadBarrierAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask

The task representing asynchronous result.
Exceptions
Type Condition
OperationCanceledException

The operation has been canceled.
QuorumUnreachableException

The quorum is not visible to the local node.
| Edit this page View Source

CombineTokens(ReadOnlySpan<CancellationToken>)

Combines multiple cancellation tokens.

Declaration
protected CancellationTokenMultiplexer.Scope CombineTokens(ReadOnlySpan<CancellationToken> tokens)
Parameters
Type Name Description
ReadOnlySpan<CancellationToken> tokens

The tokens to be combined.
Returns
Type Description
CancellationTokenMultiplexer.Scope

The lifetime of the combined token.
| Edit this page View Source

DetectLocalMemberAsync(TMember, CancellationToken)

Determines whether the specified candidate represents a local node.

Declaration
protected abstract ValueTask<bool> DetectLocalMemberAsync(TMember candidate, CancellationToken token)
Parameters
Type Name Description
TMember candidate

The candidate to check.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true if candidate represents a local node; otherwise, false.
| Edit this page View Source

Dispose(bool)

Releases managed and unmanaged resources associated with this object.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true if called from Dispose(); false if called from finalizer ~Disposable().
Overrides
| Edit this page View Source

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Declaration
public ValueTask DisposeAsync()
Returns
Type Description
ValueTask

A task that represents the asynchronous dispose operation.
| Edit this page View Source

DisposeAsyncCore()

Releases managed resources associated with this object asynchronously.

Declaration
protected override ValueTask DisposeAsyncCore()
Returns
Type Description
ValueTask

The task representing asynchronous execution of this method.
Overrides
Remarks

This method makes sense only if derived class implements IAsyncDisposable interface.

| Edit this page View Source

EnableStandbyModeAsync(CancellationToken)

Suspends any transition over Raft states.

Declaration
public ValueTask<bool> EnableStandbyModeAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true if any further state transitions are suspended successfully because the local member is in Follower state; false if operation fails because state transition is already suspended or the local member is not in Follower state.
Remarks

This method completes successfully only if the local member is in Follower state.

Exceptions
Type Condition
ObjectDisposedException

This object has been disposed.
| Edit this page View Source

ForceReplicationAsync(CancellationToken)

Forces replication.

Declaration
public ValueTask ForceReplicationAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel waiting.
Returns
Type Description
ValueTask

The task representing asynchronous result.
Remarks

This method waits for responses from all available cluster members, not from the majority of them.

Exceptions
Type Condition
NotLeaderException

The local cluster member is not a leader.
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

InstallSnapshotAsync<TSnapshot>(ClusterMemberId, long, TSnapshot, long, CancellationToken)

Handles InstallSnapshot message received from remote cluster member.

Declaration
protected ValueTask<Result<HeartbeatResult>> InstallSnapshotAsync<TSnapshot>(ClusterMemberId sender, long senderTerm, TSnapshot snapshot, long snapshotIndex, CancellationToken token) where TSnapshot : IRaftLogEntry
Parameters
Type Name Description
ClusterMemberId sender

The sender of the snapshot message.
long senderTerm

Term value provided by InstallSnapshot message sender.
TSnapshot snapshot

The snapshot to be installed into local audit trail.
long snapshotIndex

The index of the last log entry included in the snapshot.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<Result<HeartbeatResult>>

true if snapshot is installed successfully; null if snapshot is outdated.
Type Parameters
Name Description
TSnapshot

The type of snapshot record.
| Edit this page View Source

PreVoteAsync(ClusterMemberId, long, long, long, CancellationToken)

Receives preliminary vote from the potential Candidate in the cluster.

Declaration
protected ValueTask<Result<PreVoteResult>> PreVoteAsync(ClusterMemberId sender, long nextTerm, long lastLogIndex, long lastLogTerm, CancellationToken token)
Parameters
Type Name Description
ClusterMemberId sender

The sender of the replica message.
long nextTerm

Caller's current term + 1.
long lastLogIndex

Index of candidate's last log entry.
long lastLogTerm

Term of candidate's last log entry.
CancellationToken token

The token that can be used to cancel asynchronous operation.
Returns
Type Description
ValueTask<Result<PreVoteResult>>

Pre-vote result received from the member.
| Edit this page View Source

RemoveMemberAsync(ClusterMemberId, CancellationToken)

Removes the member from the collection of members visible by the current node.

Declaration
public ValueTask<TMember?> RemoveMemberAsync(ClusterMemberId id, CancellationToken token)
Parameters
Type Name Description
ClusterMemberId id

The identifier of the member.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<TMember>

The removed member.
Remarks

This method is exposed to be called by ActiveConfigurationChanged handler.

| Edit this page View Source

RemoveMemberAsync<TAddress>(ClusterMemberId, IClusterConfigurationStorage<TAddress>, Func<TMember, TAddress>, CancellationToken)

Removes the member from the cluster.

Declaration
protected Task<bool> RemoveMemberAsync<TAddress>(ClusterMemberId id, IClusterConfigurationStorage<TAddress> configurationStorage, Func<TMember, TAddress> addressProvider, CancellationToken token = default) where TAddress : notnull
Parameters
Type Name Description
ClusterMemberId id

The cluster member to remove.
IClusterConfigurationStorage<TAddress> configurationStorage

The configuration storage.
Func<TMember, TAddress> addressProvider

The delegate that allows to get the address of the member.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
Task<bool>

true if the node has been removed from the cluster successfully; false if the node rejects the replication or the address of the node cannot be committed.
Type Parameters
Name Description
TAddress

The type of the member address.
Exceptions
Type Condition
NotLeaderException

The current node is not a leader.
OperationCanceledException

The operation has been canceled or the cluster elects a new leader.
RaftCluster<TMember>.ConcurrentMembershipModificationException

The method is called concurrently.
| Edit this page View Source

ReplicateAsync<TEntry>(TEntry, CancellationToken)

Appends a new log entry and ensures that it is replicated and committed.

Declaration
public ValueTask<bool> ReplicateAsync<TEntry>(TEntry entry, CancellationToken token) where TEntry : IRaftLogEntry
Parameters
Type Name Description
TEntry entry

The log entry to be added.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true if the appended log entry has been committed by the majority of nodes; false if retry is required.
Type Parameters
Name Description
TEntry

The type of the log entry.
Exceptions
Type Condition
ObjectDisposedException

This object has been disposed.
NotLeaderException

The current node is not a leader.
OperationCanceledException

The operation has been canceled.
| Edit this page View Source

ResignAsync(CancellationToken)

Revokes leadership of the local node.

Declaration
protected ValueTask<bool> ResignAsync(CancellationToken token)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true, if leadership is revoked successfully; otherwise, false.
| Edit this page View Source

RevertToNormalModeAsync(CancellationToken)

Turns this node into the regular state when the node can be elected as leader.

Declaration
public ValueTask<bool> RevertToNormalModeAsync(CancellationToken token = default)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<bool>

true if state transition is resumed successfully; false if state transition was not suspended.
Exceptions
Type Condition
ObjectDisposedException

This object has been disposed.
| Edit this page View Source

StartAsync(CancellationToken)

Starts serving local member.

Declaration
public virtual Task StartAsync(CancellationToken token)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel the initialization process.
Returns
Type Description
Task

The task representing asynchronous execution of the method.
See Also
| Edit this page View Source

StartFollowing()

Starts Follower timer.

Declaration
protected void StartFollowing()
| Edit this page View Source

StopAsync(CancellationToken)

Stops serving local member.

Declaration
public virtual Task StopAsync(CancellationToken token)
Parameters
Type Name Description
CancellationToken token

The token that can be used to cancel shutdown process.
Returns
Type Description
Task

The task representing asynchronous execution of the method.
| Edit this page View Source

SynchronizeAsync(long, CancellationToken)

Processes SynchronizeAsync(long, CancellationToken) request.

Declaration
protected ValueTask<long?> SynchronizeAsync(long commitIndex, CancellationToken token)
Parameters
Type Name Description
long commitIndex

The index of the last committed log entry on the sender side.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<long?>

The index of the last committed log entry known by the leader.
| Edit this page View Source

TryGetLeaseToken(out CancellationToken)

Tries to get the lease that can be used to perform the read with linearizability guarantees.

Declaration
public bool TryGetLeaseToken(out CancellationToken token)
Parameters
Type Name Description
CancellationToken token

The token representing lease.
Returns
Type Description
bool

true if the current node is leader; otherwise, false.
| Edit this page View Source

TryGetMember(ClusterMemberId)

Gets the member by its identifier.

Declaration
protected TMember? TryGetMember(ClusterMemberId id)
Parameters
Type Name Description
ClusterMemberId id

The identifier of the cluster member.
Returns
Type Description
TMember

true if member found; otherwise, false.
| Edit this page View Source

UnavailableMemberDetected(TMember, CancellationToken)

Notifies that the member is unavailable.

Declaration
protected virtual ValueTask UnavailableMemberDetected(TMember member, CancellationToken token)
Parameters
Type Name Description
TMember member

The member that is considered as unavailable.
CancellationToken token

The token associated with LeadershipToken that identifies the leader state at the time of detection.
Returns
Type Description
ValueTask

The task representing asynchronous result.
Remarks

It's an infrastructure method that can be used to remove unavailable member from the cluster configuration at the leader side.

| Edit this page View Source

VoteAsync(ClusterMemberId, long, long, long, CancellationToken)

Votes for the new candidate.

Declaration
protected ValueTask<Result<bool>> VoteAsync(ClusterMemberId sender, long senderTerm, long lastLogIndex, long lastLogTerm, CancellationToken token)
Parameters
Type Name Description
ClusterMemberId sender

The vote sender.
long senderTerm

Term value provided by sender of the request.
long lastLogIndex

Index of candidate's last log entry.
long lastLogTerm

Term of candidate's last log entry.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<Result<bool>>

true if local node accepts new leader in the cluster; otherwise, false.
| Edit this page View Source

WaitForLeaderAsync(TimeSpan, CancellationToken)

Waits for the leader election asynchronously.

Declaration
public Task<TMember> WaitForLeaderAsync(TimeSpan timeout, CancellationToken token = default)
Parameters
Type Name Description
TimeSpan timeout

The time to wait; or InfiniteTimeSpan.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
Task<TMember>

The elected leader.
Exceptions
Type Condition
TimeoutException

The operation is timed out.
OperationCanceledException

The operation has been canceled.
ObjectDisposedException

The local node is disposed.
| Edit this page View Source

WaitForLeadershipAsync(TimeSpan, CancellationToken)

Waits until the local node is elected as the leader.

Declaration
public ValueTask<CancellationToken> WaitForLeadershipAsync(TimeSpan timeout, CancellationToken token = default)
Parameters
Type Name Description
TimeSpan timeout

The time to wait; or InfiniteTimeSpan.
CancellationToken token

The token that can be used to cancel the operation.
Returns
Type Description
ValueTask<CancellationToken>

The leadership token.
Exceptions
Type Condition
TimeoutException

The operation is timed out.
OperationCanceledException

The operation has been canceled.
ObjectDisposedException

The local node is disposed.
See Also

Events

| Edit this page View Source

LeaderChanged

An event raised when leader has been changed.

Declaration
public event Action<RaftCluster<TMember>, TMember?> LeaderChanged
Event Type
Type Description
Action<RaftCluster<TMember>, TMember>
| Edit this page View Source

MemberAdded

An event raised when new cluster member is detected.

Declaration
public event Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>> MemberAdded
Event Type
Type Description
Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>>
| Edit this page View Source

MemberRemoved

An event raised when cluster member is removed gracefully.

Declaration
public event Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>> MemberRemoved
Event Type
Type Description
Action<RaftCluster<TMember>, RaftClusterMemberEventArgs<TMember>>
| Edit this page View Source

ReplicationCompleted

Represents an event raised when the local node completes its replication with another node.

Declaration
public event Action<RaftCluster<TMember>, TMember> ReplicationCompleted
Event Type
Type Description
Action<RaftCluster<TMember>, TMember>

Implements

Extension Methods