startback-jobs 0.13.0 → 0.14.0

data/lib/startback/context.rb

@@ -0,0 +1,122 @@
+module Startback
+  #
+  # Defines an execution context for Startback applications, and provides
+  # a cached factory for related abstractions (see `factor`), and an
+  # extensible world, statically and dynamically.
+  #
+  # In web application, an instance of a context can be set on the Rack
+  # environment, using Context::Middleware.
+  #
+  # This class SHOULD be subclassed for application required extensions
+  # to prevent touching the global Startback state itself.
+  #
+  # Also, for event handling in distributed architectures, a Context should
+  # be dumpable and reloadable to JSON. An `h` information contract if provided
+  # for that. Subclasses may contribute to the dumping and reloading process
+  # through the `h_dump` and `h_factory` methods
+  #
+  #     module MyApp
+  #       class Context < Startback::Context
+  #
+  #         attr_accessor :foo
+  #
+  #         h_dump do |h|
+  #           h.merge!("foo" => foo)
+  #         end
+  #
+  #         h_factor do |c,h|
+  #           c.foo = h["foo"]
+  #         end
+  #
+  #       end
+  #     end
+  #
+  class Context
+    attr_accessor :original_rack_env
+
+    # An error handler can be provided on the Context class. The latter
+    # MUST expose an API similar to ruby's Logger class. It can be a logger
+    # instance, simply.
+    #
+    # Fatal errors catched by Web::CatchAll are sent on `error_handler#fatal`
+    #
+    # Deprecated, use the logger below instead.
+    attr_accessor :error_handler
+
+    # A logger can be provided on the context, and will be used for everything
+    # related to logging, audit trailing and robustness. The logger receives
+    # object following the log & trail conventions of Startback, and must
+    # convert them to wathever log format is necessary.
+    attr_accessor :logger
+
+    require_relative 'context/h_factory'
+    extend(Context::HFactory)
+
+    def initialize
+      super
+      yield(self) if block_given?
+    end
+
+    attr_writer :_world
+    protected :_world=
+
+    def self.world(who, &block)
+      @_world ||= Support::World.new
+      @_world = @_world.factory(who, &block)
+    end
+
+    def self.factor_world(context)
+      @_world ||= Support::World.new
+      @_world.with_scope(context)
+    end
+
+    def world
+      @_world ||= self.class.factor_world(self)
+    end
+
+    def with_world(world)
+      dup do |ctx|
+        ctx._world = self.world.with(world)
+      end
+    end
+
+    # Factors an instance of `clazz`, which must be a Context-related
+    # abstraction (i.e. its constructor takes the context as last parameters).
+    #
+    # Factored abstractions are cached for a given context & arguments.
+    def factor(clazz, *args)
+      @factored ||= {}
+      key = args.empty? ? clazz : [clazz] + args
+      @factored[key] ||= clazz.new(*(args << self))
+    end
+
+    def clean_factored!
+      @factored = {}
+    end
+    private :clean_factored!
+
+    def to_h
+      self.class.h_dump!(self)
+    end
+
+    def to_json(*args, &bl)
+      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!)
+        yield(c) if block_given?
+      }
+    end
+
+  end # class Context
+end # module Startback
+require_relative 'context/middleware'

data/lib/startback/errors.rb

