familia 0.10.2 → 1.0.0.pre.rc1

data/lib/familia/horreum/class_methods.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'relations_management'
+
+module Familia
+  class Horreum
+    # Class-level instance variables
+    # These are set up as nil initially and populated later
+    @redis = nil
+    @identifier = nil
+    @fields = nil # []
+    @ttl = nil
+    @db = nil
+    @uri = nil
+    @suffix = nil
+    @prefix = nil
+    @class_redis_types = nil # {}
+    @redis_types = nil # {}
+    @defined_fields = nil # {}
+    @dump_method = nil
+    @load_method = nil
+
+    # ClassMethods: Provides class-level functionality for Horreum
+    #
+    # This module is extended into classes that include Familia::Horreum,
+    # providing methods for Redis operations and object management.
+    #
+    # Key features:
+    # * Includes RelationsManagement for Redis-type field handling
+    # * Defines methods for managing fields, identifiers, and Redis keys
+    # * Provides utility methods for working with Redis objects
+    #
+    module ClassMethods
+      include Familia::Settings
+      include Familia::Horreum::RelationsManagement
+
+      attr_accessor :parent
+      attr_writer :redis, :dump_method, :load_method
+
+      def redis
+        @redis || Familia.redis(uri || db)
+      end
+
+      # The object field or instance method to call to get the unique identifier
+      # for that instance. The value returned by this method will be used to
+      # generate the key for the object in Redis.
+      def identifier(val = nil)
+        @identifier = val if val
+        @identifier
+      end
+
+      # Define a field for the class. This will create getter and setter
+      # instance methods just like any "attr_accessor" methods.
+      def field(name)
+        fields << name
+        attr_accessor name
+      end
+
+      # Returns the list of field names defined for the class in the order
+      # that they were defined. i.e. `field :a; field :b; fields => [:a, :b]`.
+      def fields
+        @fields ||= []
+        @fields
+      end
+
+      def class_redis_types
+        @class_redis_types ||= {}
+        @class_redis_types
+      end
+
+      def class_redis_types?(name)
+        class_redis_types.key? name.to_s.to_sym
+      end
+
+      def redis_object?(name)
+        redis_types.key? name.to_s.to_sym
+      end
+
+      def redis_types
+        @redis_types ||= {}
+        @redis_types
+      end
+
+      def defined_fields
+        @defined_fields ||= {}
+        @defined_fields
+      end
+
+      def ttl(v = nil)
+        @ttl = v unless v.nil?
+        @ttl || parent&.ttl
+      end
+
+      def db(v = nil)
+        @db = v unless v.nil?
+        @db || parent&.db
+      end
+
+      def uri(v = nil)
+        @uri = v unless v.nil?
+        @uri || parent&.uri
+      end
+
+      def all(suffix = :object)
+        # objects that could not be parsed will be nil
+        keys(suffix).filter_map { |k| from_key(k) }
+      end
+
+      def any?(filter = '*')
+        size(filter) > 0
+      end
+
+      def size(filter = '*')
+        redis.keys(rediskey(filter)).compact.size
+      end
+
+      def suffix(a = nil, &blk)
+        @suffix = a || blk if a || !blk.nil?
+        @suffix || Familia.default_suffix
+      end
+
+      def prefix(a = nil)
+        @prefix = a if a
+        @prefix || name.downcase.gsub('::', Familia.delim).to_sym
+      end
+
+      def create *args
+        me = from_array(*args)
+        raise "#{self} exists: #{me.rediskey}" if me.exists?
+
+        me.save
+        me
+      end
+
+      def multiget(*ids)
+        ids = rawmultiget(*ids)
+        ids.filter_map { |json| from_json(json) }
+      end
+
+      def rawmultiget(*ids)
+        ids.collect! { |objid| rediskey(objid) }
+        return [] if ids.compact.empty?
+
+        Familia.trace :MULTIGET, redis, "#{ids.size}: #{ids}", caller if Familia.debug?
+        redis.mget(*ids)
+      end
+
+      def from_key(objkey)
+        raise ArgumentError, 'Empty key' if objkey.to_s.empty?
+
+        # We use a lower-level method here b/c we're working with the
+        # full key and not just the identifier.
+        does_exist = redis.exists(objkey).positive?
+
+        Familia.ld "[.from_key] #{self} from key #{objkey} (exists: #{does_exist})"
+        Familia.trace :LOAD, redis, objkey, caller if Familia.debug?
+
+        # This is reason for calling exists first. We want to definitively and without any
+        # ambiguity know if the object exists in Redis. If it doesn't, we return nil. If
+        # it does, we proceed to load the object. Otherwise, hgetall will return an empty
+        # hash, which will be passed to the constructor, which will then be annoying to
+        # debug.
+        return unless does_exist
+
+        obj = redis.hgetall(objkey) # horreum objects are persisted as redis hashes
+        Familia.trace :HGETALL, redis, "#{objkey}: #{obj.inspect}", caller if Familia.debug?
+
+        new(**obj)
+      end
+
+      def from_redis(identifier, suffix = :object)
+        return nil if identifier.to_s.empty?
+
+        objkey = rediskey(identifier, suffix)
+        Familia.ld "[.from_redis] #{self} from key #{objkey})"
+        Familia.trace :FROMREDIS, Familia.redis(uri), objkey, caller(1..1).first if Familia.debug?
+        from_key objkey
+      end
+
+      def exists?(identifier, suffix = :object)
+        return false if identifier.to_s.empty?
+
+        objkey = rediskey identifier, suffix
+
+        ret = redis.exists objkey
+        if Familia.debug?
+          Familia.trace :EXISTS, redis, "#{objkey} #{ret.inspect}",
+                        caller
+        end
+        ret.positive?
+      end
+
+      def destroy!(identifier, suffix = :object)
+        return false if identifier.to_s.empty?
+
+        objkey = rediskey identifier, suffix
+
+        ret = redis.del objkey
+        if Familia.debug?
+          Familia.trace :DELETED, redis, "#{objkey}: #{ret.inspect}",
+                        caller
+        end
+        ret.positive?
+      end
+
+      def find(suffix = '*')
+        redis.keys(rediskey('*', suffix)) || []
+      end
+
+      def qstamp(quantum = nil, pattern = nil, now = Familia.now)
+        quantum ||= ttl || 10.minutes
+        pattern ||= '%H%M'
+        rounded = now - (now % quantum)
+        Time.at(rounded).utc.strftime(pattern)
+      end
+
+      # +identifier+ can be a value or an Array of values used to create the index.
+      # We don't enforce a default suffix; that's left up to the instance.
+      # The suffix is used to differentiate between different types of objects.
+      #
+      #
+      # A nil +suffix+ will not be included in the key.
+      def rediskey(identifier, suffix = self.suffix)
+        Familia.ld "[.rediskey] #{identifier} for #{self} (suffix:#{suffix})"
+        raise NoIdentifier, self if identifier.to_s.empty?
+
+        identifier &&= identifier.to_s
+        Familia.rediskey(prefix, identifier, suffix)
+      end
+
+      def dump_method
+        @dump_method || :to_json # Familia.dump_method
+      end
+
+      def load_method
+        @load_method || :from_json # Familia.load_method
+      end
+    end
+  end
+end

