wssio

长连接通讯库-服务端

4 服务端-API(Server-API)

4.1 Server

4.1.1 HTTP服务选项 new_Server_httpserver_options

暴露 require('wssio')

new Server([options])

• options: (object) 参数配置项

const wssio = require('wssio')
const wss = new wssio({})

可用选项：

选项	默认值	描述
path	/wssio	要捕获的路径名称
host	127.0.0.1	服务 IP 地址
port	number	监听的端口，注意：端口、服务、无服务三个选项必须有一个
server	Server	服务，注意：端口、服务、无服务三个选项必须有一个
noServer	boolean	无服务模式，注意：端口、服务、无服务三个选项必须有一个
node	boolean	标志着客户端是否是 Node 环境下运行
connectTimeout	number	连接超时时间
origins	string | string[]	允许源
backlog	number	挂起的连接队列的最大长度
verifyClient	function	连接时的身份认证回调函数
handleProtocols	any	可用于处理WebSocket子协议的函数
clientTracking	boolean	指定是否跟踪客户端
perMessageDeflate	boolean | PerMessageDeflateOptions	启用/禁用permessage-deflate
maxPayload	number	数据最大负载量
adapter	-	要使用的适配器。默认为 wssio 随附的基于内存的 Adapter 实例。见wssio-adapter
parser	-	要使用的解析器。默认为 wssio 附带的解析器实例,见wssio-parser

verifyClient 连接时的身份认证回调函数

• info: { origin: string; secure: boolean; req: http.IncomingMessage }
• callback: (res: boolean, code?: number, message?: string, headers?: http.OutgoingHttpHeaders)

或者：

• info: { origin: string; secure: boolean; req: http.IncomingMessage })
• Return: boolean

注意：部分参数描述参见 ws

4.1.2 服务器选项 new_Server_options

• options: (object) 配置参数选项

const http = require('http');
const server = http.createServer();
const wssio = require('wssio')
//有服务方式
const wss = new wssio({
    server
})
//无服务方式
const wss = new wssio({
    noServer: true
})
//无服务方式带端口方式
const wss = new wssio({
    port: 3000
})
//有服务带连接身份认证方式
function verifyClient() {
  return true; // 返回false为授权未通过, 返回true为授权通过
}
const wss = new wssio({
  server,
  verifyClient,
})

其余启动参数选项请参阅上面的可用选项列表。

4.1.3 服务器 sockets Server_sockets

• (Namespace)命名空间

namespace的默认别名(/)

const wssio = require('wssio')
const wss = new wssio({})
wss.sockets.emit('event', '数据')
// 等价于
wss.of('/').emit('event', '数据')

4.1.4 服务器适配器值 Server_adapter_value

• _adapter: (Adapter) 适配器
• Return: Server | Adapter

设置适配器值。默认为 wssio 随附的基于内存的 Adapter 实例。见 wssio-adapter 。如果没有提供参数，此方法将返回当前值。

const wssio = require('wssio')
const wss = new wssio({})
const redis= require('wssio-redis')
wss.adapter(redis({host: '127.0.0.1', port:6379}))
//或者
const wss = new wssio({
    adapter: redis
})

4.1.5 服务器连接 socket Server_onconnection_socket

• socket: (Socket)
• Return: Server

仅限高级使用，从传入的 ws 中的 Socket 创建新的 wssio 客户端。

4.1.6 服务器命名空间(nsp) Server_of_nsp

• nsp: (string|RegExp|function)
• callback?: (Socket) 每个客户端连接成功触发得回调函数
• verifyClient?: (auth: object | string) => boolean 命名空间身份认证函数
• Return: Namespace

通过路径名标识符 nsp 初始化并检索给定的 Namespcae ，如果命名空间已经初始化，它会立即返回它。

const wssio = require('wssio')
const wss = new wssio({})
const testNamespace= io.of('/test')
//还可以提供regex或函数，以便以动态方式创建命名空间：
const testNsp =io.of(/^\/test-\d+$/).on('connection', (socket) => {
    const newNamepsace= socket.nsp // newNamespace.name==='/test-101'
    // 给所有订阅这个命名空间的客户端广播
    newNamespace.emit('event')
})
// 客户端
const socket=require('wscio')('ws://127.0.0.1', {
    nsp: '/test-101'
})
// 广播到每个订阅的命名空间中的所有客户端
testNsp.emit('event')
// 为每个订阅的命名空间使用中间件
testNsp.use((socket, next) => {
})

具体函数：

