routemaster-client 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ab7db72b3f45ca016af6ddfcd31727c08448d04
-  data.tar.gz: 864cc421186071bf194c01c230f778016ab4011c
+  metadata.gz: 17d6f2b6dd28fd082771df65f57fd41f8cbbc2f6
+  data.tar.gz: a97e8c84d7c1a193e64fefbf2a55a18805d65aec
 SHA512:
-  metadata.gz: d48921d988693488e7aed1b03b22526a88cd320eb85ce97976c32b0b0458fd79703043a0ef9f3e82971a9afcc3712f6427ce55c7aacc3ce5b00af81dd15ca24e
-  data.tar.gz: 856f4e0a2f340dbbe9d5c8b13e39fea9026b94ce48f53ec81bbca6da1ba5d860fd4460339cbd5fefdf3f43129cc51bc63130b81aa5e4132a2a84ee350bd34573
+  metadata.gz: 2b8fa2d106cc69d3cb0edc75eb430d8c659a81b2686b92b6501b3789f006dbf0e92a7e4900361f2461090cb4f2560267db2d016b0f6c3d554c1171e94127e897
+  data.tar.gz: 66d7c256ae0ada32ea8afed4590bcd4a99df183791a8193a08249ea97f76d9586be067bc322f47b435bde09f90d5f88779a711121c1dc29b1df84746cec532ef

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    routemaster-client (2.1.0)
+    routemaster-client (3.0.0)
       faraday (>= 0.9.0)
       oj (~> 2.17)
       typhoeus (~> 1.1)

data/README.md

@@ -25,27 +25,42 @@ Or install it yourself as:
 
 ```ruby
 require 'routemaster/client'
-client = Routemaster::Client.new(url: 'https://bus.example.com', uuid: 'demo')
+Routemaster::Client.configure do |config|
+  config.url = 'https://bs.example.com'
+  config.uuid = 'demo'
+end
 ```
 
 You can also specify a timeout value in seconds if you like with the ```timeout``` option.
 
 ```ruby
-Routemaster::Client.new(url: 'https://bus.example.com', uuid: 'demo', timeout: 2)
+Routemaster::Client.configure do |config|
+  config.url = 'https://bs.example.com'
+  config.uuid = 'demo'
+  config.timeout = 2
+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.
 
 ```ruby
-Routemaster::Client.new(url, 'https://bus.example.com', uuid: 'demo', backend_type: Routemaster::Client::Backends::Sidekiq)
+Routemaster::Client.configure do |config|
+  config.url = 'https://bs.example.com'
+  config.uuid = 'demo'
+  config.timeout = 2
+  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:
 
 ```ruby
-client.created('widgets', 'https://app.example.com/widgets/1')
-client.updated('widgets', 'https://app.example.com/widgets/2')
-client.noop('widgets', 'https://app.example.com/widgets/3')
+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`,
@@ -59,14 +74,24 @@ 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:
 
 ```ruby
-client.created('widgets', 'https://app.example.com/widgets/1', 1473080555409)
+Routemaster::Client.created('widgets', 'https://app.example.com/widgets/1', 1473080555409)
 ```
 
+**Async**
+You can also push events asynchronously if you have an async backend defined, for each
+event method there is a corresponding `event_async` method. eg
+```ruby
+   Routemaster::Client.updated_async('widgets', 'https://app.example.com/widgets/2')
+```
+
+You cannot use these methods without defining an async backend, if you try then an error will
+be raised.
+
 **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:
 
 ```ruby
-client.subscribe(
+Routemaster::Client.subscribe(
   topics:   ['widgets', 'kitten'],
   callback: 'https://app.example.com/events',
   uuid:     'demo',
@@ -102,29 +127,29 @@ gem](https://github.com/krisleech/wisper#wisper).
 **Unsubscribe** from a single topic:
 
 ```ruby
-client.unsubscribe('widgets')
+Routemaster::Client.unsubscribe('widgets')
 ```
 
 **Unsubscribe** from all topics:
 
 ```ruby
-client.unsubscribe_all
+Routemaster::Client.unsubscribe_all
 ```
 
 **Delete** a topic (only possible if you're the emitter for this topic):
 
 ```ruby
-client.delete_topic('widgets')
+Routemaster::Client.delete_topic('widgets')
 ```
 
 
 **Monitor** the status of topics and subscriptions:
 
 ```ruby
-client.monitor_topics
+Routemaster::Client.monitor_topics
 #=> [ #<Routemaster::Topic:XXXX @name="widgets", @publisher="demo", @events=12589>, ...]
 
-client.monitor_subscriptions
+Routemaster::Client.monitor_subscriptions
 #=> [ {
 #     subscriber: 'bob',
 #     callback:   'https://app.example.com/events',

data/routemaster/client.rb

@@ -1,6 +1,9 @@
-require 'routemaster/client/backends'
+require 'routemaster/client/backends/synchronous'
 require 'routemaster/client/connection'
+require 'routemaster/client/configuration'
 require 'routemaster/client/version'
+require 'routemaster/client/errors'
+require 'routemaster/client/assertion_helpers'
 require 'routemaster/topic'
 require 'uri'
 require 'json'
