《MMO 服务器开发》3.3 协议版本与多版本兼容

+------+--------+--------+------+--------+--------+------+--------+--------+
| tag1 | len1   | value1 | tag2 | len2   | value2 | tag3 | len3   | value3 |
|  1B  |  2B BE |  N1 B  |  1B  |  2B BE |  N2 B  |  1B  |  2B BE |  N3 B  |
+------+--------+--------+------+--------+--------+------+--------+--------+

// file: internal/proto/version.go
// tier: L1
// verify: go test ./internal/proto/
package proto

import (
	"encoding/binary"
	"io"
)

// ProtocolVersion 是服务端当前实现的主协议版本。
const ProtocolVersion uint16 = 3

// VersionRange 是服务端能同时服务的主版本闭区间。
//
// 客户端版本只有落在 [Min, Max] 内才允许登录：太老解释不了新语义，太新会用到
// 服务端还不认识的字段。区间通常只往前放一个版本——老版本用一个发版周期就下线。
type VersionRange struct {
	Min uint16
	Max uint16
}

// ServerVersionRange 是 aegis 在《晨曦大陆》上线期对外声明的可服务区间。
var ServerVersionRange = VersionRange{Min: 1, Max: 3}

// LoginResp 是登录响应：无论接受与否都回带服务端可用版本区间。
type LoginResp struct {
	ServerVersion uint16
	MinVersion    uint16
	MaxVersion    uint16
	Accepted      bool
	Reason        string
}

// Negotiate 根据客户端上报的主版本号给出协商结果。
func Negotiate(clientVersion uint16) LoginResp {
	resp := LoginResp{
		ServerVersion: ProtocolVersion,
		MinVersion:    ServerVersionRange.Min,
		MaxVersion:    ServerVersionRange.Max,
	}
	switch {
	case clientVersion < ServerVersionRange.Min:
		resp.Reason = "client too old, please update"
	case clientVersion > ServerVersionRange.Max:
		resp.Reason = "client too new, server update required"
	default:
		resp.Accepted = true
	}
	return resp
}

// 载荷字段标签。标签是稳定契约：一旦分配就永不改变含义，删除字段只保留空位。
const (
	fieldName  uint8 = 1
	fieldLevel uint8 = 2
	fieldGuild uint8 = 3 // v2 新增
	fieldTitle uint8 = 4 // v2 新增
)

// FieldReader 按「标签 | 长度 | 值」逐字段读取载荷。
//
// 这是向后兼容的关键：解码器只关心认识的标签，遇到不认识的，Next 会把它的长度
// 读出来并整段跳过——新客户端多发的字段不会把老服务端读崩。
type FieldReader struct {
	buf []byte
	off int
}

// NewFieldReader 包装一段载荷。
func NewFieldReader(b []byte) *FieldReader { return &FieldReader{buf: b} }

// Next 返回下一个字段的标签与值。流正常结束返回 ok=false、err=nil；
// 中途截断返回 io.ErrUnexpectedEOF。
func (r *FieldReader) Next() (tag uint8, val []byte, ok bool, err error) {
	if r.off >= len(r.buf) {
		return 0, nil, false, nil
	}
	if r.off+3 > len(r.buf) {
		return 0, nil, false, io.ErrUnexpectedEOF
	}
	tag = r.buf[r.off]
	l := int(binary.BigEndian.Uint16(r.buf[r.off+1 : r.off+3]))
	r.off += 3
	if r.off+l > len(r.buf) {
		return 0, nil, false, io.ErrUnexpectedEOF
	}
	val = r.buf[r.off : r.off+l]
	r.off += l
	return tag, val, true, nil
}

// FieldWriter 按同样的「标签 | 长度 | 值」格式拼载荷。
type FieldWriter struct{ buf []byte }

// NewFieldWriter 预分配 cap 字节。
func NewFieldWriter(cap int) *FieldWriter { return &FieldWriter{buf: make([]byte, 0, cap)} }

// PutBytes 写入一个字节串字段。
func (w *FieldWriter) PutBytes(tag uint8, v []byte) {
	w.buf = append(w.buf, tag)
	w.buf = binary.BigEndian.AppendUint16(w.buf, uint16(len(v)))
	w.buf = append(w.buf, v...)
}

// PutString 写入一个字符串字段。
func (w *FieldWriter) PutString(tag uint8, v string) { w.PutBytes(tag, []byte(v)) }

// PutUint32 写入一个 32 位整数字段。
func (w *FieldWriter) PutUint32(tag uint8, v uint32) {
	var tmp [4]byte
	binary.BigEndian.PutUint32(tmp[:], v)
	w.PutBytes(tag, tmp[:])
}

// Bytes 返回拼好的载荷。
func (w *FieldWriter) Bytes() []byte { return w.buf }

// PlayerProfile 是 v2 的完整语义。
type PlayerProfile struct {
	Name  string
	Level uint32
	Guild string // v2 新增：老客户端不发，默认空串
	Title string // v2 新增
}

