startback 0.11.4 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 929e1ab2d7ab916eadc828ecf2d1695c14c9a43d117198457e03c70c8b479ba4
-  data.tar.gz: 2f3d212acd31e00b1910aca3c3c1154a5e8a130962aeb002c184c6a70da17ab2
+  metadata.gz: '085ac55f8fc68a8b8806570359e68ae9cba48a0c0cef83645bfb9f7133fb38ce'
+  data.tar.gz: 231685b5e7c8c53a3cb086bbdc8ef6728132a942a47b59e6ac5c1ca6560b2725
 SHA512:
-  metadata.gz: 90d448f505406727db9cd5c1db1d2fdb14b5df6ed546566ae9f3db4e573dbe43e43968f5885c9602c5ca198ceb8a7801aca769e499ef4d10acaaf2be318f779f
-  data.tar.gz: 01b21d439cc5b7d1c8ff218620b7eec13a8496919c941863df25d8d01f4d2c6d11b727a6c4269015ef61d1d8063ebe1487909c3b238c84c06c5211eccc568423
+  metadata.gz: 3c12830f86d5e0a067b801ebc752c894d7abec27c9745bb8eb307eee010a049275b49f3bfa1f55a1b7bf168c9fc3222b7039f6dc243f96c5268d369b625eabb3
+  data.tar.gz: dedb51337c356d9208ea727155c978dd6e937c2d8016189c17c606820975e81d1ede4e004a22878e8060dd58cd84280a4119f1a1996dae5c26bbdfc660009029

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/event/agent.rb

@@ -0,0 +1,73 @@
+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
+        install_listeners
+      end
+      attr_reader :engine
+
+    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)
+          dup.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)
+          dup.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
+
+    end # class Agent
+  end # class Event
+end # module Starback

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'

data/lib/startback/event/engine.rb

