Sockets

Qbix includes a small abstraction layer to interface with node.js and the socket.io to enable a distributed architecture where messages are routed to different hosts. It also takes care of pooling connections, reconnecting sockets that have been connected, and handling events that are generated via the socket.

Routing

var url = Q.nodeUrl(fields)

Here we pass some fields to determine what URL to connect our sockets to. The Q.nodeUrl.routers array contains functions which Qbix consults in case one will return a url. By default, Q.info.socketUrl is returned.

Connections

Q.Socket.connect(namespace, url, callback)

Here you pass a socket.io namespace, such as "Streams", and an optional url obtained from Q.nodeUrl(). If the socket for this namespace and url is not yet connected, a connection is attempted, otherwise the existing connection is used. In any case, the callback is called with the corresponding Q.Socket object as the first parameter.

After a successful connection, a 'session' event is emitted to the socket, with the content of the session cookie (named in Q.info.sessionName). This enables the Node.js code such as the Streams plugin to deliver messages via any connected sockets of the appropriate user.

To check whether connection has been attempted, you can do this:

var socket = Q.Socket.get(namespace, url)

This returns a Q.Socket object, or null if Q.Socket.connect hasn't been called with this namespace and url.

You can disconnect any given socket from its URL, which will affect all the namespaces:

socket.disconnect();
Q.Socket.disconnectAll(); // all of them
Q.Socket.reconnectAll(); // all of them

Events

To wait until a particular socket connects, simply use the following event factory:

Q.Socket.onConnect(namespace, url).set(...)

You can also listen for events happening on a particular Q.Socket as follows:

socket.onEvent(eventName).set(...)