redstruct 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f2a542b5597811e35ed17b643ae0df3fb01fb226
+  data.tar.gz: bc58fb20c1cc5d2b4a502c3ba085f2d2d1304056
+SHA512:
+  metadata.gz: 8a98538b8e61c874e1b42d487d46a83176cb563ede67eefa78131e577f6a16627678658fd314e11a7981c0c6f7ab0e9022ca82c61e6723e4620c0a3bb099fa1b
+  data.tar.gz: 7a230c6f9cc89433e0580efa59ddfd716bdaf569ae2f2f20c53dc2b1909d1d8f332f2b789870a834f90a9fbcc5953cc275639478ff842b40368fa41608da7add

data/README.md

@@ -0,0 +1,42 @@
+# Redstruct
+
+Provides higher level data structures in Ruby using standard Redis commands. Also provides basic object mapping for pre-existing types.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'redstruct'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install redstruct
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+*Note*
+
+Avoid using transactions; the Redis documentation suggests using Lua scripts where possible, as in most cases they will be faster than transactions. Use the `Redstruct::Utils::Scriptable` module and the `defscript` macro instead.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/npepinpe/redstruct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Bundler.require(:default, :development)
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test
+
+require 'redstruct/yard/defscript_handler'
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/**/*.rb']
+ t.options = ['--output-dir=./docs']
+end

data/lib/redstruct/configuration.rb

@@ -0,0 +1,14 @@
+module Redstruct
+  class Configuration
+    # @return [ConnectionPool] The Redis-rb connection pool to use
+    attr_accessor :connection_pool
+
+    # @return [::String] Default namespace for factories
+    attr_accessor :namespace
+
+    def initialize
+      @connection_pool = nil
+      @namespace = nil
+    end
+  end
+end

data/lib/redstruct/connection.rb

@@ -0,0 +1,29 @@
+module Redstruct
+  class Connection
+    # @return [Array<Symbol>] List of methods from the Redis class that we don't want to delegate to.
+    NON_COMMAND_METHODS = [:[], :[]=, :_eval, :_scan, :method_missing, :call, :dup, :inspect, :to_s].freeze
+
+    attr_reader :pool
+
+    def initialize(pool)
+      raise(Redstruct::Error, 'Requires a ConnectionPool to proxy to') unless pool.is_a?(ConnectionPool)
+      @pool = pool
+    end
+
+    # While slower on load, defining all methods that we want to pipe to one of the connections results in
+    # faster calls at runtime, and gives us the convenience of not going through the pool.with everytime.
+    Redis.public_instance_methods(false).each do |method|
+      next if NON_COMMAND_METHODS.include?(method)
+      class_eval <<~METHOD, __FILE__, __LINE__ + 1
+        def #{method}(*args)
+          connection = Thread.current[:__redstruct_connection]
+          if connection.nil?
+            return @pool.with { |c| c.#{method}(*args) }
+          else
+            return connection.#{method}(*args)
+          end
+        end
+      METHOD
+    end
+  end
+end

data/lib/redstruct/error.rb

@@ -0,0 +1,5 @@
+module Redstruct
+  # Used to provide a single base error type to filter all errors coming from the gem.
+  class Error < StandardError
+  end
+end

data/lib/redstruct/factory/creation.rb

@@ -0,0 +1,95 @@
+module Redstruct
+  class Factory
+    # Module to hold all the factory creation methods.
+    module Creation
+      # Builds a struct with the given key (namespaced) and sharing the factory connection
+      # Building a struct is only really useful if you plan on making only basic operations,
+      # such as delete, expire, etc. It is however recommended to always build your objects
+      # in the same way, e.g. if it's a lock, use Factory#lock
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Struct] base struct pointing to that key
+      def struct(key, **options)
+        return create(Redstruct::Types::Struct, key, **options)
+      end
+
+      # Builds a Redis string struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::String]
+      def string(key, **options)
+        return create(Redstruct::Types::String, key, **options)
+      end
+
+      # Builds a Redis list struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::List]
+      def list(key, **options)
+        return create(Redstruct::Types::List, key, **options)
+      end
+
+      # Builds a Redis set struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Set]
+      def set(key, **options)
+        return create(Redstruct::Types::Set, key, **options)
+      end
+
+      # Builds a Redis sorted set (zset) struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::SortedSet]
+      def sorted_set(key, **options)
+        return create(Redstruct::Types::SortedSet, key, **options)
+      end
+
+      # Builds a Redis hash struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Hash]
+      def hash(key, **options)
+        return create(Redstruct::Types::Hash, key, **options)
+      end
+
+      # Builds a Redis backed lock from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Lock]
+      def lock(key, **options)
+        return create(Redstruct::Types::Lock, key, **options)
+      end
+
+      # Builds a Redis counter struct from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Counter]
+      def counter(key, **options)
+        return create(Redstruct::Types::Counter, key, **options)
+      end
+
+      # Builds a Redis backed queue from the key
+      # @param [::String] key base key to use
+      # @return [Redstruct::Types::Queue]
+      def queue(key)
+        return create(Redstruct::Types::Queue, key)
+      end
+
+      # @todo The script cache is actually based on the database you will connect to. Therefore, it might be smarter to move it to the connection used?
+      # Caveat: if the script with the given ID exists in the cache, we don't bother updating it.
+      # So if the script actually changed since the first call, the one sent during the first call will
+      def script(id, script)
+        return @script_cache.synchronize do
+          @script_cache[id] = Redstruct::Types::Script.new(key: id, script: script, factory: self) if @script_cache[id].nil?
+          @script_cache[id]
+        end
+      end
+
+      # Returns a factory with an isolated namespace.
+      # @example Given a factory `f` with namespace fact:first
+      #   f.factory('second') # => Redstruct::Factory: namespace: <"fact:first:second">, script_cache: <[]>
+      # @return [Factory] namespaced factory
+      def factory(namespace)
+        return self.class.new(connection: @connection, namespace: isolate(namespace))
+      end
+
+      def create(type, key, **options)
+        return type.new(key: isolate(key), factory: self, **options)
+      end
+      private :create
+    end
+  end
+end

