README.md

Watchmen

Lots of systems have state.
They store data, and sometimes that data changes.

We believe that whenever data changes, other systems have a right to know.
It should be easy to subscribe to change notifications from any system which stores mutable data.

The Watchmen project offers a platform for propagating change notifications.

Installing Watchmen

Watchmen runs on Node.js and primarily uses RabbitMQ for publishing and dispatching messages.
If you already have Node.js installed and you have a RabbitMQ server ready to target, you can install watchmen through npm:

$ npm install -g watchmen # to run the CLI
$ npm install watchmen $ to run it programatically

This will make the watchmen command available via the command line.
You can confirm that watchmen is installed correctly by passing the -h parameter.

Watchmen expects incoming objects to have a routingKey and a message body.
The routingKey is a dot delimited string used for routing messages between exchanges and queues in RabbitMQ.
If you're not familiar with these concepts, see RabbitMQ Basics for Watchmen below.

Watchmen doesn't care what's in the message body; it can be anything, even a binary blob of bytes.
In the previous example, it's an object with properties that are meaningful to the catalog.

Using Watchmen

Even though watchmen supports a number of input and output types, watchmen's messaging patterns are based on RabbitMQ.

RabbitMQ Basics for Watchmen

RabbitMQ is a robust messaging system that implements the AMQP protocol.
Libraries are available for a wide variety of languages, making it easy to develop against.

If you'd really like to understand RabbitMQ, you should read the RabbitMQ Tutorials.
Examples are provided for Python and Java.

To publish a message in RabbitMQ, you send it to an exchange.
Exchanges route messages to queues.
When a message comes into an exchange, RabbitMQ has to figure out which queues to send it to based on characteristics of the message and the type of exchange.

There are different types of exchanges, but watchmen uses the default type, a topic exchange.
RabbitMQ uses each message's routing key—a dot delimited, hierarchical string—to determine which queues should receive the message.

To subscribe to messages from RabbitMQ, you pull messages from a queue.
Watchmen subscribers typically create their own queue, then bind it to an exchange using a routing string.
The routing string is like a routing key that allows wildcards.

For example, if you wanted to listen to messages like the one above, you'd subscribe using the routing string your-app.*.property.
The * matches exactly one dot delimited segment.

If you wanted to receive all messages from your-app, you'd use the routing string your-app.#.
The # wildcard matches any number of dot delimited segments.

Specifying an Input Source

The watchmen command line program can receive messages from any of several source types.
You specify which source you want to use with the --input (or -i) flag.

For example, suppose RabbitMQ is running on a host called jimbo.
The following command will subscribe to all messages from this host and pipe them to standard output:

$ watchmen --input amqp --input-host jimbo

You can save this data off to a file using regular shell tools:

$ watchmen --input amqp --input-host jimbo > data/example-data.dat

If you don't specify an input type, watchmen will scan standard input for JSON encoded messages.
Run watchmen with the -h flag to see the list of all supported input types and what additonal options they require.

Specifying an Output Destination

Watchmen supports a number of output types.
You specify which destination you want to send to with the --output (or -o) flag.

Suppose you wanted to send messages to RabbitMQ running on a host called jimbo.
The following command sends a simple hello world message to that host: