320 lines
7.3 KiB
Go
320 lines
7.3 KiB
Go
// Package netproto 网络协议 v1 编解码（网络协议.md §1–§3）。
|
||
//
|
||
// 帧格式：长度 u32（大端）| 消息ID u16 | 压缩标志 u8 | payload；
|
||
// 整数：定长大端 / 变长 varint（LEB128）；字符串：varint 长度 + UTF-8。
|
||
package netproto
|
||
|
||
import (
|
||
"encoding/binary"
|
||
"errors"
|
||
"fmt"
|
||
"math"
|
||
)
|
||
|
||
// 消息 ID（网络协议.md §3 消息目录）。
|
||
const (
|
||
MsgHandshake = 0x01 // C→S 握手
|
||
MsgLoginRequest = 0x02 // C→S 登录
|
||
MsgLoginResponse = 0x03 // S→C 登录结果
|
||
MsgChunkData = 0x04 // S→C 区块数据
|
||
MsgBlockChange = 0x05 // S→C 方块变更
|
||
MsgPlayerMove = 0x06 // C→S 玩家移动
|
||
MsgEntityMove = 0x07 // S→C 实体移动
|
||
MsgChatMessage = 0x09 // 双向 聊天
|
||
MsgInventorySync = 0x0A // 双向 背包
|
||
MsgHeartbeat = 0x0E // 双向 心跳
|
||
MsgDisconnect = 0x0F // 双向 断开
|
||
)
|
||
|
||
// 压缩标志（网络协议.md §1）。
|
||
const (
|
||
flagCompressed = 1 // payload 为 zstd 压缩块
|
||
)
|
||
|
||
// Frame 通用帧。
|
||
type Frame struct {
|
||
MsgID uint16
|
||
Flags uint8
|
||
Payload []byte
|
||
}
|
||
|
||
// MaxFrameSize 单帧上限 1 MiB（防御性，网络协议.md §1）。
|
||
const MaxFrameSize = 1 << 20
|
||
|
||
// ErrIncomplete 半包错误：数据不足以组成完整帧（调用方应等待更多数据）。
|
||
var ErrIncomplete = errors.New("netproto: 帧数据不完整")
|
||
|
||
// EncodeFrame 序列化一帧为字节流。
|
||
// 帧头 7 字节：长度 u32（= 消息ID 2 + 标志 1 + 载荷，不含长度字段本身）+ 消息ID u16 + 压缩标志 u8。
|
||
func EncodeFrame(f Frame) []byte {
|
||
out := make([]byte, 7+len(f.Payload))
|
||
binary.BigEndian.PutUint32(out[0:4], uint32(3+len(f.Payload)))
|
||
binary.BigEndian.PutUint16(out[4:6], f.MsgID)
|
||
out[6] = f.Flags
|
||
copy(out[7:], f.Payload)
|
||
return out
|
||
}
|
||
|
||
// DecodeFrame 从字节流解析一帧，返回帧与剩余字节。
|
||
// 数据不足时返回 ErrIncomplete（可用 errors.Is 判定半包，等待更多数据）。
|
||
func DecodeFrame(data []byte) (Frame, []byte, error) {
|
||
if len(data) < 4 {
|
||
return Frame{}, nil, fmt.Errorf("%w（帧头不足 %d 字节）", ErrIncomplete, len(data))
|
||
}
|
||
length := binary.BigEndian.Uint32(data[0:4])
|
||
if length > MaxFrameSize {
|
||
return Frame{}, nil, fmt.Errorf("netproto: 帧长度 %d 超上限", length)
|
||
}
|
||
if int(length)+4 > len(data) {
|
||
return Frame{}, nil, fmt.Errorf("%w（需 %d 字节，剩 %d）", ErrIncomplete, length+4, len(data))
|
||
}
|
||
f := Frame{
|
||
MsgID: binary.BigEndian.Uint16(data[4:6]),
|
||
Flags: data[6],
|
||
Payload: data[7 : 4+int(length)],
|
||
}
|
||
return f, data[4+int(length):], nil
|
||
}
|
||
|
||
// ---- 基础读写器（网络协议.md §2 序列化规则）----
|
||
|
||
// Writer 字节写入器。
|
||
type Writer struct{ B []byte }
|
||
|
||
// U8 写无符号 8 位。
|
||
func (w *Writer) U8(v uint8) { w.B = append(w.B, v) }
|
||
|
||
// U16 写无符号 16 位（大端）。
|
||
func (w *Writer) U16(v uint16) { w.B = binary.BigEndian.AppendUint16(w.B, v) }
|
||
|
||
// U32 写无符号 32 位（大端）。
|
||
func (w *Writer) U32(v uint32) { w.B = binary.BigEndian.AppendUint32(w.B, v) }
|
||
|
||
// I32 写有符号 32 位（大端）。
|
||
func (w *Writer) I32(v int32) { w.U32(uint32(v)) }
|
||
|
||
// F32 写 float32（位模式）。
|
||
func (w *Writer) F32(v float32) { w.U32(math.Float32bits(v)) }
|
||
|
||
// Varint 写变长整数（LEB128，无符号）。
|
||
func (w *Writer) Varint(v uint32) {
|
||
for v >= 0x80 {
|
||
w.B = append(w.B, byte(v)|0x80)
|
||
v >>= 7
|
||
}
|
||
w.B = append(w.B, byte(v))
|
||
}
|
||
|
||
// Str 写字符串（varint 长度 + UTF-8）。
|
||
func (w *Writer) Str(s string) {
|
||
w.Varint(uint32(len(s)))
|
||
w.B = append(w.B, s...)
|
||
}
|
||
|
||
// Bytes 写字节串（varint 长度 + 数据）。
|
||
func (w *Writer) Bytes(b []byte) {
|
||
w.Varint(uint32(len(b)))
|
||
w.B = append(w.B, b...)
|
||
}
|
||
|
||
// Reader 字节读取器。
|
||
type Reader struct {
|
||
B []byte
|
||
Off int
|
||
Err error
|
||
}
|
||
|
||
// NewReader 创建读取器。
|
||
func NewReader(b []byte) *Reader { return &Reader{B: b} }
|
||
|
||
// U8 读无符号 8 位。
|
||
func (r *Reader) U8() uint8 {
|
||
if r.Err != nil {
|
||
return 0
|
||
}
|
||
if r.Off+1 > len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: 读取越界")
|
||
return 0
|
||
}
|
||
v := r.B[r.Off]
|
||
r.Off++
|
||
return v
|
||
}
|
||
|
||
// U16 读无符号 16 位（大端）。
|
||
func (r *Reader) U16() uint16 {
|
||
if r.Err != nil {
|
||
return 0
|
||
}
|
||
if r.Off+2 > len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: 读取越界")
|
||
return 0
|
||
}
|
||
v := binary.BigEndian.Uint16(r.B[r.Off:])
|
||
r.Off += 2
|
||
return v
|
||
}
|
||
|
||
// U32 读无符号 32 位（大端）。
|
||
func (r *Reader) U32() uint32 {
|
||
if r.Err != nil {
|
||
return 0
|
||
}
|
||
if r.Off+4 > len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: 读取越界")
|
||
return 0
|
||
}
|
||
v := binary.BigEndian.Uint32(r.B[r.Off:])
|
||
r.Off += 4
|
||
return v
|
||
}
|
||
|
||
// I32 读有符号 32 位。
|
||
func (r *Reader) I32() int32 { return int32(r.U32()) }
|
||
|
||
// F32 读 float32。
|
||
func (r *Reader) F32() float32 { return math.Float32frombits(r.U32()) }
|
||
|
||
// Varint 读变长整数（LEB128）。
|
||
func (r *Reader) Varint() uint32 {
|
||
if r.Err != nil {
|
||
return 0
|
||
}
|
||
var v uint32
|
||
for shift := 0; shift < 35; shift += 7 {
|
||
if r.Off >= len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: varint 越界")
|
||
return 0
|
||
}
|
||
b := r.B[r.Off]
|
||
r.Off++
|
||
v |= uint32(b&0x7F) << shift
|
||
if b&0x80 == 0 {
|
||
return v
|
||
}
|
||
}
|
||
r.Err = fmt.Errorf("netproto: varint 超长")
|
||
return 0
|
||
}
|
||
|
||
// Str 读字符串（varint 长度 + UTF-8）。
|
||
func (r *Reader) Str() string {
|
||
n := r.Varint()
|
||
if r.Err != nil {
|
||
return ""
|
||
}
|
||
if n > MaxFrameSize || r.Off+int(n) > len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: 字符串越界（长度 %d）", n)
|
||
return ""
|
||
}
|
||
s := string(r.B[r.Off : r.Off+int(n)])
|
||
r.Off += int(n)
|
||
return s
|
||
}
|
||
|
||
// Bytes 读字节串。
|
||
func (r *Reader) Bytes() []byte {
|
||
n := r.Varint()
|
||
if r.Err != nil {
|
||
return nil
|
||
}
|
||
if n > MaxFrameSize || r.Off+int(n) > len(r.B) {
|
||
r.Err = fmt.Errorf("netproto: 字节串越界（长度 %d）", n)
|
||
return nil
|
||
}
|
||
b := r.B[r.Off : r.Off+int(n)]
|
||
r.Off += int(n)
|
||
return b
|
||
}
|
||
|
||
// ---- 常用消息载荷（网络协议.md §3）----
|
||
|
||
// BlockChange 方块变更（0x05）。
|
||
type BlockChange struct {
|
||
X, Y, Z int32
|
||
BlockID uint16
|
||
Meta uint8
|
||
}
|
||
|
||
// Encode 编码方块变更。
|
||
func (m BlockChange) Encode() []byte {
|
||
w := &Writer{}
|
||
w.I32(m.X)
|
||
w.I32(m.Y)
|
||
w.I32(m.Z)
|
||
w.U16(m.BlockID)
|
||
w.U8(m.Meta)
|
||
return w.B
|
||
}
|
||
|
||
// DecodeBlockChange 解码方块变更。
|
||
func DecodeBlockChange(b []byte) (BlockChange, error) {
|
||
r := NewReader(b)
|
||
m := BlockChange{
|
||
X: r.I32(),
|
||
Y: r.I32(),
|
||
Z: r.I32(),
|
||
BlockID: r.U16(),
|
||
Meta: r.U8(),
|
||
}
|
||
return m, r.Err
|
||
}
|
||
|
||
// PlayerMove 玩家移动（0x06，20Hz）。
|
||
type PlayerMove struct {
|
||
X, Y, Z float32
|
||
Yaw, Pitch float32
|
||
OnGround bool
|
||
}
|
||
|
||
// Encode 编码玩家移动。
|
||
func (m PlayerMove) Encode() []byte {
|
||
w := &Writer{}
|
||
w.F32(m.X)
|
||
w.F32(m.Y)
|
||
w.F32(m.Z)
|
||
w.F32(m.Yaw)
|
||
w.F32(m.Pitch)
|
||
if m.OnGround {
|
||
w.U8(1)
|
||
} else {
|
||
w.U8(0)
|
||
}
|
||
return w.B
|
||
}
|
||
|
||
// DecodePlayerMove 解码玩家移动。
|
||
func DecodePlayerMove(b []byte) (PlayerMove, error) {
|
||
r := NewReader(b)
|
||
m := PlayerMove{
|
||
X: r.F32(),
|
||
Y: r.F32(),
|
||
Z: r.F32(),
|
||
Yaw: r.F32(),
|
||
Pitch: r.F32(),
|
||
}
|
||
m.OnGround = r.U8() != 0
|
||
return m, r.Err
|
||
}
|
||
|
||
// Handshake 握手（0x01）。
|
||
type Handshake struct {
|
||
ProtocolVersion int
|
||
ClientID string
|
||
}
|
||
|
||
// Encode 编码握手。
|
||
func (m Handshake) Encode() []byte {
|
||
w := &Writer{}
|
||
w.Varint(uint32(m.ProtocolVersion))
|
||
w.Str(m.ClientID)
|
||
return w.B
|
||
}
|
||
|
||
// DecodeHandshake 解码握手。
|
||
func DecodeHandshake(b []byte) (Handshake, error) {
|
||
r := NewReader(b)
|
||
m := Handshake{ProtocolVersion: int(r.Varint()), ClientID: r.Str()}
|
||
return m, r.Err
|
||
}
|