familia 0.10.2 → 1.0.0.pre.rc2

data/lib/familia/logging.rb

@@ -0,0 +1,232 @@
+# rubocop:disable all
+
+require 'pathname'
+require 'logger'
+
+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 LoggerTraceRefinement::ENABLED
+
+    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 LoggerTraceRefinement::ENABLED
+      instance_id = redis_instance&.id
+      codeline = if context
+                   context = [context].flatten
+                   context.reject! { |line| line =~ %r{lib/familia} }
+                   context.first
+                 end
+      @logger.trace 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

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 :keystring, :parent, :opts
+    attr_writer :dump_method, :load_method
+
+    # +keystring+: 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(keystring, opts = {})
+      #Familia.ld " [initializing] #{self.class} #{opts}"
+      @keystring = keystring
+      @keystring = @keystring.join(Familia.delim) if @keystring.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] #{keystring} 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(keystring)
+      elsif parent_class?
+        # This is a class-level redistype object so the parent class' rediskey
+        # method is defined in Familia::Horreum::ClassMethods.
+        parent.rediskey(keystring, nil)
+      else
+        # This is a standalone RedisType object where it's keystring
+        # is the full key.
+        keystring
+      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/refinements.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'logger'
+
+# Controls whether tracing is enabled via an environment variable
+FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
+
+# FlexibleHashAccess
+#
+# This module provides a refinement for the Hash class to allow flexible access
+# to hash keys using either strings or symbols interchangeably for reading values.
+#
+# Note: This refinement only affects reading from the hash. Writing to the hash
+# maintains the original key type.
+#
+# @example Using the refinement
+#   using FlexibleHashAccess
+#
+#   h = { name: "Alice", "age" => 30 }
+#   h[:name]   # => "Alice"
+#   h["name"]  # => "Alice"
+#   h[:age]    # => 30
+#   h["age"]   # => 30
+#
+#   h["job"] = "Developer"
+#   h[:job]    # => "Developer"
+#   h["job"]   # => "Developer"
+#
+#   h[:salary] = 75000
+#   h[:salary] # => 75000
+#   h["salary"] # => nil (original key type is preserved)
+#
+module FlexibleHashAccess
+  refine Hash do
+    ##
+    # Retrieves a value from the hash using either a string or symbol key.
+    #
+    # @param key [String, Symbol] The key to look up
+    # @return [Object, nil] The value associated with the key, or nil if not found
+    def [](key)
+      super(key.to_s) || super(key.to_sym)
+    end
+  end
+end
+
+# LoggerTraceRefinement
+#
+# This module adds a 'trace' log level to the Ruby Logger class.
+# It is enabled when the FAMILIA_TRACE environment variable is set to
+# '1', 'true', or 'yes' (case-insensitive).
+#
+# @example Enabling trace logging
+#   # Set environment variable
+#   ENV['FAMILIA_TRACE'] = 'true'
+#
+#   # In your Ruby code
+#   require 'logger'
+#   using LoggerTraceRefinement
+#
+#   logger = Logger.new(STDOUT)
+#   logger.trace("This is a trace message")
+#
+module LoggerTraceRefinement
+  # Indicates whether trace logging is enabled
+  ENABLED = %w[1 true yes].include?(FAMILIA_TRACE)
+
+  # The numeric level for trace logging (same as DEBUG)
+  TRACE = 0 unless defined?(TRACE)
+
+  refine Logger do
+    ##
+    # Logs a message at the TRACE level.
+    #
+    # @param progname [String] The program name to include in the log message
+    # @yield A block that evaluates to the message to log
+    # @return [true] Always returns true
+    #
+    # @example Logging a trace message
+    #   logger.trace("MyApp") { "Detailed trace information" }
+    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

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