README.md

Bee 数据传输协议

本协议提供了一种轻量级的数据传输协议，其应用场景主要有：

1. 要求协议数据模型本身支持脚本的传输
2. 要求协议数据响应能够进行异步处理
3. 要求协议简单并且易于程序实现

协议描述

在本协议中一个完整数据包由以下部分组成:

HEAD	CMD	LEN	DATA	CRC	END
2 bytes	1 byte	8 bytes	...	8 bytes	2 bytes

每个部分表示的含义如下:

• HEAD: 协议头, 固定为 0xFF 0xFF，长度为 2 bytes
• CMD: 数据包类型，长度为 1 bytes
• LEN: 数据包长度，表示 DATA 的长度，长度为 8 bytes, 可表示一个 64 b 数字
• DATA: 数据包内容
• CRC: 校验位，表示整个数据包的长度，长度为 8 bytes, 可表示一个 64 b 数字
• END: 结束位，表示整个数据包结束的标示，固定为 0x0D 0x0A，长度为 2 bytes

其中 CMD 与 DATA 对应的关系，请参考以下说明:

• 0x00: 请求连接
• 0x01: 连接应答
• 0x02: 请求采集
• 0x03: 采集应答

例如一个无数据包内容类型的请求数据包:

HEAD	CMD	LEN	DATA	CRC	END
0xFF 0xFF	0x04	0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x01	0x00	0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x16	0x0D 0x0A

通信过程

在本协议中完成一次的脚本的执行只需要以下两个步骤:

1. 请求连接 -> 连接应答
2. 请求采集 -> 采集应答

其中步骤 1 在建立连接之后就需要立即请求，请求成功之后服务器应保持该连接。

数据类型

本协议中只提供了基本的数据类型，目前不支持数组和键值对等复杂的数据结构，不过幸运的是，本协议中支持字节流的格式，你可以将不支持的数据类型序列化为字节流来进行传输。

在本协议中数据类型的基本格式为:

type	len	data
1 byte	--	--

其中 type 表示如下:

type	说明	len	data
0x00	空类型	无	无
0x01	字符串类型	4 bytes	最大 3GB 的字符串内容， 采用 UTF-8 的格式进行编码
0x02	有符号整型	无	最大 64 位的有符号整型
0x03	有符号浮点型	无	最大 64 位的有符号浮点型
0x04	bool 类型	无	0x01 or 0x00
0x05	字节流	4 bytes	最大 3GB 的字节流数据

除了 0x01 和 0x05 类型需要 len 位时，其他类型不需要该值。

例如字符串 Bee 可以表示为:

type	len	data
0x01	0x00 0x00 0x00 0x03	0x42 0x65 0x65

错误信息

本协议提供了固定的错误信息格式:

code	msg len	msg
4 bytes	1 byte	--

其中:

• code : 错误码，采用32位有符号整型
• msg len: 错误信息的长度，只能表示为 0~255 的数字
• msg: 错误信息的内容，只能表示为 0~255 个字符

例如有以下错误信息:

{
    "code": 1,
    "msg": "Failed!"
}

则数据格式为:

code	msg len	msg
0x00 0x00 0x00 0x01	0x07	0x46 0x61 0x69 0x6C 0x65 0x64 0x21

请求连接

请求连接数据包类型为: 0x00, 每次建立 TCP 连接之后应发送该数据包来进行认证操作。 请求连接时需要提供一下参数信息：

• url: 连接信息, 采用标准 URL格式
• application: 客户端名称

例如:

请求参数为:

{
    "url": "agent://127.0.0.1:6142",
    "application": "app1"
}

则数据格式为:

url type	url len	url	application type	application len	application
0x01	0x00 0x00 0x00 0x16	0x61 0x67 0x65 0x6E 0x74 0x3A 0x2F 0x2F 0x31 0x32 0x37 0x2E 0x30 0x2E 0x30 0x2E 0x31 0x3A 0x36 0x31 0x34 0x32	0x01	0x00 0x00 0x00 0x04	0x61 0x70 0x70 0x31

请参考数据类型 章节对数据内容的描述

连接应答

当发送请求连接数据包之后，服务端必须返回一个连接应答数据包，其类型为: 0x01

连接成功

当服务器返回该数据包时，客户端可以执行下一步的 请求采集 操作，且无须再次发送 请求连接 数据包。

例如:

type
0x00

连接失败

当服务器返回该数据包时，客户端需要主动关闭 TCP 连接，因为该连接已无效。

例如应答的错误信息为:

