wkproto

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 30, 2025 License: Apache-2.0 Imports: 8 Imported by: 0

README

WKProto（WuKongIM Protocol）

1. 概述

WuKongIM Protocol（WKProto）是一套基于TCP的二进制协议，用于客户端与服务端之间的通信。WKProto的设计目标是简单、高效、易扩展。

2. 使用

go get github.com/WuKongIM/WuKongIMGoProto

import  (
    wkproto "github.com/WuKongIM/WuKongIMGoProto"
    ...
)

3. 协议格式

协议文档

Documentation

Index

Constants

View Source 
const (
	// APP APP
	APP DeviceFlag = iota
	// WEB WEB
	WEB = 1
	// PC PC
	PC = 2
	// SYSTEM 系统
	SYSTEM = 99
)
View Source 
const (
	SettingByteSize         = 1 // setting固定大小
	StringFixLenByteSize    = 2 // 字符串可变大小
	ClientSeqByteSize       = 4 // clientSeq的大小
	ChannelTypeByteSize     = 1 // channelType的大小
	VersionByteSize         = 1 // version的大小
	DeviceFlagByteSize      = 1
	ClientTimestampByteSize = 8
	TimeDiffByteSize        = 8
	ReasonCodeByteSize      = 1
	MessageIDByteSize       = 8
	MessageSeqByteSize      = 4
	TimestampByteSize       = 4
	BigTimestampByteSize    = 8
	ActionByteSize          = 1
	StreamIdByteSize        = 8
	StreamFlagByteSize      = 1
	ExpireByteSize          = 4
	NodeIdByteSize          = 8
	ChunkIDByteSize         = 8
	EndReasonByteSize       = 1
)
View Source 
const (
	// ChannelTypePerson 个人频道
	ChannelTypePerson uint8 = 1
	// ChannelTypeGroup 群频道
	ChannelTypeGroup           uint8 = 2  // 群组频道
	ChannelTypeCustomerService uint8 = 3  // 客服频道
	ChannelTypeCommunity       uint8 = 4  // 社区频道
	ChannelTypeCommunityTopic  uint8 = 5  // 社区话题频道
	ChannelTypeInfo            uint8 = 6  // 资讯频道（有临时订阅者的概念，查看资讯的时候加入临时订阅，退出资讯的时候退出临时订阅）
	ChannelTypeData            uint8 = 7  // 数据频道
	ChannelTypeTemp            uint8 = 8  // 临时频道
	ChannelTypeLive            uint8 = 9  // 直播频道(直播频道不会保存最近会话数据)
	ChannelTypeVisitors        uint8 = 10 // 访客频道 (频道id即为访客id，此频道只支持一个访客订阅者，多个客服订阅者，ChannelTypeCustomerService频道已过时，使用ChannelTypeVisitors代替)
	ChannelTypeAgent           uint8 = 11 // 单聊Agent频道（AI Agent频道，频道ID内部结构为UID@AgentID的结构，类似单聊频道，此频道会针对于AI Agent场景做优化）
	ChannelTypeAgentGroup      uint8 = 12 // 群聊Agent频道（AI Agent群聊频道，类似群聊频道，此频道会针对于多Agent协同场景做优化）

)
View Source 
const LatestVersion = 5

LatestVersion 最新版本

View Source 
const MaxRemaingLength uint32 = 1024 * 1024

MaxRemaingLength 最大剩余长度 // 1<<28 - 1

View Source 
const PayloadMaxSize = math.MaxInt16

PayloadMaxSize 最大负载大小

Variables

This section is empty.

Functions

func ToFixHeaderUint8 

func ToFixHeaderUint8(f Frame) uint8

ToFixHeaderUint8 ToFixHeaderUint8

func WriteBinary 

func WriteBinary(b []byte, w io.Writer) error

WriteBinary WriteBinary

func WriteInt16 

func WriteInt16(i int, w io.Writer) error

WriteInt16 WriteInt16

func WriteUint32 

func WriteUint32(v uint32, w io.Writer) error

WriteUint32 WriteUint32

Types

type Action 

type Action uint8
const (
	Subscribe   Action = iota // 订阅
	UnSubscribe               // 取消订阅
)

func (Action) Uint8 

func (a Action) Uint8() uint8

type Channel 

type Channel struct {
	ChannelID   string `json:"channel_id"`
	ChannelType uint8  `json:"channel_type"`
}

type ConnackPacket 

type ConnackPacket struct {
	Framer
	ServerVersion uint8      // 服务端版本
	ServerKey     string     // 服务端的DH公钥
	Salt          string     // salt
	TimeDiff      int64      // 客户端时间与服务器的差值，单位毫秒。
	ReasonCode    ReasonCode // 原因码
	NodeId        uint64     // 节点Id
}

ConnackPacket 连接回执包

func (ConnackPacket) GetFrameType 

func (c ConnackPacket) GetFrameType() FrameType

GetFrameType 获取包类型

func (ConnackPacket) String 

func (c ConnackPacket) String() string

type ConnectPacket 

type ConnectPacket struct {
	Framer
	Version         uint8      // 协议版本
	ClientKey       string     // 客户端公钥
	DeviceID        string     // 设备ID
	DeviceFlag      DeviceFlag // 设备标示(同标示同账号互踢)
	ClientTimestamp int64      // 客户端当前时间戳(13位时间戳,到毫秒)
	UID             string     // 用户ID
	Token           string     // token
}

ConnectPacket 连接包

func (ConnectPacket) GetFrameType 

func (c ConnectPacket) GetFrameType() FrameType

GetFrameType 包类型

func (ConnectPacket) String 

func (c ConnectPacket) String() string

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder 解码

func NewDecoder 

func NewDecoder(p []byte) *Decoder

NewDecoder NewDecoder

func (*Decoder) Binary 

func (d *Decoder) Binary() ([]byte, error)

Binary Binary

func (*Decoder) BinaryAll 

func (d *Decoder) BinaryAll() ([]byte, error)

BinaryAll BinaryAll

func (*Decoder) Bytes 

func (d *Decoder) Bytes(num int) ([]byte, error)

Bytes Bytes

func (*Decoder) Int16 

func (d *Decoder) Int16() (int16, error)

Int16 Int16

func (*Decoder) Int32 

func (d *Decoder) Int32() (int32, error)

Int32 Int32

func (*Decoder) Int64 

func (d *Decoder) Int64() (int64, error)

Int64 Int64

func (*Decoder) Len 

func (d *Decoder) Len() int

Len 长度

func (*Decoder) String 

func (d *Decoder) String() (string, error)

func (*Decoder) StringAll 

func (d *Decoder) StringAll() (string, error)

StringAll StringAll

func (*Decoder) Uint8 

func (d *Decoder) Uint8() (uint8, error)

Uint8 Uint8

func (*Decoder) Uint16 

func (d *Decoder) Uint16() (uint16, error)

Uint16 Uint16

func (*Decoder) Uint32 

func (d *Decoder) Uint32() (uint32, error)

Uint32 Uint32

func (*Decoder) Uint64 

func (d *Decoder) Uint64() (uint64, error)

Uint64 Uint64

func (*Decoder) Variable 

func (d *Decoder) Variable() (uint64, error)

Variable Variable

type DeviceFlag 

type DeviceFlag uint8

DeviceFlag 设备类型

func (DeviceFlag) String 

func (r DeviceFlag) String() string

func (DeviceFlag) ToUint8 

func (r DeviceFlag) ToUint8() uint8

ToUint8 转换为uint8

type DeviceLevel 

type DeviceLevel uint8

DeviceLevel 设备等级 

const (
	// DeviceLevelSlave 从设备
	DeviceLevelSlave DeviceLevel = 0
	// DeviceLevelMaster 主设备
	DeviceLevelMaster DeviceLevel = 1
)

func (DeviceLevel) String 

func (r DeviceLevel) String() string

type DisconnectPacket 

type DisconnectPacket struct {
	Framer
	ReasonCode ReasonCode // 断开原因代号
	Reason     string     // 断开原因
}

DisconnectPacket 断开连接数据包

func (DisconnectPacket) GetFrameType 

func (c DisconnectPacket) GetFrameType() FrameType

