《游戏服务端架构·规模化、全球化与成本》5.3 读写分离的可见性兜底

write v11 ──> token(v11, t0)
                    │
read at t0+100ms ───┼── replica applied v10 -> wait 最多 500ms
                    │
read at t0+700ms ───┴── 等待预算用完 -> 读主（主库有余量）
                                      -> 本地快照（主库过载）
                                      -> 拒绝（无快照）

// file: internal/rwvisibility/router.go
// tier: L1
// verify: go test ./internal/rwvisibility/
package rwvisibility

import (
	"sync"
	"time"
)

// Class 描述一次读的语义类别。Sensitive 的读永远不能落到从库。
type Class int

const (
	Profile Class = iota
	Leaderboard
	Wallet
	Settlement
	Payment
	Ban
)

func (c Class) Sensitive() bool {
	switch c {
	case Wallet, Settlement, Payment, Ban:
		return true
	default:
		return false
	}
}

// Token 是写后返回给会话的可见性令牌，Version 来自主库的单调版本号。
type Token struct {
	Session  string
	Key      string
	Version  uint64
	IssuedAt time.Time
}

// Target 是路由结论。
type Target int

const (
	TargetReplica Target = iota
	TargetPrimary
	TargetWait
	TargetLocal
	TargetReject
)

// Reason 是机器可读的判定原因，用于埋点和降级统计。
type Reason int

const (
	ReasonOK Reason = iota
	ReasonEmptyKey
	ReasonSensitive
	ReasonReplicaDown
	ReasonReadYourWrite
	ReasonLagBudget
	ReasonWaitBudget
	ReasonPrimarySaturated
	ReasonNoRoute
)

// Decision 是一次读路由的结果。Stale 为真表示调用方必须标注数据可能过期。
type Decision struct {
	Target Target
	Reason Reason
	Wait   time.Duration
	Stale  bool
}

// Policy 是延迟预算：复制落后多少就不再信任从库，读己之写最多等多久。
type Policy struct {
	LagBudget  time.Duration
	WaitBudget time.Duration
}

func (p Policy) normalized() Policy {
	if p.LagBudget <= 0 {
		p.LagBudget = 2 * time.Second
	}
	if p.WaitBudget <= 0 {
		p.WaitBudget = 500 * time.Millisecond
	}
	return p
}

// ReplicaState 是某个分片从库的观测状态。
type ReplicaState struct {
	Applied uint64
	Lag     time.Duration
	Healthy bool
	SeenAt  time.Time
}

// Request 是一次读请求。Shard 用于定位从库状态，Token 仅在写后读时携带。
type Request struct {
	Key              string
	Shard            string
	Class            Class
	Token            *Token
	PrimaryUp        bool
	PrimarySaturated bool
	LocalSnapshot    bool
	Now              time.Time
}

// Router 保存各分片的从库水位，并按策略给出读路由。
type Router struct {
	mu       sync.RWMutex
	policy   Policy
	replicas map[string]ReplicaState
}

func New(policy Policy) *Router {
	return &Router{policy: policy.normalized(), replicas: map[string]ReplicaState{}}
}

// Observe 更新从库水位。Healthy 为假时 Applied 与 Lag 只保留供排查。
func (r *Router) Observe(shard string, applied uint64, lag time.Duration, healthy bool, at time.Time) {
	r.mu.Lock()
	defer r.mu.Unlock()
	r.replicas[shard] = ReplicaState{Applied: applied, Lag: lag, Healthy: healthy, SeenAt: at}
}

func (r *Router) Replica(shard string) (ReplicaState, bool) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	state, ok := r.replicas[shard]
	return state, ok
}

func (r *Router) Decide(req Request) Decision {
	if req.Key == "" {
		return Decision{Target: TargetReject, Reason: ReasonEmptyKey}
	}
	now := req.Now
	if now.IsZero() {
		now = time.Now()
	}

	r.mu.RLock()
	state, known := r.replicas[req.Shard]
	policy := r.policy
	r.mu.RUnlock()

	if req.Class.Sensitive() {
		if req.PrimaryUp {
			return Decision{Target: TargetPrimary, Reason: ReasonSensitive}
		}
		return Decision{Target: TargetReject, Reason: ReasonNoRoute}
	}

	if !known || !state.Healthy {
		return degraded(req, ReasonReplicaDown)
	}

	if req.Token != nil && req.Token.Version > state.Applied {
		left := policy.WaitBudget - now.Sub(req.Token.IssuedAt)
		if left > 0 {
			return Decision{Target: TargetWait, Reason: ReasonReadYourWrite, Wait: left}
		}
		if req.PrimaryUp && !req.PrimarySaturated {
			return Decision{Target: TargetPrimary, Reason: ReasonReadYourWrite}
		}
		if req.LocalSnapshot {
			return Decision{Target: TargetLocal, Reason: ReasonWaitBudget, Stale: true}
		}
		if req.PrimaryUp {
			return Decision{Target: TargetReject, Reason: ReasonPrimarySaturated}
		}
		return Decision{Target: TargetReject, Reason: ReasonNoRoute}
	}

	if state.Lag > policy.LagBudget {
		return Decision{Target: TargetReplica, Reason: ReasonLagBudget, Stale: true}
	}
	return Decision{Target: TargetReplica, Reason: ReasonOK}
}

// degraded 处理从库不可用：先保住有本地快照的容忍读，再考虑主库余量。
func degraded(req Request, reason Reason) Decision {
	if req.LocalSnapshot {
		return Decision{Target: TargetLocal, Reason: reason, Stale: true}
	}
	if req.PrimaryUp && !req.PrimarySaturated {
		return Decision{Target: TargetPrimary, Reason: reason}
	}
	if req.PrimaryUp {
		return Decision{Target: TargetReject, Reason: ReasonPrimarySaturated}
	}
	return Decision{Target: TargetReject, Reason: ReasonNoRoute}
}