Disclaimer

This library is my attempt to make a javascript version of Fred George's (@fredgeorge) RapidsRivers following Zeit's Micro simple bootstrap approach. This is just an experiment at this point.

For more information on the Rapids/Rivers/Ponds paradigm, please refer to the links at the bottom of this file.

Usage

If you learn by looking at code first, check out examples directory.

Now onto the step-by-step:

First, you need to install spring-river as a runtime dependency:

npm install spring-river --save

This library requires an amqp-compatible queue. RabbitMQ works perfectly. In order to configure the queue address, you can either set the environment variable ADDRESS or add the --address (or -a) flag when starting your services and set the address as amqp://….

River

If your microservice is the one generating "solutions", add a {"start": "river"} script, like the following, to your package.json:

{
  "main": "index.js",
  "name": "my-microservice-river",
  "scripts": {
    "start": "river"
  }
}

Your index.js will look like the following. It accepts a packet, which is, for all purposes, a plain javascript object with the packet's contents, and a publish function, which can be used to publish conclusions back to the rapids.

module.exports = (packet, publish) => {
  packet.solution = 10;
  publish(packet);
};

To get you service running, all you need to do is to run:

npm start

Spring

If your microservice is the one generating "needs", add a {"start": "spring"} script, like the following, to your package.json:

{
  "main": "index.js",
  "name": "my-microservice-spring",
  "scripts": {
    "start": "spring"
  }
}

Your index.js will look like the following. It accepts a publish function, which can be used to publish conclusions (a need is a conclusion) to the rapids.

module.exports = (publish) => {
  setInterval(() => {
    publish({need: 'rental_car_offer'});
  }, 5000)
};

To get you service running, all you need to do is to run:

npm start

Predicates

By definition, your exported function will be called whenever a packet arrives (this is so we can keep the bus a dumb pipe). In order to filter out and focus only on interesting packets, you can use decorators around your to-be-exported function. E.g.:

const myFilter = require('./my-filter');

module.exports = myFilter((packet, publish) => {
  packet.solution = 10;
  publish(packet);
});

Where my-filter.js could be something that filters only packets that have {need: 'rental_car_offer'}:

module.exports = (next) => (packet, publish) => {
  if (packet.need === 'rental_car_offer') {
    next(packet, publish);
  }
}

This library ships with a few built-in predicates that you might find useful (perhaps these are candidates to be moved out into their own modules, as these are just very simple functions).

`forbid-keys`: filters out packets that contain any of the given keys;

Parameters: (...string): a list of forbidden keys

`require-keys`: filters out packets that _do not_ contain _all_ given keys;

Parameters: (...string): a list of required keys

`require-values`: filters out packets that _do not_ contain _all_ given key-value pairs;

Parameters: (object): the object with the required key-value pairs

Usage

The following example is interested in packets that contain the {need: 'rental_car_offer'} key-value pair and does not have a solution key:

const predicates = require('spring-river/predicates');
const {requireValues, forbidKeys} = predicates;

module.exports = predicates(
  requireValues({need: 'rental_car_offer'}),
  forbidKeys('solution')
)((packet, publish) => {
  packet.solution = 10;
  publish(packet);
});

Credits

First and foremost, everything here is built based on Fred George's (@fredgeorge) Rapids/Rivers/Ponds paradigm, so here's a list of resources if you want to get more familiar with this idea:

• https://vimeo.com/79866979
• https://youtu.be/2rKEveL55TY
• https://github.com/fredgeorge/rapids_rivers
• https://github.com/fredgeorge/microservice_workshop
• https://www.infoq.com/news/2016/02/not-just-microservices

The structure of this module was inspired by Zeit's Micro, so bin/index.js borrows a lot from it.

License

This software is licensed under the MIT license.

---