Server端参考手册

Notice: firstfragment, fragment, lastfragment三个事件已弃用, 请使用流式分片!
Notice: client.emitRaw()已弃用.
Notice: 新增了流式API

Server参考手册

Ok，下面进入正题。以下内容是fslider_ws提供的全部功能、详细配置参数以及全部系统级事件。

• wsf对象
  • wsf.listen方法 @httpServer，[@callback]
    绑定fslider_ws的核心逻辑到一个http.Server实例，同时（全局模式）监听它的upgrade事件。
  • wsf.close方法 @httpServer
    取消对httpServer上upgrade事件的监听。
  • wsf.connect方法 @wsurl, @callback
    作为websocket的非浏览器客户端，连接到指定fslider_ws websocket服务器，连接后会触发wsf上的connected事件。
• wsf.Server类：[@httpServer],[@options]，创建wsfServer实例
  • server.getRegistedId方法 => Array
    返回连接到当前server的已注册客户端的id组成的数组。
  • server.getClient方法 @id
    => Client
    根据已注册的id返回客户端实例
  • server.getConnectCount方法 => Number
    返回连接到当前server的全部(包括未注册)客户端数量
  • server.bind方法 @server，[@options]
    手动为server添加监听的HTTP服务器
  • server.unbind方法 取消当前server的HTTP服务器绑定
  • server.sysEmit方法 继承自EventEmitter.prototype.emit
  • server.on方法 继承自EventEmitter.prototype.on
  • server.emit方法 @client，@event，@data
    覆盖了继承的.emit方法。向指定客户端发送event
  • server.broadcast方法 @event，@data
    向客户端广播event
  • server.removeListener方法 继承自EventEmitter.prototype.removeListener
• Client类：@socket，@sockets_queue, @isClient 以net.Socket实例为参数实例化一个客户端Socket引用
  • client.emit方法 @event，@data | @dataStream
    覆盖了集成的.emit方法。向这个客户端发送event。
  • client.on方法
    继承自EventEmitter.prototype.on.
    回调参数: @dataStream | @data
  • client.send方法 @data | @dataStream
    client.emit的语法糖，向客户端触发'data'事件，等价于client.emit('data', data)。
  • client.recive方法 @callback
    client.on的语法糖，监听来自客户端的data事件，等价于client.on('data', callback)。
  • client.emitCtrl方法 @Opcode，@statusCode，@Payload_data
    向客户端发送控制帧。一般该方法不需要应用程序去调用，应该由rocket-engine自己的逻辑控制调用。
  • client.sysEmit方法 @event，@data
    在服务器端触发系统级事件。常用于socket接收到来自客户端的事件消息时通知给应用程序。一般该方法不需要应用程序去调用，应该由fslider_ws自己的逻辑控制调用。
  • client.setTimeout方法 @timeout
    设置该socket的超时等待
  • client.destory方法 强制关闭异常连接。服务器自主断开底层TCP连接。
  • client.end方法 关闭底层TCP连接,常在"关闭握手阶段"结束后调用.服务器自主断开底层TCP连接.
  • client.close方法 @code:状态码, [@reason:关闭理由]
    正常关闭连接,进入关闭握手阶段,发送CLOSE HandShake Frame。如果之前已经发送过close frame,则该方法什么也不做.
  • client.identify方法
    @id, @callback
    用id向ws服务器实例注册该client, 如果指定id已被注册,则callback参数为err.
  • client.set方法 @key, @value
    在一个client的命名空间下存储自定义键-值对.
  • client.get方法
    @key
    根据key返回存储数据.
  • client.fragmentSize属性 设置分片大小.待发送的数据帧大小超过这个限定时,会自动将其分片发送.
    注意,如果发送尺寸较大的二进制文件如高清图片,建议根据情况设定来重置分片大小,以免应用卡顿.

System-Level Events

Note：应用程序里定义的事件名称尽量不要与这些预定义的事件名称冲突

