《游戏服务端编程实践》17.1 客户端资源热更流程

// file: ch17/manifest/manifest.go
// tier: L1
// verify: go test ./ch17/manifest/

// Package manifest 生成与校验资源版本清单，计算全量与差量更新集合。
package manifest

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

var (
	ErrInvalidVersion     = errors.New("manifest: invalid version")
	ErrEmptyPath          = errors.New("manifest: empty path")
	ErrHashMismatch       = errors.New("manifest: hash mismatch")
	ErrSizeMismatch       = errors.New("manifest: size mismatch")
	ErrMissingFile        = errors.New("manifest: missing file")
	ErrExtraFile          = errors.New("manifest: unexpected file")
	ErrMissingDownload    = errors.New("manifest: missing download")
	ErrUnexpectedDownload = errors.New("manifest: unexpected download")
	ErrDeltaMismatch      = errors.New("manifest: delta does not match manifests")
	ErrUnknownDep         = errors.New("manifest: unknown dependency")
	ErrInvalidManifest    = errors.New("manifest: invalid manifest")
)

// File 是清单中的一个文件条目，Path 必须与 Files 的键一致。
type File struct {
	Path string   `json:"path"`
	Hash string   `json:"hash"`
	Size int64    `json:"size"`
	Deps []string `json:"deps,omitempty"`
}

// Manifest 描述一个完整可用的资源版本。
type Manifest struct {
	Version int             `json:"version"`
	Files   map[string]File `json:"files"`
}

// Build 根据文件内容生成清单，哈希只使用文件字节。
func Build(version int, files map[string][]byte) (*Manifest, error) {
	if version < 1 {
		return nil, fmt.Errorf("%w: %d", ErrInvalidVersion, version)
	}
	m := &Manifest{Version: version, Files: make(map[string]File, len(files))}
	for path, data := range files {
		if path == "" {
			return nil, ErrEmptyPath
		}
		sum := sha256.Sum256(data)
		m.Files[path] = File{
			Path: path,
			Hash: hex.EncodeToString(sum[:]),
			Size: int64(len(data)),
		}
	}
	return m, nil
}

// SetDeps 记录依赖；依赖必须也在清单里，传入切片会被复制并排序。
func (m *Manifest) SetDeps(path string, deps ...string) error {
	if m == nil {
		return ErrInvalidManifest
	}
	f, ok := m.Files[path]
	if !ok {
		return fmt.Errorf("%w: %s", ErrMissingFile, path)
	}
	if len(deps) == 0 {
		return nil
	}
	sorted := append([]string(nil), deps...)
	sort.Strings(sorted)
	for _, dep := range sorted {
		if _, ok := m.Files[dep]; !ok {
			return fmt.Errorf("%w: %s -> %s", ErrUnknownDep, path, dep)
		}
	}
	f.Deps = sorted
	m.Files[path] = f
	return nil
}

// Validate 校验文件内容；清单外的额外文件被忽略。
func (m *Manifest) Validate(files map[string][]byte) error {
	if m == nil || m.Version < 1 || m.Files == nil {
		return ErrInvalidManifest
	}
	for path, f := range m.Files {
		data, ok := files[path]
		if !ok {
			return fmt.Errorf("%w: %s", ErrMissingFile, path)
		}
		if int64(len(data)) != f.Size {
			return fmt.Errorf("%w: %s size=%d want=%d",
				ErrSizeMismatch, path, len(data), f.Size)
		}
		sum := sha256.Sum256(data)
		if hex.EncodeToString(sum[:]) != f.Hash {
			return fmt.Errorf("%w: %s", ErrHashMismatch, path)
		}
	}
	return nil
}

// ValidateExact 在 Validate 基础上拒绝清单外的文件。
func (m *Manifest) ValidateExact(files map[string][]byte) error {
	if err := m.Validate(files); err != nil {
		return err
	}
	for path := range files {
		if _, ok := m.Files[path]; !ok {
			return fmt.Errorf("%w: %s", ErrExtraFile, path)
		}
	}
	return nil
}

// Digest 返回清单规范化 JSON 的 SHA-256。
func (m *Manifest) Digest() (string, error) {
	if m == nil {
		return "", ErrInvalidManifest
	}
	data, err := json.Marshal(m)
	if err != nil {
		return "", fmt.Errorf("%w: %v", ErrInvalidManifest, err)
	}
	sum := sha256.Sum256(data)
	return hex.EncodeToString(sum[:]), nil
}