@@ -0,0 +1,176 @@
+require 'rack'
+require 'webrick'
+require 'startback'
+module Startback
+  class Event
+    #
+    # This class is the starting point of event handling in
+    # Startback. It holds a Bus instance to which emitters
+    # and listeners can connect, and the possibility for the
+    # the listening part to start an infinite loop (ServerEngine).
+    #
+    # The Engine automatically runs a Webrick small webapp
+    # with a /healthcheck webservice. The class can be extended
+    # and method `on_health_check` overriden to run specific
+    # checks.
+    #
+    # This class goes hand in hand with the `startback:engine`
+    # docker image. It can be extended by subclasses to override
+    # the following methods:
+    #
+    #   - bus to use something else than a simple memory bus
+    #   - on_health_check to check specific health conditions
+    #   - create_agents to instantiate all listening agents
+    #     (unless auto_create_agents is used)
+    #
+    class Engine
+      include Support::Robustness
+
+      DEFAULT_OPTIONS = {
+
+        # To be passed to ServerEngine
+        server_engine: {}
+
+      }
+
+      def initialize(options = {}, context = Context.new)
+        @options = DEFAULT_OPTIONS.merge(options)
+        @context = context
+        @context.engine = self
+      end
+      attr_reader :options, :context
+
+      class << self
+        def auto_create_agents?
+          !!@auto_create_agents
+        end
+
+        # Register a base class which will be used to discover
+        # the agents to start when the engine is ran.
+        def auto_create_agents(base_class = nil)
+          @auto_create_agents ||= base_class
+          @auto_create_agents
+        end
+      end
+
+      # This method is executed on health check and can be
+      # overriden by subclasses to perform specific checks.
+      def on_health_check
+        "Ok"
+      end
+
+      def bus
+        ::Startback::Event::Bus.new
+      end
+
+      def connect
+        log(:info, self, "Connecting to the bus now!")
+        bus.connect
+      end
+
+      def run(options = {})
+        connect
+
+        log(:info, self, "Running agents and server engine!")
+        create_agents
+        Runner.new(self, options[:server_engine] || {}).run
+      end
+
+      def create_agents
+        return unless parent = self.class.auto_create_agents
+
+        ObjectSpace
+          .each_object(Class)
+          .select { |klass| klass < parent }
+          .each { |klass| klass.new(self) }
+      end
+
+      def factor_event(event_data)
+        Event.json(event_data, context.dup)
+      end
+
+      class Runner
+
+        DEFAULT_SERVER_ENGINE_OPTIONS = {
+          daemonize: false,
+          worker_type: 'process',
+          workers: 1
+        }
+
+        def initialize(engine, options = {})
+          raise ArgumentError if engine.nil?
+
+          @engine = engine
+          @options = DEFAULT_SERVER_ENGINE_OPTIONS.merge(options)
+          require 'serverengine'
+        end
+        attr_reader :engine, :options
+
+        def run(options = {})
+          health = self.class.build_health_check(engine)
+          worker = self.class.build_worker(engine, health)
+          se = ServerEngine.create(nil, worker, options)
+          se.run
+          se
+        end
+
+        class << self
+          def run(*args, &bl)
+            new.run(*args, &bl)
+          end
+
+          def build_health_check(engine)
+            Rack::Builder.new do
+              map '/health-check' do
+                health = Startback::Web::HealthCheck.new {
+                  engine.on_health_check
+                }
+                run(health)
+              end
+            end
+          end
+
+          def build_worker(engine, health)
+            Module.new do
+              include Support::Env
+
+              def initialize
+                @stop_flag = ServerEngine::BlockingFlag.new
+              end
+
+              define_method(:health) do
+                health
+              end
+
+              define_method(:engine) do
+                engine
+              end
+
+              def run
+                ran = false
+                until @stop_flag.set?
+                  if ran
+                    engine.send(:log, :warn, engine, "Restarting internal loop")
+                  else
+                    engine.send(:log, :info, engine, "Starting internal loop")
+                  end
+                  Rack::Handler::WEBrick.run(health, {
+                    :Port => env('STARTBACK_ENGINE_PORT', '3000').to_i,
+                    :Host => env('STARTBACK_ENGINE_LISTEN', '0.0.0.0')
+                  })
+                  ran = true
+                end
+              end
+
+              def stop
+                engine.send(:log, :info, engine, "Stopping internal loop")
+                @stop_flag.set!
+                Rack::Handler::WEBrick.shutdown
+              end
+            end
+          end
+        end # class << self
+      end # class Runner
+    end # class Engine
+  end # class Event
+end # module Startback

data/lib/startback/event/ext/context.rb

@@ -0,0 +1,5 @@
+module Startback
+  class Context
+    attr_accessor :engine
+  end # class Context
+end # module Startback

data/lib/startback/event/ext/operation.rb

@@ -0,0 +1,13 @@
+module Startback
+  class Operation
+
+    def self.emits(type, &bl)
+      after_call do
+        event_data = instance_exec(&bl)
+        event = type.new(type.to_s, event_data, context)
+        context.engine.bus.emit(event)
+      end
+    end
+
+  end # class Operation
+end # module Startback

data/lib/startback/event.rb

@@ -20,14 +20,10 @@ module Startback
     end
     attr_reader :context, :type, :data
 
-    def self.json(src, world = {})
+    def self.json(src, context)
       parsed = JSON.parse(src)
-      context = if world[:context]
-        world[:context]
-      elsif world[:context_factory]
-        world[:context_factory].call(parsed)
-      end
-      Event.new(parsed['type'], parsed['data'], context)
+      klass = Kernel.const_get(parsed['type'])
+      klass.new(parsed['type'], parsed['data'], context)
     end
 
     def to_json(*args, &bl)
@@ -41,3 +37,8 @@ module Startback
 
   end # class Event
 end # module Startback
+require_relative 'event/ext/context'
+require_relative 'event/ext/operation'
+require_relative 'event/agent'
+require_relative 'event/bus'
+require_relative 'event/engine'