《游戏服务端架构·规模化、全球化与成本》3.3 全球同服的状态归属

ACTIVE ──BEGIN──▶ DRAINING ──DRAINED──▶ COPYING ──COPIED──▶ VERIFYING
   │                  │                    │                    │
   │                  └────ABORT───────────┴────────ABORT───────┤
   │                                                           ▼
   │                                                       CUTOVER
   │                                                           │
   │                                            COMMIT ────────┤
   ▼                                                           ▼
 (source writes)                                            DONE
                                                        (target writes)

// file: internal/globalstate/ownership.go
// tier: L1
// verify: go test ./internal/globalstate/
package globalstate

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

// Domain is a kind of state, not a service. One domain has exactly one writer
// region at a time; everything else is a reader with a declared staleness
// window. Mixing domains in one rule is how split-brain starts.
type Domain string

const (
	DomainPlayerMaster Domain = "player_master"
	DomainWorldState   Domain = "world_state"
	DomainSocialGraph  Domain = "social_graph"
	DomainRanking      Domain = "ranking"
)

// Region is an operational unit that owns storage for a domain.
type Region string

// Owner names the single writer for one domain. Shard is empty for state that
// is not sharded, such as a global social graph.
type Owner struct {
	Domain Domain
	Region Region
	Shard  string
}

// Placement is the authoritative map from domain to owner. Unknown domains
// fail closed: a request does not fall back to a default region.
type Placement map[Domain]Owner

// Windows is the maximum age of a cross-region read that the product accepts
// for each domain. A zero window means the reader must go to the owner.
type Windows map[Domain]time.Duration

var (
	ErrNoOwner      = errors.New("globalstate: domain has no owner")
	ErrBadPlacement = errors.New("globalstate: invalid placement")
	ErrBadRequest   = errors.New("globalstate: invalid request")
)

// Validate requires every owner to name a region and to agree with its map
// key. A silent mismatch between key and Domain is a routing bug that only
// appears under load.
func (p Placement) Validate() error {
	if len(p) == 0 {
		return fmt.Errorf("%w: empty placement", ErrBadPlacement)
	}
	for domain, owner := range p {
		if domain == "" {
			return fmt.Errorf("%w: empty domain", ErrBadPlacement)
		}
		if owner.Domain != domain {
			return fmt.Errorf("%w: %q maps to owner for %q", ErrBadPlacement, domain, owner.Domain)
		}
		if owner.Region == "" {
			return fmt.Errorf("%w: %q has no region", ErrBadPlacement, domain)
		}
	}
	return nil
}

// Operation is read or write. There is no "read your writes" mode: a write
// must go to the owner, otherwise the caller would be guessing.
type Operation string

const (
	OpRead  Operation = "READ"
	OpWrite Operation = "WRITE"
)

// Request is one access with the caller's local view. Staleness is how old
// the caller's cached copy is; a zero value means no cache was consulted.
type Request struct {
	Domain    Domain
	Region    Region
	Operation Operation
	Shard     string
	Staleness time.Duration
}

// Decision returns the owner even when the request is denied, so the caller
// can redirect instead of retrying the same wrong region.
type Decision struct {
	Owner        Owner
	Allowed      bool
	CrossRegion  bool
	MaxStaleness time.Duration
	Reason       string
}

// Resolve applies ownership and staleness rules. Writes are owner-only.
// Reads are local or, when the domain has a window, served from a stale copy
// no older than that window. A shard mismatch is denied before any of this:
// the request was routed to the wrong place, and freshness cannot fix it.
func Resolve(p Placement, windows Windows, req Request) (Decision, error) {
	if err := p.Validate(); err != nil {
		return Decision{}, err
	}
	owner, ok := p[req.Domain]
	if !ok {
		return Decision{}, fmt.Errorf("%w: %q", ErrNoOwner, req.Domain)
	}
	if req.Region == "" {
		return Decision{}, fmt.Errorf("%w: empty region", ErrBadRequest)
	}
	if req.Operation != OpRead && req.Operation != OpWrite {
		return Decision{}, fmt.Errorf("%w: unknown operation %q", ErrBadRequest, req.Operation)
	}
	if req.Staleness < 0 {
		return Decision{}, fmt.Errorf("%w: negative staleness", ErrBadRequest)
	}
	window := windows[req.Domain]
	if window < 0 {
		return Decision{}, fmt.Errorf("%w: negative window for %q", ErrBadRequest, req.Domain)
	}
	d := Decision{Owner: owner, CrossRegion: req.Region != owner.Region, MaxStaleness: window}
	if req.Shard != "" && req.Shard != owner.Shard {
		d.Reason = fmt.Sprintf("wrong shard: want %q", owner.Shard)
		return d, nil
	}
	if req.Operation == OpWrite {
		if req.Region == owner.Region {
			d.Allowed = true
			d.Reason = "owner region write"
		} else {
			d.Reason = "writes are owner-only"
		}
		return d, nil
	}
	if req.Region == owner.Region {
		d.Allowed = true
		d.Reason = "owner region read"
		return d, nil
	}
	if req.Staleness <= window {
		d.Allowed = true
		d.Reason = "cross-region read within window"
	} else {
		d.Reason = fmt.Sprintf("snapshot age %s exceeds window %s", req.Staleness, window)
	}
	return d, nil
}