Class: P2PRouter

P2PRouter(configDataopt)

Transparently routes messages to/from available peer-to-peer interfaces.

Constructor

new P2PRouter(configDataopt)

Creates an instance of P2PRouter.
Parameters:
Name Type Attributes Default Description
configData Object <optional>
 null Application configuration data, usually as loaded at startup.
Source:
See:

Extends

Members

(static) supportedTransports :Object

Contains information on all the transports currently supported or recognized by P2PRouter.
Type:
  • Object
Properties:
Name Type Attributes Default Description
preferred Array <optional>
 ["webrtc","wss","ortc"] Indexed list of transports in the order of default preference (i.e. index 0 is most preferred). The first available preferred transport will be used when communicating with peers unless another order is specified when sending. If defined in the application config, the p2p.transports.preferred array will be used instead of the internal default.
options Object Name-value pairs of transports and their availabilities.
Properties
Name Type Description
webrtc Boolean WebRTC connectivity is available.
wss Boolean WebSocket Sessions connectivity is available.
ortc Boolean ObjectRTC connectivity is available.
sendModel Object Describes how messages sent to multiple recipients should be treated, either "single" (single transport per recipient), or "multi" (shared transport for multiple recipients). Unavailable transports will have a model of "none".
Properties
Name Type Description
webrtc String WebRTC message sending model. Usually "single".
wss String WebSocket Sessions message sending model. Usually "multi".
ortc String ObjectRTC message sending model. Usually "single".
Source:

(readonly) config

Properties:
Name Type Description
config Object Application configuration data, usually loaded at application startup (settings.json file).
Source:

(readonly) peerConnections :Object

Contains PeerConnectionObject for any connected or desired peers, stored by private ID. That is:
peerConnections[privateID]=PeerConnectionObject
Type:
  • Object
Source:

(readonly) peers :Array

A list of currently connected peer IDs gathered from peerConnections.
Type:
  • Array
Source:

privateID :String

The privateID assigned to the session by the rendezvous. This value will be null if no session has been established.
Type:
  • String
Source:

rendezvous :*

A reference to the P2P rendezvous, signalling, and fallback connection handler, or null if no such connection exists or is invalid.
Type:
  • *
Source:

serverToken :String

Server-generated token required by the rendezvous.
Type:
  • String
Source:

userToken :String

Internally-generated user token required by the rendezvous.
Type:
  • String
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, prefTransportsopt) → {Promise}

Sends a routed broadcast message to all connected peers using the first preferred and available peer-to-peer communication transport foe each peer as efficiently as possible.
Parameters:
Name Type Attributes Default Description
data * The data / message to send.
prefTransports Array <optional>
 P2PRouter.supportedTransports.preferred Indexed array of preferred transports to use to send the data / message. Each recipient is evaluated and the first available (lowest index), transport matching this list is used. Shared transports such as WebSocket Sessions are used as efficiently as possible (e.g. sending to multiple recipients with one request).
Source:
Returns:
An asynchronous Promise that will contain the results of all send operations or will throw an error on failure.
Type
Promise

(async) changePrivateID(newPrivateID, allSuccessopt) → {Promise}

Changes the private ID associated with this instance. Any connected peers are notified of this change.
Parameters:
Name Type Attributes Default Description
newPrivateID String The new private ID to set for this instance.
allSuccess Boolean <optional>
 false If true, all attached peers must be successfully notified of the change in order for the returned promise to resolve with true. If false, only the rendezvous server must be successfully updated.
Source:
Returns:
The promise resolves with true if the private ID was successfully changed, otherwise it rejects with false. If allSuccess is true, all connected peers must be successfully notified of the change for the promise to resolve with true, otherwise only the rendezvous server needs to be successfully updated.
Type
Promise

connectPeer(privateID, transportType, requestTimeout)

