Class: WSSTunnel

WSSTunnel(handshakeServerAddressopt)

A tunneling WebSocket Sessions interface based on WSSClient. Once established, a tunneled connection appears and behaves nearly identically to a WSSClient connection.

Constructor

new WSSTunnel(handshakeServerAddressopt)

Creates an instance of WSSTunnel.
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.
Inherited From:
Source:

(readonly) peerOptions

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

(readonly) peers

Properties:
Name Type Description
peers Array A list of currently connected peers, as managed by this instance.
Inherited From:
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.
Inherited From:
Source:

serverToken

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

socketServerAddr

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

tunnelInfo

Properties:
Name Type Default Description
tunnelInfo Object null Contains a userToken, serverToken, and privateID used to establish a connection with the tunneling server. Use these credentials when communicating with the tunneling server instead of the standard class properties which are used with the tunneled endpoint.
Source:

userToken

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

webSocket

Properties:
Name Type Description
webSocket WebSocket The WebSocket object being used for this session.
Inherited From:
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).
Inherited From:
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.
Inherited From:
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, connectData)

Creates a WebSocket Session tunnel by performing a handshake, subsequent connection to the WSS server, opening the tunnel, and finally connecting to the tunneled server endpoint via connectEndpoint
Parameters:
Name Type Attributes Default Description
socketServerAddr String <optional>
 null The WebSocket Sessions tunneling 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 Data to include with the connect and tunelling API calls
Properties
Name Type Attributes Description
tunnelParams Object <optional>
 An object containing the tunelling parameters.
Properties
Name Type Attributes Description
endpoint Object <optional>
 An object containing the tunneling endpoint candidates and associated parameters.
Properties
Name Type Attributes Description
aliases Array <optional>
 An indexed array of tunnel candidate aliases (usually based on the endpoint private ID). The connection process will attempt to connect to each alias in the order provided.
Overrides:
Source:
Throws:
Thrown when a valid handshake / socket server address was not supplied, tunelling information was omitted or erroneous, or the connection could not be established.
Type
Error

(async) connectEndpoint(connectDataopt)

Attempts to connect to a tunneled WebSocket Sessions endpoint. Existing userToken, serverToken, and privateID values will be replaced with ones generated for / by the endpoint.
Parameters:
Name Type Attributes Default Description
connectData Object <optional>
 null Endpoint and peer connection information.
Properties
Name Type Attributes Description
options Object <optional>
 Peer connectivity options to advertise to other peers through the endpoint.
Properties
Name Type Attributes Default Description
wss Object <optional>
 true Defines if WebSocket Sessions connectivity is available (true), or not (false).
webrtc Object <optional>
 false Defines if WebRTC connectivity is available (true), or not (false).
ortc Object <optional>
 false Defines if ObjectRTC connectivity is available (true), or not (false).
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
Source:

handleSocketMessage(eventObj)

Handles WebSocket message events for the tunnel. Any messages that are not tunnels-specific are passed to the parent WSSClient.handleSocketMessage function.
Parameters:
Name Type Description
eventObj Event A "message" event dispatched by the tunneled WebSocket instance.
Overrides:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
Source: