《游戏服务端编程实践》16.1 GM 权限与命令系统

// file: ch16/gm/gm.go
// tier: L1
// verify: go test ./ch16/gm/

package gm

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

var (
	ErrUnknownCommand       = errors.New("gm: unknown command")
	ErrPermissionDenied     = errors.New("gm: permission denied")
	ErrConfirmationRequired = errors.New("gm: confirmation required")
	ErrInvalidArgument      = errors.New("gm: invalid argument")
)

type RiskLevel int

const (
	RiskLow RiskLevel = iota
	RiskMedium
	RiskHigh
)

type Principal struct {
	ID    string
	Roles []string
}

type Request struct {
	Operator *Principal
	Command  string
	Target   string
	Args     map[string]string
	Confirm  string
}

type Command struct {
	Name       string
	Permission string
	Risk       RiskLevel
	Required   []string
	Handler    func(Request) (string, error)
}

type AuditRecord struct {
	Seq       uint64
	At        time.Time
	Operator  string
	Command   string
	Target    string
	Args      map[string]string
	Confirmed bool
	Outcome   string
	Message   string
	PrevHash  string
	Hash      string
}

type Registry struct {
	mu       sync.RWMutex
	commands map[string]*Command
	grants   map[string]map[string]struct{}
	audit    []AuditRecord
	now      func() time.Time
}

func NewRegistry() *Registry { return NewRegistryWithClock(time.Now) }

func NewRegistryWithClock(now func() time.Time) *Registry {
	if now == nil {
		now = time.Now
	}
	return &Registry{
		commands: map[string]*Command{},
		grants:   map[string]map[string]struct{}{},
		now:      now,
	}
}

func (r *Registry) Register(cmd Command) error {
	if cmd.Name == "" || cmd.Permission == "" || cmd.Handler == nil {
		return fmt.Errorf("gm: invalid command %q", cmd.Name)
	}
	cmd.Required = append([]string(nil), cmd.Required...)
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, ok := r.commands[cmd.Name]; ok {
		return fmt.Errorf("gm: command %q already registered", cmd.Name)
	}
	r.commands[cmd.Name] = &cmd
	return nil
}

func (r *Registry) Grant(role string, perms ...string) {
	r.mu.Lock()
	defer r.mu.Unlock()
	set := r.grants[role]
	if set == nil {
		set = map[string]struct{}{}
		r.grants[role] = set
	}
	for _, perm := range perms {
		set[perm] = struct{}{}
	}
}

func ConfirmationToken(command, target string) string {
	sum := sha256.Sum256([]byte(command + "\x00" + target))
	return "confirm-" + hex.EncodeToString(sum[:8])
}

func (r *Registry) Execute(req Request) (string, error) {
	started := r.now()
	r.mu.RLock()
	cmd, known := r.commands[req.Command]
	allowed := known && req.Operator != nil
	if allowed {
		allowed = false
		for _, role := range req.Operator.Roles {
			if _, ok := r.grants[role][cmd.Permission]; ok {
				allowed = true
				break
			}
		}
	}
	r.mu.RUnlock()
	if !known {
		return r.finish(req, nil, started, "", ErrUnknownCommand)
	}
	if !allowed {
		return r.finish(req, cmd, started, "", ErrPermissionDenied)
	}
	for _, name := range cmd.Required {
		if strings.TrimSpace(req.Args[name]) == "" {
			return r.finish(req, cmd, started, "",
				fmt.Errorf("%w: missing %q", ErrInvalidArgument, name))
		}
	}
	if cmd.Risk >= RiskHigh && req.Confirm != ConfirmationToken(cmd.Name, req.Target) {
		return r.finish(req, cmd, started, "", ErrConfirmationRequired)
	}
	out, err := cmd.Handler(req)
	return r.finish(req, cmd, started, out, err)
}

func (r *Registry) finish(req Request, cmd *Command, at time.Time, output string, err error) (string, error) {
	rec := AuditRecord{
		At:      at,
		Command: req.Command,
		Target:  req.Target,
		Args:    cloneArgs(req.Args),
		Outcome: "ok",
		Message: output,
	}
	if req.Operator != nil {
		rec.Operator = req.Operator.ID
		rec.Confirmed = cmd != nil && cmd.Risk >= RiskHigh &&
			req.Confirm == ConfirmationToken(cmd.Name, req.Target)
	}
	if err != nil {
		rec.Outcome = "error"
		rec.Message = err.Error()
	}

	r.mu.Lock()
	rec.Seq = uint64(len(r.audit) + 1)
	if n := len(r.audit); n > 0 {
		rec.PrevHash = r.audit[n-1].Hash
	}
	rec.Hash = hashRecord(rec)
	r.audit = append(r.audit, rec)
	r.mu.Unlock()
	return output, err
}

func hashRecord(rec AuditRecord) string {
	rec.Hash = ""
	body, _ := json.Marshal(rec)
	sum := sha256.Sum256(body)
	return hex.EncodeToString(sum[:])
}

func (r *Registry) AuditLog() []AuditRecord {
	r.mu.RLock()
	defer r.mu.RUnlock()
	out := make([]AuditRecord, len(r.audit))
	for i, rec := range r.audit {
		rec.Args = cloneArgs(rec.Args)
		out[i] = rec
	}
	return out
}

func (r *Registry) AuditByOperator(id string) []AuditRecord {
	out := make([]AuditRecord, 0)
	for _, rec := range r.AuditLog() {
		if rec.Operator == id {
			out = append(out, rec)
		}
	}
	return out
}

func (r *Registry) VerifyAudit() error {
	r.mu.RLock()
	defer r.mu.RUnlock()
	prev := ""
	for i, rec := range r.audit {
		if rec.Seq != uint64(i+1) || rec.PrevHash != prev || rec.Hash != hashRecord(rec) {
			return fmt.Errorf("gm: audit chain broken at record %d", rec.Seq)
		}
		prev = rec.Hash
	}
	return nil
}

func cloneArgs(in map[string]string) map[string]string {
	out := make(map[string]string, len(in))
	for k, v := range in {
		out[k] = v
	}
	return out
}

cd .local/checks/gs-practice-lab
gofmt -l ch16/gm
go vet ./ch16/gm/
go test ./ch16/gm/ -count=1