type	code	msg len	msg
0x01	0x00 0x00 0x00 0x01	0x07	0x46 0x61 0x69 0x6C 0x65 0x64 0x21

请参考错误信息 章节对数据内容的描述

请求采集

必须在客户端与服务器建立连接之后才能发送此数据包。请求采集数据包类型为: 0x02， 请求参数如下:

• id: 请求ID，32 位无符号整型
• script: 请求执行的脚本
• timeout: 执行超时时间(s)

例如:

请求参数为:

{
    "id": 1,
    "script": "SELECT *FROM m_test()",
    "timeout": 10
}

则数据格式为:

id type	id	script type	script len	script	timeout type	timeout
0x02	0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x01	0x01	0x00 0x00 0x00 0x15	0x53 0x45 0x4C 0x45 0x43 0x54 0x20 0x2A 0x46 0x52 0x4F 0x4D 0x20 0x6D 0x5F 0x74 0x65 0x73 0x74 0x28 0x29	0x02	0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x0A

请参考数据类型 章节对数据内容的描述

采集应答

采集应答数据包类型为: 0x03。

当 请求采集 执行成功时，服务端必须分为三个步骤应答信息:

1. 应答数据列的结构定义
2. 应答数据行的内容信息
3. 应答数据行的结束

客户端在收到以上应答信息之后，无须发送 ACK 来给服务端确认。

当 请求采集 执行失败时，服务端必须 应答错误信息。

应答数据列的结构定义

id	type	col size	col name len ...	col name ...	col type ...
4 bytes	0x00	1 byte	1 byte	...	1 byte

其中:

• id: 请求 ID，4 字节无符号整型
• type: 固定值 0x00, 表示应答的数据内容为列的结构定义
• col len: 列的大小，最多只支持 255 列, 从此处之后字节流都需要通过该值来迭代解码
• col name len ...: 表示列名字符串的长度，它决定了 col name ... 读取多少位来进行解码
• col type ...: 表示该列对应的类型值，请参考 数据类型 说明

比如请求 ID 为 1，并且应答的内容为:

String  : "Name",
Number  : "Age",
Integer : "Count",
Boolean : "IsNice",
Bytes   : "Image",
Nil     : "Phone"

则对应的数据内容为:

id	type	col size	col name len 1	col name 1	col type 1	col name len 2	col name 2	col type 2	col name len 3	col name 3	col type 3	col name len 4	col name 4	col type 4	col name len 5	col name 5	col type 5	col name len 6	col name 6	col type 6
0x00 0x00 0x00 0x01	0x00	0x06	0x04	Name	0x01	0x03	Age	0x03	0x05	Count	0x02	0x06	IsNice	0x04	0x05	Image	0x05	0x05	Phone	0x00

应答数据行的内容信息

id	type	col size	col type	col value
4 bytes	0x01	1 byte	1 byte	...

其中:

• id: 请求 ID，4 字节无符号整型
• type: 固定值 0x01, 表示应答的数据内容为数据行的信息
• col size: 列的大小，最多只支持 255 列, 从此处之后字节流都需要通过该值来迭代解码
• col type ...: 列值的类型
• col value ...: 列值的内容, 请参考 数据类型 说明

比如请求 ID 为 1，并且应答的内容为:

[10, 20.0, "Name", false, b"\x01\x02"]

则对应的数据内容为:

id	type	col size	col type 1	col value 1	col type 2	col value 2	col type 3	col len 3	col value 3	col type 4	col value 4	col type 5	col len 5	col value 5
0x00 0x00 0x00 0x01	0x01	0x05	0x02	0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x0A	0x03	0x40 0x34 0x00 0x00 0x00 0x00 0x00 0x00	0x01	0x00 0x00 0x00 0x04	0x4e 0x61 0x6d 0x65	0x04	0x00	0x05	0x00 0x00 0x00 0x02	0x01 0x02

应答数据行的结束

客户端收到该应答数据包时，应该告知业务数据处理完毕。

id	type
4 bytes	0x02

应答错误信息

客户端收到该应答数据包时，则服务端未内成功执行采集。

例如请求 ID 为 1, 应答的错误信息为:

{
    "code": 1,
    "msg": "Failed!"
}

则对应的数据内容为:

id	type	code	msg len	msg
0x00 0x00 0x00 0x01	0x03	0x00 0x00 0x00 0x01	0x07	0x46 0x61 0x69 0x6C 0x65 0x64 0x21

请参考错误信息 章节对数据内容的描述