const wssio = require('wssio')
const wss = new wssio({})
wss.of((name, query, next) => {
}).on('connection',socket=>{})

4.1.7 服务器关闭回调 Server_close_callback

• callback: (function)

关闭 wssio 服务器，callback (回调)参数是可选的，将在关闭所有连接时调用。

const wssio = require('wssio')
const wss = new wssio({})
wss.close((err) => {
}) //关闭当前的服务器

4.2 命名空间 (Namespace)

4.2.1 命名空间选项 new_Namespace

• server: Server
• name: string
• verifyClient?: (auth: object | string) => boolean 命名空间身份认证函数

表示在由路径名标识的给定作用域下连接的 socket 池（例如：/group）。 客户端总是连接到/（主命名空间），然后可能连接到其他命名空间（同时使用相同的基础连接）。

4.2.2 命名空间名称 Namespace_name

• (string)

命名空间标识符属性。

4.2.3 命名空间连接 namespace_sockets

• (object)

连接到此命名空间并按 SocketId 索引的 Scoket 对象的哈希。

4.2.4 命名空间适配器 Namespace_adapter

• (Adapter)

用于命名空间的适配器。当使用基于 redis 的适配器时很有用，因为它公开了跨集群管理 socket 和房间的方法。

注意：主命名空间的适配器可以使用io.of('/').adapter访问。

4.2.5 命名空间到房间 Namespace_to_room

• room: (string) 房间名
• Return: Namespace 用于连接

为后续事件设置一个修饰符，该事件将仅广播给已加入指定的 room 客户端，要emit到多个房间，可以多次调用。

const wssio = require('wssio')
const wss = new wssio({})
const testNamespace=wss.of('/test')
testNamespace.to('room').emit('event', { data: 'data' })

4.2.6 命名空间发送事件参数 Namespace_emit_event_args

• event: (string) 事件名
• args: (any)

向所有连接的客户端 emit 事件，以下方法两个是等同的：

const wssio = require('wssio')
const wss = new wssio({})
wss.emit('event') //主命名空间
const chat = wss.of('/chat')
wss.emit('chat');

注意：从命名空间发出时不支持回执。

4.2.7 命名空间客户端回调 Namespace_clients_callback

• callback: (function(sids: Array<string | number>, cids: Array<string | number>))
• Return: : Namespace | Promise<{sids: Set<SocketId>, cids: Set<ClientId> }>

获取连接到此命名空间的客户端 SocketId 以及在线 SocketId 列表（如果适用，跨所有节点）。

const wssio = require('wssio')
const wss = new wssio({})
wss.of('/test'),clients((error, clients)=>{
    console.log(clients) // => {cids: [...], sids: [...]}
})

获取命名空间房间中所有客户端的示例：

const wssio = require('wssio')
const wss = new wssio({})
wss.of('/chat').to('group').clients((error, clients) => {
    console.log(clients) // => {cids: [...], sids: [...]}
})

与广播一样，默认值是来自默认命名空间 / 的所有客户端：

const wssio = require('wssio')
const wss = new wssio({})
wss.clients((error, clients) => {
    console.log(clients) // => {cids: [...], sids: [...]}
})

4.2.8 命名空间客户端返回 Namespace_allSockets

• Return: Promise<Set<SocketId>>

返回命名空间下所有在线的客户端 SocketId

4.2.9 命名空间中间件函数 Namespace_use_fn

• fn (function)

注册一个中间件，它是一个为每个传入 Socket 执行的函数，并作为参数接收 socket 和一个函数，以选择将执行推迟到下一个注册的中间件。

传递到中间件回调的错误作为特殊错误包发送到客户端。

const wssio = require('wssio')
const wss = new wssio({})
wss.use((socket, next) => {
    next(new Error('')) //根据具体逻辑返回
    next()
})

4.2.10 连接事件 event_connect | event_connection

• socket: (Socket) 与 客户端的socket 连接

在来自客户端的连接上触发，两者都是一样

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connect', (socket) => {})
wss.on('connection', (socket) => {})
wss.of('/nsp').on('connect', (socket) => {})
wss.of('/nsp').on('connection', (socket) => {})

4.2.1 可见性标志位 flag_volatile

为后续事件发出设置一个修饰符，如果客户端没有准备好接收消息（由于网络缓慢或其他问题，或者由于它们通过长轮询连接并且处于请求响应周期的中间），则事件数据可能会丢失。

