routemaster-client
¶ ↑
A Ruby API and CLI for the Routemaster event bus.
Installation | Library usage | CLI usage
Installation¶ ↑
gem install routemaster-client
Library usage¶ ↑
Add this line to your application's Gemfile:
gem 'routemaster-client'
Configure your client:
require 'routemaster/client' Routemaster::Client.configure do |config| config.url = 'https://bus.example.com' config.uuid = 'demo' # HTTP Basic token used to talk to the bus config.timeout = 2 # in seconds end
If you are using Sidekiq in your project, you can specify the usage of a Sidekiq backend, where event sending will be processed asynchronously.
Routemaster::Client.configure do |config| # ... config.async_backend = Routemaster::Client::Backends::Sidekiq.configure do |sidekiq| sidekiq.queue = :realtime sidekiq.retry = false end end
Push an event about an entity in the topic widgets
with a callback URL:
Routemaster::Client.created('widgets', 'https://app.example.com/widgets/1') Routemaster::Client.updated('widgets', 'https://app.example.com/widgets/2') Routemaster::Client.noop('widgets', 'https://app.example.com/widgets/3')
There are methods for the four canonical event types: created
, updated
, deleted
, and noop
.
noop
is typically used when a subscriber is first connected (or reset), and the publisher floods with noop
s for all existing entities so subscribers can refresh their view of the domain.
A timestamp argument may be passed (it will be set by the bus automatically otherwise); it must be an integer number of milliseconds since the UNIX Epoch:
Routemaster::Client.created('widgets', 'https://app.example.com/widgets/1', t: 1473080555409)
You can also push events asynchronously if you have configured a backend that supports this (otherwise an error will be raised):
Routemaster::Client.updated('widgets', 'https://app.example.com/widgets/2', async: true)
A data payload can be sent alongside the event. It is strongly discouraged to do this except extrame circumstances (particularly as schema migrations become very painful):
Routemaster::Client.created('cats', 'https://app.example.com/cats/42', data: { 'color' => 'teal' })
Subscribe to be notified about widgets
and kitten
at most 60 seconds after events, in batches of at most 500 events, to a given callback URL:
Routemaster::Client.subscribe( topics: ['widgets', 'kitten'], callback: 'https://app.example.com/events', uuid: 'demo', timeout: 60_000, max: 500)
Unsubscribe from a single topic:
Routemaster::Client.unsubscribe('widgets')
Unsubscribe from all topics:
Routemaster::Client.unsubscribe_all
Delete a topic (only possible if you're the emitter for this topic):
Routemaster::Client.delete_topic('widgets')
Monitor the status of topics and subscriptions:
Routemaster::Client.monitor_topics #=> [ #<Routemaster::Topic:XXXX @name="widgets", @publisher="demo", @events=12589>, ...] Routemaster::Client.monitor_subscriptions #=> [ { # subscriber: 'bob', # callback: 'https://app.example.com/events', # topics: ['widgets', 'kitten'], # events: { sent: 21_450, queued: 498, oldest: 59_603 } # } ... ]
CLI usage¶ ↑
This gem includes the rtm
binary, which can be used to interact with a Routemaster
bus.
Commands¶ ↑
rtm token add [options] SERVICE TOKEN
Adds TOKEN
to the list of API tokens permitted to use the bus API. SERVICE
is a human-readable name for this token.
rtm token del [options] TOKEN
Removes TOKEN
from permitted tokens if it exists.
rtm token list [options]
Lists currently permitted API tokens.
rtm sub add [options] URL TOPICS... [--latency MS] [--batch-size COUNT]
Adds (or updates) a subscription. Note that the TOKEN
passed in option
must be that of the subscriber, not a root token.
-
URL
must be HTTPS and include an authentication username (used by the bus when delivering events). -
TOPICS
is a list of topic names. -
MS
, if specified, is the target delivery latency for this subscriber (ie. how long to buffer events). -
COUNT
, if specified, is the maximum number of events in a delivered batch.
rtm sub del [options] [TOPICS]
Updates or removes a subscription. Note that the TOKEN
passed in option
must be that of the subscriber, not a root token. If no TOPICS
are specified, the subscription is entirely removed.
rtm sub list [options]
List existing subscriptions.
rtm pub [options] EVENT TOPIC URL
Publishes an event to the bus. Note that the TOKEN
passed in option
must be that of the subscriber, not a root token. EVENT
must be one of created
, updated
, deleted
, or noop
. TOPIC
must be a valid topic name. URL
must be a valid HTTPS URL.
Global options¶ ↑
-b|--bus DOMAIN|@NAME
The domain names of the bus to interact with, or a reference (NAME
) to global configuration.
Note that DOMAIN
is not a URL.
-t|--token TOKEN
An API token to use when querying the bus.
rtm
will load a configuration file in Yaml format (.rtmrc
or ~/.rtmrc
). Example:
# .rtmrc production: bus: prod.bus.example.com token: 2bf959d1-04fb-4912-8450-ab646888d476
With this configuration, rtm token list -b @production
will list API tokens for the bus at the domain specified in the config.
Contributing¶ ↑
-
Fork it ( github.com/deliveroo/routemaster-client/fork )
-
Create your feature branch (
git checkout -b my-new-feature
) -
Commit your changes (
git commit -am 'Add some feature'
) -
Push to the branch (
git push origin my-new-feature
) -
Create new Pull Request