startback 0.4.5 → 0.5.0

data/lib/startback/event.rb

@@ -0,0 +1,43 @@
+module Startback
+  #
+  # An Event occuring a given context and having a type and attached data.
+  #
+  # Event instances have String types that are by default unrelated to ruby
+  # classes. Also, this Event class has a `json` information contract that
+  # allows dumping & reloading them easily. A context or context_factory may
+  # be provided in dress world to reload the event context from data, but
+  # that logic is opaque to this class.
+  #
+  # This class is intended to be subclassed if a more specific event protocol
+  # is wanted.
+  #
+  class Event
+
+    def initialize(type, data, context = nil)
+      @type = type.to_s
+      @data = OpenStruct.new(data)
+      @context = context
+    end
+    attr_reader :context, :type, :data
+
+    def self.json(src, world = {})
+      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)
+    end
+
+    def to_json(*args, &bl)
+      h = {
+        type: self.type,
+        data: data.to_h
+      }
+      h[:context] = context if context
+      h.to_json(*args, &bl)
+    end
+
+  end # class Event
+end # module Startback

data/lib/startback/operation.rb

@@ -1,16 +1,45 @@
 module Startback
+  #
+  # High-level Operation abstraction, that is a piece of code that executes
+  # on demand and (generally) changes the state of the software system.
+  #
+  # An operation is basically an object that respond to `call`, but that
+  # executes within a given world (see `bind`). It also has before and
+  # after hooks that allows specifying what needs to be done before invoking
+  # call and after having invoked it. All this protocol is actually under
+  # the responsibility of an `OperationRunner`. Operations should not be
+  # called manually by third-party code.
+  #
+  # Example:
+  #
+  #     class SayHello < Startback::Operation
+  #
+  #       before_call do
+  #         # e.g. check_some_permissions
+  #       end
+  #
+  #       def call
+  #         puts "Hello"
+  #       end
+  #
+  #       after_call do
+  #         # e.g. log and/or emit something on a bus
+  #       end
+  #
+  #     end
+  #
   class Operation
     include Errors
+    include Support::OperationRunner
+    include Support::Hooks.new(:call)
 
     attr_accessor :world
-
     protected :world=
 
     def bind(world)
       return self unless world
-      dup.tap{|op|
-        op.world = world
-      }
+      self.world = world
+      self
     end
 
     def method_missing(name, *args, &bl)
@@ -19,10 +48,14 @@ module Startback
       world.fetch(name){ super }
     end
 
+    def respond_to?(name, *args)
+      super || (world && world.has_key?(name))
+    end
+
   protected
 
-    def run(operation)
-      operation.bind(self.world).call
+    def operation_world(op)
+      self.world
     end
 
   end # class Operation

data/lib/startback/support/fake_logger.rb

@@ -0,0 +1,18 @@
+module Startback
+  module Support
+    class FakeLogger < Logger
+
+      def initialize(*args)
+        @last_msg = nil
+      end
+      attr_reader :last_msg
+
+      [:debug, :info, :warn, :error, :fatal].each do |meth|
+        define_method(meth) do |msg|
+          @last_msg = msg
+        end        
+      end
+
+    end # class Logger
+  end # module Support
+end # module Startback

data/lib/startback/support/hooks.rb

