muweb-socket
WebSocket communications made available for mudb
, using uws
for the WebSocket server implementation.
example
server.js
var http = var MuWebSocketServer = MuWebSocketServervar MuServer = MuServer var httpServer = http// use a pre-created HTTP servervar socketServer = server: httpServervar muServer = socketServer muServerstart /* event handlers */ // should call `listen()` when using an external HTTP/S serverhttpServer
client.js
var MuWebSocket = MuWebSocketvar MuClient = MuClient var socket = sessionId: Math url: /* URL to server */ maxSockets: 10 // how many WebSockets to be openedvar muClient = socket muClientstart /* event handlers */
table of contents
1 install
npm i muweb-socket
2 api
2.1 interfaces
Purely instructive types used to describe the API:
SessionId
:string
Data
:Uint8Array | string
SocketState
: an enum consisting of three membersSocketState.INIT
SocketState.OPEN
SocketState.CLOSED
SocketServerState
: an enum consisting of three membersSocketServerState.INIT
SocketServerState.RUNNING
SocketServerState.SHUTDOWN
2.2 MuWebSocketServer(spec)
A MuWebSocketServer
can be used to create a MuServer
. It handles client-server communications over the WebSocket protocol.
spec:object
server:http.Server | https.Server
an HTTP/S server
2.2.1 state:SocketServerState
A tri-valued field determining the availability of the socket server. It is initialized to SocketServerState.INIT
.
2.2.2 clients:MuWebSocketClient[]
Virtual server-side sockets each of which is used to communicate with a specific client.
2.2.3 start(spec)
Spins up a WebSocket server and hooks handlers. state
is set to SocketServerState.RUNNING
.
spec:object
ready()
called when the WebSocket server is ready to handle connectionsconnection(socket:MuWebSocketClient)
called when a client first connectsclose(error?)
called when the WebSocket server is shut down
2.2.4 close()
Shuts down the WebSocket server. state
is set to SocketServerState.SHUTDOWN
.
2.3 MuWebSocket(spec)
A MuWebSocket
can be used to create a MuClient
. It is a virtual client-side socket used to communicate with the server over the WebSocket protocol.
spec:object
sessionId:SessionId
: a unique session id used to identify a clienturl:string
: URL to the servermaxSockets?:number
: optional, the number of connections to be opened, which defaults to 5
Two data channels can exist simultaneously in each MuWebSocket
, one delivers in order and the other delivers out of order but with potentially lower latency. The first established connection is used as the in-order data channel.
2.3.1 sessionId:SessionId
The unique session id identifying the client.
2.3.2 state:SocketState
A tri-valued field determining the availability of the socket. It is initialized to SocketState.INIT
.
2.3.3 open(spec)
Opens a number of connections to the server. state
is set to SocketState.OPEN
when the in-order data channel is determined.
spec:object
ready()
called when the in-order channel is readymessage(data:Data, unreliable:boolean)
called when receiving dataclose(error?)
called when the in-order channel is closed
2.3.4 send(data:Data, unreliable?:boolean)
Sends data to the server, either via the in-order channel or the out-of-order channel.
data:Data
data to be sent, can either be a JSON string or aUint8Array
unreliable?:boolean
optional, data is sent via the out-of-order channel if set totrue
to allow potential performance improvements
2.3.5 close()
Closes all connections. state
is set to SocketState.CLOSED
.
credits
Copyright (c) 2017 Mikola Lysenko, Shenzhen Dianmao Technology Company Limited