• Public
  • Public/Protected
  • All

Interface Options

Provide Session configuration options.

There are several option values that can be configured to change how Diffusion establishes a connection. These options are used to derive a connection URL in the format: {protocol}://{host}:{port}/{path}. The protocol used is determined by the chosen transports and whether secure connections are enabled.
Option Default value Description
host localhost The hostname to connect to.
port 80 or 443 The port to connect to. The default value is the default secure port if secure connections are enabled, otherwise the default value is the default insecure port.

In case the client is being run in a page served via https (http), the default secure (insecure) port is the port of the URI of the current page, otherwise the default secure (insecure) port is 443 (80).

path /diffusion The URL path to apply after the hostname/port. This allows additional context to be provided, such as might be used by load balancers.
secure true Determines if secure transports will be used. If the port is not explicitly specified this value defaults to true. If the port is explicitly specified the default value is true only if the port is equal to the default secure port, otherwise false.

In case the client is being run in a page served via https, the default secure port is the port of the URI of the current page, otherwise the default secure port is 443.


Reconnection is enabled by default. The reconnect key accepts several different option values.

Option type Default value Description
boolean true Enables or disables reconnection. If set to true, reconnection will be enabled using the default timeout value and a periodic back-off strategy.
number 60000 Passing a number will enable reconnection with the default strategy and the reconnection timeout set to the specified value. The reconnection timeout determines how long, in milliseconds, the client will remain in a disconnected state before the client is closed.
function(reconnect, abort) {
    setTimeout(reconnect, 5000);
A strategy function that will be called when the client enters a disconnected state, and subsequently if attempts to reconnect fail. Two arguments are provided, reconnect and abort - these are functions to be called within the strategy. The reconnect argument will initiate a reconnect attempt. abort may be called to abort reconnection, in which case the client will be closed.
    timeout : <number>,
    strategy : <function>
    timeout : 60000,
    strategy : function(reconnect, abort) {
        setTimeout(reconnect, 5000);
An object containing both the timeout and strategy options as specified above, allowing both to be set together.

The transports property configures how the session should connect. It can be set to either a string, or an array of strings to provide a transport cascading capability.

Transport key Description
ws, WS, WEBSOCKET The WebSocket transport. A single, long-lived WebSocket connection will be used to send and receive data.
xhr, XHR, HTTP_POLLING An XHR-based polling transport. Data will be queued on the client and server, and sent in batches.
The client will use the transports in the order provided, for example: transports: ['WS', 'XHR'] indicates that the client will attempt to connect with the WebSocket transport, and if the connection fails, the client will attempt to connect with the HTTP Polling transport. When no transports value is provided the client will default to using the WebSocket transport. Any string values that do not have an associated transport will be ignored.

When the diffusion client is run in a browser environment, transports will default to ['WEBSOCKET', 'XHR']. When run in Node, transports will default to ['WEBSOCKET'].


Supplied session properties will be provided to the server when a session is created using this session factory. The supplied properties will be validated during authentication and may be discarded or changed.

The specified properties will be added to any existing properties set for this session factory. If any of the keys have been previously declared then they will be overwritten with the new values.

For details of how session properties are used see Session.


  • Options



Optional connectionTimeout

connectionTimeout: undefined | number

The timeout in milliseconds used when connecting to the server. (default 10000)

Optional credentials

credentials: string | Buffer | TypedArray | number[]

A password string to authenticate with, a buffer containing custom credentials in binary format, a typed array, or a regular array of octets.

Optional host

host: undefined | string

The hostname to connect to (default 'localhost')

Optional httpProxyAgent

httpProxyAgent: any

An optional HTTP/HTTPS proxy agent. (default undefined)

If this is set, then the client will attempt to connect to the Diffusion server via a proxy server.

The proxy agent will be passed to the WebSocket constructor as the agent option. See https://www.npmjs.com/package/https-proxy-agent for an example of a proxy agent.

This option is used for web socket connections and is intended for Node based clients only. Browser based clients will automatically use the browser's proxy settings.


const HttpsProxyAgent = require('https-proxy-agent');
const url = require('url');
const diffusion = require('diffusion');

const agent = new HttpsProxyAgent(url.parse('https://proxy.example.com:80'));

  host: 'https://diffusion.foo.com',
  httpProxyAgent: agent
}).then((session) => {
 // connected through proxy server

Optional maxMessageSize

maxMessageSize: undefined | number

The maximum size of messages that may be received from the server. (default 2147483647)

Optional path

path: undefined | string

The request path used for connections (default /diffusion)

Optional port

port: number | string

The port to connect to (default 443)

Optional principal

principal: undefined | string

The principal name this session should connect with. Used for authentication.

Optional properties

properties: undefined | object

An object of key-value pairs that define the user-defined session properties.

Property values will be sent as string values. Non-string properties must implement the toString() method to allow conversion.

For details of how session properties are used see Session.

Optional reconnect

reconnect: boolean | number | ReconnectStrategy | object

Reconnection options. (default true)

Optional secure

secure: undefined | false | true

Whether to use secure connections.

Optional transports

transports: string | string[]

The transports to be used for connection establishment. (default "WEBSOCKET")