leader

type BackoffConfig struct {
	InitialBackoff    time.Duration
	MaxBackoff        time.Duration
	BackoffMultiplier float64
	Jitter            float64
}

type CircuitBreaker struct {
	// contains filtered or unexported fields
}

type CircuitState int

type ConnectionMonitor interface {
	Start(ctx context.Context) error
	Stop() error
	Status() ConnectionStatus
	OnDisconnect(func())
	OnReconnect(func())
	SetStatus(ConnectionStatus) // Set status (used after verification)
}

type ConnectionStatus int

type Election interface {
	// Start begins participating in the election.
	// This method starts background goroutines for:
	//   - Attempting to acquire leadership
	//   - Watching for leader changes (if follower)
	//   - Sending heartbeats (if leader)
	//   - Validating tokens (if leader)
	//   - Monitoring connection health
	//
	// Start returns an error if:
	//   - The election is already started (ErrAlreadyStarted)
	//   - The configuration is invalid (ErrInvalidConfig)
	//   - The NATS connection cannot access JetStream
	//
	// The context is used for cancellation. If the context is cancelled,
	// the election will stop gracefully.
	//
	// Example:
	//   ctx := context.Background()
	//   if err := election.Start(ctx); err != nil {
	//       log.Fatal(err)
	//   }
	Start(ctx context.Context) error

	// Stop stops participating in the election and cleans up resources.
	// This method:
	//   - Stops all background goroutines
	//   - Does NOT delete the leadership key (if leader)
	//   - Does NOT wait for OnDemote callback
	//
	// For graceful shutdown with options, use StopWithContext instead.
	//
	// Stop returns an error if the election is already stopped (ErrAlreadyStopped).
	//
	// Example:
	//   if err := election.Stop(); err != nil {
	//       log.Printf("Error stopping election: %v", err)
	//   }
	Stop() error

	// StopWithContext stops the election with configurable options.
	// This method provides graceful shutdown capabilities:
	//   - Optional key deletion for fast failover
	//   - Optional waiting for OnDemote callback
	//   - Timeout handling via context
	//
	// Options:
	//   - DeleteKey: If true, deletes the leadership key immediately,
	//     allowing a new leader to be elected without waiting for TTL expiration.
	//   - WaitForDemote: If true, waits for the OnDemote callback to complete
	//     before returning. This ensures leader tasks are stopped before shutdown.
	//   - Timeout: Maximum time to wait. If 0, uses context timeout or 5s default.
	//
	// Example:
	//   ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	//   defer cancel()
	//   err := election.StopWithContext(ctx, StopOptions{
	//       DeleteKey:      true,
	//       WaitForDemote:  true,
	//   })
	StopWithContext(ctx context.Context, opts StopOptions) error

	// Status returns the current status of the election.
	// This includes:
	//   - Current state (INIT, CANDIDATE, LEADER, FOLLOWER, DEMOTED, STOPPED)
	//   - Whether this instance is the leader
	//   - Current leader ID
	//   - Fencing token (if leader)
	//   - Last heartbeat time (if leader)
	//   - Last state transition time
	//   - Current KV revision (if leader)
	//   - NATS connection status
	//
	// Example:
	//   status := election.Status()
	//   if status.IsLeader {
	//       log.Printf("I am the leader, token: %s", status.Token)
	//   } else {
	//       log.Printf("Current leader: %s", status.LeaderID)
	//   }
	Status() ElectionStatus

	// IsLeader returns true if this instance currently holds leadership.
	// This is a convenience method equivalent to Status().IsLeader.
	//
	// Example:
	//   if election.IsLeader() {
	//       performLeaderTasks()
	//   }
	IsLeader() bool

	// LeaderID returns the instance ID of the current leader.
	// Returns empty string if no leader is known.
	// This may be this instance's ID (if leader) or another instance's ID (if follower).
	//
	// Example:
	//   leaderID := election.LeaderID()
	//   if leaderID == "" {
	//       log.Println("No leader known")
	//   } else if leaderID == myInstanceID {
	//       log.Println("I am the leader")
	//   } else {
	//       log.Printf("Leader is: %s", leaderID)
	//   }
	LeaderID() string

	// Token returns the current fencing token for this instance if it is the leader.
	// Returns empty string if not leader.
	//
	// The fencing token is a UUID that uniquely identifies the current leadership.
	// It should be validated before performing critical operations to ensure
	// this instance is still the leader.
	//
	// Example:
	//   if election.IsLeader() {
	//       token := election.Token()
	//       // Use token for fencing in external systems
	//   }
	Token() string

	// OnPromote registers a callback that is executed when this instance becomes leader.
	// The callback receives:
	//   - A context that is cancelled when leadership is lost
	//   - The fencing token for this leadership term
	//
	// The callback is called in a separate goroutine, so it should not block.
	// If the callback panics, the panic is caught and logged, but does not
	// affect the election process.
	//
	// Multiple calls to OnPromote replace the previous callback.
	//
	// Example:
	//   election.OnPromote(func(ctx context.Context, token string) {
	//       log.Printf("Became leader with token: %s", token)
	//       go startLeaderTasks(ctx, token)
	//   })
	OnPromote(func(ctx context.Context, token string))

	// OnDemote registers a callback that is executed when this instance loses leadership.
	// The callback is called in a separate goroutine, so it should not block.
	// If the callback panics, the panic is caught and logged, but does not
	// affect the election process.
	//
	// Multiple calls to OnDemote replace the previous callback.
	//
	// Example:
	//   election.OnDemote(func() {
	//       log.Println("Lost leadership")
	//       stopLeaderTasks()
	//   })
	OnDemote(func())

	// ValidateToken validates the current token against the KV store.
	// Returns true if the token is valid (this instance is still leader),
	// false if invalid (this instance is no longer leader or not leader).
	//
	// This method performs a synchronous check by reading from the KV store.
	// For periodic validation, use ValidationInterval in ElectionConfig instead.
	//
	// Example:
	//   valid, err := election.ValidateToken(ctx)
	//   if err != nil {
	//       log.Printf("Error validating token: %v", err)
	//   } else if !valid {
	//       log.Println("Token invalid - no longer leader")
	//   }
	ValidateToken(ctx context.Context) (bool, error)

	// ValidateTokenOrDemote validates the token and demotes if invalid.
	// Returns true if the token is valid, false if invalid (and demoted).
	//
	// This is a convenience method that combines ValidateToken with automatic
	// demotion. Use this before critical operations to ensure this instance
	// is still the leader.
	//
	// Example:
	//   if !election.ValidateTokenOrDemote(ctx) {
	//       log.Println("Token invalid, operation aborted")
	//       return
	//   }
	//   // Perform critical operation...
	ValidateTokenOrDemote(ctx context.Context) bool
}

