《游戏服务端编程实践》3.4.2 通用消息封装结构

// file: ch03/wire/frame.go
// tier: L1
// verify: go test ./ch03/wire/

// Package wire defines the transport envelope for game messages. The envelope
// is deliberately small and self-describing; the body is an opaque payload
// that an IDL such as Protobuf can encode.
package wire

import (
	"encoding/binary"
	"errors"
	"fmt"
	"hash/crc32"
	"io"
)

const (
	// HeaderSize is fixed so a reader can buffer exactly one header first.
	HeaderSize = 20
	// Magic rejects random bytes and most desynchronised streams early.
	Magic = 0x4753 // "GS"
	// Version1 is the only version this lab accepts.
	Version1 = 1
	// MaxBody caps allocations triggered by an untrusted length field.
	MaxBody  = 1 << 20
	MaxFrame = HeaderSize + MaxBody

	FlagRequest  = 1 << 0
	FlagResponse = 1 << 1

	// Offsets inside the header. Reserved bytes 18..19 are included in the
	// checksum so a peer cannot silently repurpose them.
	offMagic    = 0
	offVersion  = 2
	offFlags    = 3
	offCmd      = 4
	offSeq      = 6
	offBodyLen  = 10
	offChecksum = 14
	offReserved = 18
)

var (
	ErrShortHeader = errors.New("wire: short header")
	ErrShortFrame  = errors.New("wire: short frame")
	ErrBadMagic    = errors.New("wire: bad magic")
	ErrBadVersion  = errors.New("wire: unknown version")
	ErrTooLarge    = errors.New("wire: body too large")
	ErrChecksum    = errors.New("wire: checksum mismatch")
)

// Frame is one application message after envelope decoding.
type Frame struct {
	Version uint8
	Flags   uint8
	Cmd     uint16
	Seq     uint32
	Body    []byte
}

// frameChecksum covers every header byte except the checksum field itself,
// followed by the body. Both sides must use the same byte ranges, otherwise
// valid frames fail only under load, when a field they thought was covered
// happens to differ.
func frameChecksum(hdr []byte, body []byte) uint32 {
	crc := crc32.ChecksumIEEE(hdr[:offChecksum])
	crc = crc32.Update(crc, crc32.IEEETable, hdr[offReserved:HeaderSize])
	return crc32.Update(crc, crc32.IEEETable, body)
}

// Encode serialises one frame, including its length prefix.
func Encode(f Frame) ([]byte, error) {
	if f.Version == 0 {
		f.Version = Version1
	}
	if f.Version != Version1 {
		return nil, fmt.Errorf("%w: %d", ErrBadVersion, f.Version)
	}
	if len(f.Body) > MaxBody {
		return nil, fmt.Errorf("%w: %d > %d", ErrTooLarge, len(f.Body), MaxBody)
	}
	buf := make([]byte, HeaderSize+len(f.Body))
	binary.BigEndian.PutUint16(buf[offMagic:], Magic)
	buf[offVersion] = f.Version
	buf[offFlags] = f.Flags
	binary.BigEndian.PutUint16(buf[offCmd:], f.Cmd)
	binary.BigEndian.PutUint32(buf[offSeq:], f.Seq)
	binary.BigEndian.PutUint32(buf[offBodyLen:], uint32(len(f.Body)))
	copy(buf[HeaderSize:], f.Body)
	binary.BigEndian.PutUint32(buf[offChecksum:], frameChecksum(buf[:HeaderSize], f.Body))
	return buf, nil
}

// inspectHeader validates everything that can be checked from the fixed
// header alone and returns the declared body length.
func inspectHeader(hdr []byte) (int, error) {
	if len(hdr) < HeaderSize {
		return 0, ErrShortHeader
	}
	if got := binary.BigEndian.Uint16(hdr[offMagic:]); got != Magic {
		return 0, fmt.Errorf("%w: 0x%04x", ErrBadMagic, got)
	}
	if v := hdr[offVersion]; v != Version1 {
		return 0, fmt.Errorf("%w: %d", ErrBadVersion, v)
	}
	bodyLen := binary.BigEndian.Uint32(hdr[offBodyLen:])
	if bodyLen > MaxBody {
		return 0, fmt.Errorf("%w: %d > %d", ErrTooLarge, bodyLen, MaxBody)
	}
	return int(bodyLen), nil
}

// TotalLen is what a buffering reader needs before it can decode the frame
// that starts with hdr.
func TotalLen(hdr []byte) (int, error) {
	bodyLen, err := inspectHeader(hdr)
	if err != nil {
		return 0, err
	}
	return HeaderSize + bodyLen, nil
}

// DecodeBytes parses the first frame in buf and reports how many bytes it
// consumed. It never consumes a partial frame: on ErrShortFrame the caller
// keeps the bytes and retries after reading more from the socket.
func DecodeBytes(buf []byte) (Frame, int, error) {
	bodyLen, err := inspectHeader(buf)
	if err != nil {
		return Frame{}, 0, err
	}
	total := HeaderSize + bodyLen
	if len(buf) < total {
		return Frame{}, 0, fmt.Errorf("%w: have %d need %d", ErrShortFrame, len(buf), total)
	}
	want := binary.BigEndian.Uint32(buf[offChecksum:])
	if got := frameChecksum(buf[:HeaderSize], buf[HeaderSize:total]); got != want {
		return Frame{}, 0, fmt.Errorf("%w: got 0x%08x want 0x%08x", ErrChecksum, got, want)
	}
	body := make([]byte, bodyLen)
	copy(body, buf[HeaderSize:total])
	return Frame{
		Version: buf[offVersion],
		Flags:   buf[offFlags],
		Cmd:     binary.BigEndian.Uint16(buf[offCmd:]),
		Seq:     binary.BigEndian.Uint32(buf[offSeq:]),
		Body:    body,
	}, total, nil
}

// Decode reads exactly one frame from a stream. A short read means the
// connection died mid-frame; callers that need to survive that should use
// DecodeBytes with their own buffer instead.
func Decode(r io.Reader) (Frame, error) {
	var hdr [HeaderSize]byte
	if _, err := io.ReadFull(r, hdr[:]); err != nil {
		if errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF) {
			return Frame{}, ErrShortHeader
		}
		return Frame{}, err
	}
	bodyLen, err := inspectHeader(hdr[:])
	if err != nil {
		return Frame{}, err
	}
	body := make([]byte, bodyLen)
	if _, err := io.ReadFull(r, body); err != nil {
		if errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF) {
			return Frame{}, ErrShortFrame
		}
		return Frame{}, err
	}
	want := binary.BigEndian.Uint32(hdr[offChecksum:])
	if got := frameChecksum(hdr[:], body); got != want {
		return Frame{}, fmt.Errorf("%w: got 0x%08x want 0x%08x", ErrChecksum, got, want)
	}
	return Frame{
		Version: hdr[offVersion],
		Flags:   hdr[offFlags],
		Cmd:     binary.BigEndian.Uint16(hdr[offCmd:]),
		Seq:     binary.BigEndian.Uint32(hdr[offSeq:]),
		Body:    body,
	}, nil
}

go test -race ./ch03/wire/