Class: WSSClient

WSSClient(handshakeServerAddressopt)

A WebSocket Session client interface used to connect to peers. Requires RPC and EventPromise to exist in the current execution context.

Constructor

new WSSClient(handshakeServerAddressopt)

Creates an instance of WSSClient.
Parameters:
Name Type Attributes Description
handshakeServerAddress String <optional>
 The address of the WSS handshake server (available as handshakeServerAddr). If not provided and connect is called then the socket server address will be assigned to the handshake server address and used for both.
Source:

Extends

Members

handshakeServerAddr

Properties:
Name Type Description
handshakeServerAddr String The assigned handshake server address of the WSS instance.
Source:

(readonly) peerOptions

Properties:
Name Type Description
peerOptions Object Options objects associated with peer private IDs in the peers list. That is:
peerOptions=optionsObject
Source:

(readonly) peers

Properties:
Name Type Description
peers Array A list of currently connected peers, as managed by this instance.
Source:

privateID

Properties:
Name Type Description
privateID String The privateID assigned to the session by the server. This value may also be derived by hashing (SHA256) a concatenation of the serverToken and userToken.
Source:

serverToken

Properties:
Name Type Description
serverToken String The server-generated user token that is combined with the generated userToken to produce the privateID.
Source:

socketServerAddr

Properties:
Name Type Description
socketServerAddr String The assigned WebSocket server address of the WSS instance.
Source:

userToken

Properties:
Name Type Description
userToken String internally-generated user token that is combined with the returned serverToken to produce the privateID.
Source:

webSocket

Properties:
Name Type Description
webSocket WebSocket The WebSocket object being used for this session.
Source:

Methods

addEventListener(type, listener, contextopt)

