receptacle 0.1.0

data/examples/simple_repo.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require 'bundler/inline'
+
+gemfile true do
+  source 'https://rubygems.org'
+  gem 'receptacle', '../'
+  gem 'mongo'
+end
+
+User = Struct.new(:id, :name)
+
+# define our Repository
+module Repository
+  module User
+    include Receptacle::Repo
+    mediate :find
+    mediate :create
+  end
+end
+
+# we should have a global mongo connection which can be easily reused
+module Connection
+  class Mongo
+    include Singleton
+
+    def initialize
+      @client = ::Mongo::Client.new
+    end
+    attr_reader :client
+    def self.client
+      instance.client
+    end
+  end
+end
+
+# some strategies
+module Repository
+  module User
+    module Strategy
+      class Mongo
+        def find(id:)
+          mongo_to_model(collection.find(_id: id))
+        rescue
+          nil
+        end
+
+        def create(name:)
+          ret = collection.insert_one(name: name)
+          find(id: ret['_id']) # TODO: check this
+        end
+
+        private
+
+        def mongo_to_model(doc)
+          ::User.new(doc['_id'], doc['name'])
+        end
+
+        def collection
+          Connection::Mongo.client[:users]
+        end
+      end
+
+      # in memory is using a simple class instance variable as internal storage
+
+      class InMemory
+        class << self; attr_accessor :store end
+        @store = {}
+        def find(id:)
+          store[id]
+        end
+
+        def create(name:)
+          id = BSON::ObjectId.new
+          store[id] = User.new(id, name)
+        end
+
+        private
+
+        def store
+          self.class.store
+        end
+      end
+    end
+  end
+end
+
+# configure the repository and use it
+Repository::User.strategy Repository::User::Strategy::InMemory
+
+user = Repository::User.create(name: 'foo')
+p user
+p Repository::User.find(id: user.id)
+
+# switching to mongo and we see it's using a different store but keeps the same interface
+Repository::User.strategy Repository::User::Strategy::Mongo
+
+p Repository::User.find(id: user.id)
+#-> nil
+
+user = Repository::User.create(name: 'foo')
+p user
+p Repository::User.find(id: user.id)

data/lib/receptacle/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Receptacle
+  module Errors
+    class NotConfigured < StandardError
+      attr_reader :repo
+      def initialize(repo:)
+        @repo = repo
+        super("Missing Configuration for repository: <#{repo}>")
+      end
+    end
+    class ReservedMethodName < StandardError; end
+  end
+end

data/lib/receptacle/interface_methods.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+require 'receptacle/registration'
+require 'receptacle/errors'
+
+module Receptacle
+  module InterfaceMethods
+    RESERVED_METHOD_NAMES = Set.new(%i(wrappers mediate strategy delegate_to_strategy))
+    private_constant :RESERVED_METHOD_NAMES
+
+    # registers a method_name for the to be mediated or forwarded to the configured strategy
+    #
+    # @param method_name [String] name of method to register
+    def mediate(method_name)
+      raise Errors::ReservedMethodName if RESERVED_METHOD_NAMES.include?(method_name)
+      Registration.repositories[self].methods << method_name
+    end
+    alias delegate_to_strategy mediate
+
+    # get or sets the strategy
+    #
+    # @note will set the strategy for this receptacle if passed in; will only
+    #      return the current strategy if nil or no parameter passed include
+    # @param value [Class,nil]
+    # @return [Class] current configured strategy class
+    def strategy(value = nil)
+      if value
+        Registration.repositories[self].strategy = value
+        Registration.clear_method_cache(self)
+      else
+        Registration.repositories[self].strategy
+      end
+    end
+
+    # get or sets the wrappers
+    #
+    # @note will set the wrappers for this receptacle if passed in; will only
+    #      return the current wrappers if nil or no parameter passed include
+    # @param value [Class,Array(Class),nil] wrappers
+    # @return [Array(Class)] current configured wrappers
+    def wrappers(value = nil)
+      if value
+        Registration.repositories[self].wrappers = Array(value)
+        Registration.clear_method_cache(self)
+      else
+        Registration.repositories[self].wrappers
+      end
+    end
+  end
+end