const wssio = require('wssio')
const wss = new wssio({})
wss.volatile.emit('event', { data: 'data' }) // 客户端可能会收到，也可能不会收到。

4.2.12 是否开启压缩标志位 Namespace.compress(compress)

• compress: (boolean) 是否压缩数据传输标志
• Return: Namespace

为后续事件发送设置一个修饰符，该修饰符只在值为 true 时压缩事件数据。不调用方法时默认为 true 。

const wssio = require('wssio')
const wss = new wssio({})
wss.compress(false).emit('event', { data: new Buffer(1024) })

4.2.13 本地标记位 flag_local

后续事件发出设置一个修饰符，该修饰符表示事件数据将仅广播到当前节点（使用 redis 适配器时）。

const wssio = require('wssio')
const wss = new wssio({})
wss.local.emit('event', { data: 'data' })

4.3 Socket

4.3.1 Socket_id

• (string)

会话的唯一标识符，来自基础客户端

4.3.2 Socket_rooms

• Return: (Set<Room>)

标识此socket所在房间的的所有房间名。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.join('room 237', ()=>{
        console.log(socket.rooms); //['room 237']
    })
})

4.3.3 Socket_client

• (Client)

对基础客户端对象的引用。

4.3.4 Socket_conn

• (ws.WebSocket)

对基础客户端传输连接（ws WebSocket 对象）的引用。这允许访问 IO 传输层，该层仍然（大部分）抽象实际的 TCP/IP socket。

4.3.5 Socket_request

• (Request)

返回对发出底层的 request 的引用的 getter 代理。用于访问请求头，如 Cookie 或 User-Agent。

4.3.6 Socket_handshake

• (object)

握手细节：

{
    "headers": "",//作为握手的一部分发送的头
    "time":"",//创建日期（字符串）
    "address":"",//客户端的IP对象
    "remotePort": 8888,//客户端请求端口
    "remoteAddress": "",//客户端请求地址
    "xdomian":"",//连接是否跨域
    "secure":"",//连接是否安全
    "issued":"",//创建日期（作为Unix时间戳）
    "url":"",//请求URL字符串
    "query":"",//查询的对象
    "auth":""//命名空间连接认证参数
}

使用：

const wssio = require('wssio')
const wss = new wssio({})
wss.use((socket, next) => {
    let handshake= socket.handshake
})
wss.on('connection', (socket) => {
    let handshake= socket.handshake
})

4.3.7 Socket_use_fn

• fn (function) (event: string | number, datas: Array, next: Function)

注册一个中间件，它是一个为每个传入数据包执行并作为参数接收数据包的函数，以及一个可选地推迟执行到下一个注册的中间件的函数，传递到中间件回调的错误作为特殊error包发送到客户端。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.use((event, datas, next) => {
        //具体处理对next函数的调用
    })
})

4.3.8 Socket_send_args_ack

• args: (any)
• ack: (function)
• Return: Socket

发送一个 message 事件，见 socket.emit(eventName[, …args][, ack])

4.3.9 Socket_emit_event_args_ack

• event: (string) 事件名
• args: (any) 数据列表
• ack: (function) 回执函数
• Return: Socket

