redstruct 0.1.7 → 0.2.0

data/lib/redstruct/utils/iterable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Redstruct
+  module Utils
+    # Adds iterable capabilities to any object which implements a to_enum method with the correct arguments.
+    module Iterable
+      # Iterates over the keys of this factory using one of the redis scan commands (scan, zscan, hscan, sscan)
+      # For more about the scan command, see https://redis.io/commands/scan
+      # @param [String] match will prepend the factory namespace to the match string; see the redis documentation for the syntax
+      # @param [Integer] count maximum number of items returned per scan command (see Redis internals)
+      # @param [Integer] max_iterations maximum number of iterations; if nil given, could potentially never terminate
+      # @param [Integer] batch_size if greater than 1, will yield arrays of keys of size between 1 and batch_size
+      # @return [Enumerator] if no block given, returns an enumerator that you can chain with others
+      def each(match: '*', count: 10, max_iterations: 10_000, batch_size: 1, **options, &block) # rubocop: disable Metrics/ParameterLists
+        enumerator = to_enum(match: match, count: count, **options)
+        enumerator = enumerator.each_slice(batch_size) if batch_size > 1
+        enumerator = Redstruct::Utils::Iterable.bound_enumerator(enumerator, max: max_iterations) unless max_iterations.nil?
+
+        return enumerator unless block_given?
+        return enumerator.each(&block)
+      end
+
+      # Including classes should overload this class to provide an initial enumerator
+      # NOTE: to namespace the matcher (which you should), use `@factory.prefix(match)`
+      # @param [String] match see the redis documentation for the syntax
+      # @param [Integer] count number of keys fetched from redis per scan command (NOTE the enum still passes each keys 1 by 1)
+      def to_enum(match: '*', count: 10) # rubocop: disable Lint/UnusedMethodArgument
+        raise NotImplementedError.new, 'including classes should overload to_enum'
+      end
+
+      class << self
+        # Returns an enumerator which limits the maximum number of iterations
+        # possible on another enumerator.
+        # @param [Enumerator] enumerator the unbounded enumerator to wrap
+        # @param [Integer] max maximum number of iterations possible
+        # @return [Enumerator]
+        def bound_enumerator(enumerator, max:)
+          raise ArgumentError, 'max must be greater than 0' unless max.positive?
+
+          return Enumerator.new do |yielder|
+            iterations = 0
+            loop do
+              yielder << enumerator.next
+              iterations += 1
+              raise StopIteration if iterations == max
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redstruct/utils/scriptable.rb

@@ -1,18 +1,44 @@
+# frozen_string_literal: true
+
+require 'digest'
+
 module Redstruct
   module Utils
+    # Provides utility methods to add lua scripts to any class
     module Scriptable
+      # Callback called whenever the module is included. Adds all methods under ClassMethods as class methods of the
+      # includer.
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # Class methods added when the module is included at the class level (i.e. extend)
       module ClassMethods
-        def defscript(id, source)
-          constant = "SCRIPT_SOURCE_#{id.upcase}"
+        # Creates a method with the given id, which will create a constant and a method in the class. This allows you
+        # to use defscript as a macro for your lua scripts, which gets translated to Ruby code at compile time.
+        # @param [String] id the script ID
+        # @param [String] script the lua script source
+        def defscript(id, script)
+          raise ArgumentError, 'no script given' unless script && !script.empty?
+
+          script = script.strip
+          constant = "SCRIPT_#{id.upcase}"
+
+          if const_defined?(constant)
+            Redstruct.logger.warn("cowardly aborting defscript #{id}; constant with name #{constant} already exists!")
+            return
+          end
+
+          if method_defined?(id)
+            Redstruct.logger.warn("cowardly aborting defscript #{id}; method with name #{id} already exists!")
+            return
+          end
+
           class_eval <<~METHOD, __FILE__, __LINE__ + 1
