《游戏服务端架构·品类、状态与拓扑》10.2 UGC 地图的隔离、审核与发布

// file: internal/ugc/ugc.go
// tier: L1
// verify: go test ./internal/ugc/
package ugc

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"sync"
	"time"
)

var (
	ErrEmptyMap          = errors.New("ugc: empty map id")
	ErrEmptyContent      = errors.New("ugc: empty content")
	ErrBadQuota          = errors.New("ugc: quota must not be negative")
	ErrQuotaMaps         = errors.New("ugc: map quota reached")
	ErrQuotaBytes        = errors.New("ugc: byte quota reached")
	ErrQuotaVersions     = errors.New("ugc: version quota reached")
	ErrQuotaDeps         = errors.New("ugc: dependency quota reached")
	ErrUnlockedDep       = errors.New("ugc: dependency is not pinned by digest")
	ErrDuplicateDep      = errors.New("ugc: duplicate dependency")
	ErrDependencyCycle   = errors.New("ugc: dependency cycle")
	ErrVersionNotFound   = errors.New("ugc: version not found")
	ErrIllegalTransition = errors.New("ugc: illegal status transition")
	ErrNotValidated      = errors.New("ugc: sandbox requires a validated version")
	ErrNotApproved       = errors.New("ugc: canary requires an approved version")
	ErrCanaryPercent     = errors.New("ugc: canary percent must be in [1,50]")
	ErrResourceBomb      = errors.New("ugc: sandbox limits exceeded")
	ErrNotPublished      = errors.New("ugc: map has no live version")
	ErrRollbackTarget    = errors.New("ugc: rollback target is not a published version")
)

type Status string

const (
	Uploaded   Status = "uploaded"
	Validated  Status = "validated"
	Sandboxed  Status = "sandboxed"
	InReview   Status = "in_review"
	Approved   Status = "approved"
	Canary     Status = "canary"
	Published  Status = "published"
	Rejected   Status = "rejected"
	RolledBack Status = "rolled_back"
)

// transitions is the generic review pipeline. Sandbox, Canary, Publish and
// Rollback are deliberately absent: they have their own gates, and a plain
// status change must never make a version serve traffic.
var transitions = map[Status][]Status{
	Uploaded:   {Validated, Rejected},
	Validated:  {Rejected},
	Sandboxed:  {InReview, Rejected},
	InReview:   {Approved, Rejected},
	Approved:   {Rejected},
	Canary:     {Rejected},
	Published:  {},
	Rejected:   {},
	RolledBack: {},
}

func (s Status) CanTransition(to Status) bool {
	for _, candidate := range transitions[s] {
		if candidate == to {
			return true
		}
	}
	return false
}

type Quota struct {
	MaxMaps     int
	MaxBytes    int64
	MaxVersions int
	MaxDeps     int
}

type Limits struct {
	MaxMemoryBytes int64
	MaxCPUMillis   int64
	MaxWallClock   time.Duration
}

// Dependency is a lock, not a range: map + version + digest. A re-tagged
// dependency cannot silently change a reviewed map.
type Dependency struct {
	MapID   string
	Version uint64
	Digest  string
}

