data

data @libp2p/observer-data

Helper functions to perform common operations on libp2p Introspection data.

These functions are "vanilla" ES6+ JavaScript (with an ES5 webpack build available) and may therefore be imported and used in React components, in Node.js scripts and in tests alike.

• Usage
• Exported functions by file
  • binary.js
    • parseArrayBuffer( ArrayBuffer )
    • parseBase64( string )
    • parseBuffer( Buffer )
    • parseBufferList( BufferList )
    • parseImport( any )
  • connectionsList.js
    • getAllConnections( Array, { filter: function, latest: boolean } )
    • getAllStreamsAtTime( State )
    • getConnections( State )
    • getMissingClosedConnections( State, Array )
    • getConnectionId( Connection )
    • getConnectionAge( Connection, State )
    • getConnectionTimeClosed( Connection, State )
    • getConnectionTraffic( Connection, direction:string, type:string )
    • getStreams( Connection )
    • getStreamAge( Stream, State )
    • getStreamTimeClosed( Stream, State )
    • getStreamTraffic( Connection, direction:string, type:string )
  • dht.js
  • enums.js
    • getEnumByName( name:string, Object )
    • dhtStatusNames
    • statusNames
    • roleNames
    • transportNames
    • dhtQueryResultNames
    • dhtQueryDirectionNames
    • dhtQueryEventNames
  • events.js
    • getEventType( Event )
    • getEventPropertyLookup( EventType )
    • getEventTypeWithProperties ({ eventType:Object, propertyTypeLookup: Object })
  • runtime.js
    • getRuntimeEventTypes( Runtime )
    • getRuntimeEventProperties( Runtime )
  • states.js
    • getLatestState( Array )
    • getSubsystems( State )
    • getStateIndex( Array, number )
    • getStateRangeTimes( Array )
    • getStateTimes( State )

Usage

An easy way to browse and experiment with the available functions is to:

• Run the libp2p Observer demo app with npm run start:app
• Select a data sample from the UI menu
• Open browser developer tools
• Explore the functions on window.libp2pObs.data

Guidance is printed to the browser console on what data and other resources are available in the global scope.

Exported functions by file

binary.js

parseArrayBuffer( ArrayBuffer )

Decode libp2p Introspection binary data that has been provided as an ArrayBuffer

parseBase64( string )

Decode libp2p Introspection binary data that has been provided as a Base64 string.

parseBuffer( Buffer )

Decode libp2p Introspection binary data that has been provided as a singular buffer.

parseBufferList( BufferList )

Decode libp2p Introspection binary data that has been provided as a BufferList.

parseImport( any )

Decode libp2p Introspection binary data of any supported type.

connectionsList.js

getAllConnections( Array, { filter: function, latest: boolean } )

For an array of States, returns an array containing the earliest occurence of each connection that was at any point present.

If a filter function is passed, connections are passed to this function and excluded if it returns false. If latest is truthy, the latest rather than earliest occurence of each connection is returned.

getAllStreamsAtTime( State )

Returns an array containing an object for each stream present in each connection in a state message, with keys stream for the stream data and connection for the connection the stream is attached to.

getConnections( State )

Returns an array of connections for a state, or an empty array if it is missing the connectionsList subsystem.

getMissingClosedConnections( State, Array )

For a State in an array of States, looks back at earlier States and returns an array of closed connections that are not included in the given State's connectionList.

getConnectionId( Connection )

Returns the id of a connection in string format, allowing comparison between ids using ===.

getConnectionAge( Connection, State )

Returns a number for the number of miliseconds the connection was open in the given State.

getConnectionTimeClosed( Connection, State )

Returns a number for the number of miliseconds the connection had been closed in the given State.

getConnectionTraffic( Connection, direction:string, type:string )

Returns the cumulative traffic of a connection for a given direction ('in' or 'out') and data type ('bytes' or 'packets').

getStreams( Connection )

Returns an array of streams attached to the given Connection.

getStreamAge( Stream, State )

Returns a number for the number of miliseconds the stream was open in the given State.

getStreamTimeClosed( Stream, State )

Returns a number for the number of miliseconds the stream had been closed in the given State.

getStreamTraffic( Connection, direction:string, type:string )

Returns the cumulative traffic of a stream for a given direction ('in' or 'out') and data type ('bytes' or 'packets').

dht.js

The DHT implementation and related introspection data model is currently in flux, so the DHT functions here should be considered unstable until this upstream work is complete.

enums.js

getEnumByName( name:string, Object )

Returns the number corresponding to the given name in the provided Object.

dhtStatusNames

statusNames

roleNames

transportNames

dhtQueryResultNames

dhtQueryDirectionNames

dhtQueryEventNames

Objects inumerating the given names as per the protobuf definition given in @libp2p/observer-proto

events.js

getEventType( Event )

Returns a string of the event's event type name.

getEventPropertyLookup( EventType )

For an EventType message object, returns an object enumerating property types defined in the protobuf, with numeric keys and string values.

getEventTypeWithProperties ({ eventType:Object, propertyTypeLookup: Object })

Returns an array containing an object for each property type of an eventType, with the name and type as strings and a boolean value hasMultiple true if the property can have more than one vlue per event.

runtime.js

getRuntimeEventTypes( Runtime )

Returns an array of objects containing the name and properties (as expanded by getEventTypeWithProperties) of each event type defined in the provided runtime; or an empty array if no runtime is present.

getRuntimeEventProperties( Runtime )

Returns an array of all event properties in all event types in a runtime (as expanded by getEventTypeWithProperties), or an empty array if no runtime is present.

states.js

getLatestState( Array )

For a sorted array of states, returns the most recent, or null if the array is empty.

getSubsystems( State )

Returns the subsystems of a state, such as connectionList and dht, or null if no state is available.

getStateIndex( Array, number )

For an array of states and numeric timestamp, returns the index number of the state that has the given timestamp as its "end" time.

getStateRangeTimes( Array )

For an array of states, returns an object with the start and end timestamps of the earliest and latest State messages, and a duration value for the number miliseconds between these two points; or all values as 0 if the array is empty.

getStateTimes( State )

Returns an object with the start and end timestamps of the State message, and a duration value for the number of miliseconds spanned by the State message.