《MMO 服务器开发》2.2 Leader 选举与服务所有权

t0  scene-01 抢到领导键，自认为 leader，开始处理 Boss 结算
t1  网络分区：scene-01 与 etcd 失联，但它自己不知道，仍在写
t2  scene-01 的租约到期，etcd 删键；scene-02 抢到键，成为新 leader
t3  分区恢复，scene-01 以为自己还是 leader，继续往共享存储写
t4  两个 leader 同时写 → 脑裂（split-brain），数据被写坏

// file: internal/discovery/election.go
// tier: L2
// verify: go test ./internal/discovery/ -run TestEtcd -v
package discovery

import (
	"context"
	"errors"
	"fmt"
	"sync"
	"time"

	clientv3 "go.etcd.io/etcd/client/v3"
)

var (
	// ErrNotLeader：这次竞选没抢到领导权（已被别人占着）。
	ErrNotLeader = errors.New("discovery: not leader")
	// ErrFenced：写操作的 fencing token 不比见过的更大，说明自己已经是旧 leader。
	ErrFenced = errors.New("discovery: fenced by newer token")
)

// Leadership 是一次成功的竞选结果。
type Leadership struct {
	Node NodeID
	// Token 是 fencing token：取得领导权那一刻 etcd 的事务 revision。
	// etcd 的 revision 全局单调递增，所以「越晚当选的 token 越大」是硬保证。
	Token int64

	cli    *clientv3.Client
	key    string
	lease  clientv3.LeaseID
	cancel context.CancelFunc
	once   sync.Once
}

// Election 是同一 name 下的一次「单例领导权」竞选。
type Election struct {
	cli    *clientv3.Client
	prefix string
	name   string
	ttl    int64
}

// NewElection 创建一个挂在 cli 上的竞选器，领导键为 prefix+"election/"+name。
func NewElection(cli *clientv3.Client, prefix, name string, ttl time.Duration) *Election {
	return &Election{cli: cli, prefix: prefix, name: name, ttl: int64(ttl.Seconds())}
}

func (e *Election) key() string { return e.prefix + "election/" + e.name }

// Campaign 尝试抢占领导权。成功返回 Leadership；已被别人占着返回 ErrNotLeader。
//
// 抢占用一次事务完成：只有当领导键的 CreateRevision == 0（即键不存在）
// 时才写入自己。etcd 对事务串行化，所以同一时刻至多一个事务能成功——
// 这就是「同一时刻只有一个 leader」的根据，不需要额外的分布式锁。
func (e *Election) Campaign(ctx context.Context, id NodeID) (*Leadership, error) {
	grant, err := e.cli.Grant(ctx, e.ttl)
	if err != nil {
		return nil, err
	}
	resp, err := e.cli.Txn(ctx).
		If(clientv3.Compare(clientv3.CreateRevision(e.key()), "=", 0)).
		Then(clientv3.OpPut(e.key(), string(id), clientv3.WithLease(grant.ID))).
		Commit()
	if err != nil {
		_, _ = e.cli.Revoke(context.Background(), grant.ID)
		return nil, err
	}
	if !resp.Succeeded {
		// 没抢到，把自己建的租约还回去，别白占资源。
		_, _ = e.cli.Revoke(context.Background(), grant.ID)
		return nil, ErrNotLeader
	}
	hbCtx, cancel := context.WithCancel(context.Background())
	kaCh, err := e.cli.KeepAlive(hbCtx, grant.ID)
	if err != nil {
		cancel()
		_, _ = e.cli.Revoke(context.Background(), grant.ID)
		return nil, err
	}
	l := &Leadership{
		Node:   id,
		Token:  resp.Header.Revision,
		cli:    e.cli,
		key:    e.key(),
		lease:  grant.ID,
		cancel: cancel,
	}
	go func() {
		for range kaCh {
			// 续约成功什么都不用做；通道关闭即租约失效、领导权自动让出。
		}
	}()
	return l, nil
}

// Resign 主动让出领导权（撤销租约，键立即消失）。
func (l *Leadership) Resign(ctx context.Context) error {
	var err error
	l.once.Do(func() {
		l.cancel()
		_, err = l.cli.Revoke(ctx, l.lease)
	})
	return err
}

// Leader 读回当前领导键指向的节点及其 token。
func (e *Election) Leader(ctx context.Context) (NodeID, int64, error) {
	resp, err := e.cli.Get(ctx, e.key())
	if err != nil {
		return "", 0, err
	}
	if len(resp.Kvs) == 0 {
		return "", 0, ErrNotLeader
	}
	return NodeID(resp.Kvs[0].Value), resp.Kvs[0].ModRevision, nil
}

// Fencer 用单调递增的 fencing token 挡住「醒过来的旧 leader」。
//
// 脑裂场景：旧 leader 与 etcd 之间网络断了，它自己还以为在任上，会继续
// 往共享资源（分片分配表、掉落结算表）写。下游只要在每次有副作用的写之前
// 调一次 Check，就能保证旧 token 的写被拒——它见过的最大值只会前进不会后退。
type Fencer struct {
	mu       sync.Mutex
	lastSeen int64
}

// Check 校验一个 token。比见过的最大值大就放行并推进；否则返回 ErrFenced。
func (f *Fencer) Check(token int64) error {
	f.mu.Lock()
	defer f.mu.Unlock()
	if token <= f.lastSeen {
		return fmt.Errorf("%w: token %d <= seen %d", ErrFenced, token, f.lastSeen)
	}
	f.lastSeen = token
	return nil
}

// LastSeen 返回当前见过的最大 token（排障用）。
func (f *Fencer) LastSeen() int64 {
	f.mu.Lock()
	defer f.mu.Unlock()
	return f.lastSeen
}

// snippet: token 就是取得领导权那一刻 etcd 的事务 revision
l := &Leadership{ /* ... */ Token: resp.Header.Revision /* ... */ }

// snippet: Leader 保护一次有副作用的写（在分片分配表上的落点）
func (l *Leadership) commitAssignment(ctx context.Context, f *Fencer, plan Assignment) error {
	// 写之前先过 fencing：如果自己已经不是最新任期的 leader，直接拒绝。
	if err := f.Check(l.Token); err != nil {
		return err // ErrFenced：放弃这次写，让新 leader 接手
	}
	return store.Apply(ctx, plan)
}

=== RUN   TestEtcdLeaderElectionSingleLeader
    election_test.go:56: elected leader=scene-03 token=451
    election_test.go:96: takeover leader=scene-01 token=453 (was 451)
--- PASS: TestEtcdLeaderElectionSingleLeader (0.08s)
PASS
ok  	aegis/internal/discovery	0.485s