Skip to content

Latest commit

 

History

History
168 lines (118 loc) · 7.84 KB

readme.md

File metadata and controls

168 lines (118 loc) · 7.84 KB
Raw

Detox transport Travis CI

Transport layer implementation for Detox project.

This library provides transport layer implementation with simple API that:

  • ensures constant data rate on connection
  • supports sending numeric commands with payload
  • compresses payloads of some commands

How to install

npm install @detox/transport

How to use

Node.js:

var detox_transport = require('@detox/transport')

detox_transport.ready(function () {
    // Do stuff
});

Browser:

requirejs(['@detox/transport'], function (detox_transport) {
    detox_transport.ready(function () {
        // Do stuff
    });
})

API

detox_transport.P2P_transport(id : Uint8Array, peer_id : Uint8Array, initiator : boolean, ice_servers : Object[], packets_per_second : number, uncompressed_commands_offset : number) : detox_transport.P2P_transport

Constructor for peer-to-peer transport between 2 nodes in Detox network.

  • id - own ID
  • peer_id - ID of a peer
  • initiator - whether current node initiates connection
  • ice_servers - array of objects as in RTCPeerConnection constructor
  • packets_per_second - packets are sent at constant rate (which together with fixed packet size of 512 bytes can be used to identify bandwidth requirements for specific connection), 1 is minimal supported rate, actual rate is negotiated between 2 nodes on connection
  • uncompressed_commands_offset - commands with number less than this will be compressed/decompressed with zlib

detox_transport.P2P_transport.signal(signal : Uint8Array)

  • signal - as generated by signal event

detox_transport.P2P_transport.update_peer_id(peer_id : Uint8Array)

Allows to change old peer ID to new one, is useful when connection needs to be initialized, but peer's ID is not yet known, so that random ID can be used and then updated to correct one.

detox_transport.P2P_transport.send(command : number, data : Uint8Array)

Send command with some payload to the remote node.

  • command - command from range [0, 255]
  • data - command payload, up to detox_transport.MAX_COMPRESSED_DATA_SIZE bytes for commands below uncompressed_commands_offset and up to detox_transport.MAX_DATA_SIZE bytes for other commands

detox_transport.P2P_transport.destroy()

Destroy instance, disconnect from the remote node.

detox_transport.P2P_transport.on(event: string, callback: Function) : detox_transport.P2P_transport

Register event handler.

detox_transport.P2P_transport.once(event: string, callback: Function) : detox_transport.P2P_transport

Register one-time event handler (just on() + off() under the hood).

detox_transport.P2P_transport.off(event: string[, callback: Function]) : detox_transport.P2P_transport

Unregister event handler.

Event: signal

Payload consists of single Uint8Array argument signal.

Event is fired when signaling data is available and should be sent to remote node.

Event: connected

Event is fired when new remote node is connected.

Event: disconnected

Event is fired when new remote node is disconnected.

Event: data

Payload consists of two arguments: command (number) and data (Uint8Array). Event is fired when new remote node have sent data using send() method.

detox_transport.Transport(id : Uint8Array, ice_servers : Object[], packets_per_second : number, uncompressed_commands_offset : number, connect_timeout : number) : detox_transport.Transport

Constructor for transport object that encapsulates multiple P2P connections and uses P2P_transport under the hood.

  • id - own ID
  • ice_servers - array of objects as in RTCPeerConnection constructor
  • packets_per_second - packets are sent at constant rate (which together with fixed packet size of 512 bytes can be used to identify bandwidth requirements for specific connection), 1 is minimal supported rate, actual rate is negotiated between 2 nodes on connection
  • uncompressed_commands_offset - commands with number less than this will be compressed/decompressed with zlib
  • connect_timeout - how many seconds since signal generation to wait for connection before failing

detox_transport.Transport.create_connection(initiator : boolean, peer_id : Uint8Array) : detox_transport.P2P_transport

Create new connection for peer_id as initiator or responder.

Returns instance of P2P_transport on success.

detox_transport.Transport.get_connection(peer_id : Uint8Array) : detox_transport.P2P_transport

Get connection for peer_id that was already created.

Returns instance of P2P_transport if it was already created or null otherwise.

detox_transport.Transport.update_peer_id(old_peer_id : Uint8Array, new_peer_id : Uint8Array) : boolean

Allows to change old peer ID to new one, is useful when connection needs to be initialized, but peer's ID is not yet known, so that random ID can be used and then updated to correct one.

Returns true if update succeeded (will fail when connection to peer with new_peer_id already exists).

detox_transport.Transport.destroy_connection(peer_id : Uint8Array)

Destroy connection for peer_id.

detox_transport.Transport.signal(peer_id : Uint8Array, signal : Uint8Array)

  • peer_id - as generated by signal event
  • signal - as generated by signal event

detox_transport.Transport.send(peer_id : Uint8Array, command : number, data : Uint8Array)

Send command with some payload to the remote node.

  • peer_id - peer to which sent command
  • command - command from range [0, 255]
  • data - command payload, up to detox_transport.MAX_COMPRESSED_DATA_SIZE bytes for commands below uncompressed_commands_offset and up to detox_transport.MAX_DATA_SIZE bytes for other commands

detox_transport.Transport.destroy()

Destroy instance, disconnect from all of the peers.

detox_transport.Transport.on(event: string, callback: Function) : detox_transport.Transport

Register event handler.

detox_transport.Transport.once(event: string, callback: Function) : detox_transport.Transport

Register one-time event handler (just on() + off() under the hood).

detox_transport.Transport.off(event: string[, callback: Function]) : detox_transport.Transport

Unregister event handler.

Event: signal

Payload consists of two Uint8Array arguments: peer_id and signal.

Event is fired when signaling data is available and should be sent to remote node.

Event: connected

Payload consists of single Uint8Array argument peer_id.

Event is fired when new remote node is connected.

Event: disconnected

Payload consists of single Uint8Array argument peer_id.

Event is fired when new remote node is disconnected.

Event: data

Payload consists of three arguments: peer_id (Uint8Array), command (number) and data (Uint8Array).

Event is fired when new remote node have sent data using send() method.

detox_transport.MAX_DATA_SIZE : number

Constant that defines max data size supported for sending for non-compressed commands (controlled by uncompressed_commands_offset option).

detox_transport.MAX_COMPRESSED_DATA_SIZE : number

Constant that defines max data size supported for sending for compressed commands (controlled by uncompressed_commands_offset option).

Contribution

Feel free to create issues and send pull requests (for big changes create an issue first and link it from the PR), they are highly appreciated!

When reading LiveScript code make sure to configure 1 tab to be 4 spaces (GitHub uses 8 by default), otherwise code might be hard to read.

License

Free Public License 1.0.0 / Zero Clause BSD License

https://opensource.org/licenses/FPL-1.0.0

https://tldrlegal.com/license/bsd-0-clause-license