Faye

Browser client

Setting up

In order to use the browser client, you’ll need to start up a Faye server to handle message delivery between clients. See the Node.js or Ruby documentation for more information.

With the server up and running, you just need to include the client script in your page. Let’s assume you’ve mounted a server at http://localhost:8000/faye.

<script type="text/javascript" 
        src="http://localhost:8000/faye/client.js">
        </script>

You can then create a client. You should make sure you only create one client per target server, since browsers impose a per-host connection limit and creating more clients will saturate the available connections in many browsers.

To make a client, all you need is the mount point of the server you want to connect to:

<script type="text/javascript">
  var client = new Faye.Client('http://localhost:8000/faye');
</script>

Timeouts

You can optionally specify a timeout; if the server does not send back any data for the given period of time, the client will assume the server has gone away and will attempt to reconnect. Specify the timeout as follows:

var client = new Faye.Client(url, {timeout: 120});

The timeout is given in seconds and should be larger that the timeout you set up on the server side, so we give the server ample time to respond before assuming there’s been a network error.

Retry interval

If the connection to the server is lost, the client will periodically try to reconnect and redeliver dropped messages. You can control how often these retries happen using the retry setting. It sets the amount of time the client will wait between detecting a network error and attempting to resend a message.

var client = new Faye.Client(url, {retry: 5});

Custom headers

Some services require the use of additional HTTP headers to connect to their Bayeux server. You can add these headers using the setHeader() method, and they will be sent if the underlying transport supports user-defined headers (currently long-polling only).

client.setHeader('Authorization', 'OAuth abcd-1234');

Cross-domain operation

Faye clients and servers transparently support cross-domain communication, so your client can connect to a server on any domain you like without further configuration.

Per-transport endpoints

Sometimes, you may need to have the Faye client use different endpoints for different transports. For example, you want to send all normal HTTP traffic to http://example.com/faye but send WebSocket connections to http://ws.example.com/. You can set per-transport endpoints using the endpoints option:

var client = new Faye.Client(url, {
  endpoints: { websocket: 'http://ws.example.com/' }
});

Disabling specific transports

For some applications you may need to exclude some transports from use. For example you may know your deployment environment cannot support WebSockets, or you have reasons to stick to polling. In such situations you can disable a transport like so:

client.disable('websocket');

You can disable any transport, but bear in mind some transports are essential for establishing a connection so disabling them can render the client useless. These mandatory transports are:

• long-polling – Based on XMLHttpRequest, used for same-domain connections
• callback-polling – Based on JSON-P, used for cross-domain connections
• in-process – Used for server-side clients in the same process as the server

Turning off auto-disconnect

When running in a web browser, the client listens to the beforeunload event and sends a disconnection message to the server. If this message is not sent, the server will eventually clean up the client’s data due to inactivity, but having clients explicitly disconnect helps reduce the work the periodic garbage collection has to do.

If this behaviour causes problems for your application, you can stop the client automatically disconnecting like so:

client.disable('autodisconnect');

Logging

You can set a custom logger that will be used to collect logs from Faye. By default there is no logging.

Faye.logger = window.console;