Table of Contents

Class LeaderElectionOptions

Namespace
Excalibur.Dispatch.LeaderElection
Assembly
Excalibur.Dispatch.LeaderElection.Abstractions.dll

Options for configuring leader election.

public class LeaderElectionOptions
Inheritance
LeaderElectionOptions
Inherited Members
Extension Methods

Remarks

Configuration invariant (enforced by LeaderElectionOptionsValidator): all timing values are positive, and RenewInterval + GracePeriod plus reserved headroom must be strictly less than LeaseDuration. Validation alone does not enforce a runtime deadline, bound network operations or prove exclusive ownership.

Runtime failover and renewal behavior are provider-specific. PostgreSQL and SQL Server use session-owned locks rather than a server lease with this duration; Consul has a separate session TTL. Fencing is required for stale-worker safety: process-local timing cannot establish mutual exclusion through arbitrary pauses or network partitions.

Properties

CandidateMetadata

Gets additional metadata for this candidate.

public IDictionary<string, string> CandidateMetadata { get; }

Property Value

IDictionary<string, string>

Additional metadata for this candidate.

EnableHealthChecks

Gets or sets a value indicating whether to enable health-based elections.

public bool EnableHealthChecks { get; set; }

Property Value

bool

true if health-based elections are enabled; otherwise, false.

GracePeriod

Gets or sets the additional interval in the local ownership-proof budget.

public TimeSpan GracePeriod { get; set; }

Property Value

TimeSpan

The additional local proof interval.

Remarks

Redis, SQL Server, PostgreSQL and Consul use a monotonic local deadline of RenewInterval plus this interval from the latest successful ownership request's start. This is not a remote-candidate death timeout or a server-side lock expiration guarantee.

InstanceId

Gets or sets the identity this instance competes under, or null to let it be resolved from the environment.

public string? InstanceId { get; set; }

Property Value

string

The configured instance identifier, or null when none was configured.

Remarks

Leave this unset unless you have a stable identity to supply. When it is null the identity is taken from the container's own name for the process, which is stable across a restart; only when the environment supplies nothing is an identifier generated, and a generated one is unique but NOT stable across a restart, so such an instance cannot recognise its own prior tenure.

This property is nullable so that "nobody configured one" is expressible. A non-null default would make a generated identity indistinguishable from a chosen one, and every provider would have to assume the value was deliberate. Resolution happens in exactly one place, so every provider competes under an identity of the same shape.

LeaseDuration

Gets or sets the lease duration for leadership.

public TimeSpan LeaseDuration { get; set; }

Property Value

TimeSpan

The lease duration for leadership.

MinimumHealthScore

Gets or sets the minimum health score to be eligible for leadership.

[Range(0, 1)]
public double MinimumHealthScore { get; set; }

Property Value

double

The minimum health score to be eligible for leadership.

RenewInterval

Gets or sets the renewal interval (should be less than LeaseDuration).

public TimeSpan RenewInterval { get; set; }

Property Value

TimeSpan

The renewal interval (should be less than LeaseDuration).

RetryInterval

Gets or sets the retry interval when attempting to acquire leadership.

public TimeSpan RetryInterval { get; set; }

Property Value

TimeSpan

The retry interval when attempting to acquire leadership.

StepDownWhenUnhealthy

Gets or sets a value indicating whether to automatically step down when unhealthy.

public bool StepDownWhenUnhealthy { get; set; }

Property Value

bool

true if the instance automatically steps down when unhealthy; otherwise, false.