GetFrameType 包类型

func (DisconnectPacket) String 

func (c DisconnectPacket) String() string

type EncodeOption 

type EncodeOption func(*EncodeOptions)

func EcodeWithCap 

func EcodeWithCap(cap int) EncodeOption

type EncodeOptions 

type EncodeOptions struct {
	Cap int
}

func NewEncodeOptions 

func NewEncodeOptions() *EncodeOptions

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder 编码者

func NewEncoder 

func NewEncoder() *Encoder

NewEncoder NewEncoder

func NewEncoderBuffer 

func NewEncoderBuffer(w Writer) *Encoder

func (*Encoder) Bytes 

func (e *Encoder) Bytes() []byte

Bytes Bytes

func (*Encoder) End 

func (e *Encoder) End()

func (*Encoder) Len 

func (e *Encoder) Len() int

Len Len

func (*Encoder) WriteBinary 

func (e *Encoder) WriteBinary(b []byte)

WriteBinary WriteBinary

func (*Encoder) WriteByte 

func (e *Encoder) WriteByte(b byte) error

WriteByte WriteByte

func (*Encoder) WriteBytes 

func (e *Encoder) WriteBytes(b []byte)

WriteBytes WriteBytes

func (*Encoder) WriteInt 

func (e *Encoder) WriteInt(i int) error

WriteInt WriteInt

func (*Encoder) WriteInt16 

func (e *Encoder) WriteInt16(i int)

WriteInt16 WriteInt16

func (*Encoder) WriteInt32 

func (e *Encoder) WriteInt32(i int32)

WriteInt32 WriteInt32

func (*Encoder) WriteInt64 

func (e *Encoder) WriteInt64(i int64)

WriteInt64 WriteInt64

func (*Encoder) WriteString 

func (e *Encoder) WriteString(str string)

WriteString WriteString

func (*Encoder) WriteStringAll 

func (e *Encoder) WriteStringAll(str string)

WriteStringAll WriteStringAll

func (*Encoder) WriteUint8 

func (e *Encoder) WriteUint8(i uint8)

WriteUint8 WriteUint8

func (*Encoder) WriteUint16 

func (e *Encoder) WriteUint16(i uint16)

WriteUint16 WriteUint16

func (*Encoder) WriteUint32 

func (e *Encoder) WriteUint32(i uint32)

WriteUint32 WriteUint32

func (*Encoder) WriteUint64 

func (e *Encoder) WriteUint64(i uint64)

WriteUint64 WriteUint64

func (*Encoder) WriteVariable 

func (e *Encoder) WriteVariable(v int)

WriteVariable WriteVariable

type EventPacket 

type EventPacket struct {
	Framer
	// 事件ID(可以为空)
	Id string
	// 事件类型
	Type string
	// 事件时间戳
	Timestamp int64
	// 事件数据
	Data []byte
}

func (*EventPacket) GetFrameType 

func (e *EventPacket) GetFrameType() FrameType

func (*EventPacket) Size 

func (e *EventPacket) Size() int

func (*EventPacket) String 

func (e *EventPacket) String() string

type Frame 

type Frame interface {
	GetFrameType() FrameType
	GetRemainingLength() uint32
	// GetPersist 是否存储
	GetNoPersist() bool
	// GetRedDot 是否显示红点
	GetRedDot() bool
	// GetsyncOnce 是否只被同步一次
	GetsyncOnce() bool
	// 是否是重发的消息
	GetDUP() bool
	GetFrameSize() int64       // 总个frame的大小（不参与编码解码）
	GetHasServerVersion() bool // 是否有服务端版本 connack包用到

	GetEnd() bool
}

Frame 接口

type FrameType 

type FrameType uint8
func SettingFromUint8(v uint8) Setting {
	s := Setting{}
	s.Receipt = (v >> 7 & 0x01) > 0
	return s
}

FrameType 包类型 

