familia 0.10.2 → 1.0.0.pre.rc1

data/lib/familia/redistype.rb

@@ -0,0 +1,185 @@
+# rubocop:disable all
+
+require_relative 'redistype/commands'
+require_relative 'redistype/serialization'
+
+module Familia
+
+  # RedisType - Base class for Redis data type wrappers
+  #
+  # This class provides common functionality for various Redis data types
+  # such as String, List, Set, SortedSet, and HashKey.
+  #
+  # @abstract Subclass and implement Redis data type specific methods
+  class RedisType
+    include Familia::Base
+
+    @registered_types = {}
+    @valid_options = %i[class parent ttl default db key redis]
+    @db = nil
+    @ttl = nil
+
+    class << self
+      attr_reader :registered_types, :valid_options
+      attr_accessor :parent
+      attr_writer :ttl, :db, :uri
+
+      # To be called inside every class that inherits RedisType
+      # +methname+ is the term used for the class and instance methods
+      # that are created for the given +klass+ (e.g. set, list, etc)
+      def register(klass, methname)
+        Familia.ld "[#{self}] Registering #{klass} as #{methname}"
+
+        @registered_types[methname] = klass
+      end
+
+      def ttl(val = nil)
+        @ttl = val unless val.nil?
+        @ttl || parent&.ttl
+      end
+
+      def db(val = nil)
+        @db = val unless val.nil?
+        @db || parent&.db
+      end
+
+      def uri(val = nil)
+        @uri = val unless val.nil?
+        @uri || (parent ? parent.uri : Familia.uri)
+      end
+
+      def inherited(obj)
+        obj.db = db
+        obj.ttl = ttl
+        obj.uri = uri
+        obj.parent = self
+        super(obj)
+      end
+
+      def valid_keys_only(opts)
+        opts.select { |k, _| RedisType.valid_options.include? k }
+      end
+    end
+
+    attr_reader :name, :parent, :opts
+    attr_writer :dump_method, :load_method
+
+    # +name+: If parent is set, this will be used as the suffix
+    # for rediskey. Otherwise this becomes the value of the key.
+    # If this is an Array, the elements will be joined.
+    #
+    # Options:
+    #
+    # :class => A class that responds to Familia.load_method and
+    # Familia.dump_method. These will be used when loading and
+    # saving data from/to redis to unmarshal/marshal the class.
+    #
+    # :parent => The Familia object that this redistype object belongs
+    # to. This can be a class that includes Familia or an instance.
+    #
+    # :ttl => the time to live in seconds. When not nil, this will
+    # set the redis expire for this key whenever #save is called.
+    # You can also call it explicitly via #update_expiration.
+    #
+    # :default => the default value (String-only)
+    #
+    # :db => the redis database to use (ignored if :redis is used).
+    #
+    # :redis => an instance of Redis.
+    #
+    # :key => a hardcoded key to use instead of the deriving the from
+    # the name and parent (e.g. a derived key: customer:custid:secret_counter).
+    #
+    # Uses the redis connection of the parent or the value of
+    # opts[:redis] or Familia.redis (in that order).
+    def initialize(name, opts = {})
+      #Familia.ld " [initializing] #{self.class} #{opts}"
+      @name = name
+      @name = @name.join(Familia.delim) if @name.is_a?(Array)
+
+      # Remove all keys from the opts that are not in the allowed list
+      @opts = opts || {}
+      @opts = RedisType.valid_keys_only(@opts)
+
+      init if respond_to? :init
+    end
+
+    def redis
+      return @redis if @redis
+
+      parent? ? parent.redis : Familia.redis(opts[:db])
+    end
+
+    # Produces the full redis key for this object.
+    def rediskey
+      Familia.ld "[rediskey] #{name} for #{self.class} (#{opts})"
+
+      # Return the hardcoded key if it's set. This is useful for
+      # support legacy keys that aren't derived in the same way.
+      return opts[:key] if opts[:key]
+
+      if parent_instance?
+        # This is an instance-level redistype object so the parent instance's
+        # rediskey method is defined in Familia::Horreum::InstanceMethods.
+        parent.rediskey(name)
+      elsif parent_class?
+        # This is a class-level redistype object so the parent class' rediskey
+        # method is defined in Familia::Horreum::ClassMethods.
+        parent.rediskey(name, nil)
+      else
+        # This is a standalone RedisType object where it's name
+        # is the full key.
+        name
+      end
+    end
+
+    def class?
+      !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
+    end
+
+    def parent_instance?
+      parent.is_a?(Familia::Horreum)
+    end
+
+    def parent_class?
+      parent.is_a?(Class) && parent <= Familia::Horreum
+    end
+
+    def parent?
+      parent_class? || parent_instance?
+    end
+
+    def parent
+      @opts[:parent]
+    end
+
+    def ttl
+      @opts[:ttl] || self.class.ttl
+    end
+
+    def db
+      @opts[:db] || self.class.db
+    end
+
+    def uri
+      @opts[:uri] || self.class.uri
+    end
+
+    def dump_method
+      @dump_method || self.class.dump_method
+    end
+
+    def load_method
+      @load_method || self.class.load_method
+    end
+
+    include Commands
+    include Serialization
+  end
+
+  require_relative 'types/list'
+  require_relative 'types/unsorted_set'
+  require_relative 'types/sorted_set'
+  require_relative 'types/hashkey'
+  require_relative 'types/string'
+end

