ataraxia

ataraxia

Mesh networking with peer-to-peer messaging for NodeJS and the browser. Ataraxia connects different instances together and allows messages to be passed between these instances. Some instances may act as routers for other instances to create a partially connected mesh network.

Features

• Instances can send and receive messages from other instances
• Partially connected mesh network, messages will be routed to their target
• Authentication support, anonymous and shared secret authentication available in core
• RPC support via ataraxia-services that lets you call methods and receive events from services registered anywhere in the network
• Support for different transports
  • ataraxia-local provides a machine-local transport
  • ataraxia-tcp provides a TCP-based transport with customizable discovery of peers and encrypted connections
  • ataraxia-ws-client and ataraxia-ws-server for websockets
  • ataraxia-hyperswarm provides a transport that uses Hyperswarm to connect to peers over the public Internet

Example with TCP transport

import { Network, AnonymousAuth } from 'ataraxia';
import { TCPTransport, TCPPeerMDNSDiscovery } from 'ataraxia-tcp';

// Setup a network with a TCP transport
const net = new Network({
  name: 'name-of-your-app-or-network',
  
  transports: [

    new TCPTransport({
      // Discover peers using mDNS
      discovery: new TCPPeerMDNSDiscovery(),

      // Setup anonymous authentication
      authentication: [
        new AnonymousAuth()
      ]
    })
  
  ]
});

net.onNodeAvailable(node => {
  console.log('A new node is available:', node.id);
  node.send('hello');
});

net.onMessage(msg => {
  console.log('A message was received', msg.type, 'with data', msg.data, 'from', msg.source.id);
});

// Start the network
await net.start();

Example with machine-local transport and TCP transport

This example creates a network where instances on the same machine connect to each other locally first and then elects one instance to handle connections to other machines on the same network.

import { Network, AnonymousAuth } from 'ataraxia';
import { TCPTransport, TCPPeerMDNSDiscovery } from 'ataraxia-tcp';
import { MachineLocalTransport } from 'ataraxia-local';

// Setup a network
const net = new Network({
  name: 'name-of-your-app-or-network'
});

net.addTransport(new MachineLocalTransport([
  onLeader: () => {
    /*
    * The leader event is emitted when this instance becomes the leader
    * of the machine-local network. This instance will now handle
    * connections to other machines in the network.
    */
    net.addTransport(new TCPTransport({
      discovery: new TCPPeerMDNSDiscovery(),

      authentication: [
        new AnonymousAuth()
      ]
    }));
  }
]);

await net.start();

API

Network

• new Network(options)

  Create a new network using the given options.

  • options
    • name: string, name of the network, should be short and describe the app or library.
    • transports?: Transport[], transports to start with
    • endpoint?: boolean, request that the local node is an endpoint that should not perform routing.

• networkId: string

  The automatically generated id of this node.

• start(): Promise<Boolean>

  Returns: true if network was started, false otherwise

  Start the network and its transports. This will start up all transports and perform initial connections to peers.

• stop(): Promise<Boolean>

  Returns: true if network was stopped, false otherwise

  Stop the network and its transports. This will attempt to gracefully disconnect to the current peers and shut down the transports.

• addTransport(transport: Transport): void

  Add a transport that should be used. Used in addition to providing transports in the constructor to allow for dynamic configuration. If the network has been started this will start the transport asynchronously.

• onNodeAvailable(callback: (node: Node) => void)

  A node has been found and messages can now be sent and received to/from it.

• onNodeUnavailable(callback: (node: Node) => void)

  A node is no longer available.

• onMessage(callback: (message: Message) => void)

  A message has been received from a node.

Node

• id: string

  The id of the node.

• onUnavailable(callback: () => void)

  Event emitted when node is no longer available.

• onMessage(callback: (message: Message) => void)

  Event emitted when a message has been received from this node.

• send(type: string, data: any): Promise<void>

  Send a message of the given type with the specified data to the node.

Message

• source: Node

  The node that sent the message. Can be used to send an answer back.

• type: string

  The type of the message.

• data: any

  The data of the message.