data/lib/receptacle/method_cache.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+module Receptacle
+  # Cache describing which strategy and wrappers need to be applied for this method
+  # @api private
+  class MethodCache
+    # @return [Symbol] name of the method this cache belongs to
+    attr_reader :method_name
+    # @return [Class] strategy class currently setup
+    attr_reader :strategy
+    # @return [Array(Class)] Array of wrapper classes which implement a wrapper for this method
+    attr_reader :wrappers
+    # @return [Symbol] name of the before action method
+    attr_reader :before_method_name
+    # @return [Symbol] name of the after action method
+    attr_reader :after_method_name
+
+    def initialize(method_name:, strategy:, before_wrappers:, after_wrappers:)
+      @strategy = strategy
+      @before_method_name = :"before_#{method_name}"
+      @after_method_name = :"after_#{method_name}"
+      @method_name = method_name.to_sym
+      before_wrappers ||= []
+      after_wrappers ||= []
+      @wrappers = before_wrappers | after_wrappers
+      @skip_before_wrappers = before_wrappers.empty?
+      @skip_after_wrappers = after_wrappers.empty?
+    end
+
+    # @return [Boolean] true if no before wrappers need to be applied for this method
+    def skip_before_wrappers?
+      @skip_before_wrappers
+    end
+
+    # @return [Boolean] true if no after wrappers need to be applied for this method
+    def skip_after_wrappers?
+      @skip_after_wrappers
+    end
+  end
+end

