README

wscio

长连接通讯库-客户端

3 客户端 `API`

3.1 wscio

wscio

作为独立生成中的 wscio 命名空间暴露，或调用 require('wscio')

<script>
    const socket= wscio('http://127.0.0.1');
</script>

const wscio= require('wscio')
//或者使用import 语法
import { wscio } from 'wscio'

3.1.1 `wscio.protocpl`

Number

解析协议版本号

3.1.2 `wscio([url][,optiosn])`

url (string) (默认为 window.location)

options (object)

forceNew? (boolean) 是否重用现有连接

query? (string) 第一次请求连接时 URL 请求参数

nsp? (string) 命名空间

auth? (string | object) 命名空间连接时验证参数

... 其余参数在 Client 实例时所需参数

Return: Socket

为给定的URL创建新的管理器，并尝试在后续调用中重用现有的管理器，除非用false传递多路复用选项。传递此选项等同于传递 force new connection：true 或 forcenew:true 。

有关可用选项的列表，见 new Client(url[, options])

3.1.3 带多路复用

默认情况下，连接到不同命名空间时使用单个连接（以最小化资源）

const wscio= require('wscio')
const socket= wscio()
const test =wscio('/test')
//  将建立单一连接

使用forceNew选项可以禁用该行为：

const wscio= require('wscio')
const socket = wscio();
const test = wscio('/test',{forceNew:true})
// 将创建两个不同的连接

3.1.4 自定义路径

const wscio = require('wscio')
const socket = wscio('http://127.0.0.1',{
    path:"/mypath"
})
// 服务端
const wss = new require('wssio')({
    path:"/mypath"
})

请求的 URL 会像：127.0.0.1/mypath

3.1.5 查询参数

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1?token=abc');
// 服务端
functionverifyClient(data, callback) {//这样能彻底断开连接
    const url = data.req.url;
    //处理逻辑
    callback(); //传入处理结果
}
const wss = new require('wssio')({
  verifyClient,
})
// 中间件验证并不能断开socket原始连接
wss.use((socket,next)=>{
    const token = socket.handshake.query.token;
    if (isValid(token)){
        return next();
    }
    return next(new Error('验证失败'))
})
// 然后
wss.on('connection', (socket) => {
    const token= socket.handshake.query.token
})

3.1.6 自定义解析器

待完成

3.2 `Client`

3.2.1 new Client(url[,options])

url (string)

options? (object)

Return: Client

可用的选项：

选项	默认值	描述
`path`	`/wssio`	在服务器端捕获的路径的名称
`reconection`	`true`	是否自动重新连接
`reconnectionAttempts`	`Infinity`	放弃前重新连接尝试的次数
`reconnectionDelay`	`1000`	在尝试重新连接之前，最初等待多长时间（`1000`）。受+/- `randomizationFactor`的影响，例如，默认初始延迟将在500到1500毫秒之间。
`reconnectionDelayMax`	`5000`	重新连接之间等待的最长时间（`5000`）。每次尝试都会增加2倍的重新连接延迟，并随机分组，如上所述。
`randomizationFactor`	`0.5`	0 <= `randomizationFactor` <= 1
`timeout`	`20000`	在发出`connect_error`和`connect_timeout`事件之前的连接超时
`authConnect`	`true`	如果设置为`false`，则必须在确定合适时调用`client.open`
`query`	`{}`	连接命名空间时发送的其他查询参数（然后在服务器端的`socket.handshake.query`对象中找到）
`parser`	-	要使用的解析器。默认为wssio附带的解析器实例。请参见wssio-parser。
`protocols`	-	子协议列表（参见MDN参考）（仅适用于WebSocket传输）。

运行与 Node 端时 ws 库基本客户端选项参见 ws库文档

3.3 `Socket`

3.3.1 `socket.id`

(string)

socket 会话的唯一标识符。在触发 connect 事件后设置，并在 reconnect 事件后更新。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
console.log(socket.id) //undefined
socket.on('connect',()=>{
    console.log(socket.id) // xxxx...
})

3.3.2 `socket.connected`

(boolean)

socket 是否连接到服务器。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
console.log(socket.connected) //false
socket.on('connect',()=>{
    console.log(socket.connected) //true
})

3.3.3 `socket.disconnected`

见 socket.close()

3.3.4 `socket.open([value])`

auth?: object | string 连接时上传的认证参数

Return: Socket

手动打开 socket

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1', {
    autoConnect:false
})
// ...
socket.open() //手动打开连接

它还可用于手动重新连接：

socket.on('disconnect',()=>{
    socket.open()
})

3.3.5 `socket.connect()`

同 socket.open()，但不支持参数

3.3.6 `socket.send([...args][,ack])`

args: (any) 数据列表，可以时多个

ack: (function) 回执函数

Return: Socket

3.3.7 `socket.emit(event,[...args][,ack])`

event: (string) 事件名

args: (any) 数据列表

ack: (function) 回执函数

