(Rata)Toskr

In Norse Mythology, Ratatoskr is the squirrel whos runs up and down Yggdrasil, the tree of life, and carries angry messages between Níðhöggr(the worm who lives in the roots of Yggrasil), and the eagle which lives on the top most branches of the tree. From the Prose Edda

An eagle sits at the top of the ash, and it has knowledge of many things. 
Between its eyes sits the hawk called Vedrfolnir [...]. The squirrel called Ratatosk [...]
runs up and down the ash. He tells slanderous gossip, provoking the eagle and Nidhogg.

What?

(Rata)Toskr, the crap-talking squirrel, is obviously a fantastic messanger god and in our system it's no different. Toskr allows communication between the various services in our system, all through a centralized Pub Sub(Nats) server.

Nats' most fundamental functionality is the publishing of and subscription to messages on various channels known as topics.

For example: Say a user in our system just created a post. The topic might be "user.created.post" and the message associated with this event might be a json string containing information about the user, the post, and the event in general.

With this library, you can easily publish these messages, specifying both the topic and the message.

You can also easily subscribe to all topics which your service is interested in.

Assumptions

The default configuration assumes that you have a local running Nats server listening on port 4222 However, this is fully configurable.

If you want to avoid an outside connection to Nats (say, for testing) there is a mock nats implementation

Installation

If available in Hex, the package can be installed by adding toskr to your list of dependencies in mix.exs:

def deps do
  [
    {:toskr, "~> 0.1.0"},
  ]
end

Publishing

Subscribing

Subscribing is done through the TopicRouter, a module in which the messages from a given topic can be routed into any specified function. The topics given in the router must be unique as each one acts as the global name of the listener process which will actually receive the message from our Nats server

Testing

If you want your app to not connect to an actually nats server, there is a mock of the gnat hex which will make no external api calls. This mock module is called Mat (mock-Gnat) To do this, in your test.exs:

config :toskr,
  nats_client: Mat,

Configuration

Toskr is fully configurable using environment variables.

ENV Var	Default
NATS_HOST	127.0.0.1

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/toskr.