const (
	UNKNOWN    FrameType = iota // 保留位
	CONNECT                     // 客户端请求连接到服务器(c2s)
	CONNACK                     // 服务端收到连接请求后确认的报文(s2c)
	SEND                        // 发送消息(c2s)
	SENDACK                     // 收到消息确认的报文(s2c)
	RECV                        // 收取消息(s2c)
	RECVACK                     // 收取消息确认(c2s)
	PING                        //ping请求
	PONG                        // 对ping请求的相应
	DISCONNECT                  // 请求断开连接
	SUB                         // 订阅
	SUBACK                      // 订阅确认
	EVENT                       // 事件
)

包类型

func (FrameType) String 

func (p FrameType) String() string

type Framer 

type Framer struct {
	FrameType        FrameType
	RemainingLength  uint32 // 控制报文总长度等于固定报头的长度加上剩余长度
	NoPersist        bool   // 是否不持久化
	RedDot           bool   // 是否显示红点
	SyncOnce         bool   // 此消息只被同步或被消费一次
	DUP              bool   // 是否是重发消息
	HasServerVersion bool   // 是否有服务端版本 connack包用到
	End              bool   // 消息块：是否是最后一包
	FrameSize        int64
}

Framer 包的基础framer

func FramerFromUint8 

func FramerFromUint8(v uint8) Framer

FramerFromUint8 FramerFromUint8

func (Framer) GetDUP 

func (f Framer) GetDUP() bool

GetDUP 是否是重发消息

func (Framer) GetEnd 

func (f Framer) GetEnd() bool

func (Framer) GetFrameSize 

func (f Framer) GetFrameSize() int64

func (Framer) GetFrameType 

func (f Framer) GetFrameType() FrameType

GetFrameType GetFrameType

func (Framer) GetHasServerVersion 

func (f Framer) GetHasServerVersion() bool

func (Framer) GetNoPersist 

func (f Framer) GetNoPersist() bool

GetNoPersist 是否不持久化

func (Framer) GetRedDot 

func (f Framer) GetRedDot() bool

GetRedDot 是否显示红点

func (Framer) GetRemainingLength 

func (f Framer) GetRemainingLength() uint32

GetRemainingLength 包剩余长度

func (Framer) GetsyncOnce 

func (f Framer) GetsyncOnce() bool

GetsyncOnce 是否只被同步一次

func (Framer) String 

func (f Framer) String() string

type PacketDecodeFunc 

type PacketDecodeFunc func(frame Frame, remainingBytes []byte, version uint8) (Frame, error)

PacketDecodeFunc 包解码函数

type PacketEncodeFunc 

type PacketEncodeFunc func(frame Frame, version uint8) ([]byte, error)

PacketEncodeFunc 包编码函数

type PingPacket 

type PingPacket struct {
	Framer
}

PingPacket ping包

func (*PingPacket) GetFrameType 

func (p *PingPacket) GetFrameType() FrameType

GetFrameType 包类型

type PongPacket 

type PongPacket struct {
	Framer
}

PongPacket pong包对ping的回应

func (*PongPacket) GetFrameType 

func (p *PongPacket) GetFrameType() FrameType

GetFrameType 包类型

type Protocol 

type Protocol interface {
	// DecodeFrame 解码消息 返回frame 和 数据大小 和 error
	DecodeFrame(data []byte, version uint8) (Frame, int, error)
	// EncodeFrame 编码消息
	EncodeFrame(packet Frame, version uint8) ([]byte, error)

	// WriteFrame 编码报文，并写入writer
	WriteFrame(w Writer, packet Frame, version uint8) error
}

Protocol Protocol

type ReasonCode 

type ReasonCode uint8

ReasonCode 原因码 