data/lib/familia/horreum/commands.rb

@@ -0,0 +1,59 @@
+# rubocop:disable all
+#
+module Familia
+  # InstanceMethods - Module containing instance-level methods for Familia
+  #
+  # This module is included in classes that include Familia, providing
+  # instance-level functionality for Redis operations and object management.
+  #
+  class Horreum
+
+    # Methods that call Redis commands (InstanceMethods)
+    #
+    # NOTE: There is no hgetall for Horreum. This is because Horreum
+    # is a single hash in Redis that we aren't meant to have be working
+    # on in memory for more than, making changes -> committing. To
+    # emphasize this, instead of "refreshing" the object with hgetall,
+    # just load the object again.
+    #
+    module Commands
+
+      def exists?
+        ret = redis.exists rediskey
+        ret.positive?
+      end
+
+      def expire(ttl = nil)
+        ttl ||= self.class.ttl
+        redis.expire rediskey, ttl.to_i
+      end
+
+      def realttl
+        redis.ttl rediskey
+      end
+
+      def hdel!(field)
+        redis.hdel rediskey, field
+      end
+
+      def redistype(suffix = nil)
+        redis.type rediskey(suffix)
+      end
+
+      def hmset(suffix = nil)
+        suffix ||= self.class.suffix
+        redis.hmset rediskey(suffix), to_h
+      end
+
+      def delete!
+        Familia.trace :DELETE!, redis, redisuri, caller(1..1) if Familia.debug?
+        ret = redis.del rediskey
+        ret.positive?
+      end
+      protected :delete!
+
+    end
+
+    include Commands # these become Familia::Horreum instance methods
+  end
+end

