《游戏服务端架构·核心系统与契约》13.2 系统边界与数据所有权总表

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

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

// Channel is the only way a non-owner may influence a dataset. None of these
// channels is a direct write: the owning system still performs the write.
type Channel string

const (
	ChannelEvent     Channel = "event"
	ChannelAPI       Channel = "api"
	ChannelReconcile Channel = "reconcile"
)

var (
	ErrUnknownSystem  = errors.New("ownershipmap: unknown system")
	ErrUnknownDataset = errors.New("ownershipmap: unknown dataset")
	ErrDuplicate      = errors.New("ownershipmap: duplicate dataset")
	ErrOwner          = errors.New("ownershipmap: owner is not a registered system")
	ErrDeleteOwner    = errors.New("ownershipmap: delete owner is not a registered system")
	ErrRetention      = errors.New("ownershipmap: retention must not be negative")
	ErrNoReader       = errors.New("ownershipmap: dataset needs at least one reader")
	ErrReader         = errors.New("ownershipmap: reader is not a registered system")
	ErrChannel        = errors.New("ownershipmap: channel is not valid")
	ErrChannelDenied  = errors.New("ownershipmap: channel is not approved for this dataset")
	ErrCrossWrite     = errors.New("ownershipmap: direct write by a non-owner")
	ErrOwnerRequest   = errors.New("ownershipmap: the owner does not need a request")
)

// Dataset is one row of the ownership table. Writers is deliberately absent:
// the owner is the only writer. Cross-system influence is expressed through
// Channels, and the owner still applies the change.
type Dataset struct {
	Name          string
	Owner         string
	Readers       []string
	RetentionDays int // 0 means until account deletion
	DeleteOwner   string
	Channels      []Channel
}

func channelValid(c Channel) bool {
	switch c {
	case ChannelEvent, ChannelAPI, ChannelReconcile:
		return true
	}
	return false
}

// Map is the complete ownership table for one topology.
type Map struct {
	systems  map[string]bool
	datasets map[string]Dataset
}

// NewMap registers the known systems. Registering a system here does not give
// it any write permission; permission comes only from Dataset.Owner.
func NewMap(systems []string) (*Map, error) {
	if len(systems) == 0 {
		return nil, fmt.Errorf("ownershipmap: at least one system is required")
	}
	m := &Map{systems: make(map[string]bool, len(systems)), datasets: make(map[string]Dataset)}
	for _, s := range systems {
		if s == "" {
			return nil, fmt.Errorf("ownershipmap: empty system name")
		}
		if m.systems[s] {
			return nil, fmt.Errorf("ownershipmap: duplicate system %q", s)
		}
		m.systems[s] = true
	}
	return m, nil
}

func (m *Map) validateDataset(d Dataset) error {
	if d.Name == "" {
		return fmt.Errorf("ownershipmap: empty dataset name")
	}
	if !m.systems[d.Owner] {
		return fmt.Errorf("%w: dataset %q names %q", ErrOwner, d.Name, d.Owner)
	}
	if !m.systems[d.DeleteOwner] {
		return fmt.Errorf("%w: dataset %q names %q", ErrDeleteOwner, d.Name, d.DeleteOwner)
	}
	if d.RetentionDays < 0 {
		return fmt.Errorf("%w: dataset %q has %d days", ErrRetention, d.Name, d.RetentionDays)
	}
	if len(d.Readers) == 0 {
		return fmt.Errorf("%w: dataset %q", ErrNoReader, d.Name)
	}
	seen := make(map[string]bool, len(d.Readers))
	for _, r := range d.Readers {
		if !m.systems[r] {
			return fmt.Errorf("%w: dataset %q names %q", ErrReader, d.Name, r)
		}
		if seen[r] {
			return fmt.Errorf("ownershipmap: dataset %q lists reader %q twice", d.Name, r)
		}
		seen[r] = true
	}
	for _, c := range d.Channels {
		if !channelValid(c) {
			return fmt.Errorf("%w: %q on dataset %q", ErrChannel, c, d.Name)
		}
	}
	return nil
}