const (
	// ReasonUnknown 未知错误
	ReasonUnknown ReasonCode = iota
	// ReasonSuccess 成功
	ReasonSuccess
	// ReasonAuthFail 认证失败
	ReasonAuthFail
	// ReasonSubscriberNotExist 订阅者在频道内不存在
	ReasonSubscriberNotExist
	// ReasonInBlacklist 在黑名单列表里
	ReasonInBlacklist
	// ReasonChannelNotExist 频道不存在
	ReasonChannelNotExist
	// ReasonUserNotOnNode 用户没在节点上
	ReasonUserNotOnNode
	// ReasonSenderOffline // 发送者离线了，这条消息将发不成功
	ReasonSenderOffline
	// ReasonMsgKeyError 消息key错误 说明消息不合法
	ReasonMsgKeyError
	// ReasonPayloadDecodeError payload解码失败
	ReasonPayloadDecodeError
	// ReasonForwardSendPacketError 转发发送包失败
	ReasonForwardSendPacketError
	// ReasonNotAllowSend 不允许发送消息
	ReasonNotAllowSend
	// ReasonConnectKick 连接被踢
	ReasonConnectKick
	// ReasonNotInWhitelist 没在白名单内
	ReasonNotInWhitelist
	// 查询用户token错误
	ReasonQueryTokenError
	// 系统错误
	ReasonSystemError
	// 错误的频道ID
	ReasonChannelIDError
	// ReasonNodeMatchError 节点匹配错误
	ReasonNodeMatchError
	// ReasonNodeNotMatch 节点不匹配
	ReasonNodeNotMatch
	ReasonBan                   // 频道被封禁
	ReasonNotSupportHeader      // 不支持的header
	ReasonClientKeyIsEmpty      // clientKey 是空的
	ReasonRateLimit             // 速率限制
	ReasonNotSupportChannelType // 不支持的频道类型
	ReasonDisband               // 频道已解散
	ReasonSendBan               // 发送被封禁
)

func (ReasonCode) Byte 

func (r ReasonCode) Byte() byte

Byte 转换为byte

func (ReasonCode) String 

func (r ReasonCode) String() string

type RecvPacket 

type RecvPacket struct {
	Framer
	Setting     Setting
	MsgKey      string // 用于验证此消息是否合法（仿中间人篡改）
	Expire      uint32 // 消息过期时间 0 表示永不过期
	MessageID   int64  // 服务端的消息ID(全局唯一)
	MessageSeq  uint32 // 消息序列号 （用户唯一，有序递增）
	ClientMsgNo string // 客户端唯一标示

	// 以下三个字段在5版本后不再支持
	StreamNo   string     // 流式编号
	StreamId   uint64     // 流式序列号
	StreamFlag StreamFlag // 流式标示

	Timestamp   int32  // 服务器消息时间戳(10位，到秒)
	ChannelID   string // 频道ID
	ChannelType uint8  // 频道类型
	Topic       string // 话题ID
	FromUID     string // 发送者UID
	Payload     []byte // 消息内容

	// ---------- 以下不参与编码 ------------
	ClientSeq uint64 // 客户端提供的序列号，在客户端内唯一
}

RecvPacket 收到消息的包

func (*RecvPacket) GetFrameType 

func (r *RecvPacket) GetFrameType() FrameType

GetPacketType 获得包类型

func (*RecvPacket) Reset 

func (r *RecvPacket) Reset()

func (*RecvPacket) Size 

func (r *RecvPacket) Size() int

func (*RecvPacket) SizeWithProtoVersion 

func (r *RecvPacket) SizeWithProtoVersion(protVersion uint8) int

func (*RecvPacket) String 

func (r *RecvPacket) String() string

func (*RecvPacket) VerityBytes 

func (r *RecvPacket) VerityBytes(buf *bytebufferpool.ByteBuffer)

func (*RecvPacket) VerityString 

func (r *RecvPacket) VerityString() string

type RecvackPacket 

type RecvackPacket struct {
	Framer
	MessageID  int64  // 服务端的消息ID(全局唯一)
	MessageSeq uint32 // 消息序列号
}

RecvackPacket 对收取包回执

func (*RecvackPacket) GetFrameType 

func (s *RecvackPacket) GetFrameType() FrameType

GetPacketType 包类型

func (*RecvackPacket) String 

func (s *RecvackPacket) String() string

type SendPacket 

type SendPacket struct {
	Framer
	Setting     Setting
	MsgKey      string // 用于验证此消息是否合法（仿中间人篡改）
	Expire      uint32 // 消息过期时间 0 表示永不过期
	ClientSeq   uint64 // 客户端提供的序列号，在客户端内唯一
	ClientMsgNo string // 客户端消息唯一编号一般是uuid，为了去重
	StreamNo    string // 流式编号
	ChannelID   string // 频道ID（如果是个人频道ChannelId为个人的UID）
	ChannelType uint8  // 频道类型（1.个人 2.群组）
	Topic       string // 消息topic
	Payload     []byte // 消息内容

}