向字符串名称标识的 socket 发出事件。可以包括任何其他参数。支持所有可序列化的数据结构，包括`Buffer。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.emit('event', arg1, arg2, ...)
    socket.emit('event', { data: new Buffer(6) })
    //ack参数是可选的，将通过客户端应答调用。
    socket.emit('event1', 'data', function(data) {
        console.log(data) // data 将是 'data1'
    })
})

4.3.10 Socket_on_event_callback

• event: (string) 事件名
• callback: (function) 接收事件响应数据

为给定事件注册新的处理程序。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.on('event', function(data) {
        console.log(data)
    })
    // 多个参数
    socket.on('event', function(arg1, arg2, arg3, ...) {
        // ...
    })
    // 没有参数使用回调
    socket.on('event', function(cb) {
        cb(0)
    })
    // 使用参数+回调
    socket.on('event', function(arg1, arg2, arg3, ..., cb) {
        cb(0)
    })
})

4.3.11 Socket_join_room_callback

• room: (string | string[]) 房间名，可以是个数组
• callback: (function)
• Return: Socket

将客户端添加到 room | rooms 中，并根据需要触发带有 err 签名（如果有）的回调。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.join('room1', ()=>{
        console.log(socket.rooms); // ['room1']
        wss.to('room1').emit('event'); // 广播给房间里的每个人
    })
})

连接室的机制由已配置的 Adapter（参见上面的 Server#adapter）处理，默认为 wssio-adapter。

为了您的方便，每个 socket 自动连接由其ID标识的房间（请参见 Socket#id ），这使得向其他 socket 广播消息变得容易：

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.on('event',(id, msg)=>{
        // 使用给定的ID向socket发送私有消息
        socket.to(id).emit('event', msg)
    })
})

4.3.12 Socket_leave_room_callback

• room: (string) 房间名
• callback: (function)
• Return: Socket

从房间中移除 socket，并选择性地触发带有错误签名（如果有）的回调。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.join('room1', ()=>{
        console.log(socket.rooms); // ['room1']
        wss.to('room1').emit('event'); // 广播给房间里的每个人
        socket.leave('room1', () => {}) //离开房间room1
    })
})

断开后房间自动保留。

4.3.13 Socket_leaveAll

离开所有房间

4.3.14 Socket_to_room

• room: (string) 房间名
• Return: Socekt

为后续事件设置一个修饰符，该事件将仅广播给已加入给定房间的客户端（排除自己 socket）。要发送到多个房间，可以多次调用，要发送到多个房间，可以多次调用。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    // 到一个房间
    socket.to('room').emit('event', { data: 'data' })
    // 到多个房间
    socket.to('room1').to('room2').emit('event')
    // 发送私信到另外一个socket
    socket.to(/*另外一个socket id*/).emit('event')
    // 警告：` socket.to（socket.id）.emit（）`将不起作用，因为它将发送给房间中的每个人
})

注意：广播时不支持确认。

4.3.15 Socket_compress_value

• compress: (boolean) 是否压缩以下数据包
• Return: Socket

为后续事件设置一个修饰符，该修饰符只在值为 true 时压缩事件数据。不调用方法时默认为 true 。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.compress(false).emit('event', '数据')
})

4.3.16 Socket_disconnect_close_value

• close: (boolean) 标志是否断开所有连接

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.close() //断开该命名空间下的socket
    socket.close(true) //断开该连接下的所有socket
    socket.disconnect() //断开该命名空间下的socket，与close一样
    socket.disconnect(true) //断开该连接下的所有socket，与close一样
})

4.3.17 flag_broadcast

为后续事件设置一个修饰符，该修饰符使事件数据仅广播到除发送方之外的每个 socket 。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.broadcast.emit('event', { data: 'data' }) // 除了发送者，其他人都能收到
})

4.3.18 flag_volatile

为后续事件发出设置一个修饰符，如果客户端没有准备好接收消息（由于网络缓慢或其他问题，或者由于它们通过长轮询连接并且处于请求响应周期的中间），则事件数据可能会丢失。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.volatile.emit('event', { data: 'data' }); //客户可能会收到，也可能不会收到。
})

4.2.19 flag_local

后续事件发出设置一个修饰符，该修饰符表示事件数据将仅广播到当前节点。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.local.emit('event', { data: 'data' })
})

4.3.20 event_disconnect

• reason: (string) 断开连接的原因（客户端或服务器端）

断开时触发

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.on('disconnect', (reason) => {
    })
})

可能的原因：

原因	所在端	描述
transport error 传输错误	服务端	传输错误
server namespace disconnect	服务端	服务端执行 socket.disconnect()
client namespace disconnect	客户端	从客户端获取断开数据包

4.3.21 event_error

• error: (object) 错误对象

发生错误时触发。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.on('error', (error) => {
    })
})

4.3.22 event_disconnecting

• reason: (string) 断开连接的原因（客户端或服务器端）

当客户端将要断开连接（但尚未离开其房间）时触发。

const wssio = require('wssio')
const wss = new wssio({})
wss.on('connection', (socket) => {
    socket.on('disconnecting', (reason) => {})
})

这些是保留的事件（连同 connect 、 newlistener 和 removelistener ），不能用作事件名称。

4.4 Client

4.4.1 Client

Client 类表示传入传输（ ws ）连接， Client 可以与属于不同命名空间的多个多路复用 Socket 相关联。

4.4.2 Client_conn

• (ws.WebSocket)

对基础ws WebSocket连接的引用。

4.4.3 Client_request

• (Requst)

返回对发出 ws 连接的 request 的引用的 getter 代理。用于访问请求头，如 Cookie 或 User-Agent (用户代理)。

4.5 ParentNamespace 继承与 Namespace

4.5.1 ParentNamespace_createChild_name

• name: (string|RegExp|function)
• Return: Namespace

找到指定命名空间下的所有子节点