data/lib/redstruct/factory/deserialization.rb

@@ -0,0 +1,7 @@
+module Redstruct
+  class Factory
+    # Module to hold all the factory creation methods.
+    module Deserialization
+    end
+  end
+end

data/lib/redstruct/factory.rb

@@ -0,0 +1,45 @@
+module Redstruct
+  # Main interface of the gem; this class should be used to build all Redstruct
+  # objects, even when deserializing them.
+  class Factory
+    include Redstruct::Utils::Inspectable, Redstruct::Factory::Creation
+    extend Redstruct::Factory::Deserialization
+
+    # @return [Connection] The connection proxy to use when executing commands. Shared by all factory produced objects.
+    attr_reader :connection
+
+    # @param [Redstruct::Connection] connection connection to use for all objects built by the factory
+    # @param [ConnectionPool] pool pool to use to build a connection from if no connection param given
+    # @param [::String] namespace all objects build from the factory will have their keys namespaced under this one
+    # @return [Factory]
+    def initialize(connection: nil, pool: nil, namespace: nil)
+      namespace ||= Redstruct.config.namespace
+
+      if connection.nil?
+        pool ||= Redstruct.config.connection_pool
+        raise(Redstruct::Error, 'A connection pool is required to create a factory, but none was given') if pool.nil?
+        connection = Redstruct::Connection.new(pool)
+      end
+
+      @connection = connection
+      @namespace = namespace
+      @script_cache = {}.tap { |hash| hash.extend(MonitorMixin) }
+    end
+
+    # Returns a namespaced version of the key (unless already namespaced)
+    # @param [String] key the key to isolate/namespace
+    # @return [String] namespaced version of the key (or the key itself if already namespaced)
+    def isolate(key)
+      return @namespace.nil? || key.start_with?(@namespace) ? key : "#{@namespace}:#{key}"
+    end
+
+    # :nocov:
+
+    # Helper method for serialization
+    def inspectable_attributes
+      return { namespace: @namespace, script_cache: @script_cache.keys }
+    end
+
+    # :nocov:
+  end
+end