type ElectionConfig struct {
	// Bucket is the name of the NATS KV bucket to use for leadership storage.
	// The bucket must exist before creating an election instance.
	// Example: "leaders", "elections", "my-app-leaders"
	Bucket string

	// Group is the election group/role identifier.
	// Multiple instances with the same Group participate in the same election.
	// Different Groups represent independent elections (multi-role support).
	// Example: "control-manager", "scheduler", "coordinator"
	Group string

	// InstanceID is a unique identifier for this instance.
	// Must be unique across all instances participating in the same election.
	// Typically: hostname, pod name, container ID, or UUID.
	// Example: "instance-1", "pod-abc123", "host-192.168.1.1"
	InstanceID string

	// TTL is the time-to-live for the leadership key in the KV store.
	// The key will expire if not refreshed within this duration.
	// Must be >= HeartbeatInterval * 3 (enforced by validation).
	// Recommended: 3-5x HeartbeatInterval for safety margin.
	// Example: 10 * time.Second (with HeartbeatInterval: 1 * time.Second)
	TTL time.Duration

	// HeartbeatInterval is how often the leader refreshes the leadership key.
	// Must be < TTL / 3 (enforced by validation).
	// Shorter intervals provide faster failover but more KV operations.
	// Recommended: 1-2 seconds for most use cases.
	// Example: 1 * time.Second
	HeartbeatInterval time.Duration

	// Logger is an optional structured logger for observability.
	// If nil, logging is disabled (no-op logger).
	// Implementations should use zap.Field for structured data.
	// Example: zap.NewProduction(), zap.NewDevelopment()
	Logger Logger

	// ValidationInterval is how often to validate the fencing token in the background.
	// If 0, background validation is disabled (not recommended for production).
	// Recommended: 5-10 seconds for most use cases.
	// Example: 5 * time.Second
	ValidationInterval time.Duration

	// DisconnectGracePeriod is how long to wait before demoting on NATS disconnect.
	// If 0, uses default: max(3 * HeartbeatInterval, 5 seconds).
	// During this period, the leader continues to act as leader, allowing
	// for brief network interruptions without triggering failover.
	// Example: 5 * time.Second
	DisconnectGracePeriod time.Duration

	// Metrics is an optional metrics recorder for observability.
	// If nil, metrics recording is disabled.
	// Use NewPrometheusMetrics() to create a Prometheus implementation.
	// Example: leader.NewPrometheusMetrics(prometheus.DefaultRegisterer)
	Metrics Metrics

	// HealthChecker is an optional health checker for self-monitoring.
	// If nil, health checking is disabled.
	// If provided, health is checked before each heartbeat.
	// If health check fails MaxConsecutiveFailures times consecutively,
	// the leader will automatically demote itself.
	// Example: &MyHealthChecker{}
	HealthChecker HealthChecker

	// MaxConsecutiveFailures is the maximum number of consecutive health check
	// failures before automatic demotion.
	// Only used if HealthChecker is set.
	// Default: 3
	// Example: 3
	MaxConsecutiveFailures int

	// Priority is used for leader selection when AllowPriorityTakeover is true.
	// Higher number = higher priority.
	// Default: 0 (no priority, first-come-first-served).
	// Must be > 0 if AllowPriorityTakeover is true (enforced by validation).
	// Example: 10 (lower priority), 20 (higher priority)
	Priority int

	// AllowPriorityTakeover enables priority-based preemption.
	// If true, a higher-priority instance can take over from a lower-priority leader.
	// If false, priority is ignored and first-come-first-served applies.
	// Default: false (disabled for safety).
	//
	// WARNING: Priority takeover can cause service disruption. Use with caution.
	// Prefer voluntary demotion (health checks, graceful shutdown) over forced preemption.
	//
	// Use cases:
	//   - Primary/backup datacenter scenarios
	//   - Maintenance mode (lower priority to allow takeover)
	//   - Clear priority hierarchy
	//
	// Example: true (enable priority takeover)
	AllowPriorityTakeover bool
}

