《MMO 服务器开发》16.1 协议 fuzz 与畸形包

// file: internal/proto/frame.go
// tier: L1
// verify: go test ./internal/proto/

// Package proto 定义 aegis 线上协议的固定头与长度前缀分帧（卷一共享约定）。
package proto

import (
	"encoding/binary"
	"errors"
	"io"
)

// HeaderSize 是固定头的字节数：length(4) + cmd(2) + seq(4) + flags(1)。
const HeaderSize = 11

// MaxPayload 是单个帧载荷的字节上限（1 MiB）。
//
// 长度字段来自网络，是不可信输入。没有上限时，一个声明「长度 = 4 GiB」的
// 畸形包就能让服务端按声明预分配巨量内存——这是最省事的 DoS。
const MaxPayload = 1 << 20

// 分帧错误。三者都是「拒绝这一帧」而不是「崩溃」：
// 解析器对任意字节序列都必须安全返回。
var (
	ErrShortFrame      = errors.New("proto: buffer shorter than fixed header")
	ErrBadLength       = errors.New("proto: length field below fixed overhead")
	ErrPayloadTooLarge = errors.New("proto: payload exceeds MaxPayload")
)

// Cmd 是 16 位命令号：高字节是模块号，低字节是模块内序号。
type Cmd uint16

// Flags 是 8 位标志位：方向位与载荷处理方式各占几位。
type Flags uint8

// Frame 是一条已经切干净的完整消息。
type Frame struct {
	Cmd     Cmd
	Seq     uint32
	Flags   Flags
	Payload []byte
}

// DecodeFrom 从 buf 头部解出一帧，返回帧与消耗的字节数。
//
// 数据不足一整帧时返回 io.ErrUnexpectedEOF 且消耗字节数为 0，调用方应保留
// 未消费的 buf 等下一次读取补齐，而不是丢弃它。
func DecodeFrom(buf []byte) (Frame, int, error) {
	if len(buf) < HeaderSize {
		return Frame{}, 0, ErrShortFrame
	}
	length := binary.BigEndian.Uint32(buf[0:4])
	if length < uint32(HeaderSize-4) {
		// length 比它必须覆盖的 cmd+seq+flags 还短，是畸形包。
		return Frame{}, 0, ErrBadLength
	}
	payloadLen := int(length) - (HeaderSize - 4)
	if payloadLen > MaxPayload {
		return Frame{}, 0, ErrPayloadTooLarge
	}
	total := HeaderSize + payloadLen
	if len(buf) < total {
		return Frame{}, 0, io.ErrUnexpectedEOF
	}
	payload := make([]byte, payloadLen)
	copy(payload, buf[HeaderSize:total])
	return Frame{
		Cmd:     Cmd(binary.BigEndian.Uint16(buf[4:6])),
		Seq:     binary.BigEndian.Uint32(buf[6:10]),
		Flags:   Flags(buf[10]),
		Payload: payload,
	}, total, nil
}

// file: internal/proto/fuzz_test.go
// tier: L1
// verify: go test -run=^$ -fuzz=FuzzDecodeFrom -fuzztime=5s ./internal/proto/

package proto

import (
	"bytes"
	"encoding/binary"
	"io"
	"testing"
)

// FuzzDecodeFrom 要求 DecodeFrom 对任意字节序列都不 panic、不无限分配。
// 断言只看成功路径的不变量：消耗字节数等于帧总长，且不超过输入长度。
func FuzzDecodeFrom(f *testing.F) {
	good := make([]byte, HeaderSize)
	binary.BigEndian.PutUint32(good[0:4], uint32(HeaderSize-4))
	f.Add(good)
	f.Add([]byte{})
	f.Add([]byte{0x00, 0x00, 0x00, 0x05}) // 截断的固定头
	f.Add([]byte{0xff, 0xff, 0xff, 0xff, 0x00, 0x01, 0, 0, 0, 0, 0x01})
	f.Add([]byte{0x00, 0x00, 0x00, 0x03, 0x00, 0x01, 0, 0, 0, 0, 0x20})
	f.Add(bytes.Repeat([]byte{0xff}, HeaderSize))

	f.Fuzz(func(t *testing.T, data []byte) {
		fr, n, err := DecodeFrom(data)
		if err != nil {
			return
		}
		if n != HeaderSize+len(fr.Payload) {
			t.Fatalf("consumed %d != frame size %d", n, HeaderSize+len(fr.Payload))
		}
		if n > len(data) {
			t.Fatalf("consumed %d > input %d", n, len(data))
		}
		if len(fr.Payload) > MaxPayload {
			t.Fatalf("payload %d > MaxPayload", len(fr.Payload))
		}
	})
}

// TestDecodeRejectsMalformed 用表格覆盖四类畸形包。
func TestDecodeRejectsMalformed(t *testing.T) {
	cases := []struct {
		name string
		in   []byte
		want error
	}{
		{"empty", nil, ErrShortFrame},
		{"truncated_header", make([]byte, 5), ErrShortFrame},
		{"length_below_overhead", []byte{0, 0, 0, 3, 0, 1, 0, 0, 0, 0, 0x20}, ErrBadLength},
		{"oversized", []byte{0xff, 0xff, 0xff, 0xff, 0, 1, 0, 0, 0, 0, 0}, ErrPayloadTooLarge},
		{"payload_not_arrived", []byte{0, 0, 0, 10, 0, 1, 0, 0, 0, 0, 0}, io.ErrUnexpectedEOF},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			if _, _, err := DecodeFrom(tc.in); err != tc.want {
				t.Fatalf("err = %v, want %v", err, tc.want)
			}
		})
	}
}

// TestDecodeFlagsAllCombinations 遍历 256 种 flags，确认解析器只透传、不 panic。
func TestDecodeFlagsAllCombinations(t *testing.T) {
	for fl := 0; fl < 256; fl++ {
		buf := make([]byte, HeaderSize)
		binary.BigEndian.PutUint32(buf[0:4], uint32(HeaderSize-4))
		buf[10] = byte(fl)
		fr, n, err := DecodeFrom(buf)
		if err != nil {
			t.Fatalf("flags=%#x: unexpected err %v", fl, err)
		}
		if n != HeaderSize || Flags(fl) != fr.Flags {
			t.Fatalf("flags=%#x: n=%d got=%#x", fl, n, fr.Flags)
		}
	}
}