@detox/transport
v0.38.3
Published
Transport layer implementation for Detox project
Downloads
16
Maintainers
Readme
Detox transport
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 IDpeer_id
- ID of a peerinitiator
- whether current node initiates connectionice_servers
- array of objects as in RTCPeerConnection constructorpackets_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 connectionuncompressed_commands_offset
- commands with number less than this will be compressed/decompressed with zlib
detox_transport.P2P_transport.signal(signal : Uint8Array)
signal
- as generated bysignal
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 todetox_transport.MAX_COMPRESSED_DATA_SIZE
bytes for commands belowuncompressed_commands_offset
and up todetox_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 IDice_servers
- array of objects as in RTCPeerConnection constructorpackets_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 connectionuncompressed_commands_offset
- commands with number less than this will be compressed/decompressed with zlibconnect_timeout
- how many seconds sincesignal
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 bysignal
eventsignal
- as generated bysignal
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 commandcommand
- command from range[0, 255]
data
- command payload, up todetox_transport.MAX_COMPRESSED_DATA_SIZE
bytes for commands belowuncompressed_commands_offset
and up todetox_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