leaderelection

type Config struct {
	// RedisKeyName is the Redis key used for leader election.
	// Default: "maplefile:leader:lock"
	RedisKeyName string

	// RedisInfoKeyName is the Redis key used to store leader information.
	// Default: "maplefile:leader:info"
	RedisInfoKeyName string

	// LockTTL is how long the leader lock lasts before expiring.
	// The leader must renew the lock before this time expires.
	// Default: 10 seconds
	// Recommended: 10-30 seconds
	LockTTL time.Duration

	// HeartbeatInterval is how often the leader renews its lock.
	// This should be significantly less than LockTTL (e.g., LockTTL / 3).
	// Default: 3 seconds
	// Recommended: LockTTL / 3
	HeartbeatInterval time.Duration

	// RetryInterval is how often followers check for leadership opportunity.
	// Default: 2 seconds
	// Recommended: 1-5 seconds
	RetryInterval time.Duration

	// InstanceID uniquely identifies this application instance.
	// If empty, will be auto-generated from hostname + random suffix.
	// Default: auto-generated
	InstanceID string

	// Hostname is the hostname of this instance.
	// If empty, will be auto-detected.
	// Default: os.Hostname()
	Hostname string
}

type LeaderElection interface {
	// Start begins participating in leader election.
	// This method blocks and runs the election loop until ctx is cancelled or an error occurs.
	// The instance will automatically attempt to become leader and maintain leadership.
	Start(ctx context.Context) error

	// IsLeader returns true if this instance is currently the leader.
	// This is a local check and does not require network communication.
	IsLeader() bool

	// GetLeaderID returns the unique identifier of the current leader instance.
	// Returns empty string if no leader exists (should be rare).
	GetLeaderID() (string, error)

	// GetLeaderInfo returns detailed information about the current leader.
	GetLeaderInfo() (*LeaderInfo, error)

	// OnBecomeLeader registers a callback function that will be executed when
	// this instance becomes the leader. Multiple callbacks can be registered.
	OnBecomeLeader(callback func())

	// OnLoseLeadership registers a callback function that will be executed when
	// this instance loses leadership (either voluntarily or due to failure).
	// Multiple callbacks can be registered.
	OnLoseLeadership(callback func())

	// Stop gracefully stops leader election participation.
	// If this instance is the leader, it releases leadership allowing another instance to take over.
	// This should be called during application shutdown.
	Stop() error

	// GetInstanceID returns the unique identifier for this instance.
	GetInstanceID() string
}

type LeaderInfo struct {
	// InstanceID is the unique identifier of the leader instance
	InstanceID string `json:"instance_id"`

	// Hostname is the hostname of the leader instance
	Hostname string `json:"hostname"`

	// StartedAt is when this instance became the leader
	StartedAt time.Time `json:"started_at"`

	// LastHeartbeat is the last time the leader renewed its lock
	LastHeartbeat time.Time `json:"last_heartbeat"`
}