data/lib/familia/horreum/relations_management.rb

@@ -0,0 +1,141 @@
+module Familia
+  class Horreum
+    #
+    # RelationsManagement: Manages Redis-type fields and relations
+    #
+    # This module uses metaprogramming to dynamically create methods
+    # for managing different types of Redis objects (e.g., sets, lists, hashes).
+    #
+    # Key metaprogramming features:
+    # * Dynamically defines methods for each Redis type (e.g., set, list, hashkey)
+    # * Creates both instance-level and class-level relation methods
+    # * Provides query methods for checking relation types
+    #
+    # Usage:
+    #   Include this module in classes that need Redis-type management
+    #   Call setup_relations_accessors to initialize the feature
+    #
+    module RelationsManagement
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.setup_relations_accessors
+      end
+
+      module ClassMethods
+        # Sets up all Redis-type related methods
+        # This method is the core of the metaprogramming logic
+        #
+        def setup_relations_accessors
+          Familia::RedisType.registered_types.each_pair do |kind, klass|
+            Familia.ld "[registered_types] #{kind} => #{klass}"
+
+            # Dynamically define instance-level relation methods
+            #
+            # Once defined, these methods can be used at the class-level of a
+            # Familia member to define *instance-level* relations to any of the
+            # RedisType types (e.g. set, list, hash, etc).
+            #
+            define_method :"#{kind}" do |*args|
+              name, opts = *args
+              attach_instance_redis_object_relation name, klass, opts
+              redis_types[name.to_s.to_sym]
+            end
+            define_method :"#{kind}?" do |name|
+              obj = redis_types[name.to_s.to_sym]
+              !obj.nil? && klass == obj.klass
+            end
+            define_method :"#{kind}s" do
+              names = redis_types.keys.select { |name| send(:"#{kind}?", name) }
+              names.collect! { |name| redis_types[name] }
+              names
+            end
+
+            # Dynamically define class-level relation methods
+            #
+            # Once defined, these methods can be used at the class-level of a
+            # Familia member to define *class-level relations* to any of the
+            # RedisType types (e.g. class_set, class_list, class_hash, etc).
+            #
+            define_method :"class_#{kind}" do |*args|
+              name, opts = *args
+              attach_class_redis_object_relation name, klass, opts
+            end
+            define_method :"class_#{kind}?" do |name|
+              obj = class_redis_types[name.to_s.to_sym]
+              !obj.nil? && klass == obj.klass
+            end
+            define_method :"class_#{kind}s" do
+              names = class_redis_types.keys.select { |name| send(:"class_#{kind}?", name) }
+              # TODO: This returns instances of the RedisType class which
+              # also contain the options. This is different from the instance
+              # RedisTypes defined above which returns the Struct of name, klass, and opts.
+              # names.collect! { |name| self.send name }
+              # OR NOT:
+              names.collect! { |name| class_redis_types[name] }
+              names
+            end
+          end
+        end
+      end
+      # End of ClassMethods module
+
+      # Creates an instance-level relation
+      def attach_instance_redis_object_relation(name, klass, opts)
+        Familia.ld "[Attaching instance-level #{name}] #{klass} => (#{self}) #{opts}"
+        raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
+
+        name = name.to_s.to_sym
+        opts ||= {}
+
+        redis_types[name] = Struct.new(:name, :klass, :opts).new
+        redis_types[name].name = name
+        redis_types[name].klass = klass
+        redis_types[name].opts = opts
+
+        attr_reader name
+
+        define_method :"#{name}=" do |val|
+          send(name).replace val
+        end
+        define_method :"#{name}?" do
+          !send(name).empty?
+        end
+
+        redis_types[name]
+      end
+
+      # Creates a class-level relation
+      def attach_class_redis_object_relation(name, klass, opts)
+        Familia.ld "[#{self}] Attaching class-level #{name} #{klass} => #{opts}"
+        raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
+
+        name = name.to_s.to_sym
+        opts = opts.nil? ? {} : opts.clone
+        opts[:parent] = self unless opts.key?(:parent)
+
+        class_redis_types[name] = Struct.new(:name, :klass, :opts).new
+        class_redis_types[name].name = name
+        class_redis_types[name].klass = klass
+        class_redis_types[name].opts = opts
+
+        # An accessor method created in the metaclass will
+        # access the instance variables for this class.
+        singleton_class.attr_reader name
+
+        define_singleton_method :"#{name}=" do |v|
+          send(name).replace v
+        end
+        define_singleton_method :"#{name}?" do
+          !send(name).empty?
+        end
+
+        redis_object = klass.new name, opts
+        redis_object.freeze
+        instance_variable_set(:"@#{name}", redis_object)
+
+        class_redis_types[name]
+      end
+    end
+    # End of RelationsManagement module
+  end
+end