SendPacket 发送包

func (*SendPacket) GetFrameType 

func (s *SendPacket) GetFrameType() FrameType

GetPacketType 包类型

func (*SendPacket) String 

func (s *SendPacket) String() string

func (*SendPacket) UniqueKey 

func (s *SendPacket) UniqueKey() string

func (*SendPacket) VerityString 

func (s *SendPacket) VerityString() string

VerityString 验证字符串

type SendackPacket 

type SendackPacket struct {
	Framer
	MessageID   int64      // 消息ID（全局唯一）
	MessageSeq  uint32     // 消息序列号（用户唯一，有序）
	ClientSeq   uint64     // 客户端序列号 (客户端提供，服务端原样返回)
	ClientMsgNo string     // 客户端消息编号(目前只有mos协议有效)
	ReasonCode  ReasonCode // 原因代码
}

SendackPacket 发送回执包

func (*SendackPacket) GetFrameType 

func (s *SendackPacket) GetFrameType() FrameType

GetPacketType 包类型

func (*SendackPacket) String 

func (s *SendackPacket) String() string

type Setting 

type Setting uint8
const (
	SettingUnknown        Setting = 0
	SettingReceiptEnabled Setting = 1 << 7 // 是否开启回执
	SettingSignal         Setting = 1 << 5 // 是否开启signal加密
	SettingNoEncrypt      Setting = 1 << 4 // 是否不加密
	SettingTopic          Setting = 1 << 3 // 是否有topic
	SettingStream         Setting = 1 << 1 // 是否开启流

)

func (*Setting) Clear 

func (s *Setting) Clear(v Setting)

func (Setting) IsSet 

func (s Setting) IsSet(v Setting) bool

func (*Setting) Set 

func (s *Setting) Set(v Setting) Setting

func (Setting) Uint8 

func (s Setting) Uint8() uint8

type StreamFlag 

type StreamFlag uint8
const (
	StreamFlagStart StreamFlag = 0 // 开始
	StreamFlagIng   StreamFlag = 1 // 进行中
	StreamFlagEnd   StreamFlag = 2 // 结束
)

type SubPacket 

type SubPacket struct {
	Framer
	Setting     Setting
	SubNo       string
	ChannelID   string // 频道ID（如果是个人频道ChannelId为个人的UID）
	ChannelType uint8  // 频道类型
	Action      Action // 动作
	Param       string // 参数
}

func (*SubPacket) GetFrameType 

func (s *SubPacket) GetFrameType() FrameType

GetPacketType 包类型

type SubackPacket 

type SubackPacket struct {
	Framer
	SubNo       string     // 订阅编号
	ChannelID   string     // 频道ID（如果是个人频道ChannelId为个人的UID）
	ChannelType uint8      // 频道类型
	Action      Action     // 动作
	ReasonCode  ReasonCode // 原因码
}

func (*SubackPacket) GetFrameType 

func (s *SubackPacket) GetFrameType() FrameType

GetPacketType 包类型

type WKProto 

type WKProto struct {
	sync.RWMutex
}

WKroto 悟空IM协议对象

func New 

func New() *WKProto

New 创建wukong协议对象

func (*WKProto) DecodeFrame 

func (l *WKProto) DecodeFrame(data []byte, version uint8) (Frame, int, error)

DecodePacket 解码包

func (*WKProto) DecodePacketWithConn 

func (l *WKProto) DecodePacketWithConn(conn io.Reader, version uint8) (Frame, error)

DecodePacketWithConn 解码包

func (*WKProto) EncodeFrame 

func (l *WKProto) EncodeFrame(frame Frame, version uint8) ([]byte, error)

EncodePacket 编码包

func (*WKProto) WriteFrame 

func (l *WKProto) WriteFrame(w Writer, packet Frame, version uint8) error

type Writer 

type Writer interface {
	io.Writer
	io.ByteWriter
	io.WriterTo
	Bytes() []byte
	Len() int
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.