familia 0.10.2 → 1.0.0.pre.rc1

data/lib/familia/horreum.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Familia
+  #
+  # Horreum: A module for managing Redis-based object storage and relationships
+  #
+  # Key features:
+  # * Provides instance-level access to a single hash in Redis
+  # * Includes Familia for class/module level access to Redis types and operations
+  # * Uses 'hashkey' to define a Redis hash referred to as "object"
+  # * Applies a default expiry (5 years) to all keys
+  #
+  # Metaprogramming:
+  # * The class << self block defines class-level behavior
+  # * The `inherited` method extends ClassMethods to subclasses like
+  #  `MyModel` in the example below
+  #
+  # Usage:
+  #   class MyModel < Familia::Horreum
+  #     field :name
+  #     field :email
+  #   end
+  #
+  class Horreum
+    include Familia::Base
+
+    # == Singleton Class Context
+    #
+    # The code within this block operates on the singleton class (also known as
+    # eigenclass or metaclass) of the current class. This means:
+    #
+    # 1. Methods defined here become class methods, not instance methods.
+    # 2. Constants and variables set here belong to the class, not instances.
+    # 3. This is the place to define class-level behavior and properties.
+    #
+    # Use this context for:
+    # * Defining class methods
+    # * Setting class-level configurations
+    # * Creating factory methods
+    # * Establishing relationships with other classes
+    #
+    # Example:
+    #   class MyClass
+    #     class << self
+    #       def class_method
+    #         puts "This is a class method"
+    #       end
+    #     end
+    #   end
+    #
+    #   MyClass.class_method  # => "This is a class method"
+    #
+    # Note: Changes made here affect the class itself and all future instances,
+    # but not existing instances of the class.
+    #
+    class << self
+      # Extends ClassMethods to subclasses and tracks Familia members
+      def inherited(member)
+        Familia.trace :INHERITED, nil, "Inherited by #{member}", caller if Familia.debug?
+        member.extend(ClassMethods)
+        member.extend(Features)
+
+        # Tracks all the classes/modules that include Familia. It's
+        # 10pm, do you know where you Familia members are?
+        Familia.members << member
+        super
+      end
+    end
+
+    # Instance initialization
+    # This method sets up the object's state, including Redis-related data
+    def initialize(*args, **kwargs)
+      Familia.ld "[Horreum] Initializing #{self.class}"
+      initialize_relatives
+
+      # If there are positional arguments, they should be the field
+      # values in the order they were defined in the implementing class.
+      #
+      # Handle keyword arguments
+      # Fields is a known quantity, so we iterate over it rather than kwargs
+      # to ensure that we only set fields that are defined in the class. And
+      # to avoid runaways.
+      if args.any?
+        initialize_with_positional_args(*args)
+      elsif kwargs.any?
+        initialize_with_keyword_args(**kwargs)
+      else
+        Familia.ld "[Horreum] #{self.class} initialized with no arguments"
+        # If there are no arguments, we need to set the default values
+        # for the fields. This is done in the order they were defined.
+        # self.class.fields.each do |field|
+        #  default = self.class.defaults[field]
+        #  send(:"#{field}=", default) if default
+        # end
+      end
+
+      # Implementing classes can define an init method to do any
+      # additional initialization. Notice that this is called
+      # after the fields are set.
+      init if respond_to?(:init)
+    end
+
+    # Sets up related Redis objects for the instance
+    # This method is crucial for establishing Redis-based relationships
+    #
+    # This needs to be called in the initialize method.
+    #
+    def initialize_relatives
+      # Generate instances of each RedisType. These need to be
+      # unique for each instance of this class so they can piggyback
+      # on the specifc index of this instance.
+      #
+      # i.e.
+      #     familia_object.rediskey              == v1:bone:INDEXVALUE:object
+      #     familia_object.redis_type.rediskey == v1:bone:INDEXVALUE:name
+      #
+      # See RedisType.install_redis_type
+      self.class.redis_types.each_pair do |name, redis_type_definition|
+        klass = redis_type_definition.klass
+        opts = redis_type_definition.opts
+        Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
+
+        # As a subclass of Familia::Horreum, we add ourselves as the parent
+        # automatically. This is what determines the rediskey for RedisType
+        # instance and which redis connection.
+        #
+        #   e.g. If the parent's rediskey is `customer:customer_id:object`
+        #     then the rediskey for this RedisType instance will be
+        #     `customer:customer_id:name`.
+        #
+        opts[:parent] = self # unless opts.key(:parent)
+
+        # Instantiate the RedisType object and below we store it in
+        # an instance variable.
+        redis_type = klass.new name, opts
+
+        # Freezes the redis_type, making it immutable.
+        # This ensures the object's state remains consistent and prevents any modifications,
+        # safeguarding its integrity and making it thread-safe.
+        # Any attempts to change the object after this will raise a FrozenError.
+        redis_type.freeze
+
+        # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
+        instance_variable_set :"@#{name}", redis_type
+      end
+    end
+
+    def initialize_with_positional_args(*args)
+      self.class.fields.zip(args).each do |field, value|
+        send(:"#{field}=", value) if value
+      end
+    end
+    private :initialize_with_positional_args
+
+    def initialize_with_keyword_args(**kwargs)
+      self.class.fields.each do |field|
+        # Redis will give us field names as strings back, but internally
+        # we use symbols. So we do both.
+        value = kwargs[field.to_sym] || kwargs[field.to_s]
+        send(:"#{field}=", value) if value
+      end
+    end
+    private :initialize_with_keyword_args
+
+    # Determines the unique identifier for the instance
+    # This method is used to generate Redis keys for the object
+    def identifier
+      definition = self.class.identifier # e.g.
+      # When definition is a symbol or string, assume it's an instance method
+      # to call on the object to get the unique identifier. When it's a callable
+      # object, call it with the object as the argument. When it's an array,
+      # call each method in turn and join the results. When it's nil, raise
+      # an error
+      unique_id = case definition
+                  when Symbol, String
+                    send(definition)
+                  when Proc
+                    definition.call(self)
+                  when Array
+                    Familia.join(definition.map { |method| send(method) })
+                  else
+                    raise Problem, "Invalid identifier definition: #{definition.inspect}"
+                  end
+
+      # If the unique_id is nil, raise an error
+      raise Problem, "Identifier is nil for #{self}" if unique_id.nil?
+      raise Problem, 'Identifier is empty' if unique_id.empty?
+
+      unique_id
+    end
+  end
+end
+
+require_relative 'horreum/class_methods'
+require_relative 'horreum/commands'
+require_relative 'horreum/serialization'
+require_relative 'horreum/settings'
+require_relative 'horreum/utils'