Requests a direct connection to a peer with a specific transport.
Parameters:
Name Type Default Description
privateID String The private ID of the peer to request the connection to.
transportType String The transport type to request the direct connection on. This should be one of the supported transports listed in P2PRouter.supportedTransports.
requestTimeout Number 20 The number of seconds to wait before considering the request timed out and invalid. The connection status will be set to "failed" after this timer elapses without a successfull connection.
Source:

(async) connectRendezvous(connectInfo)

Establishes a connection to a main / default rendezvous and fallback server. If no such connection is established, the local privateID must be set manually prior to establishing any peer-to-peer connections.
Parameters:
Name Type Description
connectInfo Object An object containing information about the rendezvous/fallback server to connect to. The object must contain at least a type property.
Properties
Name Type Attributes Description
transport String Specifies the type of transport defined by the connectInfo object. This parameter is case-sensitive. Valid types include:
  • wss: WebSocket Sessions
  • wsst: WebSocket Sessions Tunnel
tunnelParams Object <optional>
 Tunneling parameters such as a list of possible endpoints for use with the tunneling connection (if connectInfo.transport="wsst", for example).
Source:
Throws:
Thrown when the specified server could not be contacted or if there is a problem with the connectioInfo parameter.
Type
Error

createSharedTransportGroups(recipients, transports) → {Array}

Creates arrays of privateIDs based on their shared transports.
Parameters:
Name Type Description
recipients Array An indexed array of recipient private IDs. The length of this array match the length of the transports one.
transports Array References to the transports used by the private IDs of the recipients array.
Source:
Returns:
The returned indexed array contains objects, each containing a unique transport reference shared by the private IDs in a recipients array. A null object is returned if the recipients and transports parameter lengths don't match.
Type
Array

createTransportGroups(recipients, preferredopt, onlyAvailopt) → {Object}

Groups private IDs by their preferred or first available transports.
Parameters:
Name Type Attributes Default Description
recipients Array Indexed array of recipient private IDs to group by preferred / available transport.
preferred Array <optional>
 P2PRouter.supportedTransports.preferred Indexed array of preferred transport ordering to use for creating groups.
onlyAvail Boolean <optional>
 true If true, only private IDs with available transports are returned. If false, a special none transport type array is included with all private IDs that have no available transport.
Source:
Returns:
Contains child objects accessible via their transport types (names), with each object containing an indexed recipients array and accompanying transports array. A special object named none contains any recipients without available transports (all null), if onlyAvail=false.
Type
Object

(async) destroy()

Prepares the instance for destruction by closing any open transports, = null; removing references and event listeners, and otherwise cleaning up.
Source:

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

getPCOByTransport(transport) → {PeerConnectionObject}

Returns a PeerConnectionObject contained in peerConnections by one of its transport references.
Parameters:
Name Type Description
transport Object A reference to a specific transport instance for which to return a peerConnections. If this is a shared transport such as WebSocket Sessions instance, the first matching peerConnections object will be returned.
Source:
Returns:
The first object in peerConnections containing a matching transport reference. null is returned if no match can be found.
Type
PeerConnectionObject

getPIDByTransport(transport) → {Object}

Returns a private ID associated with a PeerConnectionObject in peerConnections.
Parameters:
Name Type Description
transport Object A reference to a specific transport instance for which to return a private ID. If this is a shared transport such as WebSocket Sessions instance, the first matching peerConnections's private ID will be returned.
Source:
Returns:
The private ID of the first peerConnections containing a matching transport reference. null is returned if no match can be found.
Type
Object

getPreferredTransport(privateID, preferredopt) → {Object}

Returns the preferred or next available transport for a peer.
Parameters:
Name Type Attributes Default Description
privateID String The private ID of the peer for which to retrieve the transport.
preferred Array <optional>
 ["webrtc","wss","ortc"] The preferred transport order with the first transport being the most preferred. Any transports not included in this list will not be considered.
Source:
Returns:
An object containing a reference to the first preferred transport with an "open" status and its type. If no transport is open then null is returned.
Type
Object

