wssio v1.8.6
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
: Servername
: stringverifyClient
?: (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\,cids
: Set\ }>获取连接到此命名空间的客户端
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
找到指定命名空间下的所有子节点
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago