Streamlined websocket access for routers

[kecso]

Although the router (or any middleware) has access to the raw websocket of the WebGME server, it is extremely complicated to extend on the basic messages. It is even more though to do so on the client side which practically makes specialized communication impossible. As new and improved visualizers would require high traffic connections to the server (and not just in terms of the models and modeling API), it would be beneficial to allow a specialized communication channel that would be easy to setup and use for routers and clients (in this case the visualizers).

The following is a short description of the API that we would provide on the server and on the client side. The communication is very basic, but as the payload is a single JSON object, it is easy to see that it can be expanded and specialized to any need.

Server:
websocket.getWebsocketRouter(routerId) - this call reserves the router specific channel on the server and returns with the websocketRouter instance that will allow messaging and client counting.
websocketRouter.onConnect(handleFn) - function to pass the handle function for new connecting clients (the function will retrieve a user object that allows specific message receive and send functionality)
websocketRouter.send(payload) - broadcast message that will be sent to every connected user, the payload is a user defined JSON object (has to be stringifiable!)
user.onMessage(handleFn) - handle function for receiving message, the argument will be a JSON object payload.
user.onDisconnect(handleFn) - handle function for bookkeeping when the client disconnects from the routers service.
user.send(payload) - dedicated messaging to the user with a single payload.
user.error(Error) - send a negative message to the user with an error reason.
user.disconnect(ErrorReason) - disconnects the user forcefully from the specific channel.

Client:
client.getRouterAccess(routerId) - this call reserves a clientAccess object specific to the given router id (the client will book-keep so there will be a single instance per routerId, which will be returned for later get requests).
clientAccess.connect(onMessageFn, onErrorFn, onDisconnectFn) - let the server know that the client wishes to use the router specific channel (optionally, the handle functions can be passed as argument, so no separate call is needed)
clientAccess.onMessage(handleFn) - handle for regular message processing, the argument is a single JSON payload
clientAccess.onError(handleFn) - handle for error messages from the server
clientAccess.onDisconnect(handleFn) - handle for disconnect event (which originates from the server)
clientAccess.send(data, callback) - user initiated message and response from server
clientAccess.disconnect(callback) - user initiated disconnect (will not trigger onDisconnect)

[brollb]

A couple questions/thoughts:

websocket.getWebsocketRouter(routerId)

Would it be better to have the webgme server set the router ID? (ie, change the method signature to websocket.getWebsocketRouter()) Maybe it would be nice though if we wanted to create multiple websocket routers...

Would it be possible to support binary data at least for user.send? It may not be really pressing but it would be nice for sending large amounts of numeric data or other edge use-cases.

[brollb]

Also, I am assuming user.send is sending it to a single websocket connection and not to all instances for a connected user. Is that right?

[kecso]

• it is a router related channel, this means that knowledge is required for the use at implementation time (i do not see why a single router would require multiple channels, but show me a use-case and we can discuss it) we could by default use the id of the router, but that would mess up the implementation (and would end up being practically the same solution, when the router send the info, or send a reference to itself, so that the websocket server could generate some id...)
• i believe that you could easily convert binary data to string and string is the most common datatype so writing conversion to and from should be easy enough (if not already available)
• yes, the user.send only sends to the specific user