// Load 解析并做结构校验；JSON 编码会排序 map 键，摘要因此稳定。
func Load(data []byte) (*Manifest, error) {
	var m Manifest
	if err := json.Unmarshal(data, &m); err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidManifest, err)
	}
	if m.Version < 1 || m.Files == nil {
		return nil, ErrInvalidManifest
	}
	for path, f := range m.Files {
		if path == "" || f.Path != path || f.Size < 0 {
			return nil, fmt.Errorf("%w: entry=%q path=%q",
				ErrInvalidManifest, path, f.Path)
		}
		if len(f.Hash) != sha256.Size*2 {
			return nil, fmt.Errorf("%w: hash=%q", ErrInvalidManifest, f.Hash)
		}
		if _, err := hex.DecodeString(f.Hash); err != nil {
			return nil, fmt.Errorf("%w: hash=%q", ErrInvalidManifest, f.Hash)
		}
		for _, dep := range f.Deps {
			if _, ok := m.Files[dep]; !ok {
				return nil, fmt.Errorf("%w: %s -> %s", ErrUnknownDep, path, dep)
			}
		}
	}
	return &m, nil
}

// Delta 描述从 From 到 To 的变更；Downloads 只含字节变化的文件。
type Delta struct {
	From      int      `json:"from"`
	To        int      `json:"to"`
	Added     []string `json:"added,omitempty"`
	Changed   []string `json:"changed,omitempty"`
	Removed   []string `json:"removed,omitempty"`
	Downloads []string `json:"downloads,omitempty"`
	Bytes     int64    `json:"bytes"`
}

// Diff 计算差量；old 为 nil 表示全量更新，版本必须严格递增。
func Diff(old, new *Manifest) (Delta, error) {
	if new == nil || new.Version < 1 {
		return Delta{}, ErrInvalidManifest
	}
	d := Delta{To: new.Version}
	if old != nil {
		if old.Version < 1 {
			return Delta{}, ErrInvalidManifest
		}
		if new.Version <= old.Version {
			return Delta{}, fmt.Errorf("%w: from=%d to=%d",
				ErrDeltaMismatch, old.Version, new.Version)
		}
		d.From = old.Version
	}
	for path, nf := range new.Files {
		var of File
		ok := false
		if old != nil {
			of, ok = old.Files[path]
		}
		switch {
		case !ok:
			d.Added = append(d.Added, path)
			d.Downloads = append(d.Downloads, path)
			d.Bytes += nf.Size
		case of.Hash != nf.Hash || of.Size != nf.Size:
			d.Changed = append(d.Changed, path)
			d.Downloads = append(d.Downloads, path)
			d.Bytes += nf.Size
		case !equalStrings(of.Deps, nf.Deps):
			d.Changed = append(d.Changed, path)
		}
	}
	if old != nil {
		for path := range old.Files {
			if _, ok := new.Files[path]; !ok {
				d.Removed = append(d.Removed, path)
			}
		}
	}
	sort.Strings(d.Added)
	sort.Strings(d.Changed)
	sort.Strings(d.Removed)
	sort.Strings(d.Downloads)
	return d, nil
}

// Apply 应用差量，download 必须恰好覆盖 Downloads，最后用目标清单校验。
func (d Delta) Apply(base map[string][]byte, download map[string][]byte, target *Manifest) (map[string][]byte, error) {
	if target == nil || target.Version != d.To || target.Version < 1 {
		return nil, fmt.Errorf("%w: target=%v delta_to=%d",
			ErrDeltaMismatch, target, d.To)
	}
	out := make(map[string][]byte, len(target.Files))
	for path, data := range base {
		out[path] = data
	}
	for _, path := range d.Removed {
		delete(out, path)
	}
	needed := make(map[string]struct{}, len(d.Downloads))
	for _, path := range d.Downloads {
		data, ok := download[path]
		if !ok {
			return nil, fmt.Errorf("%w: %s", ErrMissingDownload, path)
		}
		needed[path] = struct{}{}
		out[path] = data
	}
	for path := range download {
		if _, ok := needed[path]; !ok {
			return nil, fmt.Errorf("%w: %s", ErrUnexpectedDownload, path)
		}
	}
	if err := target.Validate(out); err != nil {
		return nil, err
	}
	return out, nil
}

func equalStrings(a, b []string) bool {
	if len(a) != len(b) {
		return false
	}
	for i := range a {
		if a[i] != b[i] {
			return false
		}
	}
	return true
}

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