startback 0.11.5 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9e440ddba682a1c59c98a5635b0febafe08222e9cee2de68d3262c6da6d8d4
-  data.tar.gz: '09a4748015aa374687c4016341d7f6a699d80718da7f9b4a6449294d69cf7897'
+  metadata.gz: 7f4770d1267ad944224e11f6c10ddaae3f2c3666860ef31c05ea3323282dda34
+  data.tar.gz: ec1a61367ab0947be2088dae981c6956359a26bc2517282a464e44e6449331b4
 SHA512:
-  metadata.gz: 6f832ba94f865dfd66c372fcf19623c68f43c76019623fd49da96e88fa2c7355bc78916ae98f3ae32de7e4deb0f08d9ade5d7eb2b3fa9f9bebb5544c0de698d4
-  data.tar.gz: 6ec4e88b7f2bc2ffd58d6e0cddb5bfffc5411149b71a97d1a51e7195105bd907568b45afec40f47916c17dbc45dfe81a5e6432781fa821dbdb2b1ba47f614c86
+  metadata.gz: 19813029ac9f81b1aed96f69a8e6ddd45e509d87e5b3bd05859f0b9155c16c5a05035cf2a28ff7df2df28f467a368702fa83180c24a62caf498337c3dde6d7da
+  data.tar.gz: 57abc7390c595f5c024276ed07ccb3580312d2de76a6a622e0a3284afefb38244b000b26e9f005d4516de67f3afccdc4789988466ffbb220f106cce3514f83b4

data/lib/startback/context/middleware.rb

@@ -18,7 +18,7 @@ module Startback
     #
     #     # Use a user defined context class
     #     Rack::Builder.new do
-    #       use Startback::Context::Middleware, context_class: MyContextClass
+    #       use Startback::Context::Middleware, MyContextClass.new
     #
     #       run ->(env){
     #         ctx = env[Startback::Context::Middleware::RACK_ENV_KEY]
@@ -31,18 +31,14 @@ module Startback
 
       RACK_ENV_KEY = 'SAMBACK_CONTEXT'
 
-      DEFAULT_OPTIONS = {
-        context_class: Context
-      }
-
-      def initialize(app, options = {})
+      def initialize(app, context = Context.new)
         @app = app
-        @options = DEFAULT_OPTIONS.merge(options || {})
+        @context = context
       end
-      attr_reader :options
+      attr_reader :context
 
       def call(env)