data/lib/redstruct/hls/lock.rb

@@ -0,0 +1,175 @@
+require 'securerandom'
+
+module Redstruct
+  module Hls
+    # Implementation of a simple binary lock (locked/not locked), with option to block and wait for the lock.
+    # Uses two redis structures: a string for the lease, and a list for blocking operations.
+    # @see #acquire
+    # @see #release
+    # @see #locked
+    # @attr_reader [::String, nil] token the current token or nil
+    # @attr_reader [Fixnum] expiry expiry of the underlying redis structures in milliseconds
+    # @attr_reader [Fixnum, nil] timeout the timeout to wait when attempting to acquire the lock, in seconds
+    class Lock < Redstruct::Types::Base
+      include Redstruct::Utils::Scriptable, Redstruct::Utils::Coercion
+
+      # The default expiry on the underlying redis keys, in milliseconds
+      DEFAULT_EXPIRY = 1000
+
+      # The default timeout when blocking, in seconds; a nil value means it is non-blocking
+      DEFAULT_TIMEOUT = nil
+
+      attr_reader :token, :expiry, :timeout
+
+      # @param [Integer] expiry in milliseconds; to prevent infinite locking, each mutex is released after a certain expiry time
+      # @param [Integer] timeout in seconds; if > 0, will block for this amount of time when trying to obtain the lock
+      def initialize(expiry: DEFAULT_EXPIRY, timeout: DEFAULT_TIMEOUT, **options)
+        super(**options)
+
+        @token = nil
+        @expiry = expiry
+        @timeout = timeout.to_i
+
+        create do |factory|
+          @lease = factory.string('lease')
+          @tokens = factory.list('tokens')
+        end
+      end
+
+      # Executes the given block if the lock can be acquired
+      # @yield Block to be executed if the lock is acquired
+      def locked
+        yield if acquire
+      ensure
+        release
+      end
+
+      # Whether or not the lock will block when attempting to acquire it
+      # @return [Boolean]
+      def blocking?
+        return @timeout.positive?
+      end
+
+      # Attempts to acquire the lock. First attempts to grab the lease (a redis string).
+      # If the current token is already the lease token, the lock is considered acquired.
+      # If there is no current lease, then sets it to the current token.
+      # If there is a current lease that is not the current token, then:
+      #   1) If this not a blocking lock (see Lock#blocking?), return false
+      #   2) If this is a blocking lock, block and wait for the next token to be pushed on the tokens list
+      #   3) If a token was pushed, set it as our token and refresh the expiry
+      # @return [Boolean] True if acquired, false otherwise
+      def acquire
+        acquired = false
+        token = non_blocking_acquire(@token)
+        token = blocking_acquire if token.nil? && blocking?
+
+        unless token.nil?
+          @token = token
+          acquired = true
+        end
+
+        return acquired
+      end
+
+      # Releases the lock only if the current token is the value of the lease.
+      # If the lock is a blocking lock (see Lock#blocking?), push the next token on the tokens list.
+      # @return [Boolean] True if released, false otherwise
+      def release
+        return false if @token.nil?
+
+        next_token = SecureRandom.uuid
+        return coerce_bool(release_script(keys: [@lease.key, @tokens.key], argv: [@token, next_token, @expiry]))
+      end
+
+      def non_blocking_acquire(token = nil)
+        token ||= generate_token
+        return acquire_script(keys: @lease.key, argv: [token, @expiry])
+      end
+      private :non_blocking_acquire
+
+      def blocking_acquire
+        timeout = @timeout == Float::INFINITY ? 0 : @timeout
+        token = @tokens.pop(timeout: timeout)
+
+        # Attempt to reacquire in a non blocking way to:
+        # 1) assert we do own the lock (edge case)
+        # 2) touch the lock expiry
+        token = non_blocking_acquire(token) unless token.nil?
+
+        return token
+      end
+      private :blocking_acquire
+
+      # The acquire script attempts to set the lease (keys[1]) to the given token (argv[1]), only
+      # if it wasn't already set. It then compares to check if the value of the lease is that of the token,
+      # and if so refreshes the expiry (argv[2]) time of the lease.
+      # @param [Array<(::String)>] keys The lease key specifying who owns the mutex at the moment
+      # @param [Array<(::String, Fixnum)>] argv The current token; the expiry time in milliseconds
+      # @return [::String] Returns the token if acquired, nil otherwise.
+      defscript :acquire_script, <<~LUA
+        local token = ARGV[1]
+        local expiry = tonumber(ARGV[2])
+
+        redis.call('set', KEYS[1], token, 'NX')
+        if redis.call('get', KEYS[1]) == token then
+          redis.call('pexpire', KEYS[1], expiry)
+          return token
+        end
+
+        return false
+      LUA
+
+      # The release script compares the given token (argv[1]) with the lease value (keys[1]); if they are the same,
+      # then a new token (argv[2]) is set as the lease, and pushed on the tokens (keys[2]) list
+      # for the next acquire request.
+      # @param [Array<(::String, ::String)>] keys The lease key; the tokens list key
+      # @param [Array<(::String, ::String, Fixnum)>] argv The current token; the next token to push; the expiry time of both keys
+      # @return [Fixnum] 1 if released, 0 otherwise
+      defscript :release_script, <<~LUA
+        local currentToken = ARGV[1]
+        local nextToken = ARGV[2]
+        local expiry = tonumber(ARGV[3])
+
+        if redis.call('get', KEYS[1]) == currentToken then
+          redis.call('set', KEYS[1], nextToken, 'PX', expiry)
+          redis.call('lpush', KEYS[2], nextToken)
+          redis.call('pexpire', KEYS[2], expiry)
+          return true
+        end
+
+        return false
+      LUA
+
+      # @!group Serialization
+      # Returns a hash representation of the object
+      # @see Lock#from_h
+      # @return [Hash<Symbol, Object>] hash representation of the lock
+      def to_h
+        return super.merge(token: @token, expiry: @expiry, timeout: @timeout)
+      end
+
+      class << self
+        # Builds a lock from a hash.
+        # @see Lock#to_h
+        # @see Factory#create_from_h
+        # @param [Hash] hash hash generated by calling Lock#to_h. Ensure beforehand that keys are symbols.
+        # @return [Lock]
+        def from_h(hash, factory)
+          hash[:factory] = factory
+          return new(**hash)
+        end
+      end
+      # @!endgroup
+
+      def generate_token
+        return SecureRandom.uuid
+      end
+      private :generate_token
+
+      # Helper method for easy inspection
+      def inspectable_attributes
+        super.merge(expiry: @expiry, blocking: blocking?)
+      end
+    end
+  end
+end