data/lib/receptacle/method_delegation.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+require 'receptacle/method_cache'
+require 'receptacle/registration'
+require 'receptacle/errors'
+
+module Receptacle
+  # module which enables a repository to mediate methods dynamically to wrappers and strategy
+  # @api private
+  module MethodDelegation
+    # dynamically build mediation method on first invocation if the method is registered
+    def method_missing(method_name, *arguments, &block)
+      if Registration.repositories[self].methods.include?(method_name)
+        public_send(__build_method(method_name), *arguments, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      Registration.repositories[self].methods.include?(method_name) || super
+    end
+
+    # @param method_name [#to_sym]
+    # @return [void]
+    def __build_method(method_name)
+      method_cache = __build_method_call_cache(method_name)
+      if method_cache.wrappers.nil? || method_cache.wrappers.empty?
+        __define_shortcut_method(method_cache)
+      else
+        __define_full_method(method_cache)
+      end
+    end
+
+    # build method cache for given method name
+    # @param method_name [#to_sym]
+    # @return [MethodCache]
+    def __build_method_call_cache(method_name)
+      config = Registration.repositories[self]
+      before_method_name = :"before_#{method_name}"
+      after_method_name = :"after_#{method_name}"
+
+      raise Errors::NotConfigured, repo: self if config.strategy.nil?
+      MethodCache.new(
+        strategy: config.strategy,
+        before_wrappers: config.wrappers.select { |w| w.method_defined?(before_method_name) },
+        after_wrappers: config.wrappers.select { |w| w.method_defined?(after_method_name) },
+        method_name: method_name
+      )
+    end
+
+    # build lightweight method to mediate method calls to strategy without wrappers
+    # @param method_cache [MethodCache] method_cache of the method to be build
+    # @return [void]
+    def __define_shortcut_method(method_cache)
+      define_singleton_method(method_cache.method_name) do |*args, &inner_block|
+        method_cache.strategy.new.public_send(method_cache.method_name, *args, &inner_block)
+      end
+    end
+
+    # build method to mediate method calls to strategy with full wrapper support
+    # @param method_cache [MethodCache] method_cache of the method to be build
+    # @return [void]
+    def __define_full_method(method_cache)
+      define_singleton_method(method_cache.method_name) do |*args, &inner_block|
+        __run_wrappers(method_cache, *args) do |*call_args|
+          method_cache.strategy.new.public_send(method_cache.method_name, *call_args, &inner_block)
+        end
+      end
+    end
+
+    # runtime method to call before and after wrapper in correct order
+    # @param method_cache [MethodCache] method_cache for the current method
+    # @param input_args input parameter of the repository method call
+    # @return strategy method return value after all wrappers where applied
+    def __run_wrappers(method_cache, input_args)
+      wrappers = method_cache.wrappers.map(&:new)
+      args = if method_cache.skip_before_wrappers?
+               input_args
+             else
+               __run_before_wrappers(wrappers, method_cache.before_method_name, input_args)
+             end
+      ret = yield(args)
+      return ret if method_cache.skip_after_wrappers?
+      __run_after_wrappers(wrappers, method_cache.after_method_name, args, ret)
+    end
+
+    # runtime method to execute all before wrappers
+    # @param wrappers [Array] all wrapper instances to be executed
+    # @param method_name [Symbol] name of method to be executed on wrappers
+    # @param args input args of the repository method
+    # @return processed method args by before wrappers
+    def __run_before_wrappers(wrappers, method_name, args)
+      wrappers.each do |wrapper|
+        next unless wrapper.respond_to?(method_name)
+        args = wrapper.public_send(method_name, args)
+      end
+      args
+    end
+
+    # runtime method to execute all after wrappers
+    # @param wrappers [Array] all wrapper instances to be executed
+    # @param method_name [Symbol] name of method to be executed on wrappers
+    # @param args input args to the strategy method (after processing in before wrappers)
+    # @param return_value return value of strategy method
+    # @return processed return value by all after wrappers
+    def __run_after_wrappers(wrappers, method_name, args, return_value)
+      wrappers.reverse_each do |wrapper|
+        next unless wrapper.respond_to?(method_name)
+        return_value = wrapper.public_send(method_name, return_value, args)
+      end
+      return_value
+    end
+  end
+end

data/lib/receptacle/registration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+require 'singleton'
+require 'set'
+module Receptacle
+  # keeps global state of repositories, the defined strategy, set wrappers and methods to mediate
+  class Registration
+    include Singleton
+    Tuple = Struct.new(:strategy, :wrappers, :methods)
+
+    attr_reader :repositories
+
+    def initialize
+      @repositories = Hash.new do |h, k|
+        h[k] = Tuple.new(nil, [], Set.new)
+      end
+    end
+
+    def self.repositories
+      instance.repositories
+    end
+
+    # {clear_method_cache} removes dynamically defined methods
+    # this is needed to make strategy and wrappers changes inside the codebase possible
+    def self.clear_method_cache(receptacle)
+      instance.repositories[receptacle].methods.each do |method_name|
+        begin
+          receptacle.singleton_class.send(:remove_method, method_name)
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/receptacle/test_support.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module Receptacle
+  module TestSupport
+    # provides helpful method to toggle strategies during testing
+    #
+    # can be used in rspec like this
+    #
+    #    require 'receptacle/test_support'y
+    #    RSpec.configure do |c|
+    #      c.include Receptacle::TestSupport
+    #    end
+    #
+    #    RSpec.describe(UserRepository) do
+    #      around do |example|
+    #        with_strategy(strategy){example.run}
+    #      end
+    #      let(:strategy) { UserRepository::Strategy::MySQL }
+    #      ...
+    #    end
+    #
+    # or similar with minitest
+    #
+    #    require 'receptacle/test_support'
+    #    class UserRepositoryTest < Minitest::Test
+    #      def described_class
+    #        UserRepository
+    #      end
+    #      def repo_exists(strategy)
+    #        with_strategy(strategy) do
+    #          assert described_class.exists(id: 5)
+    #        end
+    #      end
+    #      def test_mysql
+    #        repo_exists(UserRepository::Strategy::MySQL)
+    #      end
+    #      def test_fake
+    #        repo_exists(UserRepository::Strategy::Fake)
+    #      end
+    #    end
+    def with_strategy(strategy, repo = described_class)
+      original_strategy = repo.strategy
+      repo.strategy strategy
+      yield
+      repo.strategy original_strategy
+    end
+  end
+end

data/lib/receptacle/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Receptacle
+  VERSION = '0.1.0'
+end

data/lib/receptacle.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require 'receptacle/version'
+require 'receptacle/interface_methods'
+require 'receptacle/method_delegation'
+
+module Receptacle
+  module Repo
+    def self.included(base)
+      base.extend(InterfaceMethods)
+      base.extend(MethodDelegation)
+    end
+  end
+end

data/performance/benchmark.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require 'bundler/inline'
+
+gemfile false do
+  source 'https://rubygems.org'
+  gem 'benchmark-ips'
+  gem 'receptacle', path: './..'
+end
+
+require_relative 'speed_receptacle'
+
+Speed.strategy(Speed::Strategy::One)
+Speed.wrappers [Speed::Wrappers::W1,
+                Speed::Wrappers::W2,
+                Speed::Wrappers::W3,
+                Speed::Wrappers::W4,
+                Speed::Wrappers::W5,
+                Speed::Wrappers::W6]
+
+print 'w/ wrappers'
+Benchmark.ips do |x|
+  x.warmup = 10 if RUBY_ENGINE == 'jruby'
+  x.report('a: 2x around, 1x before, 1x after') { Speed.a(1) }
+  x.report('b: 1x around, 1x before, 1x after') { Speed.b(1) }
+  x.report('c: 1x before, 1x after') { Speed.c(1) }
+  x.report('d: 1x after') { Speed.d(1) }
+  x.report('e: 1x before') { Speed.e(1) }
+  x.report('f: 1x around') { Speed.f(1) }
+  x.report('g: no wrappers') { Speed.g(1) }
+end
+
+Speed.wrappers []
+print 'method dispatching w/ wrappers'
+Benchmark.ips do |x|
+  x.warmup = 10 if RUBY_ENGINE == 'jruby'
+  x.report('via receptacle') { Speed.a(:foo) }
+  x.report('direct via public_send') { Speed::Strategy::One.new.public_send(:a, :foo) }
+  x.report('direct via method-method') do
+    m = Speed::Strategy::One.new.method(:a)
+    m.call(:foo)
+  end
+  x.report('direct method-call') { Speed::Strategy::One.new.a(:foo) }
+  x.compare!
+end

data/performance/profile.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# run with --profile.api in JRUBY_OPTS
+require 'bundler/inline'
+require 'jruby/profiler'
+PROFILE_NAME = 'receptacle'
+
+gemfile false do
+  source 'https://rubygems.org'
+  gem 'receptacle', path: './..'
+end
+require_relative 'speed_receptacle'
+
+Speed.strategy(Speed::Strategy::One)
+Speed.wrappers [Speed::Wrappers::W1,
+                Speed::Wrappers::W2,
+                Speed::Wrappers::W3,
+                Speed::Wrappers::W4,
+                Speed::Wrappers::W5,
+                Speed::Wrappers::W6]
+Speed.a(1)
+Speed.b(1)
+Speed.c(1)
+Speed.d(1)
+Speed.e(1)
+Speed.f(1)
+Speed.g(1)
+
+GC.disable
+profile_data = JRuby::Profiler.profile do
+  100_000.times { Speed.a(1) }
+end
+
+profile_printer = JRuby::Profiler::GraphProfilePrinter.new(profile_data)
+profile_printer.printProfile(File.open("#{PROFILE_NAME}.graph.profile", 'w+'))
+profile_printer.printProfile(STDOUT)
+
+profile_printer = JRuby::Profiler::FlatProfilePrinter.new(profile_data)
+profile_printer.printProfile(File.open("#{PROFILE_NAME}.flat.profile", 'w+'))

data/performance/speed_receptacle.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+require 'receptacle'
+module Speed
+  include Receptacle::Repo
+  mediate :a
+  mediate :b
+  mediate :c
+  mediate :d
+  mediate :e
+  mediate :f
+  mediate :g
+  module Strategy
+    class One
+      def a(arg)
+        arg
+      end
+      alias b a
+      alias c a
+      alias d a
+      alias e a
+      alias f a
+      alias g a
+    end
+  end
+
+  module Wrappers
+    class W1
+      def before_a(args)
+        args
+      end
+
+      def after_a(return_values, _)
+        return_values
+      end
+
+      def before_f(args)
+        args
+      end
+
+      def after_f(return_values, _)
+        return_values
+      end
+    end
+
+    class W2
+      # :a
+      def before_a(args)
+        args
+      end
+
+      def after_a(return_values, _)
+        return_values
+      end
+
+      # :b
+      def before_b(args)
+        args
+      end
+
+      def after_b(return_values, _)
+        return_values
+      end
+    end
+    class W3
+      def before_a(args)
+        args
+      end
+
+      def before_c(args)
+        args
+      end
+    end
+
+    class W4
+      def after_a(return_values, _)
+        return_values
+      end
+
+      def after_d(return_value, _)
+        return_value
+      end
+    end
+
+    class W5
+      def before_b(args)
+        args
+      end
+
+      def after_c(return_value, _)
+        return_value
+      end
+    end
+
+    class W6
+      def after_b(return_value, _)
+        return_value
+      end
+
+      def before_e(args)
+        args
+      end
+    end
+  end
+end

data/receptacle.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+# frozen_string_literal: true
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'receptacle/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'receptacle'
+  spec.version       = Receptacle::VERSION
+  spec.authors       = ['Andreas Eger']
+  spec.email         = ['dev@eger-andreas.de']
+
+  spec.summary       = 'repository pattern'
+  spec.description   = 'provides functionality for the repository or strategy pattern'
+  spec.homepage      = 'https://github.com/andreaseger/receptacle'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '~> 2.2'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rubocop_runner', '~> 2.0'
+  spec.add_development_dependency 'rubocop', '~> 0.46.0'
+  spec.add_development_dependency 'simplecov', '~> 0.13'
+  spec.add_development_dependency 'codecov'
+  spec.add_development_dependency 'guard'
+  spec.add_development_dependency 'guard-minitest'
+  spec.add_development_dependency 'guard-rubocop'
+end