• 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 depends on whether secure connections are enabled, or if the client is being run in a page served via `http` or `https`.
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 no `port` option is specified, this will also determine the port to use.

Reconnection is enabled by default, and 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` ``` 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.

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 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 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.

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")