data/lib/redstruct/hls/queue.rb

@@ -0,0 +1,29 @@
+module Redstruct
+  module Hls
+    class Queue < Redstruct::Types::List
+      include Redstruct::Utils::Scriptable
+
+      def enqueue(*elements)
+        self.connection.rpush(@key, elements)
+      end
+
+      def dequeue(length: 1)
+        elements = dequeue_script(keys: @key, argv: length)
+        length == 1 ? elements.first : elements
+      end
+
+      # Dequeues up to argv[1] amount of items from the list at keys[1]
+      # @param [Array<(::String)>] keys The key of the list to dequeue from
+      # @param [Array<(Fixnum)>] argv The number of items to dequeue
+      # @return [Array] An array of items dequeued or an empty array
+      defscript :dequeue_script, <<~LUA
+        local length = tonumber(ARGV[1])
+        local elements = redis.call('lrange', KEYS[1], 0, length - 1)
+        redis.call('ltrim', KEYS[1], length, -1)
+
+        return elements
+      LUA
+      protected :dequeue_script
+    end
+  end
+end

data/lib/redstruct/hls.rb

@@ -0,0 +1,2 @@
+require 'redstruct/hls/lock'
+require 'redstruct/hls/queue'

data/lib/redstruct/types/base.rb

@@ -0,0 +1,47 @@
+module Redstruct
+  module Types
+    # Base class for all objects a factory can produce
+    class Base
+      include Redstruct::Utils::Inspectable
+      extend Forwardable
+
+      def_delegators :@factory, :connection, :connection
+
+      # @return [String] The key used to identify the struct on redis
+      attr_reader :key
+
+      def initialize(key:, factory:)
+        @factory = factory
+        @key = key
+      end
+
+      def with
+        self.connection.pool.with do |c|
+          begin
+            Thread.current[:__redstruct_connection] = c
+            yield(c)
+          ensure
+            Thread.current[:__redstruct_connection] = nil
+          end
+        end
+      end
+
+      def to_h
+        return { key: @key }
+      end
+
+      def create
+        return unless block_given?
+        subfactory = @factory.factory(@key)
+        yield(subfactory)
+      end
+      protected :create
+
+      # :nocov:
+      def inspectable_attributes
+        { key: @key, factory: @factory }
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/redstruct/types/counter.rb