Return: Socket

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

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect', function() {
    socket.emit('event', arg1, arg2, ...)
    socket.emit('event', { data: new Buffer(6) })
    //ack参数是可选的，将通过服务器应答调用。
    socket.emit('event1', 'data', function(data) {
        console.log(data) // data 将是 'data1'
    })
})
// 服务器：
const wss = new require('wssio')()
wss.on('connection', (socket) => {
    socket.on('event1',(name,fn)=>{
        fn('data1');
    })
})

3.3.8 `socket.on(event,callback)`

event: (string) 事件名

callback: (function) 接收事件响应数据

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

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)
})

socket 实际上继承了 Emitter 类的每个方法，比如 hasListeners ， once 或 off （删除一个事件监听器）

3.3.9 `socket.compress(compress)`

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

Return: Socket

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

socket.compress(false).emit('event', { data: new Buffer(1024) })

3.3.10 `socket.close()`

Return: Socket

手动断开 socket 。

3.3.11 `socket.disconnect()`

同 socket.close()相同

3.3.12 `event:connect`

第一次连接成功时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect', function() {
    //第一次连接成功触发事件
})
// 注意：您应该在connect之外注册事件处理程序，
// 因此重新连接时不会再次注册它们
socket.on('myevent',()=>{
    // ....
})

3.3.13 `event:connect_error`

error: (object) 错误对象

在连接错误时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect_error', function(error) {
    // error为错误信息
})

3.3.14 `event:error`

error: (object) 错误对象

发生错误时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('error', function(error) {
    // error为错误信息
})

3.3.15 `event:disconnect`

reason: (string | number) '值为 客户端断开连接 时为客户端断开'，值为 3666 时为服务器端授权失败被动断开，其余值根据具体情况考虑

断开时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('disconnect',(reason)=>{
    if(reason.code !== 3666 && reason != '客户端断开连接'){
        // 断开连接是由服务器启动的，需要手动重新连接
        socket.connect()
    }
    // 否则，socket将自动尝试重新连接
})

3.3.16 `event:reconnect`

attempt: (number) 重新连接尝试次数

在成功重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect',(attemptNumber)=>{
    //重连成功触发，不在触发connect事件
})

3.3.17 `event:reconnect_attempt`

attempt: (number) 重新连接尝试次数

试图重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.io('reconnect_attempt',(attemptNumber)=>{
    //试图重新连接时触发
})

3.3.18 `event:reconnecting`

attempt: (number) 重新连接尝试次数

正在试图重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnecting',(attemptNumber)=>{
    //正在试图重新连接时触发。
})

3.3.19 `event:reconnect_error`

error: (object) 错误对象

在重新连接尝试错误时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect_error',(error)=>{
    //在重新连接尝试错误时触发。
})

3.3.20 `event:reconnect_failed`

在 reconnectionAttempts （尝试重连）内无法重新连接时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect_failed',()=>{
    //在 `reconnectionAttempts` （尝试重连）内无法重新连接时触发
})

3.3.21 `event:ping`

在将ping数据包写入服务器时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('ping',()=>{
    //在将ping数据包写入服务器时触发。 
})

Usage no npm install needed!

README

wscio

3 客户端 API

3.1 wscio

3.1.1 wscio.protocpl

3.1.2 wscio([url][,optiosn])

3.1.3 带多路复用

3.1.4 自定义路径

3.1.5 查询参数

3.1.6 自定义解析器

3.2 Client

3.2.1 new Client(url[,options])

3.3 Socket

3.3.1 socket.id

3.3.2 socket.connected

3.3.3 socket.disconnected

3.3.4 socket.open([value])

3.3.5 socket.connect()

3.3.6 socket.send([...args][,ack])

3.3.7 socket.emit(event,[...args][,ack])

3.3.8 socket.on(event,callback)

3.3.9 socket.compress(compress)

3.3.10 socket.close()

3.3.11 socket.disconnect()

3.3.12 event:connect

3.3.13 event:connect_error

3.3.14 event:error

3.3.15 event:disconnect

3.3.16 event:reconnect

3.3.17 event:reconnect_attempt

3.3.18 event:reconnecting

3.3.19 event:reconnect_error

3.3.20 event:reconnect_failed

3.3.21 event:ping

3 客户端 `API`

3.1.1 `wscio.protocpl`

3.1.2 `wscio([url][,optiosn])`

3.2 `Client`

3.3 `Socket`

3.3.1 `socket.id`

3.3.2 `socket.connected`

3.3.3 `socket.disconnected`

3.3.4 `socket.open([value])`

3.3.5 `socket.connect()`

3.3.6 `socket.send([...args][,ack])`

3.3.7 `socket.emit(event,[...args][,ack])`

3.3.8 `socket.on(event,callback)`

3.3.9 `socket.compress(compress)`

3.3.10 `socket.close()`

3.3.11 `socket.disconnect()`

3.3.12 `event:connect`

3.3.13 `event:connect_error`

3.3.14 `event:error`

3.3.15 `event:disconnect`

3.3.16 `event:reconnect`

3.3.17 `event:reconnect_attempt`

3.3.18 `event:reconnecting`

3.3.19 `event:reconnect_error`

3.3.20 `event:reconnect_failed`

3.3.21 `event:ping`