-        env[RACK_ENV_KEY] ||= options[:context_class].h({}).tap{|c|
+        env[RACK_ENV_KEY] ||= context.dup.tap{|c|
           c.original_rack_env = env.dup
         }
         @app.call(env)

data/lib/startback/context.rb

@@ -112,6 +112,13 @@ module Startback
       to_h.to_json(*args, &bl)
     end
 
+    def fork(h = nil)
+      dup.tap{|duped|
+        self.class.h_factor!(duped, h) if h
+        yield(duped) if block_given?
+      }
+    end
+
     def dup
       super.tap{|c|
         c.send(:clean_factored!)

data/lib/startback/event/agent.rb

@@ -1,7 +1,83 @@
 module Startback
   class Event
+    #
+    # An agent listen to specific events and react with its
+    # `call` method.
+    #
+    # This class is intended to be subclasses and the following
+    # methods overriden:
+    #
+    #   - install_listeners that installs sync and async listeners
+    #   - call to create a context and implement reaction behavior
+    #
     class Agent
       include Support::OperationRunner
+      include Support::Robustness
+
+      def initialize(engine)
+        @engine = engine
+        @context = nil
+        install_listeners
+      end
+      attr_reader :engine
+      attr_accessor :context
+      protected :context=
+
+    protected
+
+      # Installs the various event handlers by calling `sync`
+      # and `async` methods.
+      #
+      # This method is intended to be overriden.
+      def install_listeners
+      end
+
+      # Returns the underlying bus
+      def bus
+        engine.bus
+      end
+
+      # Asynchronously listen to a specific event.
+      #
+      # See Bus#listen
+      def async(exchange, queue)
+        bus.async.listen(exchange, queue) do |event_data|
+          event = engine.factor_event(event_data)
+          with_context(event.context).call(event)
+        end
+      end
+
+      # Synchronously listen to a specific event.
+      #
+      # See Bus#listen
+      def sync(exchange, queue)
+        bus.listen(exchange, queue) do |event_data|
+          event = engine.factor_event(event_data)
+          with_context(event.context).call(event)
+        end
+      end
+
+      # Reacts to a specific event.
+      #
+      # This method must be implemented by subclasses and raises
+      # an error by default.
+      def call(event = nil)
+        log(:fatal, {
+          op: self.class,
+          op_data: event,
+          error: %Q{Unexpected call to Startback::Event::Agent#call},
+          backtrace: caller
+        })
+        raise NotImplementedError
+      end
+
+      def with_context(context)
+        dup.tap{|a| a.send(:context=, context) }
+      end
+
+      def operation_world(op)
+        super(op).merge(context: ctx)
+      end
 
     end # class Agent
   end # class Event

data/lib/startback/event/bus/bunny/async.rb

@@ -0,0 +1,162 @@
+require 'bunny'
+module Startback
+  class Event
+    class Bus
+      module Bunny
+        #
+        # Asynchronous implementation of the bus abstraction, on top of RabbitMQ
+        # and using the 'bunny' gem (you need to include it in your Gemfile
+        # yourself: it is NOT a startback official dependency).
+        #
+        # This bus implementation emits events by dumping them to RabbitMQ using
+        # the event type as exchange name. Listeners may use the `processor`
+        # parameter to specify the queue name ; otherwise a default "main" queue
+        # is used.
+        #
+        # Examples:
+        #
+        #     # Connects to RabbitMQ using all default options
+        #     #
+        #     # Uses the STARTBACK_BUS_BUNNY_ASYNC_URL environment variable for
+        #     # connection URL if present.
+        #     Startback::Bus::Bunny::Async.new
+        #
+        #     # Connects to RabbitMQ using a specific URL
+        #     Startback::Bus::Bunny::Async.new("amqp://rabbituser:rabbitpass@192.168.17.17")
+        #     Startback::Bus::Bunny::Async.new(url: "amqp://rabbituser:rabbitpass@192.168.17.17")
+        #
+        #     # Connects to RabbitMQ using specific connection options. See Bunny's own
+        #     # documentation
+        #     Startback::Bus::Bunny::Async.new({
+        #       connection_options: {
+        #         host: "192.168.17.17"
+        #       }
+        #     })
+        #
+        class Async
+          include Support::Robustness
+
+          CHANNEL_KEY = 'Startback::Bus::Bunny::Async::ChannelKey'
+
+          DEFAULT_OPTIONS = {
+            # (optional) The URL to use for connecting to RabbitMQ.
+            url: ENV['STARTBACK_BUS_BUNNY_ASYNC_URL'],
+
+            # (optional) The options has to pass to ::Bunny constructor
+            connection_options: nil,
+
+            # (optional) The options to use for the emitter/listener fanout
+            fanout_options: {},
+
+            # (optional) The options to use for the listener queue
+            queue_options: {},
+
+            # (optional) Default event factory to use, if any
+            event_factory: nil,
+
+            # (optional) A default context to use for general logging
+            context: nil,
+
+            # (optional) Size of consumer pool
+            consumer_pool_size: 1,
+
+            # (optional) Whether the program must be aborted on consumption
+            # error
+            abort_on_exception: true,
+
+            # (optional) Whether connection occurs immediately,
+            # or on demand later
+            autoconnect: false
+          }
+
+          # Creates a bus instance, using the various options provided to
+          # fine-tune behavior.
+          def initialize(options = {})
+            options = { url: options } if options.is_a?(String)
+            @options = DEFAULT_OPTIONS.merge(options)
+            connect if @options[:autoconnect]
+          end
+          attr_reader :options
+
+          def connect
+            disconnect
+            conn = options[:connection_options] || options[:url]
+            try_max_times(10) do
+              @bunny = ::Bunny.new(conn)
+              @bunny.start
+              channel # make sure we already create the channel
+              log(:info, {op: "#{self.class.name}#connect", op_data: conn}, options[:context])
+            end
+          end
+
+          def disconnect
+            if channel = Thread.current[CHANNEL_KEY]
+              channel.close
+              Thread.current[CHANNEL_KEY] = nil
+            end
+            @bunny.close if @bunny
+          end
+
+          def channel
+            unless @bunny
+              raise Startback::Errors::Error, "Please connect your bus first, or use autoconnect: true"
+            end
+
+            Thread.current[CHANNEL_KEY] ||= @bunny.create_channel(
+              nil,
+              consumer_pool_size, # consumer_pool_size
+              abort_on_exception? # consumer_pool_abort_on_exception
+            )
+          end
+
+          def emit(event)
+            stop_errors(self, "emit", event.context) do
+              fanout = channel.fanout(event.type.to_s, fanout_options)
+              fanout.publish(event.to_json)
+            end
+          end
+
+          def listen(type, processor = nil, listener = nil, &bl)
+            raise ArgumentError, "A listener must be provided" unless listener || bl
+
+            fanout = channel.fanout(type.to_s, fanout_options)
+            queue = channel.queue((processor || "main").to_s, queue_options)
+            queue.bind(fanout)
+            queue.subscribe do |delivery_info, properties, body|
+              stop_errors(self, "listen") do
+                (listener || bl).call(body)
+              end
+            end
+          end
+
+        protected
+
+          def consumer_pool_size
+            options[:consumer_pool_size]
+          end
+
+          def abort_on_exception?
+            options[:abort_on_exception]
+          end
+
+          def fanout_options
+            options[:fanout_options]
+          end
+
+          def queue_options
+            options[:queue_options]
+          end
+
+          def factor_event(body)
+            if options[:event_factory]
+              options[:event_factory].call(body)
+            else
+              Event.json(body, options)
+            end
+          end
+
+        end # class Async
+      end # module Bunny
+    end # class Bus
+  end # class Event
+end # module Startback

data/lib/startback/event/bus/memory/async.rb

@@ -0,0 +1,45 @@
+module Startback
+  class Event
+    class Bus
+      module Memory
+        #
+        # Asynchronous implementation of the Bus abstraction, for use between
+        # components sharing the same process.
+        #
+        # This implementation actually calls listeners synchronously (it mays)
+        # but hides error raised by them. See Bus::Bunny::Async for another
+        # implementation that is truly asynchronous and relies on RabbitMQ.
+        #
+        class Async
+          include Support::Robustness
+
+          DEFAULT_OPTIONS = {
+          }
+
+          def initialize(options = {})
+            @options = DEFAULT_OPTIONS.merge(options)
+            @listeners = {}
+          end
+
+          def connect
+          end
+
+          def emit(event)
+            (@listeners[event.type.to_s] || []).each do |l|
+              stop_errors(self, "emit", event) {
+                l.call(event)
+              }
+            end
+          end
+
+          def listen(type, processor = nil, listener = nil, &bl)
+            raise ArgumentError, "A listener must be provided" unless listener || bl
+            @listeners[type.to_s] ||= []
+            @listeners[type.to_s] << (listener || bl)
+          end
+
+        end # class Sync
+      end # module Memory
+    end # class Bus
+  end # class Event
+end # module Startback

data/lib/startback/event/bus/memory/sync.rb

@@ -0,0 +1,35 @@
+module Startback
+  class Event
+    class Bus
+      module Memory
+        #
+        # Synchronous implementation of the Bus abstraction, for use between
+        # components sharing the same process.
+        #
+        class Sync
+          include Support::Robustness
+
+          def initialize
+            @listeners = {}
+          end
+
+          def connect
+          end
+
+          def emit(event)
+            (@listeners[event.type.to_s] || []).each do |l|
+              l.call(event)
+            end
+          end
+
+          def listen(type, processor = nil, listener = nil, &bl)
+            raise ArgumentError, "A listener must be provided" unless listener || bl
+            @listeners[type.to_s] ||= []
+            @listeners[type.to_s] << (listener || bl)
+          end
+
+        end # class Sync
+      end # module Memory
+    end # class Bus
+  end # class Event
+end # module Startback

data/lib/startback/event/bus.rb

@@ -0,0 +1,100 @@
+module Startback
+  class Event
+    #
+    # Sync and async bus abstraction allowing to register listeners and
+    # emitting events towards them.
+    #
+    # This bus actually decorates two busses, one in synchronous and the
+    # other one is asynchronous (optional).
+    #
+    # * A synchronous bus MUST call the listeners as part of emitting
+    #   process, and MUST re-raise any error occuring during that process.
+    #   See, e.g. Startback::Bus::Memory::Sync
+    #
+    # * An asynchronous bus MAY call the listeners later, but MUST hide
+    #   errors to the emitter.
+    #   See, e.g. Startback::Bus::Memory::Async
+    #
+    # This bus facade emits events to both sync and async busses (if any),
+    # and listen on the sync one by default.
+    #
+    # For emitters:
+    #
+    #     # This will synchronously call every listeners who `listen`
+    #     # on the synchronous bus (& reraise exceptions) then call
+    #     # (possibly later) all listeners who `listen` on the
+    #     # asynchronous bus if any (& hide exceptions).
+    #     bus.emit(event)
+    #
+    #     # This only reaches sync listeners
+    #     bus.sync.emit(event)
+    #
+    #     # This only reaches async listeners (an async bus must be set)
+    #     bus.async.emit(event)
+    #
+    # Please note that there is currently no way to reach sync listeners
+    # without having to implement error handling on the emitter side.
+    #
+    # For listeners:
+    #
+    #     # This will listen synchronously and make the emitter fail if
+    #     # anything goes wrong with the callback:
+    #     bus.listen(event_type) do |event|
+    #       ...
+    #     end
+    #
+    #     # It is a shortcut for:
+    #     bus.sync.listen(event_type) do |event| ... end
+    #
+    #     This will listen asynchronously and could not make the emitter
+    #     fail if something goes wrong with the callback.
+    #     bus.async.listen(event_type) do |event|
+    #       ...
+    #     end
+    #
+    # Feel free to access the sync and async busses directly for specific
+    # cases though.
+    #
+    class Bus
+      include Support::Robustness
+
+      def initialize(sync = Memory::Sync.new, async = nil)
+        @sync = sync
+        @async = async
+      end
+      attr_reader :sync, :async
+
+      def connect
+        sync.connect if sync
+        async.connect if async
+      end
+
+      # Emits a particular event to the listeners.
+      #
+      # @arg event an event, should be an Event instance (through duck
+      #      typing is allowed)
+      def emit(event)
+        monitor({
+          op: "Startback::Bus#emit",
+          op_data: {
+            event: { type: event.type }
+          }
+        }, event.context) do
+          sync.emit(event)
+          async.emit(event) if async
+        end
+      end
+
+      # Registers `listener` as being interested in receiving events of
+      # a specific type.
+      #
+      # @arg type: Symbol, the type of event the listener is interested in.
+      # @arg listener: Proc, the listener itself.
+      def listen(type, processor = nil, listener = nil, &bl)
+        sync.listen(type, processor, listener, &bl)
+      end
+
+    end # class Bus
+  end # class Event
+end # module Startback
+require_relative 'bus/memory'