data/lib/familia/logging.rb

@@ -0,0 +1,249 @@
+# rubocop:disable all
+
+require 'pathname'
+require 'logger'
+
+module LoggerTraceRefinement
+  # Set to same value as Logger::DEBUG since 0 is the floor
+  # without either more invasive changes to the Logger class
+  # or a CustomLogger class that inherits from Logger.
+  TRACE = 2 unless defined?(TRACE)
+  refine Logger do
+
+    def trace(progname = nil, &block)
+      Thread.current[:severity_letter] = 'T'
+      add(LoggerTraceRefinement::TRACE, nil, progname, &block)
+    ensure
+      Thread.current[:severity_letter] = nil
+    end
+
+  end
+end
+
+module Familia
+  @logger = Logger.new($stdout)
+  @logger.progname = name
+  @logger.formatter = proc do |severity, datetime, progname, msg|
+    severity_letter = severity[0]  # Get the first letter of the severity
+    pid = Process.pid
+    thread_id = Thread.current.object_id
+    full_path, line = caller[4].split(":")[0..1]
+    parent_path = Pathname.new(full_path).ascend.find { |p| p.basename.to_s == 'familia' }
+    relative_path = full_path.sub(parent_path.to_s, 'familia')
+    utc_datetime = datetime.utc.strftime("%m-%d %H:%M:%S.%6N")
+
+    # Get the severity letter from the thread local variable or use
+    # the default. The thread local variable is set in the trace
+    # method in the LoggerTraceRefinement module. The name of the
+    # variable `severity_letter` is arbitrary and could be anything.
+    severity_letter = Thread.current[:severity_letter] || severity_letter
+
+    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  <#{relative_path}:#{line}>\n"
+  end
+
+  # The Logging module provides a set of methods and constants for logging messages
+  # at various levels of severity. It is designed to be used with the Ruby Logger class
+  # to facilitate logging in applications.
+  #
+  # == Constants:
+  # Logger::TRACE::
+  #   A custom log level for trace messages, typically used for very detailed
+  #   debugging information.
+  #
+  # == Methods:
+  # trace::
+  #   Logs a message at the TRACE level. This method is only available if the
+  #   LoggerTraceRefinement is used.
+  #
+  # debug::
+  #   Logs a message at the DEBUG level. This is used for low-level system information
+  #   for debugging purposes.
+  #
+  # info::
+  #   Logs a message at the INFO level. This is used for general information about
+  #   system operation.
+  #
+  # warn::
+  #   Logs a message at the WARN level. This is used for warning messages, typically
+  #   for non-critical issues that require attention.
+  #
+  # error::
+  #   Logs a message at the ERROR level. This is used for error messages, typically
+  #   for critical issues that require immediate attention.
+  #
+  # fatal::
+  #   Logs a message at the FATAL level. This is used for very severe error events
+  #   that will presumably lead the application to abort.
+  #
+  # == Usage:
+  # To use the Logging module, you need to include the LoggerTraceRefinement module
+  # and use the `using` keyword to enable the refinement. This will add the TRACE
+  # log level and the trace method to the Logger class.
+  #
+  # Example:
+  #   require 'logger'
+  #
+  #   module LoggerTraceRefinement
+  #     refine Logger do
+  #       TRACE = 0
+  #
+  #       def trace(progname = nil, &block)
+  #         add(TRACE, nil, progname, &block)
+  #       end
+  #     end
+  #   end
+  #
+  #   using LoggerTraceRefinement
+  #
+  #   logger = Logger.new(STDOUT)
+  #   logger.trace("This is a trace message")
+  #   logger.debug("This is a debug message")
+  #   logger.info("This is an info message")
+  #   logger.warn("This is a warning message")
+  #   logger.error("This is an error message")
+  #   logger.fatal("This is a fatal message")
+  #
+  # In this example, the LoggerTraceRefinement module is defined with a refinement
+  # for the Logger class. The TRACE constant and trace method are added to the Logger
+  # class within the refinement. The `using` keyword is used to apply the refinement
+  # in the scope where it's needed.
+  #
+  # == Conditions:
+  # The trace method and TRACE log level are only available if the LoggerTraceRefinement
+  # module is used with the `using` keyword. Without this, the Logger class will not
+  # have the trace method or the TRACE log level.
+  #
+  # == Minimum Ruby Version:
+  # This module requires Ruby 2.0.0 or later to use refinements.
+  #
+  module Logging
+    attr_reader :logger
+
+    # Gives our logger the ability to use our trace method.
+    #using LoggerTraceRefinement if Familia.debug
+
+    def info(*msg)
+      @logger.info(*msg)
+    end
+
+    def warn(*msg)
+      @logger.warn(*msg)
+    end
+
+    def ld(*msg)
+      return unless Familia.debug?
+      @logger.debug(*msg)
+    end
+
+    def le(*msg)
+      @logger.error(*msg)
+    end
+
+    # Logs a trace message for debugging purposes if Familia.debug? is true.
+    #
+    # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
+    #   :FROMREDIS, :LOAD, :EXISTS).
+    # @param redis_instance [Object] The Redis instance being used.
+    # @param ident [String] An identifier or key related to the operation being
+    #   traced.
+    # @param context [Array<String>, String, nil] The calling context, typically
+    #   obtained from `caller` or `caller.first`. Default is nil.
+    #
+    # @example
+    #   Familia.trace :LOAD, Familia.redis(uri), objkey, caller if Familia.debug?
+    #
+    #
+    # @return [nil]
+    #
+    def trace(label, redis_instance, ident, context = nil)
+      return unless Familia.debug? && ENV.key?('FAMILIA_TRACE')
+      instance_id = redis_instance&.id
+      codeline = if context
+                   context = [context].flatten
+                   context.reject! { |line| line =~ %r{lib/familia} }
+                   context.first
+                 end
+      @logger.debug format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
+    end
+
+  end
+end
+
+
+__END__
+
+
+### Example 1: Basic Logging
+```ruby
+require 'logger'
+
+logger = Logger.new($stdout)
+logger.info("This is an info message")
+logger.warn("This is a warning message")
+logger.error("This is an error message")
+```
+
+### Example 2: Setting Log Level
+```ruby
+require 'logger'
+
+logger = Logger.new($stdout)
+logger.level = Logger::WARN
+
+logger.debug("This is a debug message") # Will not be logged
+logger.info("This is an info message")  # Will not be logged
+logger.warn("This is a warning message")
+logger.error("This is an error message")
+```
+
+### Example 3: Customizing Log Format
+```ruby
+require 'logger'
+
+logger = Logger.new($stdout)
+logger.formatter = proc do |severity, datetime, progname, msg|
+  "#{datetime}: #{severity} - #{msg}\n"
+end
+
+logger.info("This is an info message")
+logger.warn("This is a warning message")
+logger.error("This is an error message")
+```
+
+### Example 4: Logging with a Program Name
+```ruby
+require 'logger'
+
+logger = Logger.new($stdout)
+logger.progname = 'Familia'
+
+logger.info("This is an info message")
+logger.warn("This is a warning message")
+logger.error("This is an error message")
+```
+
+### Example 5: Logging with a Block
+```ruby
+require 'logger'
+
+# Calling any of the methods above with a block
+#   (affects only the one entry).
+#   Doing so can have two benefits:
+#
+#   - Context: the block can evaluate the entire program context
+#     and create a context-dependent message.
+#   - Performance: the block is not evaluated unless the log level
+#     permits the entry actually to be written:
+#
+#       logger.error { my_slow_message_generator }
+#
+#     Contrast this with the string form, where the string is
+#     always evaluated, regardless of the log level:
+#
+#       logger.error("#{my_slow_message_generator}")
+logger = Logger.new($stdout)
+
+logger.info { "This is an info message" }
+logger.warn { "This is a warning message" }
+logger.error { "This is an error message" }
+```

data/lib/familia/redistype/commands.rb

@@ -0,0 +1,56 @@
+# rubocop:disable all
+
+class Familia::RedisType
+
+  # Must be included in all RedisType classes to provide Redis
+  # commands. The class must have a rediskey method.
+  module Commands
+
+    def move(db)
+      redis.move rediskey, db
+    end
+
+    def rename(newkey)
+      redis.rename rediskey, newkey
+    end
+
+    def renamenx(newkey)
+      redis.renamenx rediskey, newkey
+    end
+
+    def type
+      redis.type rediskey
+    end
+
+    def delete!
+      redis.del rediskey
+    end
+    alias clear delete!
+    alias del delete!
+
+    def exists?
+      redis.exists(rediskey) && !size.zero?
+    end
+
+    def realttl
+      redis.ttl rediskey
+    end
+
+    def expire(sec)
+      redis.expire rediskey, sec.to_i
+    end
+
+    def expireat(unixtime)
+      redis.expireat rediskey, unixtime
+    end
+
+    def persist
+      redis.persist rediskey
+    end
+
+    def echo(meth, trace)
+      redis.echo "[#{self.class}\##{meth}] #{trace} (#{@opts[:class]}\#)"
+    end
+
+  end
+end

data/lib/familia/redistype/serialization.rb

