《后端架构设计·分布式与数据一致性》10.2 分布式锁：租约、fencing token 与 Redis 边界

// file: internal/platform/lock/lease.go
// tier: L2
// verify: go test ./lock/ -count=1
package lock

import (
	"errors"
	"fmt"
	"sync"
	"time"
)

var (
	// ErrLocked means another live lease owns the key.
	ErrLocked = errors.New("lock: key already leased")
	// ErrLeaseLost means the caller no longer owns a live lease.
	ErrLeaseLost = errors.New("lock: lease lost")
	// ErrStaleToken means a write arrived from an older fencing token.
	ErrStaleToken = errors.New("lock: stale fencing token")
)

// Token is a monotonically increasing fencing token issued at acquisition.
type Token int64

// Clock is the wall clock, injectable for tests.
type Clock interface {
	Now() time.Time
}

// Manager issues leases and fencing tokens. It stands in for etcd or Redis;
// the safety argument below does not depend on which one is used.
type Manager struct {
	mu      sync.Mutex
	clock   Clock
	leases  map[string]lease
	nextTok Token
}

type lease struct {
	token     Token
	expiresAt time.Time
}

// NewManager returns an empty lease manager.
func NewManager(clock Clock) *Manager {
	return &Manager{clock: clock, leases: make(map[string]lease)}
}

// Acquire grants a lease for key and returns its fencing token.
func (m *Manager) Acquire(key string, ttl time.Duration) (Token, error) {
	m.mu.Lock()
	defer m.mu.Unlock()
	now := m.clock.Now()
	if cur, ok := m.leases[key]; ok && now.Before(cur.expiresAt) {
		return 0, fmt.Errorf("lock: acquire %q held by token %d: %w", key, cur.token, ErrLocked)
	}
	m.nextTok++
	l := lease{token: m.nextTok, expiresAt: now.Add(ttl)}
	m.leases[key] = l
	return l.token, nil
}

// Renew extends a live lease. A lease that already expired cannot be revived.
func (m *Manager) Renew(key string, token Token, ttl time.Duration) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	cur, ok := m.leases[key]
	if !ok || cur.token != token || !m.clock.Now().Before(cur.expiresAt) {
		return fmt.Errorf("lock: renew %q token %d: %w", key, token, ErrLeaseLost)
	}
	cur.expiresAt = m.clock.Now().Add(ttl)
	m.leases[key] = cur
	return nil
}

// Release drops a lease only if token still owns it.
func (m *Manager) Release(key string, token Token) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	cur, ok := m.leases[key]
	if !ok || cur.token != token {
		return fmt.Errorf("lock: release %q token %d: %w", key, token, ErrLeaseLost)
	}
	delete(m.leases, key)
	return nil
}

// FenceStore is the resource that the lease protects. It remembers the
// highest token it has seen per key and rejects anything older.
type FenceStore struct {
	mu       sync.Mutex
	maxToken map[string]Token
	values   map[string]string
	rejected int
}

// NewFenceStore returns an empty store.
func NewFenceStore() *FenceStore {
	return &FenceStore{maxToken: make(map[string]Token), values: make(map[string]string)}
}

// Write accepts value only when token is not behind the fence.
func (s *FenceStore) Write(key string, token Token, value string) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if max, ok := s.maxToken[key]; ok && token < max {
		s.rejected++
		return fmt.Errorf("lock: write %q token %d behind fence %d: %w", key, token, max, ErrStaleToken)
	}
	if max, ok := s.maxToken[key]; !ok || token > max {
		s.maxToken[key] = token
	}
	s.values[key] = value
	return nil
}

// Value returns the stored value.
func (s *FenceStore) Value(key string) string {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.values[key]
}

// Rejected reports how many stale writes were refused.
func (s *FenceStore) Rejected() int {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.rejected
}

// NaiveStore is the counterexample: it stores values without checking tokens,
// which is what a lease-only design degrades to after a pause.
type NaiveStore struct {
	mu    sync.Mutex
	value string
}

// Write overwrites the value unconditionally.
func (s *NaiveStore) Write(_ Token, value string) {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.value = value
}

// Value returns the stored value.
func (s *NaiveStore) Value() string {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.value
}

$ go test ./lock/ -v -count=1
=== RUN   TestLeaseExpiresAndNewHolderGetsToken
    lease_test.go:49: expired lease replaced: token_a=1 token_b=2
--- PASS: TestLeaseExpiresAndNewHolderGetsToken (0.00s)
=== RUN   TestFenceRejectsExpiredHolder
    lease_test.go:72: stale write rejected: token_a=1 token_b=2 rejected=1 value=reserved-by-b
--- PASS: TestFenceRejectsExpiredHolder (0.00s)
=== RUN   TestWithoutFenceExpiredHolderOverwrites
    lease_test.go:88: without fence: final value=reserved-by-a-late (stale holder won)
--- PASS: TestWithoutFenceExpiredHolderOverwrites (0.00s)
=== RUN   TestRenewBeforeExpiryExtends
--- PASS: TestRenewBeforeExpiryExtends (0.00s)
=== RUN   TestRenewAfterExpiryFails
--- PASS: TestRenewAfterExpiryFails (0.00s)
=== RUN   TestConcurrentAcquireSingleHolder
--- PASS: TestConcurrentAcquireSingleHolder (0.00s)
PASS
ok  	archlab/lock	0.263s
$ go test ./lock/ -race -count=1
ok  	archlab/lock	1.594s