data/lib/familia/horreum/serialization.rb

@@ -0,0 +1,154 @@
+# rubocop:disable all
+#
+module Familia
+  # InstanceMethods - Module containing instance-level methods for Familia
+  #
+  # This module is included in classes that include Familia, providing
+  # instance-level functionality for Redis operations and object management.
+  #
+  class Horreum
+
+    # Methods that call load and dump (InstanceMethods)
+    #
+    module Serialization
+      #include Familia::RedisType::Serialization
+
+      attr_writer :redis
+
+      def redis
+        @redis || self.class.redis
+      end
+
+      def transaction
+        original_redis = self.redis
+
+        begin
+          redis.multi do |conn|
+            self.instance_variable_set(:@redis, conn)
+            yield(conn)
+          end
+        ensure
+          self.redis = original_redis
+        end
+      end
+
+      # A thin wrapper around `commit_fields` that updates the timestamps and
+      # returns a boolean.
+      def save
+        Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
+
+        # Update timestamp fields
+        self.updated = Familia.now.to_i
+        self.created = Familia.now.to_i unless self.created
+
+        # Thr return value of commit_fields is an array of strings: ["OK"].
+        ret = commit_fields # e.g. ["OK"]
+
+        Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
+
+        # Convert the return value to a boolean
+        ret.all? { |value| value == "OK" }
+      end
+
+      # +return: [Array<String>] The return value of the Redis multi command
+      def commit_fields
+        Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
+        transaction do |conn|
+          hmset
+          update_expiration
+        end
+      end
+
+      def destroy!
+        Familia.trace :DESTROY, redis, redisuri, caller(1..1) if Familia.debug?
+        delete!
+      end
+
+      def to_h
+        # Use self.class.fields to efficiently generate a hash
+        # of all the fields for this object
+        self.class.fields.inject({}) do |hsh, field|
+          val = send(field)
+          prepared = val.to_s
+          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
+          hsh[field] = prepared
+          hsh
+        end
+      end
+
+      def to_a
+        self.class.fields.map do |field|
+          val = send(field)
+          Familia.ld " [to_a] field: #{field} val: #{val}"
+          to_redis(val)
+        end
+      end
+
+      # The to_redis method in Familia::Redistype and Familia::Horreum serve similar purposes
+      # but have some key differences in their implementation:
+      #
+      # Similarities:
+      # - Both methods aim to serialize various data types for Redis storage
+      # - Both handle basic data types like String, Symbol, and Numeric
+      # - Both have provisions for custom serialization methods
+      #
+      # Differences:
+      # - Familia::Redistype uses the opts[:class] for type hints
+      # - Familia::Horreum had more explicit type checking and conversion
+      # - Familia::Redistype includes more extensive debug tracing
+      #
+      # The centralized Familia.distinguisher method accommodates both approaches by:
+      # 1. Handling a wide range of data types, including those from both implementations
+      # 2. Providing a 'strict_values' option for flexible type handling
+      # 3. Supporting custom serialization through a dump_method
+      # 4. Including debug tracing similar to Familia::Redistype
+      #
+      # By using Familia.distinguisher, we achieve more consistent behavior across
+      # different parts of the library while maintaining the flexibility to handle
+      # various data types and custom serialization needs. This centralization
+      # also makes it easier to extend or modify serialization behavior in the future.
+      #
+      def to_redis(val)
+        prepared = Familia.distinguisher(val, false)
+
+        if prepared.nil? && val.respond_to?(dump_method)
+          prepared = val.send(dump_method)
+        end
+
+        Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}" if prepared.nil?
+        prepared
+      end
+
+      def update_expiration(ttl = nil)
+        ttl ||= opts[:ttl]
+        return if ttl.to_i.zero? # nil will be zero
+
+        Familia.ld "#{rediskey} to #{ttl}"
+        expire ttl.to_i
+      end
+    end
+
+    include Serialization # these become Horreum instance methods
+  end
+end
+
+__END__
+
+
+
+# From RedisHash
+def save
+  hsh = { :key => identifier }
+  ret = commit_fields hsh
+  ret == "OK"
+end
+
+def update_fields hsh={}
+  check_identifier!
+  hsh[:updated] = OT.now.to_i
+  hsh[:created] = OT.now.to_i unless has_key?(:created)
+  ret = update hsh  # update is defined in HashKey
+  ## NOTE: caching here like this only works if hsh has all keys
+  #self.cache.replace hsh
+  ret
+end

