Piper Push Cache Documentation Download Samples Contact  

NATS Content Based Router

The NATS Content Based Router sample is a simple example of how to use Piper Push Cache as a content based router for the NATS messaging system. It makes use of the process flow feature of Piper as well as the NATS message support of Piper.

What it does

A content based router receives messages and then re-publishes them on a different subject according to the content of the message. In this sample the message is also enhanced with a unique identifier. That is not required but demonstrates another capability of Piper.

When a messages arrive on the subject 'sample.>' it is enhanced with the addition of a unique identifier and published out on a subject form from the 'kind' and 'id' fields of the outgoing message. All messages are JSON messages.

Content based routing is often used to sort and direct messages to applications developed for processing specific messages. It allows for separating development efforts and encapsulating processing for each kind of message.

How it does it

Piper configuration defines the behavior and is used to set up Piper as a content based router. The nats_router_cfg.json file is the configuration file for the router.

The NATS portion of the configuration must be set up to receive NATS messages on what ever the desired topic is. The NATS configuration section is also where the new 'id' field is specified. In this case a time based identifier is generated and added to the incoming message.

Once the NATS portion of the configuration is specified the processing steps for the messages must be defined. A group is defined for incoming NATS messages. Note the 'group_filter_msg_only' option that indicates the full event is used for filter rules on the groups. The 'router' group defines a filter that accepts only records from a NATS connection. The group also specifies that the 'nats_router' process flow should be used for processing the records in the group.

The process flow that will be followed is in the 'nats_router.flow' file. The flow file defines two tasks in the flow. The first writes the record to the change log. The second republishes the message on 'out.<kind>.<id>' where the kind and id are taken from message being published.

To facilitate the running of the sample two basic ruby applications are included. One, listen.rb listens on a subject and prints messages received to the console. The other, publish.rb publishes messages.


[NATS](http://nats.io) must be installed before running the NATS router sample.


The gnatsd server can be started in the background using the default settings. This will allow applications to connect to is on localhost:4222.

$>gnatsd &

Routed messages will be published on 'out.>'. Start up the listener in a console window. The publshed messages will be display on that console.

$> ./listen.rb "out.>"

Next Piper Push Cache is started. Start from the downloaded piper folder.

$> bin/piper -c samples/nats_router/nats_router_cfg.json

Now publish some messages. Note they should all be valid JSON. The publish.rb script checks before publishing. Try a message that includes a 'kind' field.

$> ./publish.rb -s sample.feed '{"kind":"Log","what":"all okay","level":3}'

The listen console should display something like the following with a different 'id'.

out.Log.160301201920552076: {"kind":"Log","what":"all okay","level":3,"id":"160301201920552076"}

Now a message published on some other subject not subscribed to.

$> ./publish.rb -s ignore.feed '{"kind":"Log","what":"all okay","level":3}'

Nothing should appear on the listen console since the subject is not subscribed to.

Try a different kind of message.

$> ./publish.rb -s sample.feed '{"kind":"Status","what":"all okay"}'

The listen console should display something like the following with a different 'id'.

out.Status.160301202354987173: {"kind":"Status","what":"all okay","id":"160301202354987173"}

Building on the sample

There are many ways of extending this sample. Some of the changes include