《游戏服务端架构·平台化与架构治理》2.3 活动状态、回滚与审计

// file: internal/eventaudit/audit.go
// tier: L1
// verify: go test ./internal/eventaudit/
package eventaudit

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"sort"
	"time"
)

// State is the lifecycle position of one activity. RolledBack is a state,
// not a deletion: the activity happened, and the record must say so.
type State string

const (
	StateDraft         State = "draft"
	StatePendingReview State = "pending_review"
	StateScheduled     State = "scheduled"
	StateRunning       State = "running"
	StatePaused        State = "paused"
	StateEnded         State = "ended"
	StateRolledBack    State = "rolled_back"
)

var allowedTransitions = map[State][]State{
	StateDraft:         {StatePendingReview},
	StatePendingReview: {StateDraft, StateScheduled},
	StateScheduled:     {StatePendingReview, StateRunning, StateRolledBack},
	StateRunning:       {StatePaused, StateEnded, StateRolledBack},
	StatePaused:        {StateRunning, StateEnded, StateRolledBack},
	StateEnded:         {StateRolledBack},
	StateRolledBack:    {},
}

func ValidState(s State) bool {
	_, ok := allowedTransitions[s]
	return ok
}

func CanTransition(from, to State) bool {
	for _, candidate := range allowedTransitions[from] {
		if candidate == to {
			return true
		}
	}
	return false
}

// Transition rejects an edge that the lifecycle does not define. A direct
// draft-to-running jump is not a shortcut; it means the review record is
// missing and the audit trail would have a hole.
func Transition(from, to State) error {
	if !ValidState(from) {
		return fmt.Errorf("eventaudit: unknown source state %q", from)
	}
	if !ValidState(to) {
		return fmt.Errorf("eventaudit: unknown target state %q", to)
	}
	if !CanTransition(from, to) {
		return fmt.Errorf("eventaudit: transition %s -> %s is not allowed", from, to)
	}
	return nil
}

// Change is one field-level difference. Before and After stay strings so the
// audit log can store numbers, booleans and timestamps without a schema
// migration for every new field.
type Change struct {
	Field  string `json:"field"`
	Before string `json:"before"`
	After  string `json:"after"`
}

// Diff reports changed fields in stable order and optionally masks fields
// whose values must not be copied into the audit store.
func Diff(before, after map[string]string, redacted map[string]bool) []Change {
	keys := make(map[string]bool, len(before)+len(after))
	for k := range before {
		keys[k] = true
	}
	for k := range after {
		keys[k] = true
	}
	ordered := make([]string, 0, len(keys))
	for k := range keys {
		ordered = append(ordered, k)
	}
	sort.Strings(ordered)

	var out []Change
	for _, field := range ordered {
		b, a := before[field], after[field]
		if b == a {
			continue
		}
		if redacted[field] {
			b, a = "***", "***"
		}
		out = append(out, Change{Field: field, Before: b, After: a})
	}
	return out
}

// Entry is one append-only audit record. Hash covers every field except
// itself and PrevHash links to the previous entry, so removing or editing an
// old record breaks verification at that point and every point after it.
type Entry struct {
	Seq      int64     `json:"seq"`
	EventID  string    `json:"event_id"`
	Actor    string    `json:"actor"`
	Ticket   string    `json:"ticket"`
	At       time.Time `json:"at"`
	From     State     `json:"from"`
	To       State     `json:"to"`
	Changes  []Change  `json:"changes"`
	PrevHash string    `json:"prev_hash"`
	Hash     string    `json:"hash"`
}

// Log is an in-memory chain. Production stores the same entries in an
// append-only table or object lock; the hash chain makes a later rewrite
// detectable even when storage permissions are weaker than intended.
type Log struct {
	entries []Entry
}

func NewLog() *Log { return &Log{} }

func (l *Log) Len() int { return len(l.entries) }

// Append validates identity, ticket and lifecycle before adding the record.
// An audit row without a ticket is not evidence; it is an anonymous edit.
func (l *Log) Append(e Entry) (Entry, error) {
	if e.Seq == 0 {
		e.Seq = int64(len(l.entries)) + 1
	}
	if e.Seq != int64(len(l.entries))+1 {
		return Entry{}, fmt.Errorf("eventaudit: sequence %d does not follow %d", e.Seq, len(l.entries))
	}
	if e.EventID == "" || e.Actor == "" || e.Ticket == "" {
		return Entry{}, fmt.Errorf("eventaudit: event id, actor and ticket are required")
	}
	if e.At.IsZero() {
		return Entry{}, fmt.Errorf("eventaudit: timestamp is required")
	}
	if e.From == "" {
		if e.To != StateDraft {
			return Entry{}, fmt.Errorf("eventaudit: a new event must start in draft")
		}
	} else {
		if e.From == e.To {
			if len(e.Changes) == 0 {
				return Entry{}, fmt.Errorf("eventaudit: no-op entry has no field changes")
			}
			if !ValidState(e.From) {
				return Entry{}, fmt.Errorf("eventaudit: unknown state %q", e.From)
			}
		} else if err := Transition(e.From, e.To); err != nil {
			return Entry{}, err
		}
	}

	e.At = e.At.UTC()
	e.Changes = append([]Change(nil), e.Changes...)
	sort.Slice(e.Changes, func(i, j int) bool { return e.Changes[i].Field < e.Changes[j].Field })
	e.PrevHash = ""
	if n := len(l.entries); n > 0 {
		e.PrevHash = l.entries[n-1].Hash
	}
	e.Hash = hashEntry(e)
	l.entries = append(l.entries, e)
	return cloneEntry(e), nil
}

// Verify recomputes every hash and transition. It returns the first broken
// position so an operator can quarantine the suffix instead of the whole log.
func (l *Log) Verify() error {
	prev := ""
	for i, e := range l.entries {
		if e.Seq != int64(i)+1 {
			return fmt.Errorf("eventaudit: entry %d has sequence %d", i, e.Seq)
		}
		if e.PrevHash != prev {
			return fmt.Errorf("eventaudit: entry %d breaks the hash chain", i)
		}
		if hashEntry(e) != e.Hash {
			return fmt.Errorf("eventaudit: entry %d content does not match its hash", i)
		}
		if e.From == "" {
			if e.To != StateDraft {
				return fmt.Errorf("eventaudit: entry %d starts outside draft", i)
			}
		} else if e.From != e.To {
			if err := Transition(e.From, e.To); err != nil {
				return fmt.Errorf("eventaudit: entry %d: %w", i, err)
			}
		}
		prev = e.Hash
	}
	return nil
}

func hashEntry(e Entry) string {
	e.Hash = ""
	raw, err := json.Marshal(e)
	if err != nil {
		panic("eventaudit: marshal entry: " + err.Error())
	}
	sum := sha256.Sum256(raw)
	return hex.EncodeToString(sum[:])
}

func (l *Log) Entries() []Entry {
	out := make([]Entry, len(l.entries))
	for i, e := range l.entries {
		out[i] = cloneEntry(e)
	}
	return out
}

func cloneEntry(e Entry) Entry {
	e.Changes = append([]Change(nil), e.Changes...)
	return e
}