muweb-socket

muweb-socket

WebSocket communications made available for mudb, using uws for the WebSocket server implementation.

example

server.js

var http = require('http')
var MuWebSocketServer = require('muweb-socket/server').MuWebSocketServer
var MuServer = require('mudb/server').MuServer

var httpServer = http.createServer()
// use a pre-created HTTP server
var socketServer = new MuWebSocketServer({
    server: httpServer
})
var muServer = new MuServer(socketServer)

muServer.start({ /* event handlers */ })

// should call `listen()` when using an external HTTP/S server
httpServer.listen()

client.js

var MuWebSocket = require('muweb-socket/socket').MuWebSocket
var MuClient = require('mudb/client').MuClient

var socket = new MuWebSocket({
    sessionId: Math.random().toString(36).substr(2),
    url: /* URL to server */,
    maxSockets: 10, // how many WebSockets to be opened
})
var muClient = new MuClient(socket)

muClient.start({ /* event handlers */ })

table of contents

• 1 install
• 2 api
  • 2.1 interfaces
  • 2.2 MuWebSocketServer(spec)
    • 2.2.1 state:SocketServerState
    • 2.2.2 clients:MuWebSocketClient[]
    • 2.2.3 start(spec)
    • 2.2.4 close()
  • 2.3 MuWebSocket(spec)
    • 2.3.1 sessionId:SessionId
    • 2.3.2 state:SocketState
    • 2.3.3 open(spec)
    • 2.3.4 send(data:Data, unreliable?:boolean)
    • 2.3.5 close()

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 members
  • SocketState.INIT
  • SocketState.OPEN
  • SocketState.CLOSED
• SocketServerState: an enum consisting of three members
  • SocketServerState.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 connections
  • connection(socket:MuWebSocketClient) called when a client first connects
  • close(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 client
  • url:string: URL to the server
  • maxSockets?: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 ready
  • message(data:Data, unreliable:boolean) called when receiving data
  • close(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 a Uint8Array
• unreliable?:boolean optional, data is sent via the out-of-order channel if set to true to allow potential performance improvements

2.3.5 close()

Closes all connections. state is set to SocketState.CLOSED.

credits

Development supported by Shenzhen DianMao Digital Technology Co., Ltd.

Written in Shenzhen, China.

(c) 2017 Mikola Lysenko, Shenzhen DianMao Digital Technology Co., Ltd.