data/lib/familia/settings.rb

@@ -0,0 +1,38 @@
+# rubocop:disable all
+
+module Familia
+
+  @delim = ':'
+  @prefix = nil
+  @suffix = :object
+  @ttl = nil
+  @db = nil
+
+  module Settings
+
+    attr_writer :delim, :suffix, :ttl, :db, :prefix
+
+    def delim(val = nil)
+      @delim = val if val
+      @delim
+    end
+
+    def prefix(val = nil)
+      @prefix = val if val
+      @prefix
+    end
+
+    def suffix(val = nil)
+      @suffix = val if val
+      @suffix
+    end
+
+    # We define this do-nothing method because it reads better
+    # than simply Familia.suffix in some contexts.
+    def default_suffix
+      suffix
+    end
+
+  end
+
+end

data/lib/familia/types/hashkey.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Familia
+  class HashKey < RedisType
+    def size
+      redis.hlen rediskey
+    end
+    alias length size
+
+    def empty?
+      size.zero?
+    end
+
+    # +return+ [Integer] Returns 1 if the field is new and added, 0 if the
+    #  field already existed and the value was updated.
+    def []=(field, val)
+      ret = redis.hset rediskey, field, to_redis(val)
+      update_expiration
+      ret
+    rescue TypeError => e
+      Familia.le "[hset]= #{e.message}"
+      Familia.ld "[hset]= #{rediskey} #{field}=#{val}" if Familia.debug
+      echo :hset, caller(1..1).first if Familia.debug # logs via echo to redis and back
+      klass = val.class
+      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{rediskey}"
+      raise e.class, msg
+    end
+    alias put []=
+    alias store []=
+
+    def [](field)
+      from_redis redis.hget(rediskey, field)
+    end
+    alias get []
+
+    def fetch(field, default = nil)
+      ret = self[field]
+      if ret.nil?
+        raise IndexError, "No such index for: #{field}" if default.nil?
+
+        default
+      else
+        ret
+      end
+    end
+
+    def keys
+      redis.hkeys rediskey
+    end
+
+    def values
+      el = redis.hvals(rediskey)
+      multi_from_redis(*el)
+    end
+
+    def all
+      # TODO: Use from_redis. Also name `all` is confusing with
+      # Onetime::Customer.all which returns all customers.
+      redis.hgetall rediskey
+    end
+    alias to_hash all
+    alias clone all
+
+    def has_key?(field)
+      redis.hexists rediskey, field
+    end
+    alias include? has_key?
+    alias member? has_key?
+
+    def delete(field)
+      redis.hdel rediskey, field
+    end
+    alias remove delete
+    alias rem delete
+    alias del delete
+
+    def increment(field, by = 1)
+      redis.hincrby(rediskey, field, by).to_i
+    end
+    alias incr increment
+    alias incrby increment
+
+    def decrement(field, by = 1)
+      increment field, -by
+    end
+    alias decr decrement
+    alias decrby decrement
+
+    def update(hsh = {})
+      raise ArgumentError, 'Argument to bulk_set must be a hash' unless hsh.is_a?(Hash)
+
+      data = hsh.inject([]) { |ret, pair| ret << [pair[0], to_redis(pair[1])] }.flatten
+
+      ret = redis.hmset(rediskey, *data)
+      update_expiration
+      ret
+    end
+    alias merge! update
+
+    def values_at *fields
+      el = redis.hmget(rediskey, *fields.flatten.compact)
+      multi_from_redis(*el)
+    end
+
+    Familia::RedisType.register self, :hash # legacy, deprecated
+    Familia::RedisType.register self, :hashkey
+  end
+end

data/lib/familia/types/list.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Familia
+  class List < RedisType
+    def size
+      redis.llen rediskey
+    end
+    alias length size
+
+    def empty?
+      size.zero?
+    end
+
+    def push *values
+      echo :push, caller(1..1).first if Familia.debug
+      values.flatten.compact.each { |v| redis.rpush rediskey, to_redis(v) }
+      redis.ltrim rediskey, -@opts[:maxlength], -1 if @opts[:maxlength]
+      update_expiration
+      self
+    end
+
+    def <<(val)
+      push val
+    end
+    alias add <<
+
+    def unshift *values
+      values.flatten.compact.each { |v| redis.lpush rediskey, to_redis(v) }
+      # TODO: test maxlength
+      redis.ltrim rediskey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
+      update_expiration
+      self
+    end
+
+    def pop
+      from_redis redis.rpop(rediskey)
+    end
+
+    def shift
+      from_redis redis.lpop(rediskey)
+    end
+
+    def [](idx, count = nil)
+      if idx.is_a? Range
+        range idx.first, idx.last
+      elsif count
+        case count <=> 0
+        when 1  then range(idx, idx + count - 1)
+        when 0  then []
+        when -1 then nil
+        end
+      else
+        at idx
+      end
+    end
+    alias slice []
+
+    def delete(v, count = 0)
+      redis.lrem rediskey, count, to_redis(v)
+    end
+    alias remove delete
+    alias rem delete
+    alias del delete
+
+    def range(sidx = 0, eidx = -1)
+      el = rangeraw sidx, eidx
+      multi_from_redis(*el)
+    end
+
+    def rangeraw(sidx = 0, eidx = -1)
+      redis.lrange(rediskey, sidx, eidx)
+    end
+
+    def members(count = -1)
+      echo :members, caller(1..1).first if Familia.debug
+      count -= 1 if count.positive?
+      range 0, count
+    end
+    alias all members
+    alias to_a members
+
+    def membersraw(count = -1)
+      count -= 1 if count.positive?
+      rangeraw 0, count
+    end
+
+    def each(&blk)
+      range.each(&blk)
+    end
+
+    def each_with_index(&blk)
+      range.each_with_index(&blk)
+    end
+
+    def eachraw(&blk)
+      rangeraw.each(&blk)
+    end
+
+    def eachraw_with_index(&blk)
+      rangeraw.each_with_index(&blk)
+    end
+
+    def collect(&blk)
+      range.collect(&blk)
+    end
+
+    def select(&blk)
+      range.select(&blk)
+    end
+
+    def collectraw(&blk)
+      rangeraw.collect(&blk)
+    end
+
+    def selectraw(&blk)
+      rangeraw.select(&blk)
+    end
+
+    def at(idx)
+      from_redis redis.lindex(rediskey, idx)
+    end
+
+    def first
+      at 0
+    end
+
+    def last
+      at(-1)
+    end
+
+    # TODO: def replace
+    ## Make the value stored at KEY identical to the given list
+    # define_method :"#{name}_sync" do |*latest|
+    #  latest = latest.flatten.compact
+    #  # Do nothing if we're given an empty Array.
+    #  # Otherwise this would clear all current values
+    #  if latest.empty?
+    #    false
+    #  else
+    #    # Convert to a list of index values if we got the actual objects
+    #    latest = latest.collect { |obj| obj.index } if klass === latest.first
+    #    current = send("#{name_plural}raw")
+    #    added = latest-current
+    #    removed = current-latest
+    #    #Familia.info "#{self.index}: adding: #{added}"
+    #    added.each { |v| self.send("add_#{name_singular}", v) }
+    #    #Familia.info "#{self.index}: removing: #{removed}"
+    #    removed.each { |v| self.send("remove_#{name_singular}", v) }
+    #    true
+    #  end
+    # end
+
+    Familia::RedisType.register self, :list
+  end
+end

