An error callback
A complete map of ConnectionOptions to values.
The credentials that a session uses to authenticate itself.
A type that can be converted to an int64
Alias for the JSON interface to keep compatibility with old TypeScript definitions
Alias for the JSONDataType interface to keep compatibility with old TypeScript definitions
A reconnection strategy
A Result represents a promise for the result of an async operation.
It implements the full ES6 Promise specification and is in all respects equivalent to a Promise.
Adapted from https://www.npmjs.com/package/@types/es6-promise
Alias for the Options interface to keep compatibility with old TypeScript definitions
A callback function type for Streams
A type that can be converted to a string
A typed array that can be passed as credentials
Emitted when the Stream has been closed through completion or the underlying session has been closed. No further events will be emitted after this.
Emitted when an error occurs in the Stream or in any of its listeners. No further events will be emitted after this.
the error that occurred
Access to the Buffer API that is packaged with diffusion.
This can be used in browsers that don't have a native Buffer class. It allows the creation of buffers for use with binary datatypes.
The build version of this client library
Access to PropertyKeys
Access to the datatypes namespace
The ErrorReason enum
Valid TopicSpecification keys
Access to the locks namespace
Access to the selectors namespace
Access to the topicUpdate namespace
Access to the topics namespace
The version of this client library in the form major.minor.patch
Connect to a specified Diffusion server. This will return a Result that will complete successfully if a session can be connected, or fail if an error was encountered.
If the result is successful, the fulfilled handler will be called with a Session instance. This session will be in a connected state and may be used for subsequent API calls.
If the result fails, the rejected handler will be called with an error reason.
If sessionName and workerJs is supplied, then the call will create a
shared session inside a shared WebWorker. If a shared session with that name
already exists, this function will return an instance of the existing
session. Shared sessions can only be created when running in a browser
environment that supports the SharedWorker. For more information regarding
shared sessions, see connectShared.
Example:
diffusion.connect('example.server.com').then((session) => {
// Connected with a session
console.log('Connected!', session);
}).catch((error) => {
// Connection failed
console.log('Failed to connect', error);
});the options to construct the session with. If a string is
supplied, it will be interpreted as the host option.
the name of the shared session
the location of the diffusion worker script
a Result for this operation
Connect to a specified Diffusion server using a shared WebWorker session. This will return a Result that will complete successfully if a session can be connected, or fail if an error was encountered. Shared sessions can only be created when running in a browser environment that supports the SharedWorker.
Shared sessions are identified by a name. If a shared session with that name already exists, this function will return an instance of the existing session. Otherwise the call will fail. Sessions can only be shared across scripts originating from a single domain. Otherwise the browser will create independent shared workers resulting in one shared session for each domain.
The shared session will stay alive as long as there is an open browser tab that initiated a connection through the shared session. When the last tab is closed the shared worker holding the shared session will be terminated. The shared session is also expected to be terminated when the only tab holding a reference to the session is reloaded or experiences a page navigation. The exact behavior may be browser dependent.
The workerJs argument must be set to the URL of the diffusion-worker.js
supplied with the JavaScript distribution. The same-origin policy of
the shared worker requires the calling script and the diffusion-worker.js
to reside on the same domain.
If the result is successful, the fulfilled handler will be called with a Session instance. This session will be in a connected state and may be used for subsequent API calls.
If the result fails, the rejected handler will be called with an error reason.
Example:
const options = {
host : 'localhost',
port : '8080',
principal : 'admin',
credentials : 'password'
};
diffusion.connect(options, 'some-session', 'diffusion-worker.js').then((session) => {
console.log('Connected creating new shared session', session);
}).catch((error) => {
console.log('Failed to connect', error);
});
diffusion.connectShared('some-session', 'diffusion-worker.js').then((session) => {
console.log('Connected to existing shared session', session);
}.catch((error) => {
console.log('Failed to connect shared', error);
});the name of the shared session
the location of the diffusion worker script
a Result for this operation
Escapes special characters in a string that is to be used within a topic property or a session filter.
This is a convenience method which inserts an escape character '' before any of the special characters ' " or .
the string to be escaped
the string value with escape characters inserted as appropriate
Set the level of logging used by Diffusion. This will default to silent. Log levels are strings that represent different degrees of information to be logged. Available options are:
the log level to use
Create a new BranchMappingTableBuilder.
Create a new RemoteServerBuilder.
Create a new RemoteServerBuilder.
Create a new RemoteServerBuilder.
Create a new RemoteServerBuilder.
Create a new RemoteServerBuilder.
Create a new SessionEventParametersBuilder.
the builder
Create a new SessionMetricCollectorBuilder.
Create a new TopicMetricCollectorBuilder.
Utility method which converts a string of the format required by the $Roles session property into a mutable set of strings.
the string with quoted roles separated by whitespace or commas
set of roles
Returns an update constraint factory.
update constraint factory
Value returned by Session.getPrincipal if no principal name is associated with the session.
Dictionary containing standard session property keys
Example:
// Get the ALL_FIXED_PROPERTIES key
var props = diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES;Example:
// Get all user and fixed properties
var props = diffusion.clients.PropertyKeys.ALL_FIXED_PROPERTIES
.concat(diffusion.clients.PropertyKeys.ALL_USER_PROPERTIES);Enum representing the reason that the session has been closed.
Example:
diffusion.connect({...}).then(function(session) {...}, function(err) {
switch(err) {
case diffusion.clients.CloseReason.CLOSED_BY_CLIENT:
// Do something
case diffusion.clients.CloseReason.ACCESS_DENIED:
// Do something else
...
}
});The connection attempt failed due to a security restraint or due to invalid credentials.
The client requested close. Not recoverable.
The session has been closed by the server, or another session using the ClientControl feature.
The client could not establish a connection to the server.
An error was thrown while the client was attempting to connect to the server.
The connection attempt timed out, waiting for a response from the server.
The reconnection timeout can be controlled by the reconnect options.
There was an error parsing the handshake response.
The client received a handshake response from the server but the response was malformed and could not be deserialised.
The connection handshake was rejected by the server.
The server responded with an unknown error code when the client attempted to connect.
The client detected that the connection was idle.
The client has not received a ping message from the server for an extended period of time.
The connection request was rejected because the license limit was reached.
Loss of messages from the client has been detected. For example, whilst waiting for the arrival of missing messages in a sequence of messages a timeout has occurred.
HTTP based transports use multiple TCP connections. This can cause the messages to be received out of order. To reorder the messages those sent to the server may contain a sequence number indicating the correct order.
If a message is received out of order there is a short time for the earlier messages to be received. If the messages are not received in this time the client is closed.
Missing, invalid or duplicate sequence numbers will also close the client for this reason.
This cannot be recovered from as the client and the server are in inconsistent states.
The handshake response contained an incompatible protocol version.
The server does not support the client's protocol version.
The client version is later than the server version
Whilst disconnected, the client explicitly aborted a reconnect attempt.
There was an unexpected error with the network connection.
The underlying transport (Websocket, XHR) received an error that could not be handled.
Enum containing reason codes used to report error conditions.
Some common ErrorReason values are defined as global constants. More specific reasons may be defined by individual features.
Example:
// Handle an error from the server
session.addStream('foo', diffusion.datatypes.string()).on('error', function(e) {
if (e == diffusion.errors.ACCESS_DENIED) {
// Handle authorisation error
} else {
// Log the problem
console.log(e);
}
});The request was rejected because the caller has insufficient permissions.
An application callback threw an exception. Check logs for more information.
A cluster operation failed because partition ownership changed during processing.
This is a transient error that occurs while the cluster is recovering from failure. The session can retry the operation.
A cluster operation failed to be routed to a server within the cluster due to a communication failure, or the server that owns a partition is not currently known.
This is a transient error that occurs while the cluster is recovering from failure. The session can retry the operation.
Communication with the server failed.
A conflicting registration exists on the server.
An operation failed due to using an incompatible data type.
A topic update could not be performed because the topic is managed by a component (for example,fan-out) which prohibits external updates.
An operation failed because invalid data was received.
An invalid path was supplied.
An operation failed because an addressed session could not be found.
A recipient session has rejected a received message request.
Communication with the server failed because a service request timed out.
Communication with the server failed because the session is closed.
A conflicting registration exists on the same branch of the topic tree.
A sent message was not handled by the specified recipient.
The request was rejected because the requested operation is unsupported for this caller.
The reason that a topic could not be added.
Example:
session.topics.add('foo').then(function() { ... }, function(err) {
switch (err) {
case diffusion.topics.TopicAddFailReason.EXISTS:
...
case diffusion.topics.TopicAddFailReason.INVALID_NAME:
...
}
});When trying to create the topic the cluster was migrating the partition that owns the topic. The correct owner could not be identified and the request failed. This is a transient failure for the duration of the partition migration.
Adding the topic failed because of a license limit.
The topic already exists with the same details.
Adding the topic failed because a topic is already bound to the specified path but the caller does not have the rights to manage it.
This can be because the topic is being managed by a component with exclusive control over the topic, such as fan-out and thus the caller will not be able to update or remove the topic.
If the caller has suitable permissions then it could still subscribe to the topic, but the topic's specification may be different from that requested.
The topic already exists, with different details.
The topic details are invalid.
The supplied topic path is invalid.
Invalid permissions to add a topic at the specified path.
An unexpected error occured while creating the topic.
Enum containing possible Topic Types.
Example:
// Get a topic type for adding topics
var topicType = diffusion.topics.TopicType.JSON;
session.topics.add("foo", topicType);Binary Topic.
This is a stateful topic that handles data in Binary format.
Topic that stores and publishes IEEE 754 double-precision floating point numbers (i.e native JavaScript Numbers). Based on the double data type.
Supports null Double values.
The topic does not support delta-streams - only complete values are transmitted.
Topic that stores and publishes 64-bit integer values. Based on the int64 data type. Values are of the type Int64.
Supports null int64 values.
Does not support delta-streams - only complete values are transmitted.
JSON (JavaScript Object Notation) Topic.
This is a stateful topic that handles data in JSON representation.
Topic that stores and publishes data in the form of records and fields. Based on the RecordV2 data type.
Supports delta-streams.
Topic that stores and publishes String values. Based on the string data type.
Supports null String values.
Supports delta-streams.
Time Series Topic.
A time series is a sequence of events. Each event contains a value and has server-assigned metadata comprised of a sequence number, timestamp, and author.
A time series topic allows sessions to access a time series that is
maintained by the server. A time series topic has an associated
event data type, such as Binary, String,
or JSON, that determines the type of value associated with each
event.
The TIME_SERIES_SUBSCRIPTION_RANGE property configures the range of historic events retained by a time series topic. If the property is not specified, a time series topic will retain the ten most recent events.
The TIME_SERIES_SUBSCRIPTION_RANGE property configures a time series topic to send a range of historic events from the end of the time series to new subscribers. This is a convenient way to synchronize new subscribers without requiring the use of a range query.
By default, new subscribers will be sent the latest event if delta streams are enabled and no events if delta streams are disabled. See the description of Subscription range in the Session.timeseries time series feature} documentation.
The TIME_SERIES_EVENT_VALUE_TYPE property must be provided when creating a time series topic.
A topic type that is unsupported by the session.
Enum containing reasons that an unsubscription occurred.
Example:
// Use UnsubscribeReason to validate unsubscription notifications
session.addStream('>foo', diffusion.datatypes.string())
.on('unsubscribe', function(topic, specification, reason) {
switch (reason) {
case diffusion.topics.UnsubscribeReason.REMOVED :
// Do something if the topic was removed
default :
// Do something else if the client was explicitly unsubscribed
}
});The unsubscription occurred because the session is no longer authorized to access the topic.
The server has a significant backlog of messages for the session, and the topic specification has the conflation topic property set to 'unsubscribe'. The session can resubscribe to the topic. The unsubscription is not persisted to the cluster. If the session fails over to a different server it will be resubscribed to the topic.
The unsubscription occurred because branch mapping rules changed.
The server or another client unsubscribed this client.
The topic was removed
The unsubscription was requested by this client.
A fallback stream has been unsubscribed or subscribed due to the addition or removal of a stream that selects the topic.
The server has re-subscribed this session to the topic. Existing streams are unsubscribed because the topic type and other attributes may have changed.
This can happen if a set of servers are configured to use session replication, and the session connected to one server reconnects ('fails over') to a different server.
A stream that receives an unsubscription notification with this reason will also receive a subscription notification with the new TopicSpecification.
A reason that is unsupported by the session.
The reason that a topic could not be updated.
Example:
session.topics.update('foo', 'bar').then(function() { ... }, function(err) {
switch (err) {
case diffusion.topics.UpdateFailReason.MISSING_TOPIC:
...
case diffusion.topics.UpdateFailReason.EXCLUSIVE_UPDATER_CONFLICT:
...
}
});An update to a replicated topic failed because the cluster was repartitioning due to a server starting, stopping, or failing. The session can retry the operation.
An attempt has been made to apply a delta to a topic that has not yet has a value specified for it.
Attempt to perform a non-exclusive update to a topic branch that already has an update source registered to it.
An update could not be performed because the topic is managed by a component (e.g fan-out) that prohibits updates from the caller.
The update was of a type that is not compatible with the topic it was submitted for, or the topic does not support updating.
The updater used is not active.
An update to a replicated topic failed because the cluster was repartitioning due to a server starting, stopping, or failing. The session can retry the operation.
The topic being updated does not exist.
An update was not performed because the constraint was not satisfied.
The update failed, possibly because the content sent with the update was invalid/incompatible with topic type or data format.
Action to be taken by the system authentication handler for connection attempts that do not provide a principal name and credentials.