startback-jobs 0.13.0 → 0.14.0

data/lib/startback/support/operation_runner.rb

@@ -0,0 +1,150 @@
+module Startback
+  module Support
+    #
+    # Support module for high-level architectural components that
+    # execute operations as part of their logic, see e.g. Web::Api.
+    #
+    # This module contributes a `run` instance method that allows
+    # binding an operation with a world, and executing it while
+    # supporting around runners.
+    #
+    # Example:
+    #
+    #     class HighLevelComponent
+    #       include Startback::Support::OperationRunner
+    #
+    #       def some_method
+    #         # Runs the operation passed after some binding
+    #         run SomeOperation.new
+    #       end
+    #
+    #     protected
+    #
+    #       # Overriden to inject some extra world
+    #       def operation_world(op)
+    #         super(op).merge({ hello: "world" })
+    #       end
+    #
+    #       # Execute this around op
+    #       around_run do |op, then_block|
+    #         puts "About to run #{op.inspect}"
+    #         then_block.call
+    #       end
+    #
+    #       # SomeClass#call will be called with the operation
+    #       # as first parameter and a block as continuation
+    #       around_run SomeClass.new
+    #
+    #     end
+    #
+    module OperationRunner
+
+      # Contributes the hook DSL methods to classes that include
+      # the OperationRunner module
+      module ClassMethods
+
+        # Registers a callable to be executed around operation running.
+        #
+        # In its block form, the callable is `instance_exec`uted on the
+        # runner instance, with the operation passed as first parameter
+        # and a then_block callable as second parameter (continuation):
+        #
+        #     around_run do |op,then_block|
+        #       # do whatever you want with the op (already bounded)
+        #       puts op.inspect
+        #
+        #       # do not forget to call the continuation block
+        #       then_block.call
+        #     end
+        #
+        # With a parameter responding to `#call`, the latter is invoked
+        # with the operation as parameter and a block as continuation:
+        #
+        #     class Arounder
+        #
+        #       def call(op)
+        #         # do whatever you want with the op (already bounded)
+        #         puts op.inspect
+        #
+        #         # do not forget to call the continuation block
+        #         yield
+        #       end
+        #
+        #     end
+        #
+        def around_run(arounder = nil, &bl)
+          raise ArgumentError, "Arg or block required" unless arounder || bl
+          arounds(true) << [arounder || bl, arounder.nil?]
+        end
+
+      private
+
+        def arounds(create = false)
+          if create
+            @arounds ||= superclass.respond_to?(:arounds, true) \
+                       ? superclass.send(:arounds, true).dup \
+                       : []
+          end
+          @arounds || (superclass.respond_to?(:arounds, true) ? superclass.send(:arounds, true) : [])
+        end
+
+      end
+
+      # When included by a class/module, install the DSL methods
+      def self.included(by)
+        by.extend(ClassMethods)
+      end
+
+      # Runs `operation`, taking care of binding it and executing
+      # hooks.
+      #
+      # This method is NOT intended to be overriden. Use hooks and
+      # `operation_world` to impact default behavior.
+      def run(operation)
+        op_world = operation_world(operation)
+        op_bound = operation.bind(op_world)
+        _run_befores(op_bound)
+        r = _run_with_arounds(op_bound, self.class.send(:arounds))
+        _run_afters(op_bound)
+        r
+      end
+
+    protected
+
+      # Returns the world to use to bind an operation.
+      #
+      # The default implementation returns an empty hash. This is
+      # intended to be overriden by classes including this module.
+      def operation_world(op)
+        {}
+      end
+
+    private
+
+      def _run_befores(op_bound)
+        op_bound.before_call if op_bound.respond_to?(:before_call, true)
+      end
+
+      def _run_with_arounds(operation, arounds = [])
+        if arounds.empty?
+          operation.call
+        else
+          arounder, iexec = arounds.first
+          after_first = ->() {
+            _run_with_arounds(operation, arounds[1..-1])
+          }
+          if iexec
+            self.instance_exec(operation, after_first, &arounder)
+          else
+            arounder.call(self, operation, &after_first)
+          end
+        end
+      end
+
+      def _run_afters(op_bound)
+        op_bound.after_call if op_bound.respond_to?(:after_call, true)
+      end
+
+    end # module OperationRunner
+  end # module Support
+end # module Startback

data/lib/startback/support/robustness.rb

@@ -0,0 +1,157 @@
+module Startback
+  module Support
+    #
+    # This module provides helper methods for robustness of a software design.
+    #
+    # It is included by main Startback abstractions, and can be included by
+    # specific software components who needs fine-tuning of monitoring, logging
+    # and error handling.
+    #
+    # All public methods here follow the following free args parameters:
+    #
+    # 1. First (& second) argument(s) form the log message.
+    #
+    #    A full log message is a Hash having :op (required), :op_took (optional),
+    #    and :op_data (optional) keys.
+    #
+    #    If a String (or two) are used instead, a log message will be built taking
+    #    the former as the executer (a class or instance) and the second as a method.
+    #    `{ op: "executer#method" }`
+    #
+    # 2. The second (or third) argument should be a Logger instance, a Context,
+    #    or an instance knowing its context. The best logger is extracted from it
+    #    and used for actual logging.
+    #
+    # Examples:
+    #
+    #     log(:info, op: "hello", op_data: {foo: 12})    => logged as such on STDOUT
+    #     log(:info, "A simple message")                 => { op: "A simple message" } on STDOUT
+    #     log(:info, Startback, "hello")                 => { op: "Startback#hello"  } on STDOUT
+    #     log(:info, Event.new, "hello")                 => { op: "Event#hello" }      on STDOUT
+    #     log(:info, Event.new, "hello", "hello world")  => { op: "Event#hello", op_data: { message: "hello world" } } on STDOUT
+    #     log(:info, self, context)                      => { op: "..." } on context's logger or STDOUT
+    #     log(:info, self, event)                        => { op: "..." } on event context's logger or STDOUT
+    #     ...
+    #
+    module Robustness
+
+      # Included to avoid poluting the space of the including
+      # classes.
+      module Tools
+
+        def default_logger
+          @@default_logger ||= begin
+            l = ::Logger.new(STDOUT)
+            l.formatter = LogFormatter.new
+            l.warn(op: "#{self}", op_data: { msg: "Using default logger to STDOUT" })
+            @@default_logger = l
+          end
+          @@default_logger
+        end
+        module_function :default_logger
+
+        def logger_for(arg)
+          return arg if arg.is_a?(::Logger)
+          return arg.logger if arg.is_a?(Context) && arg.logger
+          return logger_for(arg.context) if arg.respond_to?(:context, false)
+          default_logger
+        end
+        module_function :logger_for
+
+        def parse_args(log_msg, method = nil, context = nil, extra = nil)
+          method, context, extra = nil, method, context unless method.is_a?(String)
+          context, extra = nil, context if context.is_a?(Hash) || context.is_a?(String) && extra.nil?
+          extra = { op_data: { message: extra } } if extra.is_a?(String)
+          logger = logger_for(context) || logger_for(log_msg)
+          log_msg = if log_msg.is_a?(Hash)
+            log_msg.dup
+          elsif log_msg.is_a?(String)
+            log_msg = { op: "#{log_msg}#{method.nil? ? '' : '#'+method.to_s}" }
+          elsif log_msg.is_a?(Exception)
+            log_msg = { error: log_msg }
+          else
+            log_msg = log_msg.class unless log_msg.is_a?(Module)
+            log_msg = { op: "#{log_msg.name}##{method}" }
+          end
+          log_msg.merge!(extra) if extra
+          [ log_msg, logger ]
+        end
+        module_function :parse_args
+
+        [:debug, :info, :warn, :error, :fatal].each do |meth|
+          define_method(meth) do |args, extra = nil, &bl|
+            act_args = (args + [extra]).compact
+            log_msg, logger = parse_args(*act_args)
+            logger.send(meth, log_msg)
+          end
+          module_function(meth)
+        end
+
+      end # module Tools
+
+      # Logs a specific message with a given severity.
+      #
+      # Severity can be :debug, :info, :warn, :error or :fatal.
+      # The args must follow module's conventions, see above.
+      def log(severity, *args)
+        Tools.send(severity, args)
+      end
+
+      # Calls the block and monitors then log its execution time.
+      #
+      # The args must follow module's conventions, see above.
+      def monitor(*args, &bl)
+        result = nil
+        took = Benchmark.realtime {
+          result = bl.call
+        }
+        Tools.info(args, op_took: took)
+        result
+      end
+
+      # Executes the block without letting errors propagate.
+      # Errors are logged, though. Nothing is logged if everything
+      # goes fine.
+      #
+      # The args must follow module's conventions, see above.
+      def stop_errors(*args, &bl)
+        result = nil
+        took = Benchmark.realtime {
+          result = bl.call
+        }
+        result
+      rescue => ex
+        Tools.fatal(args, op_took: took, error: ex)
+        nil
+      end
+
+      # Tries executing the block up to `n` times, until an attempt
+      # succeeds (then returning the result). Logs the first and last
+      # fatal error, if any.
+      #
+      # The args must follow module's conventions, see above.
+      def try_max_times(n, *args, &bl)
+        retried = 0
+        took = 0
+        begin
+          result = nil
+          took += Benchmark.realtime {
+            result = bl.call
+          }
+          result
+        rescue => ex
+          Tools.error(args + [{op_took: took, error: ex}]) if retried == 0
+          retried += 1
+          if retried < n
+            sleep(retried)
+            retry
+          else
+            Tools.fatal(args + [{op_took: took, error: ex}])
+            raise
+          end
+        end
+      end
+
+    end # module Robustness
+  end # module Support
+end # module Startback

data/lib/startback/support/transaction_manager.rb

@@ -0,0 +1,25 @@
+module Startback
+  module Support
+    class TransactionManager
+
+      def initialize(db, method = :transaction)
+        @db = db
+        @method = method
+      end
+
+      def call(runner, op, &then_block)
+        raise ArgumentError, "A block is required" unless then_block
+
+        before = (op.class.transaction_policy == :before_call)
+        if before
+          @db.send(@method) do
+            then_block.call
+          end
+        else
+          then_block.call
+        end
+      end
+
+    end # class TransactionManager
+  end # module Support
+end # module Startback

data/lib/startback/support/transaction_policy.rb

@@ -0,0 +1,33 @@
+module Startback
+  module Support
+    module TransactionPolicy
+
+      # Returns the operation's transaction policy
+      def transaction_policy
+        @transaction_policy || :before_call
+      end
+
+      # Sets the transaction policy to use. Valid values are:
+      # - before_call : the transaction is started by the operation
+      #   runner, right before calling the #call method on operation
+      #   instance
+      # - within_call: the transaction is started by the operation
+      #   itself, as part of its internal logic.
+      def transaction_policy=(policy)
+        unless [:before_call, :within_call].include?(policy)
+          raise ArgumentError, "Unknown policy `#{policy}`"
+        end
+        @transaction_policy = policy
+      end
+
+      def after_commit(&bl)
+        after_call do
+          db.after_commit do
+            instance_exec(&bl)
+          end
+        end
+      end
+
+    end # module TransactionPolicy
+  end # module Support
+end # module Startback

data/lib/startback/support/world.rb

@@ -0,0 +1,54 @@
+module Startback
+  module Support
+    class World
+      include DataObject
+
+      attr_accessor :_factory
+      protected :_factory=
+
+      def factory(who, &block)
+        dup.tap do |x|
+          x._factory = (self._factory || {}).merge(who => block)
+        end
+      end
+
+      attr_accessor :_scope
+      protected :_scope=
+
+      def with_scope(scope)
+        dup.tap do |x|
+          x._scope = scope
+        end
+      end
+
+      def with(hash)
+        dup.tap do |x|
+          x._data = to_data.merge(hash)
+        end
+      end
+
+    private
+
+      def _data_allow_camelize
+        false
+      end
+
+      def _data_allow_query
+        false
+      end
+
+      def _data_key_not_found(key)
+        raise Startback::Error, "Scope must be defined" unless s = _scope
+
+        block = (_factory || {})[key]
+        if block
+          factored = s.instance_exec(&block)
+          @_data = @_data.dup.merge(key => factored).freeze
+          [key, false]
+        else
+          nil
+        end
+      end
+    end # class World
+  end # module Support
+end # module Startback

