easy_sock — Make socket use easier

快速开发基于tcp连接的二进制网络协议接口的nodejs模块

A fast way to create TCP socket API in nodejs

0.3.0 updated : easy_sock supports UDP now! See test_udp.js

easy_sock帮你快速开发基于tcp协议的接口，快速打通nodejs跟其他私有协议server的交互。让你做到像调用本地接口一样调用server api。

easy_sock helps you to build a reliable, friendly used socket Api, with any kinds of binary protocols.

easy_sock主要解决以下问题：

easy_sock helps you to solve the follow probrams:

处理socket发送、接收数据，以及数据包完整性校验 Take care of send/receive message, and check whether the package is complete
封装网络请求中各种复杂的异步调用以及中间过程，屏蔽tcp连接细节 Take care of asyn calls in socket use. You don't need to call "connect()" before use.
支持长连接、socket复用以及并发请求 Keep alive mode is available. Send multi request at the same time in a single socket.
自动管理连接状态，在合适的时候帮你断开连接或重新连接 Connect and close socket Automatically
各种异常处理 Call you when error occurs

什么场景下适合使用

如果你的网络协议符合以下特性，便可以使用easy_sock： In what circumstances can I use easy_sock:

基于tcp连接，通过二进制或文本协议封包 Base on tcp connect, binary or text protocols
符合一来一回的应答试请求 Send one request and get one response
支持通过请求序列号的方式来接收和返回并发请求包(大部分网络协议都支持，否则无法支持并发) The Server side support concurrent request, use sequence number to identify certain request

安装 Install

npm install easy_sock

使用简单，任性 Easy to use

下面通过一个基于easy_sock封装的cmem接口，来演示如何使用：（下面不翻译了，自己看代码吧）

var Cmem = require("cmem_core");
var client = new Cmem({
  ip:"127.0.0.1",
  port:9101,
	keepAlive : false
});

client.getData("key1",function(err, data){...});
client.getData("key2",function(err, data){...});
client.getData("key3",function(err, data){
  client.getData("key4",function(err, data){...});
});

这是一个短连接的例子(keepAlive=false)。可以看到，代码里没有connect、close等方法的调用，因为easy_sock已经帮你封装好了，会在第一次请求的时候建立连接，在没有任何请求后断开连接。注意到代码里面实际包含了并发请求和串行请求，不用担心会同时发起多个tcp connection，所有请求只会共享一个tcp连接。

注意到key4是在key3回调后才发起请求的，这时候有可能因为前三个请求已经返回而断开连接。遇到这种情况下，程序会再次发起一个新连接完成请求，然后断开。当keepAlive=true时，会使用长连接方式，这时候必须主动调用close()方法来断开连接。

三步完成接口开发

你只需要实现以下3个方法，便可完成任何一种tcp网络请求：

All you need to do is finish the following functions, then an Api is accomplish:

encode:将需要发送的数据按协议进行二进制编码
decode:将接收到的包进行解码，转换成js可操作的格式
isReceiveComplete:判断当前数据包是否完整

你可以通过C代码来实现这三个方法。任何类型的tcp协议，只要实现了这3个接口，剩下的事情都一样。这就是为什么easy_sock能存在的原因:)

You can make a gyp to do this. As a matter of fact, no matter what protocol it is, all works are the same except these three functions. That's why easy_sock is written.

简单例子

下面通过一个demo演示各接口的使用方法：

function createSocket(){
	var easysock = new EasySock();
	easysock.setConfig({
		ip : "127.0.0.1",
		port : 9101,	
		keepAlive : false,	
		timeout : 50	//0 by default
	});
	
	//check if the package is received complete
	easysock.isReceiveComplete = function(packet){		
		var len = 0;	
		//your code here..
		
		/* 
		* Check if the package is received complete. If not, return 0.
		* Otherwise return length of the FIRST complete package.
		* If the buffer contains more than one package--it usually happens when package size is small--, 
		* just return the size of first one(not total).
		*/
		return len;
	};
	
	//encode the data to binary 
	easysock.encode = function(data, seq){
		var packet = new Buffer(100);
		packet.writeInt32BE(seq, 0);
		//your code here..

		//Translate the "data"(usually is a json or string) into a Buffer, and return the Buffer
		return packet;		
	};
	
	//decode the buffer
	easysock.decode = function(packet){
		//The packet is a Buffer with a complete response. So decode the buffer to other type of data.
		var seq = packet.readInt32BE(0);
		//do sth else
			
		//must return the result and seq
		return {
			result : {},
			seq : seq
		};
		
	};
	return easysock;
}

var client = createSocket();

client.write({
		key : ""
	}, 
	function(err, data){
		if (err){
			//err is a string
			console.log("fail:" + err);
		}
		else{
			console.log("success");
			console.dir(data);
		}
	}
);