data/lib/familia/types/sorted_set.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Familia
+  class SortedSet < RedisType
+    def size
+      redis.zcard rediskey
+    end
+    alias length size
+
+    def empty?
+      size.zero?
+    end
+
+    # Adds a new element to the sorted set with the current timestamp as the
+    # score.
+    #
+    # This method provides a convenient way to add elements to the sorted set
+    # without explicitly specifying a score. It uses the current Unix timestamp
+    # as the score, which effectively sorts elements by their insertion time.
+    #
+    # @param val [Object] The value to be added to the sorted set.
+    # @return [Integer] Returns 1 if the element is new and added, 0 if the
+    #   element already existed and the score was updated.
+    #
+    # @example
+    #   sorted_set << "new_element"
+    #
+    # @note This is a non-standard operation for sorted sets as it doesn't allow
+    #   specifying a custom score. Use `add` or `[]=` for more control.
+    #
+    def <<(val)
+      add(Time.now.to_i, val)
+    end
+
+    # NOTE: The argument order is the reverse of #add. We do this to
+    # more naturally align with how the [] and []= methods are used.
+    #
+    # e.g.
+    #     obj.metrics[VALUE] = SCORE
+    #     obj.metrics[VALUE]  # => SCORE
+    #
+    def []=(val, score)
+      add score, val
+    end
+
+    def add(score, val)
+      ret = redis.zadd rediskey, score, to_redis(val)
+      update_expiration
+      ret
+    end
+
+    def score(val)
+      ret = redis.zscore rediskey, to_redis(val, false)
+      ret&.to_f
+    end
+    alias [] score
+
+    def member?(val)
+      Familia.trace :MEMBER, redis, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+      !rank(val).nil?
+    end
+    alias include? member?
+
+    # rank of member +v+ when ordered lowest to highest (starts at 0)
+    def rank(v)
+      ret = redis.zrank rediskey, to_redis(v, false)
+      ret&.to_i
+    end
+
+    # rank of member +v+ when ordered highest to lowest (starts at 0)
+    def revrank(v)
+      ret = redis.zrevrank rediskey, to_redis(v, false)
+      ret&.to_i
+    end
+
+    def members(count = -1, opts = {})
+      count -= 1 if count.positive?
+      el = membersraw count, opts
+      multi_from_redis(*el)
+    end
+    alias to_a members
+    alias all members
+
+    def membersraw(count = -1, opts = {})
+      count -= 1 if count.positive?
+      rangeraw 0, count, opts
+    end
+
+    def revmembers(count = -1, opts = {})
+      count -= 1 if count.positive?
+      el = revmembersraw count, opts
+      multi_from_redis(*el)
+    end
+
+    def revmembersraw(count = -1, opts = {})
+      count -= 1 if count.positive?
+      revrangeraw 0, count, opts
+    end
+
+    def each(&blk)
+      members.each(&blk)
+    end
+
+    def each_with_index(&blk)
+      members.each_with_index(&blk)
+    end
+
+    def collect(&blk)
+      members.collect(&blk)
+    end
+
+    def select(&blk)
+      members.select(&blk)
+    end
+
+    def eachraw(&blk)
+      membersraw.each(&blk)
+    end
+
+    def eachraw_with_index(&blk)
+      membersraw.each_with_index(&blk)
+    end
+
+    def collectraw(&blk)
+      membersraw.collect(&blk)
+    end
+
+    def selectraw(&blk)
+      membersraw.select(&blk)
+    end
+
+    def range(sidx, eidx, opts = {})
+      echo :range, caller(1..1).first if Familia.debug
+      el = rangeraw(sidx, eidx, opts)
+      multi_from_redis(*el)
+    end
+
+    def rangeraw(sidx, eidx, opts = {})
+      # NOTE: :withscores (no underscore) is the correct naming for the
+      # redis-4.x gem. We pass :withscores through explicitly b/c
+      # redis.zrange et al only accept that one optional argument.
+      # Passing `opts`` through leads to an ArgumentError:
+      #
+      #   sorted_sets.rb:374:in `zrevrange': wrong number of arguments (given 4, expected 3) (ArgumentError)
+      #
+      redis.zrange(rediskey, sidx, eidx, **opts)
+    end
+
+    def revrange(sidx, eidx, opts = {})
+      echo :revrange, caller(1..1).first if Familia.debug
+      el = revrangeraw(sidx, eidx, opts)
+      multi_from_redis(*el)
+    end
+
+    def revrangeraw(sidx, eidx, opts = {})
+      redis.zrevrange(rediskey, sidx, eidx, **opts)
+    end
+
+    # e.g. obj.metrics.rangebyscore (now-12.hours), now, :limit => [0, 10]
+    def rangebyscore(sscore, escore, opts = {})
+      echo :rangebyscore, caller(1..1).first if Familia.debug
+      el = rangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*el)
+    end
+
+    def rangebyscoreraw(sscore, escore, opts = {})
+      echo :rangebyscoreraw, caller(1..1).first if Familia.debug
+      redis.zrangebyscore(rediskey, sscore, escore, **opts)
+    end
+
+    # e.g. obj.metrics.revrangebyscore (now-12.hours), now, :limit => [0, 10]
+    def revrangebyscore(sscore, escore, opts = {})
+      echo :revrangebyscore, caller(1..1).first if Familia.debug
+      el = revrangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*el)
+    end
+
+    def revrangebyscoreraw(sscore, escore, opts = {})
+      echo :revrangebyscoreraw, caller(1..1).first if Familia.debug
+      opts[:with_scores] = true if opts[:withscores]
+      redis.zrevrangebyscore(rediskey, sscore, escore, opts)
+    end
+
+    def remrangebyrank(srank, erank)
+      redis.zremrangebyrank rediskey, srank, erank
+    end
+
+    def remrangebyscore(sscore, escore)
+      redis.zremrangebyscore rediskey, sscore, escore
+    end
+
+    def increment(val, by = 1)
+      redis.zincrby(rediskey, by, val).to_i
+    end
+    alias incr increment
+    alias incrby increment
+
+    def decrement(val, by = 1)
+      increment val, -by
+    end
+    alias decr decrement
+    alias decrby decrement
+
+    def delete(val)
+      Familia.trace :DELETE, redis, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+      # We use `strict_values: false` here to allow for the deletion of values
+      # that are in the sorted set. If it's a horreum object, the value is
+      # the identifier and not a serialized version of the object. So either
+      # the value exists in the sorted set or it doesn't -- we don't need to
+      # raise an error if it's not found.
+      redis.zrem rediskey, to_redis(val, false)
+    end
+    alias remove delete
+    alias rem delete
+    alias del delete
+
+    def at(idx)
+      range(idx, idx).first
+    end
+
+    # Return the first element in the list. Redis: ZRANGE(0)
+    def first
+      at(0)
+    end
+
+    # Return the last element in the list. Redis: ZRANGE(-1)
+    def last
+      at(-1)
+    end
+
+    Familia::RedisType.register self, :sorted_set
+    Familia::RedisType.register self, :zset
+  end
+end