@@ -10,150 +13,174 @@ require 'typhoeus/adapters/faraday'
 require 'oj'
 
 module Routemaster
-  class Client
+  module Client
+    class << self
+      extend Forwardable
+      include AssertionHelpers
+
+      def_delegator :'Routemaster::Client::Configuration', :async_backend
+      def_delegator :'Routemaster::Client::Configuration', :lazy
+
+      def configure
+        self.tap do
+          Configuration.configure do |c|
+            yield c
+          end
+          _check_pulse! unless lazy
+        end
+      end
 
-    def initialize(options = {})
-      @_options = options.tap do |o|
-        o[:timeout] ||= 1
-        o[:backend_type] ||= Backends::Synchronous
+      def created(topic, callback, timestamp = nil)
+        _send_event('create', topic, callback, timestamp)
       end
 
-      @_backend_type = @_options.fetch(:backend_type)
+      def created_async(topic, callback, timestamp = nil)
+        _send_event('create', topic, callback, timestamp, async: true)
+      end
 
-      _assert_valid_url(@_options[:url])
-      _assert_valid_backend_type(@_backend_type)
-      _assert (@_options[:uuid] =~ /^[a-z0-9_-]{1,64}$/), 'uuid should be alpha'
-      _assert_valid_timeout(@_options[:timeout])
+      def updated(topic, callback, timestamp = nil)
+        _send_event('update', topic, callback, timestamp)
+      end
 
+      def updated_async(topic, callback, timestamp = nil)
+        _send_event('update', topic, callback, timestamp, async: true)
+      end
 
-      unless @_options[:lazy]
-        _conn.get('/pulse').tap do |response|
-          raise 'cannot connect to bus' unless response.success?
-        end
+      def deleted(topic, callback, timestamp = nil)
+        _send_event('delete', topic, callback, timestamp)
       end
-    end
 
-    def created(topic, callback, timestamp = nil)
-      _send_event('create', topic, callback, timestamp)
-    end
+      def deleted_async(topic, callback, timestamp = nil)
+        _send_event('delete', topic, callback, timestamp, async: true)
+      end
 
-    def updated(topic, callback, timestamp = nil)
-      _send_event('update', topic, callback, timestamp)
-    end
+      def noop(topic, callback, timestamp = nil)
+        _send_event('noop', topic, callback, timestamp)
+      end
 
-    def deleted(topic, callback, timestamp = nil)
-      _send_event('delete', topic, callback, timestamp)
-    end
+      def noop_async(topic, callback, timestamp = nil)
+        _send_event('noop', topic, callback, timestamp, async: true)
+      end
 
-    def noop(topic, callback, timestamp = nil)
-      _send_event('noop', topic, callback, timestamp)
-    end
+      def subscribe(topics:, callback:, **options)
+        _assert_valid_topics!(topics)
+        _assert_valid_url!(callback)
+        _assert_valid_max_events! options[:max] if options[:max]
+        _assert_valid_timeout! options[:timeout] if options[:timeout]
 
-    def subscribe(options = {})
-      if (options.keys - [:topics, :callback, :timeout, :max, :uuid]).any?
-        raise ArgumentError.new('bad options')
+        _conn.subscribe(topics: topics, callback: callback, **options)
       end
-      _assert options[:topics].kind_of?(Enumerable), 'topics required'
-      _assert options[:callback], 'callback required'
-      _assert_valid_timeout options[:timeout] if options[:timeout]
-      _assert_valid_max_events options[:max] if options[:max]
 
-      options[:topics].each { |t| _assert_valid_topic(t) }
-      _assert_valid_url(options[:callback])
-      _conn.subscribe(options)
-    end
+      def unsubscribe(*topics)
+        _assert_valid_topics!(topics)
 
-    def unsubscribe(*topics)
-      topics.each { |t| _assert_valid_topic(t) }
+        topics.each do |t|
+          response = _conn.delete("/subscriber/topics/#{t}")
 
-      topics.each do |t|
-        response = _conn.delete("/subscriber/topics/#{t}")
+          unless response.success?
+            raise 'unsubscribe rejected'
+          end
+        end
+      end
+
+      def unsubscribe_all
+        response = _conn.delete('/subscriber')
 
         unless response.success?
-          raise 'unsubscribe rejected'
+          raise 'unsubscribe all rejected'
         end
       end
-    end
 
-    def unsubscribe_all
-      response = _conn.delete('/subscriber')
+      def delete_topic(topic)
+        _assert_valid_topic!(topic)
+
+        response = _conn.delete("/topics/#{topic}")
 
-      unless response.success?
-        raise 'unsubscribe all rejected'
+        unless response.success?
+          raise 'failed to delete topic'
+        end
       end
-    end
 
-    def delete_topic(topic)
-      _assert_valid_topic(topic)
+      def monitor_topics
+        response = _conn.get('/topics') do |r|
+          r.headers['Content-Type'] = 'application/json'
+        end
 
-      response = _conn.delete("/topics/#{topic}")
+        unless response.success?
+          raise 'failed to connect to /topics'
+        end
 