// Add inserts one dataset after validating every reference. Validation is
// repeated in Validate so a table loaded from a file can be audited as a
// whole before it is trusted.
func (m *Map) Add(d Dataset) error {
	if _, ok := m.datasets[d.Name]; ok {
		return fmt.Errorf("%w: %q", ErrDuplicate, d.Name)
	}
	if err := m.validateDataset(d); err != nil {
		return err
	}
	m.datasets[d.Name] = cloneDataset(d)
	return nil
}

func cloneDataset(d Dataset) Dataset {
	out := d
	out.Readers = append([]string(nil), d.Readers...)
	out.Channels = append([]Channel(nil), d.Channels...)
	return out
}

// Dataset returns a copy of one row.
func (m *Map) Dataset(name string) (Dataset, bool) {
	d, ok := m.datasets[name]
	if !ok {
		return Dataset{}, false
	}
	return cloneDataset(d), true
}

// Validate re-checks every row in deterministic order.
func (m *Map) Validate() []error {
	var errs []error
	for _, name := range m.Datasets() {
		if err := m.validateDataset(m.datasets[name]); err != nil {
			errs = append(errs, err)
		}
	}
	return errs
}

// Datasets returns dataset names in sorted order.
func (m *Map) Datasets() []string {
	out := make([]string, 0, len(m.datasets))
	for name := range m.datasets {
		out = append(out, name)
	}
	sort.Strings(out)
	return out
}

// CheckDirectWrite rejects every writer that is not the owner. This is the
// forbidden list: there are no exceptions and no "temporary" direct writes.
func (m *Map) CheckDirectWrite(dataset, actor string) error {
	d, ok := m.datasets[dataset]
	if !ok {
		return fmt.Errorf("%w: %q", ErrUnknownDataset, dataset)
	}
	if !m.systems[actor] {
		return fmt.Errorf("%w: %q", ErrUnknownSystem, actor)
	}
	if actor == d.Owner {
		return nil
	}
	return fmt.Errorf("%w: %s must not write %s (owner %s)", ErrCrossWrite, actor, dataset, d.Owner)
}

// CheckRequest verifies the sanctioned path for a non-owner: a declared event,
// API or reconciliation channel. The request is not a write; the owner applies
// it and remains the only writer.
func (m *Map) CheckRequest(dataset, from string, ch Channel) error {
	d, ok := m.datasets[dataset]
	if !ok {
		return fmt.Errorf("%w: %q", ErrUnknownDataset, dataset)
	}
	if !m.systems[from] {
		return fmt.Errorf("%w: %q", ErrUnknownSystem, from)
	}
	if from == d.Owner {
		return fmt.Errorf("%w: %s owns %s", ErrOwnerRequest, from, dataset)
	}
	if !channelValid(ch) {
		return fmt.Errorf("%w: %q", ErrChannel, ch)
	}
	for _, allowed := range d.Channels {
		if allowed == ch {
			return nil
		}
	}
	return fmt.Errorf("%w: %s -> %s via %s", ErrChannelDenied, from, dataset, ch)
}

// CompareBaseline checks that a topology change did not orphan an owner, a
// delete owner or a reader. Ownership survives scale changes only while every
// named system still exists.
func (m *Map) CompareBaseline(baseline []string) []error {
	known := make(map[string]bool, len(baseline))
	for _, s := range baseline {
		known[s] = true
	}
	var errs []error
	for _, name := range m.Datasets() {
		d := m.datasets[name]
		if !known[d.Owner] {
			errs = append(errs, fmt.Errorf("dataset %q: owner %q is missing from the baseline topology", name, d.Owner))
		}
		if !known[d.DeleteOwner] {
			errs = append(errs, fmt.Errorf("dataset %q: delete owner %q is missing from the baseline topology", name, d.DeleteOwner))
		}
		for _, r := range d.Readers {
			if !known[r] {
				errs = append(errs, fmt.Errorf("dataset %q: reader %q is missing from the baseline topology", name, r))
			}
		}
	}
	return errs
}