@@ -0,0 +1,48 @@
+module Startback
+  module Support
+    class Hooks < Module
+
+      def initialize(suffix)
+        @suffix = suffix
+        define_method :"before_#{suffix}" do
+          self.class.__befores.each do |bl|
+            instance_exec(&bl)
+          end
+        end
+        define_method :"after_#{suffix}" do
+          self.class.__afters.each do |bl|
+            instance_exec(&bl)
+          end
+        end
+      end
+      attr_reader :suffix
+
+      def included(by)
+        by.instance_eval %Q{
+          def __befores(create = false)
+            if create
+              @__befores ||= (superclass.respond_to?(:__befores, false) ? superclass.__befores.dup : [])
+            end
+            @__befores || (superclass.respond_to?(:__befores, false) ? superclass.__befores : [])
+          end
+
+          def __afters(create = false)
+            if create
+              @__afters ||= (superclass.respond_to?(:__afters, false) ? superclass.__afters.dup : [])
+            end
+            @__afters || (superclass.respond_to?(:__afters, false) ? superclass.__afters : [])
+          end
+
+          def before_#{suffix}(&bl)
+            __befores(true) << bl
+          end
+
+          def after_#{suffix}(&bl)
+            __afters(true) << bl
+          end
+        }
+      end
+
+    end # class Hooks
+  end # module Support
+end # module Startback

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,153 @@
+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(op: "hello", op_data: {foo: 12}) => logged as such on STDOUT
+    #     log("A simple message")              => { op: "A simple message" } on STDOUT
+    #     log(Startback, "hello")              => { op: "Startback#hello"  } on STDOUT
+    #     log(Event.new, "hello")              => { op: "Event#hello" }      on STDOUT
+    #     log(self, context)                   => { op: "..." } on context's logger or STDOUT
+    #     log(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 ||= ::Logger.new(STDOUT)
+          from = caller.reject{|x| x =~ /lib\/startback/ }.first
+          @@default_logger.debug("Watch out, using default logger from: #{from}")
+          @@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) && extra.nil?
+          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}" }
+          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]
+            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.debug(args, op_took: took)
+        result
+      rescue => ex
+        Tools.error(args, error: ex)
+        raise
+      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.error(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.rb

@@ -15,3 +15,6 @@ module Startback
   end # module Support
 end # module Startback
 require_relative 'support/logger'
+require_relative 'support/robustness'
+require_relative 'support/hooks'
+require_relative 'support/operation_runner'

data/lib/startback/version.rb

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

data/lib/startback/web/api.rb

@@ -20,11 +20,10 @@ module Startback
       ###
       ### Facade over third party tools
       ###
+      include Support::OperationRunner
 
-      def run(operation)
-        operation
-          .bind({ context: context })
-          .call
+      def operation_world(op)
+        { context: context }
       end
 
       ###

data/lib/startback/web/catch_all.rb

@@ -19,6 +19,7 @@ module Startback
     #
     class CatchAll < Rack::Robustness
       include Errors
+      include Support::Robustness
 
       FATAL_ERROR = {
         code: "Startback::Errors::InternalServerError",
@@ -32,12 +33,18 @@ module Startback
       self.body FATAL_ERROR
 
       self.ensure(true) do |ex|
+        STDERR.puts(ex.message)
         context = env[Context::Middleware::RACK_ENV_KEY]
-        if context && context.respond_to?(:error_handler) && context.error_handler
-          context.error_handler.fatal(ex)
-        else
-          Startback::LOGGER.fatal(ex.message)
-          Startback::LOGGER.fatal(ex.backtrace.join("\n"))
+        begin
+          if context && context.respond_to?(:error_handler, true) && context.error_handler
+            context.error_handler.fatal(ex)
+          else
+            log(:fatal, self, "ensure", error: ex)
+          end
+        rescue => ex2
+          STDERR.puts(ex2.message)
+          STDERR.puts(ex2.backtrace[0..10].join("\n"))
+          raise
         end
       end
 

data/lib/startback/web/middleware.rb

@@ -0,0 +1,13 @@
+module Startback
+  module Web
+    module Middleware
+
+    protected
+
+      def context(env = @env)
+        ::Startback::Context::Middleware.context(env) || Errors.server_error!("Unable to find context!!")
+      end
+
+    end # module Middleware
+  end # module Web
+end # module Startback

data/lib/startback.rb

@@ -3,6 +3,8 @@ require 'rack/robustness'
 require 'finitio'
 require 'logger'
 require 'path'
+require 'ostruct'
+require 'benchmark'
 # Provides a reusable backend framework for backend components written
 # in ruby.
 #

data/spec/spec_helper.rb

@@ -1,5 +1,7 @@
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'startback'
+require 'startback/bus'
+require 'startback/support/fake_logger'
 require 'rack/test'
 
 module SpecHelpers

data/spec/unit/audit/test_trailer.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+require 'startback/audit'
+module Startback
+  module Audit
+    describe Trailer do
+
+      let(:trailer) {
+        Trailer.new("/tmp/trail.log")
+      }
+
+      describe "op_data" do
+
+        def op_data(op, trailer = self.trailer)
+          trailer.send(:op_data, op)
+        end
+
+        it 'uses to_trail in priority if provided' do
+          op = OpenStruct.new(to_trail: { foo: "bar" }, input: 12, request: 13)
+          expect(op_data(op)).to eql({ foo: "bar" })
+        end
+
+        it 'uses input then' do
+          op = OpenStruct.new(input: { foo: "bar" }, request: 13)
+          expect(op_data(op)).to eql({ foo: "bar" })
+        end
+
+        it 'uses request then' do
+          op = OpenStruct.new(request: { foo: "bar" })
+          expect(op_data(op)).to eql({ foo: "bar" })
+        end
+
+        it 'applies default blacklists for security reasons' do
+          op = OpenStruct.new(input: {
+            token: "will not be dumped",
+            a_token: "will not be dumped",
+            AToken: "will not be dumped",
+            password: "will not be dumped",
+            secret: "will not be dumped",
+            credentials: "will not be dumped",
+            foo: "bar"
+          })
+          expect(op_data(op)).to eql({
+            foo: "bar"
+          })
+        end
+
+        it 'applies default blacklists to data arrays too' do
+          op = OpenStruct.new(input: [{
+            token: "will not be dumped",
+            a_token: "will not be dumped",
+            AToken: "will not be dumped",
+            password: "will not be dumped",
+            secret: "will not be dumped",
+            credentials: "will not be dumped",
+            foo: "bar"
+          }])
+          expect(op_data(op)).to eql([{
+            foo: "bar"
+          }])
+        end
+
+        it 'uses the stop words provided at construction' do
+          t = Trailer.new("/tmp/trail.log", blacklist: "hello and     world")
+          op = OpenStruct.new(request: { Hello: "bar", World: "foo", foo: "bar" })
+          expect(op_data(op, t)).to eql({ foo: "bar" })
+        end
+
+      end
+
+      describe "op_context" do
+
+        def op_context(op, trailer = self.trailer)
+          trailer.send(:op_context, op)
+        end
+
+        it 'applies default blacklists for security reasons' do
+          op = OpenStruct.new(context: {
+            token: "will not be dumped",
+            foo: "bar"
+          })
+          expect(op_context(op)).to eql({ foo: "bar" })
+        end
+
+      end
+
+    end
+  end
+end