data/lib/startback/support.rb

@@ -0,0 +1,26 @@
+module Startback
+  module Support
+
+    def logger
+      Startback::LOGGER
+    end
+
+    def deep_merge(h1, h2)
+      h1.merge(h2){|k,v1,v2|
+        v1.is_a?(Hash) && v2.is_a?(Hash) ? deep_merge(v1, v2) : v2
+      }
+    end
+    module_function :deep_merge
+
+  end # module Support
+end # module Startback
+require_relative 'support/env'
+require_relative 'support/log_formatter'
+require_relative 'support/logger'
+require_relative 'support/robustness'
+require_relative 'support/hooks'
+require_relative 'support/operation_runner'
+require_relative 'support/transaction_policy'
+require_relative 'support/transaction_manager'
+require_relative 'support/data_object'
+require_relative 'support/world'

data/lib/startback/version.rb

@@ -0,0 +1,8 @@
+module Startback
+  module Version
+    MAJOR = 0
+    MINOR = 14
+    TINY  = 0
+  end
+  VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"
+end

data/lib/startback/web/api.rb

@@ -0,0 +1,99 @@
+module Startback
+  module Web
+    class Api < Sinatra::Base
+      include Support
+      include Errors
+
+      set :raise_errors, true
+      set :show_exceptions, false
+      set :dump_errors, false
+
+    protected
+
+      ###
+      ### Facade over context
+      ###
+
+      def context
+        env[Startback::Context::Middleware::RACK_ENV_KEY]
+      end
+
+      def with_context(ctx = nil)
+        old_context = self.context
+        new_context = ctx || self.context.dup
+        env[Startback::Context::Middleware::RACK_ENV_KEY] = new_context
+        result = ctx ? yield : yield(new_context)
+        env[Startback::Context::Middleware::RACK_ENV_KEY] = old_context
+        result
+      end
+
+      ###
+      ### Facade over third party tools
+      ###
+      include Support::OperationRunner
+
+      def operation_world(op)
+        { context: context }
+      end
+
+      ###
+      ### About the body / input
+      ###
+
+      def loaded_body
+        @loaded_body ||= case ctype = request.content_type
+        when /json/
+          json_body
+        when /multipart\/form-data/
+          file = params[:file]
+          file_body file, Path(file[:filename]).extname
+        else
+          unsupported_media_type_error!(ctype)
+        end
+      end
+
+      def json_body(body = request.body.read)
+        JSON.load(body)
+      end
+
+      def file_body(file, ctype)
+        raise UnsupportedMediaTypeError, "Unable to use `#{ctype}` as input data"
+      end
+
+      ###
+      ### Various reusable responses
+      ###
+
+      def serve_nothing
+        [ 204, {}, [] ]
+      end
+
+      def serve(entity_description, entity, ct = nil)
+        if entity.nil?
+          status 404
+          content_type :json
+          { description: "#{entity_description} not found" }.to_json
+        elsif entity.respond_to?(:to_dto)
+          ct, body = entity.to_dto(context).to(env['HTTP_ACCEPT'], ct)
+          content_type ct
+          _serve(body)
+        elsif entity.is_a?(Path)
+          _serve(entity)
+        else
+          content_type ct || "application/json"
+          entity.to_json
+        end
+      end
+
+      def _serve(body)
+        case body
+        when Path
+          send_file(body)
+        else
+          body
+        end
+      end
+
+    end # class Api
+  end # module Web
+end # module Startback

data/lib/startback/web/auto_caching.rb