type ElectionError struct {
	// Code is a short error code identifying the error type.
	Code string

	// InstanceID is the instance ID where the error occurred.
	InstanceID string

	// Reason is a human-readable description of the error.
	Reason string

	// Err is the underlying error, if any.
	Err error
}

type ElectionStatus struct {
	// State is the current state of the election.
	// Possible values: INIT, CANDIDATE, LEADER, FOLLOWER, DEMOTED, STOPPED
	State string

	// IsLeader is true if this instance is currently the leader.
	IsLeader bool

	// LeaderID is the instance ID of the current leader.
	// Empty if no leader is known.
	LeaderID string

	// Token is the fencing token for this instance if it is the leader.
	// Empty if not leader.
	Token string

	// LastHeartbeat is the time of the last successful heartbeat (if leader).
	// Zero if not leader or no heartbeat yet.
	LastHeartbeat time.Time

	// LastTransition is the time of the last state transition.
	LastTransition time.Time

	// Revision is the current KV revision (if leader).
	// Zero if not leader.
	Revision uint64
}

type Entry interface {
	Key() string
	Value() []byte
	Revision() uint64
}

type HealthChecker interface {
	// Check returns true if the instance is healthy and should retain leadership.
	// Return false if the instance is unhealthy and should demote.
	//
	// If health check fails MaxConsecutiveFailures times in a row,
	// the leader will automatically demote itself.
	Check(ctx context.Context) bool
}

type JetStreamContext interface {
	KeyValue(bucket string) (KeyValue, error)
}

type JetStreamProvider interface {
	JetStream() (JetStreamContext, error)
}

