Installation

This gem is configured through the environment, making 12factor compliance
easier.

Required:

ROUTEMASTER_DRAIN_TOKENS: a comma-separated list of valid authentication
tokens, used by Routemaster to send you events.

Optional:

ROUTEMASTER_DRAIN_REDIS: the URL of the Redis instance used for filtering
and dirty mapping. Required if you use either feature, ignored otherwise.
A namespace can be specified.
Example: redis://user:s3cr3t@myhost:1234/12/ns.

ROUTEMASTER_CACHE_REDIS: the URL of the Redis instance used for caching.
Required if you use the feature, ignored otherwise. Formatted like
ROUTEMASTER_DRAIN_REDIS.

ROUTEMASTER_CACHE_EXPIRY: if using the cache, for how long to cache
entries, in seconds. Default 1 year (31,536,000).

ROUTEMASTER_CACHE_AUTH: if using the cache, specifies what username/password
pairs to use to fetch resources. The format is a comma-separated list of
colon-separate lists of regexp, username, password values. Example:
server1:user:p4ss,server2:user:p4ass.

ROUTEMASTER_QUEUE_NAME: if using the cache, on which Resque queue the cache
population jobs should be enqueued.

ROUTEMASTER_CACHE_TIMEOUT: if using the cache, how long before Faraday will timeout fetching the resource. Defaults to 1 second.

ROUTEMASTER_CACHE_VERIFY_SSL: if using the cache, whether to verify SSL when fetching the resource. Defaults to false.

In this example, is your app was notified by Routemaster about Widget #123, the
cache will be very likely to be hit; and it will be invalidated automatically
whenever the drain gets notified about a change on that widget.

Note that Cache#fget is a future, so you can efficiently query many resources
and have any HTTP GET requests (and cache queries) happen in parallel.

Internals

The more elaborate drains are built with two components which can also be used
independently,
Dirty::Map
and
Dirty::Filter.

Dirty map

A dirty map collects entities that have been created, updated, or deleted (or
rather, their URLs). It can be used to delay your service's reaction to events,
for instance combined with Resque.

A dirty map map gets marked when an event about en entity gets processed that
indicates a state change, and swept to process those changes.

Practically, instances of
Routemaster::Dirty::Map
will emit a :dirty_entity event when a URL is marked as dirty, and can be
swept when an entity is "cleaned". If a URL is marked multiple times before
being swept (e.g. for very volatile entities), the event will only by broadcast
once.

To sweep the map, you can for instance listen to this event and call
#sweep_one.

If you're not in a hurry and would rather run through batches you can call
#sweep
which will yield URLs until it runs out of dirty resources.

Filter

Routemaster::Dirty::Filter is a simple event filter
that performs reordering. It ignores events older than the latest known
information on an entity.

It stores transient state in Redis and will emit :entity_changed events
whenever an entity has changed. This event can usefully be fed into a dirty map,
as in Receiver::Filter for instance.