Sending realtime messages from the server to one or more clients
Overview
Sails exposes two APIs for communicating with connected socket clients: the higher-level resourceful pubsub API, and the lower-level sails.sockets API.
Resourceful PubSub
The Resourceful PubSub (Published/Subscribe) API provides a high-level way to subscribe sockets to Sails model classes and instances. It is entirely possible to create a rich realtime experience (for example, a chat app) using just this API. Sails blueprints use Resourceful PubSub to automatically send out notifications about new model instances and changes to existing instances, but you can use them in your custom controller actions as well.
Example
Create a new User model instance and notify all interested clients
// Create the new user
User.create({
name: 'johnny five'
}).exec(function(err, newUser) {
if (err) {
// Handle errors here!
return;
}
// Tell any socket watching the User model class
// that a new User has been created!
User.publishCreate(newUser);
});
sails.sockets
The sails.sockets API allows for lower-level communication directly with sockets, using methods like sails.sockets.join() (subscribe a socket to all messages sent to a particular "room"), sails.sockets.leave() (unsubscribe a socket from a room), and sails.sockets.broadcast() (broadcast a message to all subscribers in one or more rooms).
Example
Add a socket to the room "funSockets"
sails.sockets.join(someSocket, "funSockets");
Broadcast a "hello" message to the "funSockets" room. This message will be received by all client sockets that have (1) been added to the "funSockets" room on the server with sails.sockets.join() and (2) added a listener for the "hello" event on the client with socket.on('hello', ...).
sails.sockets.broadcast("funSockets", "hello", "Hello to all my fun sockets!");
Reference
- View the full sails.sockets API reference
- See the reference for the sails.io.js library to learn how to use sockets on the client side to communicate with your Sails app.
- See the resourceful pub-sub reference to learn how to use Sails blueprints to automatically send realtime messages about changes to your models.
- Visit the Socket.io website to learn more about the underlying library Sails uses for realtime communication
For a better experience on sailsjs.com, update your browser.
Concepts
Built with Love
The Sails framework is built by a web & mobile shop in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!
© 2012-2024 The Sails Company.
The Sails framework is free and open-source under the MIT License.
Illustrations by Edamame.