-      unless response.success?
-        raise 'failed to delete topic'
+        Oj.load(response.body).map do |raw_topic|
+          Topic.new raw_topic
+        end
       end
-    end
 
-    def monitor_topics
-      response = _conn.get('/topics') do |r|
-        r.headers['Content-Type'] = 'application/json'
+      private
+
+      def _conn
+        Connection
       end
 
-      unless response.success?
-        raise 'failed to connect to /topics'
+      def _synchronous_backend
+        Routemaster::Client::Backends::Synchronous
       end
 
-      Oj.load(response.body).map do |raw_topic|
-        Topic.new raw_topic
+      def _assert_valid_url!(url)
+        assert_valid_url_throwing_error!(url, InvalidArgumentError)
       end
-    end
 
-    private
+      def _assert_valid_max_events!(max)
+        unless (1..10_000).include?(max)
+          raise InvalidArgumentError, "max events '#{max}' is invalid, must be between 1 and 10,000"
+        end
+      end
 
-    def _assert_valid_timeout(timeout)
-      _assert (0..3_600_000).include?(timeout), 'bad timeout'
-    end
+      def _assert_valid_topics!(topics)
+        unless topics.kind_of? Enumerable
+          raise InvalidArgumentError, "topics must be a list"
+        end
 
-    def _assert_valid_max_events(max)
-      _assert (0..10_000).include?(max), 'bad max # events'
-    end
+        unless topics.length > 0
+          raise InvalidArgumentError "topics must contain at least one element"
+        end
 
-    def _assert_valid_url(url)
-      uri = URI.parse(url)
-      _assert (uri.scheme == 'https'), 'HTTPS required'
-      return url
-    end
+        topics.each { |t| _assert_valid_topic!(t) }
+      end
 
-    def _assert_valid_topic(topic)
-      _assert (topic =~ /^[a-z_]{1,64}$/), 'bad topic name: must only include letters and underscores'
-    end
+      def _assert_valid_topic!(topic)
+        unless topic =~ /^[a-z_]{1,64}$/
+          raise InvalidArgumentError, 'bad topic name: must only include letters and underscores'
+        end
+      end
 
-    def _assert_valid_timestamp(timestamp)
-      _assert timestamp.kind_of?(Integer), 'not an integer'
-    end
+      def _assert_valid_timestamp!(timestamp)
+        unless timestamp.kind_of? Integer
+          raise InvalidArgumentError, "timestamp '#{timestamp}' is invalid, must be an integer"
+        end
+      end
 
-    def _assert_valid_backend_type(backend_type)
-      backends = Backends::NAMES
-      _assert backends.include?(backend_type.to_s), "unknown backend type, must be one of #{backends.map{ |w| "Routemaster::Backends::#{w}" }.join(", ")}"
-      backend_type
-    end
+      def _assert_valid_timeout!(timeout)
+        unless (0..3_600_000).include? timeout
+          raise InvalidArgumentError, "timeout '#{timeout}' is invalid, must be an integer between 0 and 3,600,000"
+        end
+      end
 
-    def _send_event(event, topic, callback, timestamp = nil)
-      _assert_valid_url(callback)
-      _assert_valid_topic(topic)
-      _assert_valid_timestamp(timestamp) if timestamp
-      _backend.send_event(event, topic, callback, timestamp)
-    end
+      def _send_event(event, topic, callback, timestamp = nil, async: false)
+        _assert_valid_url!(callback)
+        _assert_valid_topic!(topic)
+        _assert_valid_timestamp!(timestamp) if timestamp
 
-    def _assert(condition, message)
-      condition or raise ArgumentError.new(message)
-    end
+        backend = async ? async_backend : _synchronous_backend
+        backend.send_event(event, topic, callback, timestamp)
+      end
 
-    def _conn
-      @_conn ||= Client::Connection.new(@_options)
-    end
+      def _check_pulse!
+        _conn.get('/pulse').tap do |response|
+          raise 'cannot connect to bus' unless response.success?
+        end
+      end
 
-    def _backend
-      @_worker ||= @_backend_type.configure(@_options)
+      private :async_backend, :lazy
     end
   end
 end

data/routemaster/client/assertion_helpers.rb

@@ -0,0 +1,18 @@
+require 'uri'
+
+module Routemaster
+  module Client
+    module AssertionHelpers
+      def assert_valid_url_throwing_error!(url, error_class)
+        begin
+          uri = URI.parse(url)
+          unless uri.is_a? URI::HTTPS
+            raise error_class, "url '#{url}' is invalid, must be an https url"
+          end
+        rescue URI::InvalidURIError
+          raise error_class, "url '#{url}' is invalid, must be an https url"
+        end
+      end
+    end
+  end
+end

data/routemaster/client/backends/missing_asynchronous.rb

@@ -0,0 +1,15 @@
+require 'routemaster/client/errors'
+
+module Routemaster
+  module Client
+    module Backends
+      class MissingAsynchronous
+        class << self
+          def send_event(*)
+            raise MissingAsyncBackendError
+          end
+        end
+      end
+    end
+  end
+end