Registers a new event listener with the extending class instance.
Parameters:
Name Type Attributes Default Description
type String The event type to register.
listener function The listening function to invoke on the event.
context Object <optional>
 null Unlike the traditional addEventListener parameter, this is the context or scope in which to invoke the listening function (since we can't use capture phases). If null, the listener is invoked in the context of the EventDispatcher or extending instance.
Inherited From:
Source:

(async) broadcast(data, excludeRecipientsopt) → {Promise}

Broadcasts a message to all connected peers.
Parameters:
Name Type Attributes Default Description
data * The data / message to broadcast.
excludeRecipients Object | Array <optional>
 null If not omitted, null, or an empty array this should be an indexed array of recipient private IDs to exclude from the broadcast (if, for example, they will receive the data via another communication channel).
Source:
Returns:
An asynchronous Promise that will contain the result of the broadcast or will throw an error on failure.
Type
Promise

(async) changePrivateID(newPrivateID) → {Promise}

Changes the private ID associated with this connection. The private ID is updated on the server and reflected in the [privateID]privateID property.
Parameters:
Name Type Description
newPrivateID String The new private ID to set for this connection.
Source:
Returns:
The promise resolves with true if the private ID was successfully changed, otherwise it rejects with false.
Type
Promise

(async) connect(socketServerAddropt, useHTTPHandshakeopt, connectDataopt)

Initiates a WebSocket Session by performing a handshake and subsequent connection to the WSS server.
Parameters:
Name Type Attributes Default Description
socketServerAddr String <optional>
 null The WebSocket server address to connect to. If omitted, the assigned handshake server address will be used for both the handshake and the connection.
useHTTPHandshake Boolean <optional>
 false If true, a HTTP / HTTPS request is used for the handshake otherwise the handshake and connection both happen on the same WebSocket connection.
connectData Object <optional>
 null Optional data to include with the connect API call. If omitted or null, an empty object is created and a minimal options object is appended. If included, any user_token and server_token properties will be overriden with handshake WSSClient#userToken and WSSClient#serverToken values.
Properties
Name Type Attributes Default Description
options Object <optional>
 The peer connection options for this connection. If omitted or null a minimal connection options object is created with default values.
Properties
Name Type Attributes Default Description
wss Boolean <optional>
 true Denotes whether (true) or not (false) WebSocket Sessions is supported by the client.
webrtc Boolean <optional>
 false Denotes whether (true) or not (false) WebRTC is supported by the client.
ortc Boolean <optional>
 false Denotes whether (true) or not (false) ORTC is support by the client.
listeners Boolean <optional>
 true If false, socket listeners will not be added by this instance (for example, if this class has been extended).
Source:
Throws:
Thrown when a valid handshake / socket server address was not supplied, or the connection could not be established.
Type
Error

(async) disconnect(codeopt, reasonopt)

Disconnects the client WebSocket and removes any event listeners.
Parameters:
Name Type Attributes Default Description
code Number <optional>
 1000 The disconnection code to close the socket with. Valid status codesmay be found at https://devdocs.io/dom/closeevent#Status_codes
reason String <optional>
 Session terminated by client The brief, human-readable reason why the socket is being disconnected.
Source:
See:

getListeners(type) → {Array}

Returns all registered listeners for a specific event type.
Parameters:
Name Type Description
type String The event type to return registered listeners for.
Inherited From:
Source:
Returns:
A list of registered event listener objects for the specific event. Each object contains a listener function reference and an execution context reference.
Type
Array

(async) handleRequestResponse(expectedResponseID, resolve, resolve)

Handles asynchronous JSON-RPC 2.0 responses made using [request]{@lilnk WSSClient#request} when a responseMsgID is specified,
Parameters:
Name Type Description
expectedResponseID String | Number The expected response ID to match from messages received by the WebSocket.
resolve function A promise resolve function to invoke with the response data when the response ID matches expectedResponseID.
resolve function A promise reject function, Not currently used but may in future be used for timeouts.
Source:

handleSocketClose(eventObj)

Handles WebSocket close events for the WSS instance.
Parameters:
Name Type Description
eventObj Event A "close" event dispatched by the associated WebSocket instance.
Source:

handleSocketMessage(eventObj)

Handles WebSocket message events for the WSS instance. Most events are simply re-broadcast but some such as session messages are handled internally. Listen to "message" events on the WSS's webSocket to receive all messages.
Parameters:
Name Type Description
eventObj Event A "message" event dispatched by the associated WebSocket instance.
Source:

removeEventListener(type, listener, contextopt)

Removes an event listener from the extending instance.
Parameters:
Name Type Attributes Default Description
type String The event type to remove the function from.
listener function The listening function to remove.
context Object <optional>
 null The context or scope in which the listener exists.
Inherited From:
Source:

(async) request(requestObj, responseMsgIDopt) → {Promise}

Sends a routed JSON-RPC 2.0 request using the webSocket.
Parameters:
Name Type Attributes Default Description
requestObj Object The JSON-RPC 2.0 request to send.
responseMsgID String | Number <optional>
 null The message ID if the response to match before the returned promise resolves. If null, the first returned response will resolve, even if it's not the expected response.
Source:
Returns:
An asynchronous promise that will resolve with a JSON-RPC 2.0 response. if responseMsgID is specified, only the response with the matching JSON-RPC id property will cause the promise to resolve,
Type
Promise

(async) send(data, recipients) → {Promise}

Sends a direct message to one or more connected peers.
Parameters:
Name Type Description
data * The data / message to send.
recipients Object | Array An object or an array of recipient private IDs. If this parameter is an object, one or more additional properties are expected:
Properties
Name Type Attributes Description
rcp Array <optional>
 An indexed array of recipient private IDs. If this list is provided as the recipients parameter this structure is dynamicaly generated before sending.
Source:
Returns:
An asynchronous Promise that will contain the result of the send or reject with an Error object on failure.
Type
Promise

(async) SHA256(input) → {Promise}

Produces a SHA-256 hash of an input string. The output of this implementation should match the output of Node.js' built-in SHA-256 hash (crypto module).
Uses the SubtleCrypto interface of the Web Cryptography API.
Parameters:
Name Type Description
input String The string to hash.
Source:
See:
Returns:
A promise containing a hex-encoded result of the SHA-256 hash of the input.
Type
Promise

Events

message

A message has been received from a peer via the WSS server. This may either be a direct message or a broadcast.
Type:
  • Event
Properties:
Name Type Description
data Object The parsed JSON-RPC 2.0 object containing the received message.
Source:

peerconnect

A new peer has connected to the WSS server.
Type:
  • Event
Properties:
Name Type Description
data Object The parsed JSON-RPC 2.0 object received in the notification.
Source:

peerdisconnect

A peer has disconnected from the WSS server.
Type:
  • Event
Properties:
Name Type Description
data Object The parsed JSON-RPC 2.0 object received in the notification.
Source:

peerpid

The private ID of a connected peer has changed and the internal peers list has been updated.
Type:
  • Event
Properties:
Name Type Description
data Object The parsed JSON-RPC 2.0 object containing the change notification.
oldPrivateID String The old / previous private ID of the peer.
newPrivateID String The new / changed private ID of the peer.
Source:

privateid

The private ID of this connection has changed and a notification has been sent to the connected peer.
Type:
  • Event
Properties:
Name Type Description
privateID String The new private ID for this connection.
Source:

update

An update notification has been received from the WSS server.
Type:
  • Event
Properties:
Name Type Description
data Object The parsed JSON-RPC 2.0 object containing the received message.
Source: