Class: Websocket.server 服务端

英文原版参考

一、new WebSocket.Server(options[, callback]) 参数说明如下：

• options {Object}

  • host {String} 要绑定的服务器主机名
  • port {Number} 要绑定的服务器端口
  • backlog {Number} 挂起连接队列的最大长度.
  • server {http.Server|https.Server} 一个预创建的HTTP/S服务器
  • verifyClient {Function} 验证传入连接的函数。
  • handleProtocols {Function} 处理子协议的函数。
  • path {String} 只接受与此路径匹配的连接
  • noServer {Boolean} 启用无服务器模式
  • clientTracking {Boolean} 是否记录连接clients
  • perMessageDeflate {Boolean|Object} 开启关闭zlib压缩(配置)
  • maxPayload {Number} 最大消息载荷大小（bytes）

• callback {Function}

1. 创建一个新的服务器实例。必须提供端口、服务器或NoServer中的一个，否则会引发错误。
2. 如果端口被设置，则自动创建、启动和使用HTTP服务器。
3. 要使用外部HTTP/S服务器，只指定服务器或NoServer。此时，必须手动启动HTTP/S服务器。
4. “NoSver”模式允许WS服务器与HTTP/S服务器完全分离。
5. 这使得，可以在多个WS服务器之间共享一个HTTP/S服务器

1. verifyClient {Function} (默认自动接受)，如果设置该函数则，则该函数会接受如下两个参数：

   info {Object}
       origin {String} ```HTTP.request.header['Origin']```
       req {http.IncomingMessage} GET```HTTP.request```
       secure {Boolean} 如果设置了Req.Calnal.授权或Req.Calnal.加密，则为true。
   cb {Function} 当用户需要定制拒绝回调信息时使用，该回调可传如下参数：
       result {Boolean} 是否接受握手
       code {Number} 当```result```为```false```时，该值为指定返回的http错误状态码
       name {String} 当```result```为```false```时，该值为指定返回的http错误信息
       headers {Object} 当```result```为```false```时，该值可以设定附加的额外头部信息

示例如下：

// 1)、拒绝
verifyClient:function(info){
    return false;
}
// 2)、同意
verifyClient:function(info){
    return true;
}
// 3)、拒绝
verifyClient:function(info,cb){
    cb(false,403,'Site access denied',{'Retry-After': 120});
}

2. handleProtocols {Function} 处理子协议的函数。函数注入参数如下:

     protocols {Array} ```HTTP.request.header['Sec-WebSocket-Protocol']```
     request {http.IncomingMessage} GET```HTTP.request```

如果函数返回true则会在响应中设置header['Sec-WebSocket-Protocol']
忽略该项则使用HTTP.request.header['Sec-WebSocket-Protocol']第一个值

3. perMessageDeflate {Boolean|Object} 压缩扩展（默认：false）

     serverNoContextTakeover {Boolean} Whether to use context takeover or not.
     clientNoContextTakeover {Boolean} Acknowledge disabling of client context takeover.
     serverMaxWindowBits {Number} The value of windowBits.
     clientMaxWindowBits {Number} Request a custom client window size.
     zlibDeflateOptions {Object} [deflate options](http://nodejs.cn/api/zlib.html#zlib_class_options)
     zlibInflateOptions {Object} [inflate options](http://nodejs.cn/api/zlib.html#zlib_class_options)
     threshold {Number} 小于该值的有效载荷将不会被压缩。默认为1024字节。
     concurrencyLimit {Number} 并发数限制，默认：10。详情请参阅此问题。

如果属性为空，则使用提供的配置或默认值。当发送分段消息时，将第一片段的长度与阈值进行比较。这就决定了是否对整个消息使用压缩。
注：其实关于压缩使用了node zlib模块 参考地址

4. callback {Function}

非“noServer”模式下运行时，回调将被添加到HTTP服务器上侦听事件的侦听器中。

内置事件：

1. Event: 'close' 服务器关闭时触发 无参数

当服务器关闭时发送。此事件仅取决于HTTP服务器在内部创建时的“关闭”事件。在所有其他情况下，事件是独立发射的。

2. Event: 'connection' 成功握手连接时触发。注入参数如下:

     socket {WebSocket} socket连接句柄
     request {http.IncomingMessage} GET```HTTP.request```

3. Event: 'error' 发生错误时触发 注入一个Error对象

     error {Error}

4. Event: 'headers' 握手前触发 注入参数如下：

在响应头被写入到套接字作为握手的一部分之前发出。这允许您在发送头之前检查/修改标题。

     headers  {Array} ```HTTP.respone.header```
     request {http.IncomingMessage} GET```HTTP.request```

5. Event: 'listening' 绑定端口时触发 无参数

属性说明：

1. server.clients {Set}

存储所有连接客户端的集合。请注意，只有在客户端跟踪是truthy时才添加此属性。

内置方法：

1. server.address() 返回net.server.address()

仅当监听了端口后有值 数据参考地址

2. server.close([callback]) 关闭http服务器并终止所有客户端

如果noServer为真，则需要手动关闭客户端

3. server.handleUpgrade(request, socket, head, callback) 处理websocket升级请求 noServer模式下必须手动调用该函数

     request {http.IncomingMessage} GET```HTTP.request```
     socket {net.Socket} ```net.Socket```
     head {Buffer} 升级后的第一个数据包
     callback {Function} 如果升级成功，调用回调将以WebSoCult对象作为参数调用。

4. server.shouldHandle(request) 处理websocket升级请求 noServer模式下必须手动调用该函数

     request {http.IncomingMessage} GET```HTTP.request```

默认情况下，此方法验证请求的路径名与path属性是否匹配。返回值，TRUE或FALSE，决定是否接受握手。
当需要自定义处理逻辑时，可以重写此方法。

Class: WebSocket websocket实例 （可用于客户端连接实例、服务端接收到连接的实例）

二、new WebSocket(address[, protocols][, options]) 参数说明如下：

• address {String|url.Url|url.URL} 请求地址（例：ws://127.0.0.1:8080/）
• protocols {String|Array} 子协议列表http.request.header['Sec-WebSocket-Protocol']
• options {Object}
  • handshakeTimeout {Number} 超时时间（ms）
  • perMessageDeflate {Boolean|Object} 是否开启压缩（默认：true）
  • protocolVersion {Number} http.request.header['Sec-WebSocket-Version']
  • origin {String} http.request.header['Origin'] 或者 http.request.header['Sec-WebSocket-Origin']
  • maxPayload {Number} 最大消息载荷（bytes）
  • 其它任何 http/s.request属性
    
    

内置事件：

1. Event: 'close' 连接关闭时触发 参数如下

     code {Number} 状态码
     reason {String} 原因

2. Event: 'error' 发生错误时触发 注入一个Error对象

     error {Error}

3. Event: 'message' 接收到服务器消息时触发

     data {String|Buffer|ArrayBuffer|Buffer[]}

4. Event: 'open' 连接建立时触发 无参数

5. Event: 'ping' 服务器ping消息

     data {Buffer} 

6. Event: 'pong' 服务器pong消息

     data {Buffer}

7. Event: 'unexpected-response'

     request {http.ClientRequest} 
     response {http.IncomingMessage}

当服务器响应不是预期响应时发出，例如401响应。此事件提供了读取响应以提取有用信息的能力。如果服务器发送无效响应，并且没有该事件的侦听器，则会发出错误。

8. Event: 'upgrade'

     response {http.IncomingMessage}

Emitted when response headers are received from the server as part of the handshake. This allows you to read headers from the server, for example 'set-cookie' headers.

9. 内置方法（属性）：

10. websocket.addEventListener(type, listener) 自定义事件侦听器

     type {String} 自定义事件名称
     listener {Function} 侦听器

11. websocket.removeEventListener(type, listener) 移除事件侦听器

     type {String} 自定义事件名称
     listener {Function} 侦听器

12. websocket.send(data[, options][, callback]) 发送数据

 data {Any} 需要发送的数据
 options {Object}
     compress {Boolean} 是否压缩（启用perMessageDeflate时默认为true）
     binary {Boolean} 是否作为二进制数据发送，默认为true
     mask {Boolean} 是否掩码（客户端默认为true，服务端不允许掩码）
     fin {Boolean} 指定是否为最后的消息片段，默认：true (用于分片发送)
 callback {Function} 在写入数据时调用的可选回调。

通常options不需要设置，除非你基本熟悉websocket协议

13. websocket.ping([data[, mask]][, callback])

 data {Any} 同上
 mask {Boolean} 同上
 callback {Function} 同上

14. websocket.pong([data[, mask]][, callback])

 data {Any} 同上
 mask {Boolean} 同上
 callback {Function} 同上

15. websocket.close([code[, reason]]) 发送连接关闭信号

 code {Number} 关闭连接状态码
 reason {String} 关闭原因说明

16. websocket.terminate() 强制关闭连接 无参数

terminate()为强制关闭连接
close()为发送关闭信号，通常服务器会处理完当前发送数据然后再缓步关闭

17. websocket.readyState {Number} 实例对象的当前状态

• 0 => CONNECTING正在连接。
• 1 => OPEN连接成功，可以通信了。
• 2 => CLOSING连接正在关闭。
• 3 => CLOSED连接已经关闭，或者打开连接失败。
  
  

18. websocket.binaryType {String} 显式指定收到的二进制数据类型 默认：'nodebuffer'

右侧三选一 ["nodebuffer","arraybuffer","fragments"]

19. websocket.bufferedAmount {Number} 表示还有多少字节的二进制数据没有发送出去。它可以用来判断发送是否结束

20. websocket.protocol {String} 返回服务端选择的子协议

21. websocket.url {String} 仅在服务端socket存在该值

22. websocket.extensions {Object} 包含协商扩展的对象

以下是一些重复的事件省略（包含如下：）

 onopen、onmessage、onclose、onerror（与内置的```Event```内置事件是等效的）