// DecodePlayerProfileV2 用 v2 的语义解码任意版本的载荷：认识的字段取值，不认识的
// 字段跳过，载荷里没出现的字段保持零值——于是老格式会被解成带默认值的新结构。
func DecodePlayerProfileV2(payload []byte) (PlayerProfile, error) {
	var p PlayerProfile
	r := NewFieldReader(payload)
	for {
		tag, val, ok, err := r.Next()
		if err != nil {
			return p, err
		}
		if !ok {
			break
		}
		switch tag {
		case fieldName:
			p.Name = string(val)
		case fieldLevel:
			if len(val) != 4 {
				return p, ErrShortFrame
			}
			p.Level = binary.BigEndian.Uint32(val)
		case fieldGuild:
			p.Guild = string(val)
		case fieldTitle:
			p.Title = string(val)
		default: // 未知标签：Next 已消费，无需处理。
		}
	}
	return p, nil
}

// DecodePlayerProfileV1 是「只懂 v1」的老解码器：只认识 name 与 level，
// 对 v2 新增的 guild/title 一律走 default 跳过。
func DecodePlayerProfileV1(payload []byte) (PlayerProfile, error) {
	var p PlayerProfile
	r := NewFieldReader(payload)
	for {
		tag, val, ok, err := r.Next()
		if err != nil {
			return p, err
		}
		if !ok {
			break
		}
		switch tag {
		case fieldName:
			p.Name = string(val)
		case fieldLevel:
			if len(val) != 4 {
				return p, ErrShortFrame
			}
			p.Level = binary.BigEndian.Uint32(val)
		default: // 含 v2 的 guild/title，直接跳过。
		}
	}
	return p, nil
}

// file: internal/proto/version_test.go
// tier: L1
// verify: go test ./internal/proto/
package proto

import (
	"io"
	"testing"
)

func TestNegotiate(t *testing.T) {
	for _, c := range []struct {
		client   uint16
		accepted bool
	}{{0, false}, {1, true}, {2, true}, {3, true}, {4, false}} {
		got := Negotiate(c.client)
		if got.Accepted != c.accepted {
			t.Fatalf("client=%d accepted=%v，期望 %v", c.client, got.Accepted, c.accepted)
		}
		// 无论接受与否都回带服务端区间与自身版本。
		if got.ServerVersion != ProtocolVersion || got.MinVersion != ServerVersionRange.Min || got.MaxVersion != ServerVersionRange.Max {
			t.Fatalf("client=%d 缺区间信息：%+v", c.client, got)
		}
	}
	if Negotiate(0).Reason == "" || Negotiate(4).Reason == "" {
		t.Fatal("拒绝登录必须给出原因")
	}
}

func TestOldClientNewServer(t *testing.T) {
	// 老客户端（v1）只发 name 与 level。
	w := NewFieldWriter(64)
	w.PutString(fieldName, "晨曦小骑士")
	w.PutUint32(fieldLevel, 42)

	got, err := DecodePlayerProfileV2(w.Bytes())
	if err != nil {
		t.Fatalf("新服务端解码老格式：%v", err)
	}
	if got.Name != "晨曦小骑士" || got.Level != 42 {
		t.Fatalf("老格式语义解错：%+v", got)
	}
	if got.Guild != "" || got.Title != "" {
		t.Fatalf("新字段应填默认值，得到 %+v", got)
	}
}

func TestNewClientOldServer(t *testing.T) {
	// 新客户端（v2）多发 guild 与 title。
	w := NewFieldWriter(128)
	w.PutString(fieldName, "晨曦小骑士")
	w.PutUint32(fieldLevel, 42)
	w.PutString(fieldGuild, "破晓")
	w.PutString(fieldTitle, "屠龙者")

	got, err := DecodePlayerProfileV1(w.Bytes())
	if err != nil {
		t.Fatalf("老解码器解码新格式：%v", err)
	}
	if got.Name != "晨曦小骑士" || got.Level != 42 {
		t.Fatalf("老解码器应能读出认识的字段：%+v", got)
	}
	if got.Guild != "" || got.Title != "" {
		t.Fatalf("老解码器不该解出未知字段：%+v", got)
	}
}

func TestUnknownFieldSkipped(t *testing.T) {
	// 未知标签 99 插在已知字段中间，验证跳过时偏移不带歪。
	w := NewFieldWriter(128)
	w.PutString(fieldName, "Nova")
	w.PutUint32(99, 0xDEADBEEF)
	w.PutUint32(fieldLevel, 7)
	w.PutString(fieldName, "")

	got, err := DecodePlayerProfileV2(w.Bytes())
	if err != nil || got.Name != "" || got.Level != 7 {
		t.Fatalf("未知标签跳过后偏移错位：%+v err=%v", got, err)
	}
}

func TestFieldReaderTruncated(t *testing.T) {
	// 声明长度 10 但只给 3 字节值。
	bad := []byte{fieldName, 0x00, 0x0A, 'a', 'b', 'c'}
	if _, _, _, err := NewFieldReader(bad).Next(); err != io.ErrUnexpectedEOF {
		t.Fatalf("截断字段应返回 io.ErrUnexpectedEOF，得到 %v", err)
	}
}