《MMO 服务器开发》15.1 权威边界与信任模型

客户端可提议          服务端必须裁决
───────────────       ──────────────────
目的地 to             最终位置、朝向
技能 id              冷却到期时间、伤害数值
物品 id              背包内容、金币余额
攻击目标              命中判定、暴击结果
聊天文本              过滤结果、发送频率

// file: internal/authority/boundary.go
// tier: L1
// verify: go test ./internal/authority/ -run 'TestTrust'

package authority

import (
	"fmt"
	"sort"
)

// Trust classifies every field a client can put on the wire. The whole point of
// making it a type is that the classification stops being a thing a developer
// has to remember: it lives next to the command definition and the adjudicator
// reads it mechanically.
type Trust uint8

const (
	// Untrusted is a field the server never believes on its own. It is read,
	// used as a hint, and then recomputed from server state.
	Untrusted Trust = iota
	// Advisory is a field the server may accept, but only after the value has
	// passed a server-side validator. "Client says it moved here" is advisory.
	Advisory
	// Derived is a server-owned field. The client never sends it, and a frame
	// that carries one is a protocol violation regardless of its value.
	Derived
)

// String renders a Trust for logs.
func (t Trust) String() string {
	switch t {
	case Untrusted:
		return "untrusted"
	case Advisory:
		return "advisory"
	case Derived:
		return "derived"
	default:
		return "unknown"
	}
}

// FieldSpec is the trust contract for one field of one command.
type FieldSpec struct {
	Name  string
	Trust Trust
}

// CommandSpec is the trust contract for a single command kind. Registering the
// contract is how the boundary gets drawn: whatever is not listed is not
// accepted, and whatever is Derived may not arrive from a client.
type CommandSpec struct {
	Kind   string
	Fields []FieldSpec
}

// Violation is one breach of the trust contract found in an inbound message.
type Violation struct {
	Command string
	Field   string
	Reason  string
}

// Error implements error so a Violation can be returned directly.
func (v Violation) Error() string {
	return fmt.Sprintf("command %s field %s: %s", v.Command, v.Field, v.Reason)
}

// Registry holds the trust contract for every command the server accepts. It is
// deliberately small: the boundary is a table, not a code path.
type Registry struct {
	specs map[string]CommandSpec
}

// NewRegistry returns an empty trust registry.
func NewRegistry() *Registry {
	return &Registry{specs: make(map[string]CommandSpec)}
}

// Register installs a command's trust contract. Duplicate command kinds and
// duplicate field names are rejected so the table cannot silently drift.
func (r *Registry) Register(spec CommandSpec) error {
	if spec.Kind == "" {
		return fmt.Errorf("authority: empty command kind")
	}
	if _, dup := r.specs[spec.Kind]; dup {
		return fmt.Errorf("authority: duplicate command kind %q", spec.Kind)
	}
	seen := make(map[string]bool, len(spec.Fields))
	for _, f := range spec.Fields {
		if seen[f.Name] {
			return fmt.Errorf("authority: duplicate field %q in %q", f.Name, spec.Kind)
		}
		seen[f.Name] = true
	}
	r.specs[spec.Kind] = spec
	return nil
}

// Check reports every field the client must not have sent. The rule is narrow
// and absolute: Advisory and Untrusted fields are allowed through to the
// validator, but a Derived field arriving from a client is a violation no
// matter what value it carries. Output is sorted so tests and logs are stable.
func (r *Registry) Check(kind string, sent []string) []Violation {
	spec, ok := r.specs[kind]
	if !ok {
		return []Violation{{Command: kind, Reason: "unknown command"}}
	}
	class := make(map[string]Trust, len(spec.Fields))
	for _, f := range spec.Fields {
		class[f.Name] = f.Trust
	}
	var out []Violation
	for _, name := range sent {
		t, known := class[name]
		switch {
		case !known:
			out = append(out, Violation{Command: kind, Field: name, Reason: "field not in contract"})
		case t == Derived:
			out = append(out, Violation{Command: kind, Field: name, Reason: "client sent a server-derived field"})
		}
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].Field != out[j].Field {
			return out[i].Field < out[j].Field
		}
		return out[i].Reason < out[j].Reason
	})
	return out
}

// snippet: internal/authority/boundary_test.go（节选）

// 诚实客户端只发它被允许发的字段，不该被误报。
if v := r.Check("scene.move", []string{"to", "elapsed_ms"}); len(v) != 0 {
	t.Fatalf("honest client flagged: %v", v)
}

// 篡改客户端注入服务端自有字段，两个都必须被抓到。
got := r.Check("scene.move", []string{"to", "speed", "hp"})
if len(got) != 2 {
	t.Fatalf("got %d violations, want 2: %v", len(got), got)
}