Resourceful PubSub

Overview

For apps that rely heavily on real-time client-server communication—for example, peer-to-peer chat and social networking apps—sending and listening for socket events can quickly become overwhelming. Sails helps smooth away some of this complexity by introducing the concept of Resourceful PubSub (Publish / Subscribe). Every model (AKA resource) in your app is automatically equipped with class methods for subscribing sockets to notifications about instance creations, updates and deletions. If you’re using the Blueprint API, socket messages are automatically broadcast to subscribed sockets when a model event occurs. If not, you can use the methods described in this section to manually communicate model events to clients.

Listening for events on the client

While you are free to use any Javascript library to listen for socket events on the client, Sails does provide its own Socket Client as a convenient way to communicate with the server. Using the Sails socket client makes listening for resourceful pubsub events as easy as:

io.socket.on("<model name>", listenerFunction)

Example

Let’s say you have a model named User in your app, with a single “name” attribute. First, we’ll add a listener for “user” events:

io.socket.on("user", function(event){console.log(event);})

This will log any notifications about User models to the console. However, we won’t receive any such messages until we subscribe to the existing User model instances. If you’re using the default blueprints, you can subscribe by making a socket request from the client to /user:

io.socket.get("/user", function(resData, jwres) {console.log(resData);})

This requests the current list of users from the Sails server, and subscribes the client to events about each user. Additionally, if the autoWatch setting is on (the default), the client will also be notified whenever a new User is created, and will automatically be subscribed to the new user. The callback in this example simply logs the user list to the console. See the socket.get reference for more info about this method.

It’s important to note that in order for the subscription to take place, the /user request must be made via a websocket call, not a regular HTTP request. That is, using an AJAX request (e.g. jQuery.get("/user")) will not result in the client being subscribed to resourceful pubsub messages about User. However, once the subscription is made, any changes to models—whether they be the result of a socket call, an AJAX request, even a cURL request from the command line—will cause the client to receive a notification. Continuing with the above example, if you were to open up a new browser window and go to the following URL:

/user/create?name=joe

You would see something like the following in the console of the first window:

{
    data: {
        createdAt: "2014-08-01T05:50:19.855Z"
        id: 1
        name: "joe"
        updatedAt: "2014-08-01T05:50:19.855Z"
    },
    id: 1,
    verb: "created"
}

The verb indicates the kind of action that occurred. The id refers to the instance that the action occurred on, and data contains more information about the User that was acted upon. Each event type sends back slightly different information; see the individual resourceful pubsub method reference documents for more info.