Nit-Picking Manager

    @dxos/broadcast
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.13 • Public • Published

    Broadcast

    Abstract module to send broadcast messages.

    Allows a node to originate a message that will be received at least once, within a reasonably short time, on all nodes that are reachable from the origin node. Messages are propagated via the middleware specified. Broadcast storms are avoided by means of a flooding routing scheme.

    Broadcast messages follows the schema:

    message Packet {
      bytes seqno = 1;
      bytes origin = 2;
      bytes from = 3;
      bytes data = 4;
    }
    • seqno: By default is a random 32-bit but could be used to provide an alternative sorted sequence number.
    • origin: Represents the author's ID of the message. To identify a message (msgId) in the network you should check for the: seqno + origin.
    • from: Represents the current sender's ID of the message.
    • data: Represents an opaque blob of data, it can contain any data that the publisher wants it to defined by higher layers (e.g. a presence information message).

    Nodes send any message originating locally to all current peers. Upon receiving a message, a node delivers it locally to any listeners, and forward the message on to its current peers, excluding the peer from which it was received.

    Nodes maintain a record of the messages they have received and originated recently, by msgId(seqno + from). This is used to avoid sending the same message to the same peer more than once. These records expire after some time to limit memory consumption by: maxAge and maxSize.

    graph

    Install

    $ npm install @dxos/broadcast
    

    Usage

    import { Broadcast } from '@dxos/broadcast';
    
    const middleware = {
      subscribe: (onData, updatePeers) => {
        // Defines how to process incoming data and peers update.
    
        // on('peers', onPeers)
        // on('data', onData)
        return () => {
          // Return a dispose function.
        }
      },
      send: async (packet, node) => {
        // Define how to send your packets.
        // "packet" is the encoded message to send.
        // "node" is the peer object generate from the lookup.
      }
    };
    
    const broadcast = new Broadcast(middleware, {
      id: crypto.randomBytes(32),
      maxAge: 15 * 1000, // Timeout for each message in the LRU cache.
      maxSize: 1000 // Limit of messages in the LRU cache.
    })
    
    // We initialize the middleware and subscription inside the broadcast.
    await broadcast.open()
    
    broadcast.publish(Buffer.from('Hello everyone'))
    
    await broadcast.close()

    You can check a real example in: example

    API

    const broadcast = new Broadcast(middleware, [options])

    • middleware: The middleware defines an interface to connect the broadcast to any request/response solution.

      • subscribe: ({ onData, onPeers }) => unsubscribeFunction: Defines how to subscribe to incoming packets and peers update.
        • onData: (data: Buffer) => (Packet|undefined): Callback to process incoming data. It returns true if the broadcast could decode the message or false if not.
        • onPeers: (peers: [Peer]): Callback to update the internal list of peers. A Peer object must follow the spec: { id: Buffer, ...props }
        • unsubscribeFunction: Function: Defines a way to unsubscribe from listening messages if the broadcast stop working. Helpful if you are working with streams and event emitters.
      • send: (packet: Buffer, peer: Object) => Promise: Defines how to send the packet builded by the broadcast.
    • options

      • id: Buffer: Defines an id for the current peer. Default: crypto.randomBytes(32).
      • maxAge: number: Defines the max live time for the cache messages. Default: 10 * 1000.
      • maxSize: number: Defines the max size for the cache messages. Default: 1000.

    broadcast.open() => Promise

    Initialize the cache and runs the defined subscription.

    broadcast.close() => Promise

    Clear the cache and unsubscribe from incoming messages.

    broadcast.publish(data, [options]) -> Promise<Packet>

    Broadcast a flooding message to the peers neighboors.

    • data: Buffer: Any data that you want to broadcast.

    • options

      • seqno: Buffer: Defines a custom seqno for the message. Default: crypto.randomBytes(32).
    • Packet

      • seqno: Buffer
      • origin: Buffer
      • from: Buffer
      • data: Buffer

    Keywords

    none

    Install

    npm i @dxos/broadcast

    Homepage

    dxos.org

    DownloadsWeekly Downloads

    129

    Version

    0.1.13

    License

    MIT

    Unpacked Size

    37.2 kB

    Total Files

    16

    Last publish

    Collaborators

    • zhenya-dxos
    • mykola-vrmchk
    • dxos-bot
    • gcolotti
    • sebikap-gm2
    • richburdon
    • egorgripasov
    • marik_d
    • rzad-p
    • yivlad
    • mesch
    • zarconontol
    • wittjosiah