insertPeerConnectionObject(privateID, options, defaultStatus)

Inserts a PeerConnectionObject for a peer into the peerConnections array if one does not already exist.
Parameters:
Name Type Default Description
privateID String The private ID of the peer for which to inert a PeerConnectionObject.
options Object Name-value pairs defining the transports that the peer has advertised as being available for them to use.
defaultStatus String closed The default status to set within the PeerConnectionObject for each option.
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) send(data, recipients, prefTransportsopt) → {Promise}

Sends a routed direct message to one or more connected peers using the first preferred and available peer-to-peer communication transport for each peer as efficiently as possible.
Parameters:
Name Type Attributes Default 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.
prefTransports Array <optional>
 P2PRouter.supportedTransports.preferred Indexed array of preferred transports to use to send the data / message. Each recipient is evaluated and the first available (lowest index), transport matching this list is used. Shared transports such as WebSocket Sessions are used as efficiently as possible (e.g. sending to multiple recipients with one request).
Source:
Returns:
An asynchronous Promise that will contain the results of all send operations or will throw an error on failure.
Type
Promise

setConnectionStatus(privateID, status, transportType, transportopt, removeOnDisconnectopt)

Sets the connection status and transport for a peer within the peerConnections object, stopping any timeout time associated with a pending connection and optionally removing the PeerConnectionObject entirely if no connection on any transport is open.
Parameters:
Name Type Attributes Default Description
privateID String The private ID of the peer for which to set the connection status and transport reference.
status String The status to set for the transportType. Valid types include:
  • "closed": The transport is closed and and unavailable.
  • "pending": The transport is connection is pending / being established.
  • "open": The transport is open and available for bi-directional communication.
  • "failed": An attempt to open the transport for communication has failed.
transportType String The transport type to set the status for. Valid types include:
  • "wss"
  • "webrtc"
  • "ortc"
  • "failed"
transport Object <optional>
 null A reference to the transport associated with the transportType. This reference is assigned to the transport[transportType] property of the PeerConnectionObject.
removeOnDisconnect Boolean <optional>
 true If true, the PeerConnectionObject is automatically removed from the peerConnections object and any event listeners removed if no transport is "open" or "pending".
Source:

Events

message

A peer-to-peer message has been received on one of the routed transports being handled by this instance. Both "direct" and "message" types emit the same event (examine the data property to differentiate).
Type:
  • Event
Properties:
Name Type Description
data Object A native JSON-RPC 2.0 result or notification object.
transportType String The transport type through which the message was received. This should match one of the PeerConnectionObject.options.
transport Object A reference to the transport interface that initially handled the receipt of the message.
Source:

peerconnect

A new peer-to-peer connection has been established.
Type:
  • Event
Properties:
Name Type Description
data Object A native JSON-RPC 2.0 result or notification object.
transportType String The transport type on which the new connection was established. This should match one of the PeerConnectionObject.options.
transport Object A reference to the transport interface on which the new connection was established.
Source:

peerdisconnect

A peer-to-peer connection has closed.
Type:
  • Event
Properties:
Name Type Description
data Object A native JSON-RPC 2.0 result or notification object.
transportType String The transport type on which the connection was previously active established. This should match one of the PeerConnectionObject.options.
transport Object A reference to the transport interface on which the connection was previously active
Source:

peerpid

A connected peer has changed private IDs.
Type:
  • Event
Properties:
Name Type Description
oldPrivateID String The old / previous private ID for the peer.
newPrivateID String The new / changed private ID for the peer.
Source:

update

A server-originating "update" message has been received on one of the routed transports being handled by this instance.
Type:
  • Event
Properties:
Name Type Description
data Object A native JSON-RPC 2.0 result or notification object.
transportType String The transport type through which the message was received. This should match one of the PeerConnectionObject.options.
transport Object A reference to the transport interface that initially handled the receipt of the message.
Source: