Edit Page

sails.config.sockets

What is this?

These configuration options provide transparent access to Socket.io, the WebSocket/pubsub server encapsulated by Sails.

Commonly-Used Options

Property Type Default Details
adapter 'memory' The queue socket.io will use to deliver messages. Can be set to either 'memory' or 'socket.io-redis'. If 'socket.io-redis' is specified, you should run npm install socket.io-redis@~1.0.0 --save --save-exact.
transports ['polling', 'websocket'] An array of allowed transport strategies. This should always match your configuration in your socket client (i.e. sails.io.js). For help, see Configuring the sails.io.js Library.

Redis Configuration

If you are configuring your Sails app for production and plan to scale to more than one server, then you should set sails.config.sockets.adapter to 'socket.io-redis', set up your redis instance, and then use the following config to point at it from your app:

Property Type Default Details
db 'sails' The name of the database to use within your redis instance.
host '127.0.0.1' Hostname of your redis instance.
pass undefined The password for your redis instance.
port 6379 Port of your redis instance.

Advanced Configuration

These configuration options provide lower-level access to the underlying Socket.io server settings for complete customizability.

Property Type Default Details
afterDisconnect undefined A function to run when a client-side socket disconnects from the server. To define your own custom logic, specify a function like afterDisconnect: function (session, socket, cb) {}.
allowUpgrades true This is a raw configuration option exposed from Engine.io. It indicates whether to allow Socket.io clients to upgrade the transport that they are using (e.g. start with polling, then upgrade to a true WebSocket connection).
beforeConnect , undefined A function to run every time a new client-side socket attempts to connect to the server which can be used to reject or allow the incoming connection. Useful for tweaking your production environment to prevent DoS attacks, or reject socket.io connections based on business-specific heuristics (e.g. if stooges from a competing business create bots to post spam links about their commercial product in your chat room). To define your own custom logic, specify a function like: beforeConnect: function (handshake, cb) { /* pass back true to allow, false to deny */ return cb(null, true); } As of Sails v0.11, Sails no longer blocks incoming socket connections without cookies-- instead, cookies (and by corollary- sessions) are granted automatically. If a requesting socket.io client cannot receive a cookie (i.e. making a cross-origin socket.io connection) the sails.io.js socket client will automatically send a CORS+JSONP request to try and obtain one BEFORE CONNECTING (refer to the grant3rdPartyCookie option for details). In the antagonistic scenario where even this fails, Sails will still grant a new cookie upon connection, which allows for a one-time session.
cookie , false This is a raw configuration option exposed from Engine.io. It indicates the name of the HTTP cookie that contains the connecting socket.io client's socket id. The cookie will be set when responding to the initial Socket.io "handshake". Alternatively, may be set to false to disable the cookie altogether. Note that the sails.io.js client does not rely on this cookie, so it is disabled (set to false) by default for enhanced security. If you are using socket.io directly and need to re-enable this cookie, keep in mind that the conventional setting is "io".
grant3rdPartyCookie false Whether to expose a GET /__getcookie route that sets an HTTP-only session cookie. By default, if it detects that it is about to connect to a cross-origin server, the Sails socket client (sails.io.js) sends a JSONP request to this endpoint before it begins connecting. For user agents where 3rd party cookies are possible, this allows sails.io.js to connect the socket to the cross-origin Sails server using a user's existing session cookie, if they have one (for example, if they were already logged in.)
maxHttpBufferSize 10E7 This is a raw configuration option exposed from Engine.io. It reflects the maximum number of bytes or characters in a message when polling before automatically closing the socket (to avoid DoS).
path /socket.io Path that client-side sockets should connect to on the server. See http://socket.io/docs/server-api/#server(opts:object).
pingInterval 25000 This is a raw configuration option exposed from Engine.io. It reflects the number of miliseconds to wait between "ping packets" (i.e. this is what "heartbeats" has become, more or less)
pingTimeout 60000 This is a raw configuration option exposed from Engine.io. It reflects how many ms without a pong packet to wait before considering a socket.io connection closed
pubClient undefined When using the socket.io-redis adapter, this option allows you to specify a custom Redis client (typically created with Redis.createClient) used for publishing on channels used by Socket.io. If unspecified, Sails will create a client for you.
sendResponseHeaders true Whether to include response headers in the JWR (JSON WebSocket Response) originated for each socket request (e.g. io.socket.get() in the browser) This doesn't affect direct socket.io usage-- only if you're communicating with Sails via the request interpreter (e.g. making normal calls with the sails.io.js browser SDK). This can be useful for squeezing out more performance when tuning high-traffic apps, since it reduces total bandwidth usage. However, since Sails v0.10, response headers are trimmed whenever possible, so this option should almost never need to be used, even in extremely high-scale applications.
serveClient false Whether to serve the default Socket.io client at /socket.io/socket.io.js. Occasionally useful for advanced debugging.
subClient undefined When using the socket.io-redis adapter, this option allows you to specify a custom Redis client (typically created with Redis.createClient) used for subscribing to channels used by Socket.io. If unspecified, Sails will create a client for you.