type Version struct {
	MapID         string
	Number        uint64
	Digest        string
	Size          int64
	Deps          []Dependency
	Status        Status
	CanaryPercent int
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type SandboxRun struct {
	Passed          bool
	PeakMemoryBytes int64
	CPUMillis       int64
	WallClock       time.Duration
}

type Store struct {
	mu        sync.Mutex
	quota     Quota
	limits    Limits
	now       func() time.Time
	versions  map[string][]*Version
	published map[string]uint64
}

func NewStore(q Quota, limits Limits, now func() time.Time) (*Store, error) {
	if q.MaxMaps < 0 || q.MaxBytes < 0 || q.MaxVersions < 0 || q.MaxDeps < 0 {
		return nil, ErrBadQuota
	}
	if limits.MaxMemoryBytes <= 0 || limits.MaxCPUMillis <= 0 || limits.MaxWallClock <= 0 {
		return nil, ErrBadQuota
	}
	if now == nil {
		now = time.Now
	}
	return &Store{quota: q, limits: limits, now: now,
		versions:  make(map[string][]*Version),
		published: make(map[string]uint64)}, nil
}

// Upload is content-addressed. Uploading identical bytes again returns the
// existing version and cannot reset its review status; only new bytes create a
// new immutable version.
func (s *Store) Upload(mapID string, data []byte, deps []Dependency) (Version, error) {
	if mapID == "" {
		return Version{}, ErrEmptyMap
	}
	if len(data) == 0 {
		return Version{}, ErrEmptyContent
	}
	sum := sha256.Sum256(data)
	digest := hex.EncodeToString(sum[:])

	s.mu.Lock()
	defer s.mu.Unlock()
	existing := s.versions[mapID]
	for _, v := range existing {
		if v.Digest == digest {
			return *v, nil
		}
	}
	if existing == nil && s.quota.MaxMaps > 0 && len(s.versions) >= s.quota.MaxMaps {
		return Version{}, ErrQuotaMaps
	}
	var total int64
	for _, v := range existing {
		total += v.Size
	}
	if s.quota.MaxBytes > 0 && total+int64(len(data)) > s.quota.MaxBytes {
		return Version{}, fmt.Errorf("%w: %d + %d > %d",
			ErrQuotaBytes, total, len(data), s.quota.MaxBytes)
	}
	if s.quota.MaxVersions > 0 && len(existing) >= s.quota.MaxVersions {
		return Version{}, fmt.Errorf("%w: %d", ErrQuotaVersions, len(existing))
	}
	if s.quota.MaxDeps > 0 && len(deps) > s.quota.MaxDeps {
		return Version{}, fmt.Errorf("%w: %d > %d", ErrQuotaDeps, len(deps), s.quota.MaxDeps)
	}
	if err := s.checkDepsLocked(mapID, deps); err != nil {
		return Version{}, err
	}
	v := &Version{MapID: mapID, Number: uint64(len(existing) + 1), Digest: digest,
		Size: int64(len(data)), Deps: append([]Dependency(nil), deps...),
		Status: Uploaded, CreatedAt: s.now()}
	v.UpdatedAt = v.CreatedAt
	s.versions[mapID] = append(existing, v)
	return *v, nil
}

func (s *Store) checkDepsLocked(mapID string, deps []Dependency) error {
	seen := make(map[string]bool, len(deps))
	for _, d := range deps {
		if d.MapID == "" || d.Version == 0 || len(d.Digest) != 64 {
			return fmt.Errorf("%w: %+v", ErrUnlockedDep, d)
		}
		if _, err := hex.DecodeString(d.Digest); err != nil {
			return fmt.Errorf("%w: digest %q", ErrUnlockedDep, d.Digest)
		}
		if d.MapID == mapID {
			return fmt.Errorf("%w: %s depends on itself", ErrDependencyCycle, mapID)
		}
		key := fmt.Sprintf("%s@%d", d.MapID, d.Version)
		if seen[key] {
			return fmt.Errorf("%w: %s", ErrDuplicateDep, key)
		}
		seen[key] = true
		if s.dependsOnLocked(d.MapID, mapID, make(map[string]bool)) {
			return fmt.Errorf("%w: %s -> %s", ErrDependencyCycle, mapID, d.MapID)
		}
	}
	return nil
}

// dependsOnLocked walks only published versions. Unpublished drafts are not a
// valid lock target, so they cannot create a cycle that was never reviewed.
func (s *Store) dependsOnLocked(from, target string, visiting map[string]bool) bool {
	if from == target {
		return true
	}
	if visiting[from] {
		return false
	}
	visiting[from] = true
	for _, v := range s.versions[from] {
		if v.Number != s.published[from] {
			continue
		}
		for _, d := range v.Deps {
			if s.dependsOnLocked(d.MapID, target, visiting) {
				return true
			}
		}
	}
	return false
}

func (s *Store) getLocked(mapID string, number uint64) (*Version, error) {
	for _, v := range s.versions[mapID] {
		if v.Number == number {
			return v, nil
		}
	}
	return nil, fmt.Errorf("%w: %s v%d", ErrVersionNotFound, mapID, number)
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/ugc
$ go test -count=1 ./internal/ugc/
ok  	gsarchlab/internal/ugc	0.626s