@@ -0,0 +1,197 @@
+module Startback
+  module Errors
+
+    class Error < StandardError
+      def initialize(message = nil, causes = nil)
+        super(message)
+        @causes = Array(causes)
+      end
+      attr_reader :causes
+
+      class << self
+        def status(code = nil)
+          if code.nil?
+            @code || (superclass.respond_to?(:status) ? superclass.status : 500)
+          else
+            @code = code || @code
+          end
+        end
+
+        def keep_error(keep = nil)
+          @keep_error = keep unless keep.nil?
+          @keep_error
+        end
+      end
+
+      def message
+        msg = super
+        return msg unless msg == self.class.name
+        parts = self.class.name.split('::').last.gsub(/[A-Z]/){|x|
+          " #{x.downcase}"
+        }.strip.split(" ")
+        parts = parts[0...-1] unless self.class.keep_error
+        parts.join(" ").capitalize
+      end
+
+      def has_causes?
+        causes && !causes.empty?
+      end
+
+      def cause
+        causes&.first
+      end
+    end
+
+    class BadRequestError < Error
+      status 400
+    end
+
+      class UnauthorizedError < BadRequestError
+        status 401
+      end
+
+      class ForbiddenError < BadRequestError
+        status 403
+      end
+
+      class NotFoundError < BadRequestError
+        status 404
+      end
+
+      class MethodNotAllowedError < BadRequestError
+        status 405
+      end
+
+      class NotAcceptableError < BadRequestError
+        status 406
+      end
+
+      class ConflictError < BadRequestError
+        status 409
+      end
+
+      class GoneError < BadRequestError
+        status 410
+      end
+
+      class PreconditionFailedError < BadRequestError
+        status 412
+      end
+
+      class UnsupportedMediaTypeError < BadRequestError
+        status 415
+      end
+
+      class ExpectationFailedError < BadRequestError
+        status 417
+      end
+
+      class LockedError < BadRequestError
+        status 423
+      end
+
+      class PreconditionRequiredError < BadRequestError
+        status 428
+      end
+
+    class InternalServerError < Error
+      status 500
+      keep_error(true)
+    end
+
+      class NotImplementedError < InternalServerError
+        status 501
+      end
+
+    ### Helper methods
+
+      def bad_request_error!(msg = nil)
+        raise Startback::Errors::BadRequestError, msg
+      end
+      module_function :bad_request_error!
+
+      def unauthorized_error!(msg = nil)
+        raise Startback::Errors::UnauthorizedError, msg
+      end
+      module_function :unauthorized_error!
+
+      def forbidden_error!(msg = nil)
+        raise Startback::Errors::ForbiddenError, msg
+      end
+      module_function :forbidden_error!
+
+      def not_found_error!(msg = nil)
+        raise Startback::Errors::NotFoundError, "#{msg} not found"
+      end
+      module_function :not_found_error!
+
+      def method_not_allowed_error!(msg = nil)
+        raise Startback::Errors::MethodNotAllowedError, msg
+      end
+      module_function :method_not_allowed_error!
+
+      def not_acceptable_error!(msg = nil)
+        raise Startback::Errors::NotAcceptableError, msg
+      end
+      module_function :not_acceptable_error!
+
+      def conflict_error!(msg = nil)
+        raise Startback::Errors::ConflictError, msg
+      end
+      module_function :conflict_error!
+
+      def gone_error!(msg = nil)
+        raise Startback::Errors::GoneError, msg
+      end
+      module_function :gone_error!
+
+      def precondition_failed_error!(msg = nil)
+        raise Startback::Errors::PreconditionFailedError, msg
+      end
+      module_function :precondition_failed_error!
+
+      def unsupported_media_type_error!(media)
+        raise Startback::Errors::UnsupportedMediaTypeError, "Unable to use `#{media}` as input data"
+      end
+      module_function :unsupported_media_type_error!
+
+      def expectation_failed_error!(msg = nil)
+        raise Startback::Errors::ExpectationFailedError, msg
+      end
+      module_function :expectation_failed_error!
+
+      def locked_error!(msg = nil)
+        raise Startback::Errors::LockedError, msg
+      end
+      module_function :locked_error!
+
+      def precondition_required_error!(msg = nil)
+        raise Startback::Errors::PreconditionRequiredError, msg
+      end
+      module_function :precondition_required_error!
+
+      def internal_server_error!(msg = nil)
+        raise Startback::Errors::InternalServerError, msg
+      end
+      module_function :internal_server_error!
+
+      def not_implemented_error!(msg = nil)
+        raise Startback::Errors::NotImplementedError, msg
+      end
+      module_function :not_implemented_error!
+
+  # Aliases
+
+      def user_error!(msg = nil)
+        raise Startback::Errors::BadRequestError, msg
+      end
+      module_function :user_error!
+
+      def server_error!(msg = nil)
+        raise Startback::Errors::InternalServerError, msg
+      end
+      module_function :server_error!
+
+  end # module Errors
+  include Errors
+end # module Startback

data/lib/startback/event/agent.rb

@@ -0,0 +1,84 @@
+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: context)
+      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/bunny.rb

@@ -0,0 +1 @@
+require_relative 'bunny/async'

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/memory.rb

@@ -0,0 +1,2 @@
+require_relative 'memory/sync'
+require_relative 'memory/async'