Notes

  • In older versions of Sails (<v0.11) and Socket.io (<v1.0), the beforeConnect setting was called authorization.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Sails logo
  • Home
  • Get started
  • Support
  • Documentation
  • Documentation

For a better experience on sailsjs.com, update your browser.

Documentation

Reference Concepts App structure | Upgrading Contribution guide | Tutorials More

Reference

  • Application
    • Events
    • Lifecycle
    • sails.getRouteFor()
    • sails.getUrlFor()
    • sails.lift()
    • sails.load()
    • sails.log()
    • sails.lower()
    • sails.request()
    • sails.getBaseUrl()
  • Blueprint API
    • add to
    • create
    • destroy
    • find one
    • find where
    • populate where
    • remove from
    • update
  • Command Line Interface
    • sails console
    • sails debug
    • sails generate
    • sails lift
    • sails new
    • sails version
  • Configuration
    • sails.config.*
    • sails.config.blueprints
    • sails.config.bootstrap()
    • sails.config.connections
    • sails.config.cors
    • sails.config.csrf
    • sails.config.globals
    • sails.config.http
    • sails.config.i18n
    • sails.config.log
    • sails.config.models
    • sails.config.policies
    • sails.config.routes
    • sails.config.session
    • sails.config.sockets
    • sails.config.views
  • Request (`req`)
    • req.accepted
    • req.acceptedCharsets
    • req.acceptedLanguages
    • req.body
    • req.cookies
    • req.fresh
    • req.headers
    • req.host
    • req.ip
    • req.ips
    • req.isSocket
    • req.method
    • req.options
      • req.options.values
      • req.options.where
    • req.originalUrl
    • req.params
    • req.path
    • req.protocol
    • req.query
    • req.secure
    • req.signedCookies
    • req.socket
    • req.subdomains
    • req.url
    • req.wantsJSON
    • req.xhr
    • req.accepts()
    • req.acceptsCharset()
    • req.acceptsLanguage()
    • req.allParams()
    • req.file()
    • req.get()
    • req.is()
    • req.param()
  • Response (`res`)
    • res.attachment()
    • res.badRequest()
    • res.clearCookie()
    • res.cookie()
    • res.created()
    • res.forbidden()
    • res.get()
    • res.json()
    • res.jsonp()
    • res.location()
    • res.negotiate()
    • res.notFound()
    • res.ok()
    • res.redirect()
    • res.send()
    • res.serverError()
    • res.set()
    • res.status()
    • res.type()
    • res.view()
  • Waterline (ORM)
    • Models
      • .count()
      • .create()
      • .destroy()
      • .find()
      • .findOne()
      • .findOrCreate()
      • .native()
      • .query()
      • .stream()
      • .update()
    • Populated Values
      • .add()
      • .remove()
    • Queries
      • .exec()
      • .limit()
      • .populate()
      • .skip()
      • .sort()
      • .where()
    • Records
      • .save()
      • .toJSON()
      • .toObject()
  • WebSockets
    • Resourceful PubSub
      • .message()
      • .publishAdd()
      • .publishCreate()
      • .publishDestroy()
      • .publishRemove()
      • .publishUpdate()
      • .subscribe()
      • .unsubscribe()
      • .unwatch()
      • .watch()
      • .subscribers()
    • sails.sockets
      • .addRoomMembersToRooms()
      • .blast()
      • .broadcast()
      • .getId()
      • .join()
      • .leave()
      • .leaveAll()
      • .removeRoomMembersFromRooms()
      • sails.sockets.emit()
      • sails.sockets.id()
      • sails.sockets.rooms()
      • sails.sockets.socketRooms()
      • sails.sockets.subscribers()
    • Socket Client
      • io.sails
      • io.socket
      • SailsSocket
        • Methods
        • Properties
      • io.socket.delete()
      • io.socket.get()
      • io.socket.off()
      • io.socket.on()
      • io.socket.post()
      • io.socket.put()
      • io.socket.request()

Built with Love

The Sails framework is maintained by a web & mobile studio 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!

Sails:
  • What is Sails?
  • Treeline IDE
  • Contribute
  • Logos/artwork
About:
  • The Sails Company
  • Security
  • News
  • Legal
Help:
  • Get started
  • Documentation
  • Docs
  • Enterprise
  • Hire us

© 2012-2018 The Sails Company. 
The Sails framework is free and open-source under the MIT License.