Pomelo 协议

##Pomelo协议

###背景 0.3版本之前的Pomelo采用json格式的文本作为客户端和服务器的通讯协议，方便协议定制和修改，但同时也带来了较多的通讯冗余数据。Pomelo在0.3版本，底层通讯提供了二进制版本通讯协议的支持，同时提供了route字典压缩和protobuf压缩，提高带宽利用率，以满足诸如移动环境的需求。同时上层接口仍保持json格式的接口，对0.3版本之前的代码不产生任何影响，也保留了开发的便利。

Pomelo的二进制协议包含两层编码：package和message。Message层主要实现route压缩和protobuf压缩，message层的编码结果将传递给package层。Package层主要实现Pomelo应用基于二进制协议的握手过程，心跳和数据传输编码，package层的编码结果可以通过tcp，websocket等协议以二进制数据的形式进行传输。Message层编码可选，也替换成其他二进制编码格式，都不影响package层编码和发送。

###Pomelo Package

Package协议主要用来封装在面向连接的二进制流的通讯协议（如：tcp）上的Pomelo数据包。Package分为控制包和数据包两种类型。前者用来实现Pomelo应用层面的控制流程，包括客户端和服务器的握手，心跳和服务器主动断开连接的通知等控制信息。后者则是用来在客户端和服务器之间传输应用数据。

####Package格式

Package分为header和body两部分。Header描述package包的类型和包的长度，body则是需要传输的数据内容。具体格式如下：

• type - package类型，1个byte，取值如下。
  • 0x01: 客户端到服务器的握手请求以及服务器到客户端的握手响应
  • 0x02: 客户端到服务器的握手ack
  • 0x03: 心跳包
  • 0x04: 数据包
  • 0x05: 服务器主动断开连接通知
• length - body内容长度，3个byte的大端整数。
• body - 二进制的传输内容。

各个package类型的具体描述和控制流程如下。

####握手

握手流程主要提供一个机会，让客户端和服务器在连接建立后，进行一些初始化的数据交换。交换的数据分为系统和用户两部分。系统部分为Pomelo框架所需信息，用户部分则是用户可以在具体应用中自定义的内容。

握手的内容为utf-8编码的json字符串（不压缩），通过body字段传输。

握手请求：

{
  'sys': {
    'version': '1.1.1'
  }, 
  'user': {
  	// any customized request data
  }
}

• sys.version - 客户端的版本号。与所连接的服务器的要求有关。有的服务器要求鉴别适用的客户端版本号，如果不提供该字段或版本号过低，则无法执行后续流程。

握手响应：

{
  'code': 200, 			// result code
  'sys': {
    'heartbeat': 3, 	// heartbeat interval in second
    'dict': {}, 		// route dictionary
    'protos': {}		// protobuf definition data
  }, 
  'user': {
  	// any customized response data
  }
}

• code - 握手响应的状态码。目前的取值：200代表成功，500为处理用户自定义握手流程时失败，501为客户端版本号不符合要求。
• sys.heartbeat - 心跳时间间隔，单位为秒。
• dict - route字段压缩的映射表
• protos - protobuf压缩的数据定义

握手的流程如下：

####心跳

心跳包的length字段为0，body为空。

心跳的流程如下：

####数据

数据包用来在客户端和服务器之间传输数据所用。数据包的body是由上层传下来的任意二进制数据，package层不会对body内容做任何处理。

####服务器主动断开

当服务器主动断开客户端连接时（如：踢掉某个在线玩家），会先向客户端发送一个控制消息，然后再断开连接。客户端可以通过这个消息来判断是否是服务器主动断开连接的。

###Pomelo Message

TODO