@@ -0,0 +1,85 @@
+module Startback
+  module Web
+    #
+    # This rack middleware automatically mark response as non being cacheable
+    # in development, and being cacheble in production.
+    #
+    # The headers to set in development and production can be passed at
+    # construction, as well as whether the development environment must be
+    # forced. This class may also be configured through environment variables:
+    #
+    # - RACK_ENV: when "production" use the production headers, otherwise use
+    #     the development ones
+    # - STARTBACK_AUTOCACHING_DEVELOPMENT_CACHE_CONTROL: Cache-Control header
+    #     to use in development mode
+    # - STARTBACK_AUTOCACHING_PRODUCTION_CACHE_CONTROL: Cache-Control header
+    #     to use in production mode
+    #
+    # Example:
+    #
+    #     # Default configuration
+    #     use Autocaching
+    #
+    #     # Force development mode
+    #     use Autocaching, true
+    #
+    #     # Force production mode
+    #     use Autocaching, false
+    #
+    #     # Set production headers manually
+    #     use Autocaching, { :production => "public, no-cache, no-store" }
+    #
+    class AutoCaching
+
+      # Cache-Control header to use in development mode
+      DEVELOPMENT_CACHE_CONTROL = ENV['STARTBACK_AUTOCACHING_DEVELOPMENT_CACHE_CONTROL'] || \
+                                  "no-cache, no-store, max-age=0, must-revalidate"
+
+      # Cache-Control header to use in produdction mode
+      PRODUCTION_CACHE_CONTROL = ENV['STARTBACK_AUTOCACHING_PRODUCTION_CACHE_CONTROL'] ||\
+                                 "public, must-revalidate, max-age=3600, s-max-age=3600"
+
+      def initialize(app, development = nil, cache_headers = {})
+        development, cache_headers = nil, development if development.is_a?(Hash)
+        @app = app
+        @development = development.nil? ? infer_is_development : development
+        @cache_headers = default_headers.merge(normalize_headers(cache_headers))
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        [status, patch_response_headers(headers), body]
+      end
+
+    protected
+
+      def patch_response_headers(hs)
+        (development? ? @cache_headers[:development] : @cache_headers[:production]).merge(hs)
+      end
+
+      def development?
+        !!@development
+      end
+
+      def infer_is_development
+        ENV['RACK_ENV'] != "production"
+      end
+
+      def default_headers
+        {
+          development: {
+            "Cache-Control" => DEVELOPMENT_CACHE_CONTROL
+          },
+          production: {
+            "Cache-Control" => PRODUCTION_CACHE_CONTROL
+          }
+        }
+      end
+
+      def normalize_headers(h)
+        Hash[h.map{|k,v| [k, v.is_a?(Hash) ? v : {"Cache-Control" => v} ] }]
+      end
+
+    end # class AutoCaching
+  end # module Web
+end # module Startback

data/lib/startback/web/catch_all.rb

@@ -0,0 +1,52 @@
+module Startback
+  module Web
+    #
+    # This Rack middleware catches all exceptions that are raised by sublayers
+    # in the Rack chain. It converts them to correct 500 Errors, with a generic
+    # exception message encoded in json.
+    #
+    # This class aims at being used as top level of a Rack chain. It is not
+    # aimed at being subclassed.
+    #
+    # Fatal error cached are also sent as a `fatal` messange, on the error
+    # handler provided on Context#error_handler.fatal, if any.
+    #
+    # Examples:
+    #
+    #     Rack::Builder.new do
+    #       use Startback::Web::CatchAll
+    #     end
+    #
+    class CatchAll < Rack::Robustness
+      include Errors
+      include Support::Robustness
+
+      FATAL_ERROR = {
+        code: "Startback::Errors::InternalServerError",
+        description: "An error occured, sorry"
+      }.to_json
+
+      self.catch_all
+      self.on(Exception)
+      self.status 500
+      self.content_type 'application/json'
+      self.body FATAL_ERROR
+
+      self.ensure(true) do |ex|
+        context = env[Context::Middleware::RACK_ENV_KEY]
+        begin
+          if context && context.respond_to?(:error_handler, true) && context.error_handler
+            context.error_handler.fatal(ex)
+          else
+            log(:fatal, self, "ensure", context, error: ex)
+          end
+        rescue => ex2
+          STDERR.puts(ex2.message)
+          STDERR.puts(ex2.backtrace[0..10].join("\n"))
+          raise
+        end
+      end
+
+    end # class CatchAll
+  end # class Web
+end # module Startback