mulocal-socket

Network socket emulation for mudb.

In mulocal-socket, no real network connections are established so no Web servers are needed, meaning any mudb applications using mulocal-socket can run entirely in a browser. This can be favorable to development in that

• you can forget about restarting the server on changes
• you can debug using the dev tools provided by browsers

example

var mudb = require('mudb')
var muLocalSocket = require('mulocal-socket')

var socketServer = muLocalSocket.createLocalSocketServer()
var muServer = new mudb.MuServer(socketServer)

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

var socket = muLocalSocket.createLocalSocket()
var muClient = new mudb.MuClient(socket)

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

table of contents

• 1 install
• 2 api
  • 2.1 interfaces
  • 2.2 createLocalSocketServer()
  • 2.3 createLocalSocket(spec)
  • 2.4 MuLocalSocketServer
    • 2.4.1 state:SocketServerState
    • 2.4.2 clients:MuLocalSocket[]
    • 2.4.3 start(spec)
    • 2.4.4 close()
  • 2.5 MuLocalSocket(sessionId, server)
    • 2.5.1 sessionId:SessionId
    • 2.5.2 state:SocketState
    • 2.5.3 open(spec)
    • 2.5.4 send(data, unreliable?)
    • 2.5.5 close()

1 install

npm i mulocal-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 createLocalSocketServer()

A factory returning a new instance of MuLocalSocketServer.

2.3 createLocalSocket(spec)

Spawns and associates two new instances of MuLocalSocket, then returns the client-side socket to be used to create a MuClient.

• spec:object
  • sessionId:SessionId: a unique session id used to identify a client
  • server:MuLocalSocketServer: the socket server

Mostly you should only use the factory methods instead of the constructors.

2.4 MuLocalSocketServer

A MuLocalSocketServer is a pseudo socket server that can be used to create a MuServer. It does not create any server-side sockets and is only responsible for accumulating and closing sockets.

2.4.1 state:SocketServerState

A tri-valued field determining the availability of the socket server. It is initialized to SocketServerState.INIT.

2.4.2 clients:MuLocalSocket[]

Server-side sockets, one per client through which the server communicates with the client.

2.4.3 start(spec)

Hooks handlers and accumulates sockets. state is set to SocketServerState.RUNNING.

• spec:object
  • ready() called when the socket server is ready
  • connection(socket:MuLocalSocket) called when a new server-side socket is added
  • close(error?) called when the socket server is shut down

2.4.4 close()

Closes all sockets. state is set to SocketServerState.SHUTDOWN.

2.5 MuLocalSocket(sessionId, server)

A MuLocalSocket can either be a client-side or server-side socket and every two MuLocalSockets should be associated to form an exclusive pair. A MuLocalSocket can be used to create a MuClient when it is used as a client-side socket.

• sessionId:SessionId: a unique session id used to identify a client
• server:MuLocalSocketServer: the socket server

2.5.1 sessionId:SessionId

The unique session id identifying the client.

2.5.2 state:SocketState

A tri-valued field determining the availability of the socket. It is initialized to SocketState.INIT.

2.5.3 open(spec)

Hooks handlers and drains pending messages. state is set to SocketState.OPEN.

• spec:object
  • ready() called when the socket is ready to receive data
  • message(data:Data, unreliable:boolean) called when receiving data
  • close(error?) called when the socket is closed

2.5.4 send(data, unreliable?)

Sends data to the associated socket, which will be delivered either in order or out of order, depending on the value of unreliable.

• data:Data data to be sent, can either be a JSON string or a Uint8Array
• unreliable?:boolean optional, the data will be delivered out of order if set to true

2.5.5 close()

Closes the socket and the socket on the other end. state is set to SocketState.CLOSED.

credits

Copyright (c) 2017 Mikola Lysenko, Shenzhen Dianmao Technology Company Limited