Faye

Simple pub/sub messaging for the web

Node.js server

Server-side Node.js clients

You can use Faye clients on the server side to send messages to in-browser clients or to other server-side processes. The API is identical to the browser client.

To create a client, just supply the host you want to connect to:

var client = new faye.Client('http://localhost:8000/faye');

You can then use client.subscribe() and client.publish() to send messages to other clients; see the browser client documentation for more information.

The server has its own client attached to it so you can use the server to send messages to browsers. This client has direct access to the server without going over HTTP, and is thus more efficient. To send messages through the server just use the #getClient() method.

bayeux.getClient().publish('/email/new', {
  text:       'New email has arrived!',
  inboxSize:  34
});

Transport control

When using the client on the server, you can control parts of the transport layer that the browser doesn’t provide access to. For a start, headers added using the client.setHeader() method will be added to WebSocket connections, not just regular HTTP requests.

For the transport layer, the server-side client uses the Node.js https and tls modules to handle HTTPS endpoints. If you need to configure anything about the TLS connection, use the `tls` option which is passed through to tls.connect(). For example, to set your own root certificate instead of using the system defaults:

var client = new faye.Client(url, {
  tls: {
    ca: fs.readFileSync('path/to/certificate.pem')
  }
});

You can also request that all connections go via an HTTP proxy:

var client = new faye.Client(url, {
  proxy: 'http://username:password@proxy.example.com'
});

You can also set the http_proxy or https_proxy environment variables, which will make all Faye client connections use the given proxy by default; http_proxy for http: and ws: requests, and https_proxy for https: and wss: requests.

Finally, the WebSocket transport can be configured to use protocol extensions; any extension library compatible with websocket-extensions will work. For example, to add permessage-deflate:

var deflate = require('permessage-deflate');

client.addWebsocketExtension(deflate);