@@ -0,0 +1,110 @@
+# rubocop:disable all
+
+class Familia::RedisType
+
+  module Serialization
+
+    # Serializes an individual value for storage in Redis.
+    #
+    # This method prepares a value for storage in Redis by converting it to a string representation.
+    # If a class option is specified, it uses that class's serialization method.
+    # Otherwise, it relies on the value's own `to_s` method for serialization.
+    #
+    # @param val [Object] The value to be serialized.
+    # @param strict_values [Boolean] Whether to enforce strict value serialization (default: true). Only applies when no class option is specified because the class option is assumed to handle its own serialization.
+    # @return [String] The serialized representation of the value.
+    #
+    # @note When no class option is specified, this method attempts to serialize the value directly.
+    #       If the serialization fails, it falls back to the value's own string representation.
+    #
+    # @example With a class option
+    #   to_redis(User.new(name: "John"), strict_values: false) #=> '{"name":"John"}'
+    #   to_redis(nil, strict_values: false) #=> "" (empty string)
+    #   to_redis(true, strict_values: false) #=> "true"
+    #
+    # @example Without a class option and strict values
+    #   to_redis(123) #=> "123" (which becomes "123" in Redis)
+    #   to_redis("hello") #=> "hello"
+    #   to_redis(nil) # raises an exception
+    #   to_redis(true) # raises an exception
+    #
+    # @raise [Familia::HighRiskFactor]
+    #
+    def to_redis(val, strict_values = true)
+      ret = nil
+
+      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
+
+      if opts[:class]
+        ret = Familia.distinguisher(opts[:class], strict_values)
+        Familia.ld "  from opts[class] <#{opts[:class]}>: #{ret||'<nil>'}"
+      end
+
+      if ret.nil?
+        # Enforce strict values when no class option is specified
+        ret = Familia.distinguisher(val, true)
+        Familia.ld "  from value #{val}<#{val.class}>: #{ret}<#{ret.class}>"
+      end
+
+      Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{ret}<#{ret.class}>", caller(1..1) if Familia.debug?
+
+      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if ret.nil?
+      ret
+    end
+
+    def multi_from_redis(*values)
+      # Avoid using compact! here. Using compact! as the last expression in the method
+      # can unintentionally return nil if no changes are made, which is not desirable.
+      # Instead, use compact to ensure the method returns the expected value.
+      multi_from_redis_with_nil(*values).compact
+    end
+
+    # NOTE: `multi` in this method name refers to multiple values from
+    # redis and not the Redis server MULTI command.
+    def multi_from_redis_with_nil(*values)
+      Familia.ld "multi_from_redis: (#{@opts}) #{values}"
+      return [] if values.empty?
+      return values.flatten unless @opts[:class]
+
+      unless @opts[:class].respond_to?(load_method)
+        raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+      end
+
+      values.collect! do |obj|
+        next if obj.nil?
+
+        val = @opts[:class].send load_method, obj
+        if val.nil?
+          Familia.ld "[#{self.class}\#multi_from_redis] nil returned for #{@opts[:class]}\##{name}"
+        end
+
+        val
+      rescue StandardError => e
+        Familia.info val
+        Familia.info "Parse error for #{rediskey} (#{load_method}): #{e.message}"
+        Familia.info e.backtrace
+        nil
+      end
+
+      values
+    end
+
+    def from_redis(val)
+      return @opts[:default] if val.nil?
+      return val unless @opts[:class]
+
+      ret = multi_from_redis val
+      ret&.first # return the object or nil
+    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
+
+end