• wsf:
  • #listen 回调参数：绑定的http.Server实例。
    当全局绑定一个http.Server实例时触发。
  • #close 回调参数：解绑定的http.Server实例。
    解除绑定一个http.Server实例时触发。
  • #connected 回调函数：Client实例。
    调用wsf.connect成功建立连接后触发。
• server
  • #uptolimit 回调参数：server.MAX。
    （全局）已连接的已达到最大连接数时，有新的请求时触发
  • #connected 回调参数：client。
    握手阶段完成时触发。
  • #closing 回调参数：undefined。
    （全局）当接收到来自客户端的close frame时触发。
  • #serverclose 回调参数: undefined.
    (全局)底层TCP连接准备断开连接(发送FIN Packet)时触发.
  • #clientclose 回调参数: undefined.
    (全局)接收到客户端发送的FIN Packet时触发.
  • #disconnected 回调参数：state_code {Number}。
    （全局）当底层连接完全关闭时触发。
  • #drained 回调参数：socket.bufferSize。
    （全局）当操作系统用户态缓存队列清空时触发。
  • #timeout 回调参数：undefined。
    （全局）socket超时触发。
  • #exception 回调参数：error。
    （全局）当连接发生错误时触发。
• client
  • #uptolimit 回调参数：server.MAX。
    已连接的已达到最大连接数时，有新的请求时触发
  • #connected 回调参数：client。
    握手阶段完成时触发。
  • #closing 回调参数：undefined。
    当接收到来自客户端的close frame时触发。
  • #serverclose 回调参数: undefined.
    底层TCP连接准备断开(发送FIN Packet)时触发.
  • #clientclose 回调参数: undefined.
    客户端TCP连接准备断开(回复FIN Packet)时触发.
  • #disconnected 回调参数：state_code {Number}。
    当底层连接完全关闭时触发。
  • #drained 回调参数：socket.bufferSize。
    当操作系统用户态缓存队列清空时触发。
  • #timeout 回调参数：undefined。
    socket超时触发。
  • #exception 回调参数：error。
    当连接发生错误时触发。
  • #ping 回调参数：client。
    收到Ping包时触发
  • #pong 回调参数：client。 收到Pong包时触发。

Caveats

v0.4.x中对数据接受模块进行了重构, 新增了streamParser, 为分片提供了流式解析方式. 取代v0.3.x中的(store mode)存储模式. 极大程度降低了内存开销.

如何使用v0.4.x流式分片? 非常简单, 因为回调函数的参数src在流模式中是一个可读流!

wsf.on('connected', function (client) {
  // stream mode
  client.on('media', function (src) {
    // because I didn't implement whole stream by now
    // so, if u r not sure whether it'll receive in fragments
    // u have to do this test:
    if (src instanceof Buffer)
      console.log(src);
    else
      src.pipe(dst);
  });
});

v0.5版本提供了完整的流式(stream)API, 极大简化了媒体流/数据流的传输过程, 减轻了服务器内存压力.

// example: 使用v0.5流式API接收数据流, 转发数据流.
socket.on('lol', function (imgstream) {
    imgstream.pipe(fs.createWriteStream('./dump.gif')).on('finish', function () {
      socket.send(fs.createReadStream('./dump.gif'));
    });
  });

Notice: 为了避免过多数据在内存中驻留, 默认开启了Node stream的flowing mode. 请添加.pipe()或"data"事件回调防止数据丢失!

WebSocket连接关闭阶段的事件触发顺序

对于一次正常的关闭,事件会按如下顺序触发:

1. #closing
2. #serverclose
3. #clientclose
4. #disconnected

Note:一般情况下,如果需要监听断开连接事件,仅向disconnected事件添加监听器即可,代表底层连接完全关闭.对于开发人员,或许你会需要监听连接关闭过程中每一阶段的关闭情况,这是可以在closing事件,serverclose事件和/或clientclose事件上添加监听器.