@@ -0,0 +1,65 @@
+module Redstruct
+  module Types
+    class Counter < Redstruct::Types::String
+      include Redstruct::Utils::Scriptable
+
+      def initialize(increment: 1, max: nil, **options)
+        super(**options)
+        @increment = increment
+        @max = max
+      end
+
+      def get
+        super.to_i
+      end
+
+      def set(value)
+        super(value.to_i)
+      end
+
+      def increment(by: nil, max: nil)
+        by ||= @increment
+        max ||= @max
+
+        value = if max.nil?
+          self.connection.incrby(@key, by.to_i).to_i
+        else
+          ring_increment_script(keys: @key, argv: [by.to_i, max.to_i]).to_i
+        end
+
+        return value
+      end
+
+      def decrement(by: nil, max: nil)
+        by ||= @increment
+        by = -by.to_i
+        return increment(by: by, max: max)
+      end
+
+      def getset(value)
+        return super(value.to_i).to_i
+      end
+
+      # @!group Lua Scripts
+
+      defscript :ring_increment_script, <<~LUA
+        local by = tonumber(ARGV[1])
+        local max = tonumber(ARGV[2])
+        local current = redis.call('get', KEYS[1])
+        local value = current and tonumber(current) or 0
+
+        value = (value + by) % max
+        redis.call('set', KEYS[1], value)
+
+        return value
+      LUA
+
+      # @!endgroup
+
+      # Helper method for easy inspection
+      def inspectable_attributes
+        super.merge(max: @max, increment: @increment)
+      end
+    end
+  end
+end

data/lib/redstruct/types/hash.rb

@@ -0,0 +1,72 @@
+module Redstruct
+  module Types
+    class Hash < Redstruct::Types::Struct
+      include Redstruct::Utils::Coercion
+
+      def [](key)
+        return self.connection.hget(@key, key)
+      end
+
+      def []=(key, value)
+        self.connection.hset(@key, key, value)
+      end
+
+      def set(key, value, overwrite: true)
+        if overwrite
+          self[key] = value
+        else
+          self.connection.hsetnx(@key, key, value)
+        end
+      end
+
+      def get(*keys)
+        return self[keys.first] if keys.size == 1
+        return self.connection.mapped_hmget(@key, *keys)
+      end
+
+      def update(hash)
+        self.connection.mapped_hmset(@key, hash)
+      end
+
+      def delete(*keys)
+        return self.connection.hdel(@key, keys)
+      end
+
+      def key?(key)
+        return coerce_bool(self.connection.hexists(@key, key))
+      end
+
+      def incr(key, increment: 1)
+        if increment.is_a?(Float)
+          self.connection.hincrbyfloat(@key, key, increment.to_f)
+        else
+          self.connection.hincrby(@key, key, increment)
+        end
+      end
+
+      def decr(key, increment: 1)
+        return incr(key, (-increment))
+      end
+
+      def to_h
+        return self.connection.hgetall(@key)
+      end
+
+      def keys
+        return self.connection.hkeys(@key)
+      end
+
+      def values
+        return self.connection.hvals(@key)
+      end
+
+      def size
+        return self.connection.hlen(@key)
+      end
+
+      def each(options = {}, &block)
+        return self.connection.hscan_each(@key, options, &block)
+      end
+    end
+  end
+end