-          #{constant} = { id: '#{id}'.freeze, source: %(#{source}).freeze }.freeze
-            def #{id}(keys: [], argv: [])
-              return @factory.script(#{constant}[:id], #{constant}[:source]).eval(keys: keys, argv: argv)
-            end
+            #{constant} = { script: %(#{script}).freeze, sha1: Digest::SHA1.hexdigest(%(#{script})).freeze }.freeze
+              def #{id}(keys: [], argv: [])
+                return @factory.script(#{constant}[:script], sha1: #{constant}[:sha1]).eval(keys: keys, argv: argv)
+              end
           METHOD
         end
       end

data/lib/redstruct/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module Redstruct
-  VERSION = '0.1.7'.freeze
+  # Current version
+  VERSION = '0.2.0'
 end

data/lib/redstruct.rb

@@ -1,65 +1,31 @@
-# Dependencies
-require 'redis'
-require 'connection_pool'
+# frozen_string_literal: true
 
-# Utility
-require 'redstruct/version'
-require 'redstruct/utils/inspectable'
-require 'redstruct/utils/scriptable'
-require 'redstruct/utils/coercion'
-
-# Core
-require 'redstruct/connection'
+require 'logger'
 require 'redstruct/configuration'
-require 'redstruct/error'
-require 'redstruct/types/base'
-
-# Factory
-require 'redstruct/factory/creation'
-require 'redstruct/factory/deserialization'
 require 'redstruct/factory'
 
-# Base data types
-require 'redstruct/types/struct'
-require 'redstruct/types/string'
-require 'redstruct/types/counter'
-require 'redstruct/types/hash'
-require 'redstruct/types/list'
-require 'redstruct/types/script'
-require 'redstruct/types/set'
-require 'redstruct/types/sorted_set'
-
+# Top level namespace
+# TODO: Add documentation later
 module Redstruct
   class << self
+    # @return [Redstruct::Configuration] current default configuration
     def config
-      return @config ||= Configuration.new
+      return @config ||= Redstruct::Configuration.new
     end
 
-    def factories
-      return @factories ||= {}
+    # The current logger; if nil, will lazily create a default logger (STDOUT, WARN)
+    # @return [Logger] current logger
+    def logger
+      return @logger ||= default_logger
     end
+    attr_writer :logger
 
-    def [](key)
-      factory = factories[key]
-      factory = make(name: key) if factory.nil?
-
-      return factory
-    end
-
-    def []=(key, factory)
-      if factory.nil?
-        factories.delete(key)
-      else
-        factories[key] = factory
-      end
-    end
-
-    def make(name: nil, pool: nil, namespace: nil)
-      factory = Redstruct::Factory.new(pool: pool, namespace: namespace)
-      name = Redstruct if name.nil?
-      self[name] = factory unless name.nil?
-
-      return factory
+    def default_logger
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::WARN
+      logger.progname = 'Redstruct'
+      return logger
     end
+    private :default_logger
   end
 end

data/lib/yard/defscript_handler.rb

@@ -1,6 +1,8 @@
-module Redstruct
-  class DefscriptHandler < YARD::Handlers::Ruby::Base
-    GROUP_NAME = 'Lua Scripts'.freeze
+# frozen_string_literal: true
+
+module YARD
+  class DefscriptHandler < YARD::Handlers::Ruby::Base # :nodoc:
+    GROUP_NAME = 'Lua Scripts'
 
     handles method_call(:defscript)
     namespace_only

data/test/redstruct/configuration_test.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Redstruct
+  class ConfigurationTest < Redstruct::Test
+    def test_initialize
+      @config = Redstruct::Configuration.new
+      assert_nil @config.default_connection, 'Should have no default connection initially'
+      assert_nil @config.default_namespace, 'Should have no namespace initially'
+    end
+  end
+end

data/test/redstruct/connection_proxy_test.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Redstruct
+  # TODO: not quite sure if this test suite is good enough
+  class ConnectionProxyTest < Redstruct::Test
+    def test_initialize
+      assert_raises(ArgumentError, 'should fail to initialize without a proxy object') { Redstruct::ConnectionProxy.new }
+    end
+
+    def test_connection
+      proxy = connection_proxy(redis_connection)
+      assert_equal 'PONG', proxy.ping, 'Should correctly execute the ping command using the given redis connection'
+    end
+
+    def test_connection_pool
+      proxy = connection_proxy
+      assert_equal 'PONG', proxy.ping, 'Should correctly execute the ping command using the given connection pool'
+    end
+
+    def test_with
+      proxy = connection_proxy
+      proxy.with do |connection|
+        assert_kind_of Redis, connection, 'should have yielded a redis connection'
+        proxy.with do |new_connection|
+          assert_equal connection, new_connection, 'calling with from within a with block should return the same connection'
+        end
+      end
+
+      connection = redis_connection
+      proxy = connection_proxy(connection)
+      proxy.with do |new_connection|
+        assert_equal connection, new_connection, 'calling with when proxying a single connection should return that connection'
+      end
+    end
+
+    # it is easier to test with a mocked redis connection than with a connection pool, and as far as I can tell, has
+    # no downsides
+    def test_proxied_methods
+      connection = flexmock(redis_connection)
+      proxy = connection_proxy(connection)
+
+      proxied_methods = Redis.public_instance_methods(false) - Redstruct::ConnectionProxy::NON_COMMAND_METHODS
+      proxied_methods.each do |method|
+        retval = SecureRandom.hex(8)
+        args = generate_random_args
+        connection.should_receive(method).with(*args, Proc).and_return(retval).once
+        assert_equal retval, proxy.public_send(method, *args) {}, "#{method} should be proxied with the correct arguments and block"
+      end
+
+      # flexmock automatically verifies all expected calls were matched
+    end
+
+    def test_method_missing
+      connection = flexmock(redis_connection)
+      proxy = connection_proxy(connection)
+
+      method = '__strange_method__'
+      connection.should_receive(method).and_return(42)
+      assert_equal 42, proxy.public_send(method), 'Should proxy even missing methods to the connection object'
+    end
+
+    def test_respond_to_missing?
+      assert connection_proxy.respond_to?('__strange_method__'), 'Redis class responds to all missing method, and so should ConnectionProxy'
+    end
+
+    def connection_proxy(connection = nil)
+      connection ||= Redstruct.config.default_connection
+      return Redstruct::ConnectionProxy.new(connection)
+    end
+
+    # obtain a plain redis connection
+    def redis_connection
+      return Redstruct.config.default_connection.with { |c| c }.dup
+    end
+    private :redis_connection
+
+    def generate_random_args
+      argc = SecureRandom.random_number(10) + 1
+      return Array.new(argc) { SecureRandom.hex(4) }
+    end
+    private :generate_random_args
+  end
+end

data/test/redstruct/counter_test.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Redstruct
+  class CounterTest < Redstruct::Test
+    def setup
+      super
+      @factory = create_factory
+      @counter = @factory.counter('counter')
+      @ring = @factory.counter('ring', max: 4)
+      @pair = @factory.counter('pair', by: 2)
+    end
+
+    def test_initialize
+      assert_equal 1, @counter.default_increment, 'should have default increment'
+      assert_nil @counter.max, 'should have no maximum value by default'
+
+      assert_equal 2, @pair.default_increment, 'should increment by 2'
+      assert_nil @pair.max, 'should have no maximum value'
+
+      assert_equal 1, @ring.default_increment, 'should have a default increment'
+      assert_equal 4, @ring.max, 'should have a maximum value'
+    end
+
+    def test_get
+      assert_equal 0, @counter.get, 'initial value is always nil'
+      @counter.set(1)
+      assert_equal 1, @counter.get, 'should be now be equal to 1'
+    end
+
+    def test_set
+      assert_equal 0, @counter.get, 'initial value is always nil'
+      assert @counter.set(2), 'should return true has it has been set'
+      assert_equal 2, @counter.get, 'should be now be equal to 2 after a set'
+    end
+
+    def test_getset
+      assert_equal 0, @counter.getset(2), 'should return the old value (0)'
+      assert_equal 2, @counter.getset(4), 'should return the old value (2)'
+      assert_equal 4, @counter.get, 'should return the current value'
+    end
+
+    def test_increment
+      assert_equal 1, @counter.increment, 'should increment by 1 and return the value'
+      assert_equal 2, @counter.increment, 'should increment by 1 and return the value'
+
+      assert_equal 2, @pair.increment, 'should increment by 2 and return the value'
+      assert_equal 4, @pair.increment, 'should increment by 2 and return the value'
+    end
+
+    def test_increment_by
+      assert_equal 2, @counter.increment(by: 2), 'should increment by 2 and return the new value'
+      assert_equal 3, @counter.increment, 'should increment by 1 and return the new value'
+
+      assert_equal 3, @pair.increment(by: 3), 'should increment by 3 and return the new value'
+      assert_equal 5, @pair.increment, 'should increment by 2 and return the new value'
+
+      assert_equal 2, @ring.increment(by: 2), 'should increment by 2 and return the new value'
+      assert_equal 3, @ring.increment, 'should increment by 1 and return the new value'
+    end
+
+    def test_increment_ring
+      assert_equal 2, @counter.increment(by: 2, max: 3), 'should increment by 2 and return the new value'
+      assert_equal 0, @counter.increment(max: 3), 'should increment by 1, cycle around, and return the new value'
+
+      assert_equal 0, @pair.increment(max: 2), 'should increment by 2, cycle around, and return the new value'
+      assert_equal 0, @pair.increment(max: 2), 'should increment by 2, cycle around, and return the new value'
+
+      assert_equal 2, @ring.increment(by: 2), 'should increment by 2 and return the new value'
+      assert_equal 0, @ring.increment(by: 2), 'should increment by 2, cycle around, and return the new value'
+      assert_equal 1, @ring.increment(by: 5), 'should increment by 2, cycle around, and return the new value'
+      assert_equal 6, @ring.increment(by: 5, max: 7), 'should increment by 2, cycle around, and return the new value'
+    end
+
+    def test_decrement
+      assert_equal(-1, @counter.decrement, 'should decrement by 1 and return the value')
+      assert_equal(-2, @counter.decrement, 'should decrement by 1 and return the value')
+
+      assert_equal(-2, @pair.decrement, 'should decrement by 2 and return the value')
+      assert_equal(-4, @pair.decrement, 'should decrement by 2 and return the value')
+    end
+
+    def test_decrement_by
+      assert_equal(-2, @counter.decrement(by: 2), 'should decrement by 2 and return the new value')
+      assert_equal(-3, @counter.decrement, 'should decrement by 1 and return the new value')
+
+      assert_equal(-3, @pair.decrement(by: 3), 'should decrement by 3 and return the new value')
+      assert_equal(-5, @pair.decrement, 'should decrement by 2 and return the new value')
+
+      assert_equal(-2, @ring.decrement(by: 2), 'should decrement by 2 and return the new value')
+      assert_equal(-3, @ring.decrement, 'should decrement by 1 and return the new value')
+    end
+
+    def test_decrement_ring
+      assert_equal(-2, @counter.decrement(by: 2, max: 3), 'should decrement by 2 and return the new value')
+      assert_equal 0, @counter.decrement(max: 3), 'should decrement by 1, cycle around, and return the new value'
+
+      assert_equal 0, @pair.decrement(max: 2), 'should decrement by 2, cycle around, and return the new value'
+      assert_equal 0, @pair.decrement(max: 2), 'should decrement by 2, cycle around, and return the new value'
+
+      assert_equal(-2, @ring.decrement(by: 2), 'should decrement by 2 and return the new value')
+      assert_equal 0, @ring.decrement(by: 2), 'should decrement by 2, cycle around, and return the new value'
+      assert_equal(-1, @ring.decrement(by: 5), 'should decrement by 2, cycle around, and return the new value')
+      assert_equal(-6, @ring.decrement(by: 5, max: 7), 'should decrement by 2, cycle around, and return the new value')
+    end
+  end
+end

data/test/redstruct/factory/object_test.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Redstruct
+  class Factory
+    class ObjectTest < Redstruct::Test
+      def test_initialize
+        factory = create_factory
+        object = Redstruct::Factory::Object.new(factory: factory)
+        assert_equal factory, object.factory, 'should have the given factory as the object factory'
+      end
+
+      def test_connection
+        factory = create_factory
+        object = Redstruct::Factory::Object.new(factory: factory)
+        assert_equal factory.connection, object.connection, 'should delegate #connection to the factory connection'
+      end
+    end
+  end
+end

data/test/redstruct/factory_test.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module Redstruct
+  class FactoryTest < Redstruct::Test
+    def test_initialize_default
+      flexmock(Redstruct::ConnectionProxy).should_receive(:new).with(Redstruct.config.default_connection).once.pass_thru
+      factory = Redstruct::Factory.new
+
+      refute_nil factory.connection, 'should have the default connection when none provided'
+      assert_equal Redstruct.config.default_namespace, factory.namespace, 'should be the default namespace if none provided'
+    end
+
+    def test_initialize_params
+      namespace = 'test'
+      connection = Redstruct::ConnectionProxy.new(ConnectionPool.new(size: 1, timeout: 1) {}) # for the purpose of the test, does not matter what the pool creates
+      factory = Redstruct::Factory.new(connection: connection, namespace: namespace)
+
+      assert_equal namespace, factory.namespace, 'should have assigned the correct namespace'
+      assert_kind_of Redstruct::ConnectionProxy, factory.connection, 'should have properly constructed the proxy'
+    end
+
+    def test_initialize_no_proxy
+      assert_raises(ArgumentError, 'should fail when no connection proxy given') { Redstruct::Factory.new(connection: 'test') }
+    end
+
+    def test_prefix_no_namespace
+      factory = Redstruct::Factory.new(namespace: '')
+      assert_equal 'key', factory.prefix('key'), 'should not namespace when namespace is blank string'
+    end
+
+    def test_prefix
+      factory = Redstruct::Factory.new(namespace: 'test')
+      assert_equal 'test:key', factory.prefix('key'), 'should correctly prefix the key with a namespace'
+      assert_equal 'test:key', factory.prefix('test:key'), 'should not prefix an already prefixed key'
+      assert_equal 'test:testkey', factory.prefix('testkey'), 'should prefix even if the key starts with the namespace (but is not separated by a colon)'
+    end
+
+    def test_to_enum
+      factory, keys = populated_factory
+      enum = factory.to_enum
+      # wrap in set since we don't care about the ordering, and the redis scan command can theoretically return a key
+      # more than once
+      assert_equal ::Set.new(keys), ::Set.new(enum.to_a), 'Should retrieve all keys'
+    end
+
+    def test_to_enum_match
+      factory, keys = populated_factory
+
+      expected_key = keys[0]
+      pattern = expected_key + '*'
+
+      enum = factory.to_enum(match: pattern)
+      retrieved = enum.to_a
+      assert_equal 1, retrieved.size, 'should have retrieved only one key'
+      assert_equal expected_key, retrieved[0], 'should have retrieved the correct key'
+    end
+
+    def test_delete
+      factory, = populated_factory
+      keys_matcher = factory.prefix('*')
+
+      refute_empty factory.connection.keys(keys_matcher), 'should have at least one key in the factory, otherwise test is pointless'
+      factory.delete
+      assert_empty factory.connection.keys(keys_matcher), 'should have no more keys in the factory'
+    end
+
+    def test_script
+      factory = create_factory
+      script = factory.script('return 0')
+      assert_kind_of Redstruct::Script, script, 'should always return a script object'
+      assert_equal 0, script.eval, 'should execute script correctly'
+      assert_equal factory.connection, script.connection, 'script and factory should share the same connection'
+    end
+
+    def test_factory
+      factory = create_factory
+      sub_factory = factory.factory('sub')
+
+      assert sub_factory.namespace.start_with?(factory.namespace), 'should be prefixed with parent factory namespace'
+      assert_equal factory.connection, sub_factory.connection, 'should share the same connection'
+    end
+
+    def test_lock
+      factory1 = create_factory
+      lock1 = factory1.lock('res')
+      assert_kind_of Redstruct::Lock, lock1, 'should always return a Redstruct::Lock'
+
+      factory2 = create_factory
+      lock2 = factory2.lock('res')
+
+      assert lock1.acquire, 'should be able to acquire free lock'
+      assert lock2.acquire, 'should be able to acquire lock for the a resource with the same name but living in a different factory (i.e. not the same resource!)'
+      refute factory1.lock('res').acquire, 'should not be able to acquire lock on pre-acquired resource'
+    end
+
+    def test_hashmap
+      factory = create_factory
+      assert_struct_method(:hashmap, Redstruct::Hash, factory)
+    end
+
+    def test_structs
+      factory = create_factory
+      %w[Counter List Set SortedSet String Struct].each do |struct|
+        method = struct.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+        type = Redstruct.const_get(struct)
+        assert_struct_method(method, type, factory)
+      end
+    end
+
+    def assert_struct_method(method, type, factory)
+      assert Redstruct::Factory.method_defined?(method), "factory should have a method for #{type} named #{method}"
+
+      object = factory.public_send(method, 'key')
+      assert_equal factory.prefix('key'), object.key, 'object key should be namespaced under the factory namespace'
+      assert_equal factory, object.factory
+      assert_kind_of type, object, "factory method #{method} should always return an object of type #{type}"
+    end
+    private :assert_struct_method
+
+    def populated_factory
+      factory = create_factory
+
+      # populate between 2 and 10 objects, random keys, random values
+      objects = Array.new(SecureRandom.random_number(9) + 2) do
+        object = factory.string(SecureRandom.hex(4))
+        object.set(SecureRandom.hex(4))
+        object
+      end
+
+      return factory, objects.map(&:key)
+    end
+    private :populated_factory
+  end
+end