《游戏服务端架构·规模化、全球化与成本》3.2 数据驻留与跨境合规

// file: internal/dataregion/policy.go
// tier: L1
// verify: go test ./internal/dataregion/
package dataregion

import (
	"errors"
	"fmt"
	"sort"
)

// Category is a class of data with one residency contract. Rules are written
// per category, not per table: a single table often mixes identifiers with
// analytics rows, and a per-table rule would force one of them to be wrong.
type Category string

const (
	CategoryAccountIdentity Category = "account_identity"
	CategoryPayment         Category = "payment"
	CategoryBehaviorLog     Category = "behavior_log"
	CategoryBattleReplay    Category = "battle_replay"
	CategoryAggregate       Category = "aggregate_stats"
)

// Region is where data is stored and processed, not where the player lives.
type Region string

// Operation separates a read replica from a writable home. A copy that is
// allowed to serve reads is not thereby allowed to accept writes.
type Operation string

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

// Purpose is why the data crosses a boundary. Support access and analytics
// export carry different obligations even when the bytes look identical.
type Purpose string

const (
	PurposeService   Purpose = "SERVICE"
	PurposeAnalytics Purpose = "ANALYTICS"
	PurposeSupport   Purpose = "SUPPORT"
	PurposeDeletion  Purpose = "DELETION"
)

// TransferMode is the strongest mechanism the rule permits. Deny is the
// default; every other mode must be proven by the request.
type TransferMode string

const (
	TransferDeny         TransferMode = "DENY"
	TransferPseudonymize TransferMode = "PSEUDONYMIZE"
	TransferConsent      TransferMode = "CONSENT"
	TransferAggregate    TransferMode = "AGGREGATE_ONLY"
)

var (
	ErrBadRule        = errors.New("dataregion: invalid rule")
	ErrUnknown        = errors.New("dataregion: unknown category")
	ErrTransferDenied = errors.New("dataregion: transfer denied")
)

// Rule is the residency contract for one category. Home is the only region
// that may accept writes; Replicas may serve reads. CrossRegion applies to
// both reads outside the replica list and writes outside Home.
type Rule struct {
	Category    Category
	Home        Region
	Replicas    []Region
	CrossRegion TransferMode
}

// Validate rejects ambiguous rules. A category may appear only once, Home may
// not also be a replica, and every replica must be a non-empty region.
func Validate(rules []Rule) error {
	seen := map[Category]bool{}
	for _, r := range rules {
		if r.Category == "" {
			return fmt.Errorf("%w: empty category", ErrBadRule)
		}
		if seen[r.Category] {
			return fmt.Errorf("%w: duplicate category %q", ErrBadRule, r.Category)
		}
		seen[r.Category] = true
		if r.Home == "" {
			return fmt.Errorf("%w: %q has no home", ErrBadRule, r.Category)
		}
		if !validMode(r.CrossRegion) {
			return fmt.Errorf("%w: %q has unknown mode %q", ErrBadRule, r.Category, r.CrossRegion)
		}
		replicas := map[Region]bool{}
		for _, region := range r.Replicas {
			if region == "" {
				return fmt.Errorf("%w: %q has empty replica", ErrBadRule, r.Category)
			}
			if region == r.Home {
				return fmt.Errorf("%w: %q lists home as replica", ErrBadRule, r.Category)
			}
			if replicas[region] {
				return fmt.Errorf("%w: %q repeats replica %q", ErrBadRule, r.Category, region)
			}
			replicas[region] = true
		}
	}
	return nil
}

func validMode(m TransferMode) bool {
	switch m {
	case TransferDeny, TransferPseudonymize, TransferConsent, TransferAggregate:
		return true
	default:
		return false
	}
}

// Request is one read or write that may cross a region boundary. The caller
// must state whether identifiers were removed and whether consent exists;
// the decision function never infers either from the purpose.
type Request struct {
	Category      Category
	From          Region
	To            Region
	Operation     Operation
	Purpose       Purpose
	HasConsent    bool
	Pseudonymized bool
}

// Decision records not only allow/deny but the mechanism that made it legal.
// Redactions lists the fields that must be stripped before the bytes leave.
type Decision struct {
	Allowed    bool
	Mode       TransferMode
	ReadOnly   bool
	Redactions []string
	Reason     string
}

// Decide applies one category rule to one request. Same-region traffic is
// always allowed because no boundary is crossed. A replica read is allowed
// with no payload mutation, but a replica write is denied even when the
// category's CrossRegion mode would otherwise permit transfer.
func Decide(rules []Rule, req Request) (Decision, error) {
	if err := Validate(rules); err != nil {
		return Decision{}, err
	}
	var rule *Rule
	for i := range rules {
		if rules[i].Category == req.Category {
			rule = &rules[i]
			break
		}
	}
	if rule == nil {
		return Decision{}, fmt.Errorf("%w: %q", ErrUnknown, req.Category)
	}
	if req.From == "" || req.To == "" {
		return Decision{}, fmt.Errorf("%w: from and to are required", ErrBadRule)
	}
	if req.Operation != OpRead && req.Operation != OpWrite {
		return Decision{}, fmt.Errorf("%w: unknown operation %q", ErrBadRule, req.Operation)
	}
	if req.From == req.To {
		return Decision{Allowed: true, Mode: TransferDeny, Reason: "same region"}, nil
	}
	if isReplica(*rule, req.To) {
		if req.Operation == OpRead {
			return Decision{Allowed: true, Mode: TransferDeny, ReadOnly: true, Reason: "read replica"}, nil
		}
		return Decision{Allowed: false, Mode: TransferDeny, Reason: "replica does not accept writes"}, nil
	}
	if req.Purpose == PurposeDeletion {
		return Decision{
			Allowed:    true,
			Mode:       TransferPseudonymize,
			Redactions: []string{"display_name", "device_id", "free_text"},
			Reason:     "deletion tombstone carries no payload",
		}, nil
	}
	switch rule.CrossRegion {
	case TransferPseudonymize:
		if !req.Pseudonymized {
			return Decision{Allowed: false, Mode: TransferPseudonymize, Reason: "identifiers were not removed"}, nil
		}
		return Decision{Allowed: true, Mode: TransferPseudonymize, Redactions: []string{"device_id", "ip_address"}}, nil
	case TransferConsent:
		if !req.HasConsent {
			return Decision{Allowed: false, Mode: TransferConsent, Reason: "consent missing"}, nil
		}
		return Decision{Allowed: true, Mode: TransferConsent, Redactions: []string{"device_id"}}, nil
	case TransferAggregate:
		if req.Purpose != PurposeAnalytics || !req.Pseudonymized {
			return Decision{Allowed: false, Mode: TransferAggregate, Reason: "aggregate export needs analytics purpose and pseudonymized rows"}, nil
		}
		return Decision{Allowed: true, Mode: TransferAggregate, Redactions: []string{"account_id", "role_id"}}, nil
	default:
		return Decision{Allowed: false, Mode: TransferDeny, Reason: "category is region-locked"}, nil
	}
}

func isReplica(r Rule, region Region) bool {
	for _, candidate := range r.Replicas {
		if candidate == region {
			return true
		}
	}
	return false
}

// SortedRegions returns the distinct regions named by rules in lexical order.
// Deterministic order keeps generated audit reports easy to diff.
func SortedRegions(rules []Rule) []Region {
	seen := map[Region]bool{}
	var out []Region
	for _, r := range rules {
		for _, region := range append([]Region{r.Home}, r.Replicas...) {
			if !seen[region] {
				seen[region] = true
				out = append(out, region)
			}
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
	return out
}