data/lib/familia/horreum/settings.rb

@@ -0,0 +1,63 @@
+# rubocop:disable all
+#
+module Familia
+  # InstanceMethods - Module containing instance-level methods for Familia
+  #
+  # This module is included in classes that include Familia, providing
+  # instance-level functionality for Redis operations and object management.
+  #
+  class Horreum
+
+    # Settings - Module containing settings for Familia::Horreum (InstanceMethods)
+    #
+    module Settings
+      attr_writer :dump_method, :load_method, :suffix
+
+      def opts
+        @opts ||= {}
+        @opts
+      end
+
+      def redisdetails
+        {
+          uri: self.class.uri,
+          db: self.class.db,
+          key: rediskey,
+          type: redistype,
+          ttl: ttl,
+          realttl: realttl
+        }
+      end
+
+      def ttl=(v)
+        @ttl = v.to_i
+      end
+
+      def ttl
+        @ttl || self.class.ttl
+      end
+
+      def db=(v)
+        @db = v.to_i
+      end
+
+      def db
+        @db || self.class.db
+      end
+
+      def suffix
+        @suffix || self.class.suffix
+      end
+
+      def dump_method
+        @dump_method || self.class.dump_method
+      end
+
+      def load_method
+        @load_method || self.class.load_method
+      end
+    end
+
+    include Settings # these become Horreum instance methods
+  end
+end

data/lib/familia/horreum/utils.rb

@@ -0,0 +1,43 @@
+# rubocop:disable all
+#
+module Familia
+  # InstanceMethods - Module containing instance-level methods for Familia
+  #
+  # This module is included in classes that include Familia, providing
+  # instance-level functionality for Redis operations and object management.
+  #
+  class Horreum
+
+    # Utils - Module containing utility methods for Familia::Horreum (InstanceMethods)
+    #
+    module Utils
+
+      def redisuri(suffix = nil)
+        u = Familia.redisuri(self.class.uri) # returns URI::Redis
+        u.db ||= self.class.db.to_s # TODO: revisit logic (should the horrerum instance know its uri?)
+        u.key = rediskey(suffix)
+        u
+      end
+
+      # +suffix+ is the value to be used at the end of the redis key
+      # (e.g. `customer:customer_id:scores` would have `scores` as the suffix
+      # and `customer_id` would have been the identifier in that case).
+      #
+      # identifier is the value that distinguishes this object from others.
+      # Whether this is a Horreum or RedisType object, the value is taken
+      # from the `identifier` method).
+      #
+      def rediskey(suffix = self.suffix, ignored = nil)
+        Familia.ld "[#rediskey] #{identifier} for #{self.class}"
+        raise Familia::NoIdentifier, "No identifier for #{self.class}" if identifier.to_s.empty?
+        self.class.rediskey identifier, suffix
+      end
+
+      def join(*args)
+        Familia.join(args.map { |field| send(field) })
+      end
+    end
+
+    include Utils # these become Horreum instance methods
+  end
+end