A [Seneca.js][] plugin

@seneca/mesh

	This open source module is sponsored and supported by Voxgig.

Install

To install, use npm

npm install seneca-balance-client
npm install seneca-mesh

The seneca-mesh plugin depends on the seneca-balance-client plugin.

And in your code:

require('seneca')()
  .use('mesh', { ... options ... })

Using Windows? seneca-mesh uses some native modules, so make sure to configure msbuild.

Quick Example

Create a microservice. The service translates color names into hex values.

// color-service.js
var Seneca = require('seneca')

Seneca()
  // Uncomment to get detailed logs
  // .test('print')
  
  // provide an action for the format:hex pattern
  .add('format:hex', function (msg, reply) {

    // red is the only color supported!
    var color = 'red' === msg.color ? '#FF0000' : '#FFFFFF'

    reply({color: color})
  })

  // load the mesh plugin
  .use('mesh', {

    // this is a base node
    isbase: true,

    // this service will respond to the format:hex pattern
    pin: 'format:hex'
  })

Run the service (and leave it running) using:

$ node color-service.js

Create a client for the service. This client joins the mesh network, performs an action, and then leaves.

// color-client.js
var Seneca = require('seneca')

Seneca({log: 'test'})

  // load the mesh plugin
  .use('mesh')

  // send a message out into the network
  // the network will know where to send format:hex messages
  .act({format: 'hex', color: 'red'}, function (err, out) {

    // prints #FF0000
    console.log(out.color)
  })

Run the client in a separate terminal using:

$ node color-client.js

The client finds the service using the mesh network. In this simple case, the color-service is configured as a base node, which means that it listens on a pre-defined local UDP port. The client checks for base nodes on this port.

Notice that the client did not need any infomation about the service location.

To join a network, you do need to know where the base nodes are. Once you've joined, you don't even need the bases anymore, as the network keeps you informed of new services.

To find base nodes, seneca-mesh provides support for discovery via configuration, multicast, service registries, and custom approaches. Base nodes are not used for service discovery. They serve only as a convenient means for new nodes to join the network.

In the above example, UDP multicast was used by default. In production you'll need to choose a discovery mechanism suitable for your network.

The examples folder contains code for this example, and other scenarios demonstrating more complex network configurations:

• local-dev-mesh: local development, including a web service API.
• multicast-discovery: multicast allows base nodes to discover each other - zero configuration!
• consul-discovery: base node discovery using a service registry, when multicast is not available.

As a counterpoint to mesh-based configuration, the local-dev example is a reminder of the burden of traditional service location.

More Examples

See test/ for usage examples.

Motivation

This plugin adds network discovery to Seneca microservices. Nodes find each other automatically using gossip networking.

Support

If you're using this module and need help, you can:

• Post a [github issue][]
• Tweet to [@senecajs][]

API

Options

The seneca-mesh plugin accepts the following set of options. Specify these when loading the plugin:

require('seneca')
    .use('mesh', {
      // options go here
    })

The options are:

• isbase: Make this node a base node. Default: false.

• bases: An array of pre-defined base nodes. Specify strings in the format: 'IP:PORT'. Default: [].

• pin: the action pattern that this service will respond to. Default: null

• listen: an array of action patterns that this service will respond to. Default: null

• stop: base node discovery stops as soon as a discovery strategies provides a list of suggested nodes. Default: true

• discover: define the base node discovery options:

  • defined: use defined base nodes, specified via the bases option.

    • active: activate this discovery strategy. Default: true

  • custom: provide a function with signature function (seneca, options, bases, next) that returns an array of base nodes. See unit test single-custom for an example.

    • active: activate this discovery strategy. Default: true

    • find: the custom function

  • registry: use the role:registry patterns to load the list of base nodes. Set to false to disable. Default is a set of sub-options - see code for details.

    • active: activate this discovery strategy. Default: true

  • multicast: base nodes broadcast their existence via IP multicast. New services briefly listen to the broadcast to get the list of base nodes, and then drop out. This keeps broadcast traffic to a minimum. Note: you need to get the broadcast address right for your network - time to run ifconfig -a!

    • active: activate this discovery strategy. Default: true

    • address: the broadcast address of the network interface used for multicast.

  • guess: Guess the location of a base by assuming it is on the same host. Default: true.

    • active: activate this discovery strategy. Default: true

Contributing

The [Senecajs org][] encourages open participation. If you feel you can help in any way, be it with documentation, examples, extra testing, or new features please get in touch.

Running tests

npm run test

Background

Uses SWIM gossip protocol for peer discovery.

[![npm version][npm-badge]][npm-url] [![Build Status][travis-badge]][travis-url] [![Gitter][gitter-badge]][gitter-url] swim module that makes this [senecajs.org][]. We have everything from tutorials to sample apps to [configure local-dev example is a reminder of the multicast-discovery example, the HTTP transport by default. To [MIT]: ./LICENSE [npm-badge]: https://badge.fury.io/js/seneca-mesh.svg [npm-url]: https://badge.fury.io/js/seneca-mesh [Seneca.js org]: https://github.com/senecajs/ [Seneca.js]: https://www.npmjs.com/package/seneca [@senecajs]: http://twitter.com/senecajs [senecajs.org]: http://senecajs.org/ [travis-badge]: https://travis-ci.org/senecajs/seneca-mesh.svg [travis-url]: https://travis-ci.org/senecajs/seneca-mesh [gitter-badge]: https://badges.gitter.im/Join%20Chat.svg [gitter-url]: https://gitter.im/senecajs/seneca [github issue]: https://github.com/senecajs/seneca-mesh/issues [Balance]: https://github.com/senecajs/seneca-balance-client [Lead]: https://github.com/senecajs/ [Sponsor]: http://nearform.com [CoC]: http://senecajs.org/contribute/details/code-of-conduct.html [SWIM gossip algorithm]: https://www.cs.cornell.edu/~asdas/research/dsn02-swim.pdf