type KeyValue interface {
	Create(key string, value []byte, opts ...interface{}) (uint64, error)
	Update(key string, value []byte, rev uint64, opts ...interface{}) (uint64, error)
	Get(key string) (Entry, error)
	Delete(key string) error
	Watch(key string, opts ...interface{}) (Watcher, error)
}

type Logger interface {
	Debug(msg string, fields ...zap.Field)
	Info(msg string, fields ...zap.Field)
	Warn(msg string, fields ...zap.Field)
	Error(msg string, fields ...zap.Field)
	Fatal(msg string, fields ...zap.Field)
}

type Metrics interface {
	// Gauges
	SetIsLeader(value float64, labels prometheus.Labels)
	SetConnectionStatus(value float64, labels prometheus.Labels)

	// Counters
	IncTransitions(labels prometheus.Labels)
	IncFailures(labels prometheus.Labels)
	IncAcquireAttempts(labels prometheus.Labels)
	IncTokenValidationFailures(labels prometheus.Labels)

	// Histograms
	ObserveHeartbeatDuration(duration time.Duration, labels prometheus.Labels)
	ObserveLeaderDuration(duration time.Duration, labels prometheus.Labels)
}

type MockConnAdapter struct {
	Conn *natsmock.MockConn
}

type MockEntryAdapter struct {
	Entry natsmock.Entry
}

type MockJetStreamAdapter struct {
	JS *natsmock.MockJetStream
}

type MockKeyValueAdapter struct {
	KV *natsmock.MockKeyValue
}

type MockWatcherAdapter struct {
	// contains filtered or unexported fields
}

type NATSConnectionProvider interface {
	NATSConnection() *nats.Conn
}

type RetryConfig struct {
	MaxAttempts    int
	BackoffConfig  BackoffConfig
	CircuitBreaker *CircuitBreaker
}

type StopOptions struct {
	// DeleteKey deletes the leadership key on stop for fast failover.
	// If true, the key is deleted immediately, allowing a new leader
	// to be elected without waiting for TTL expiration.
	// If false, the key remains until TTL expires (slower failover).
	// Recommended: true for graceful shutdowns, false for crashes.
	DeleteKey bool

	// WaitForDemote waits for the OnDemote callback to complete before
	// returning. If true, ensures leader tasks are stopped before shutdown.
	// If false, the callback is called but not waited for (faster shutdown).
	// Recommended: true for graceful shutdowns.
	WaitForDemote bool

	// Timeout is the maximum time to wait for shutdown operations.
	// If 0, the context timeout is used. If context has no timeout,
	// a default of 5 seconds is used.
	// Recommended: 10-30 seconds depending on cleanup time.
	Timeout time.Duration
}

type TimeoutError struct {
	// Operation is the name of the operation that timed out.
	Operation string

	// Timeout is the timeout duration that was exceeded.
	Timeout time.Duration

	// Err is the underlying error, if any.
	Err error
}

type TimingConfig struct {
	// Configuration values
	TTL                   time.Duration
	HeartbeatInterval     time.Duration
	DisconnectGracePeriod time.Duration
	ValidationInterval    time.Duration

	// Estimated operation delays
	InitialJitter         time.Duration // 10-100ms
	KVOperationDelay      time.Duration // ~10-50ms
	MaxRetryBackoff       time.Duration // up to 350ms (50ms + 100ms + 200ms)
	PeriodicCheckInterval time.Duration // 500ms (worst case)
	NATSPropagationBuffer time.Duration // ~500ms-1s for NATS propagation
}

type TokenValidationError struct {
	// LocalToken is the token stored locally by this instance.
	LocalToken string

	// KvToken is the token stored in the KV store.
	KvToken string

	// LeaderID is the current leader ID from the KV store.
	LeaderID string

	// Reason is a human-readable description of why validation failed.
	Reason string

	// Err is the underlying error, if any.
	Err error
}

type ValidationError struct {
	// Field is the name of the configuration field that failed validation.
	Field string

	// Value is the invalid value that was provided.
	Value interface{}

	// Reason is a human-readable explanation of why validation failed.
	Reason string

	// Err is the underlying error, if any.
	Err error
}

type Watcher interface {
	Updates() <-chan Entry
	Stop()
}