familia 0.10.2 → 1.0.0.pre.rc2

data/lib/familia/types/unsorted_set.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Familia
+  class Set < RedisType
+    def size
+      redis.scard rediskey
+    end
+    alias length size
+
+    def empty?
+      size.zero?
+    end
+
+    def add *values
+      values.flatten.compact.each { |v| redis.sadd? rediskey, to_redis(v) }
+      update_expiration
+      self
+    end
+
+    def <<(v)
+      add v
+    end
+
+    def members
+      echo :members, caller(1..1).first if Familia.debug
+      el = membersraw
+      multi_from_redis(*el)
+    end
+    alias all members
+    alias to_a members
+
+    def membersraw
+      redis.smembers(rediskey)
+    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 member?(val)
+      redis.sismember rediskey, to_redis(val)
+    end
+    alias include? member?
+
+    def delete(val)
+      redis.srem rediskey, to_redis(val)
+    end
+    alias remove delete
+    alias rem delete
+    alias del delete
+
+    def intersection *setkeys
+      # TODO
+    end
+
+    def pop
+      redis.spop rediskey
+    end
+
+    def move(dstkey, val)
+      redis.smove rediskey, dstkey, val
+    end
+
+    def random
+      from_redis randomraw
+    end
+
+    def randomraw
+      redis.srandmember(rediskey)
+    end
+
+    ## 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, :set
+  end
+end

data/lib/familia/utils.rb

@@ -0,0 +1,125 @@
+# rubocop:disable all
+
+require 'securerandom'
+
+module Familia
+  DIGEST_CLASS = Digest::SHA256
+
+  module Utils
+
+    def debug?
+      @debug == true
+    end
+
+    def generate_id
+      input = SecureRandom.hex(32)  # 16=128 bits, 32=256 bits
+      Digest::SHA256.hexdigest(input).to_i(16).to_s(36) # base-36 encoding
+    end
+
+    def join(*val)
+      val.compact.join(Familia.delim)
+    end
+
+    def split(val)
+      val.split(Familia.delim)
+    end
+
+    def rediskey(*val)
+      join(*val)
+    end
+
+    def redisuri(uri)
+      generic_uri = URI.parse(uri.to_s)
+
+      # Create a new URI::Redis object
+      redis_uri = URI::Redis.build(
+        scheme: generic_uri.scheme,
+        userinfo: generic_uri.userinfo,
+        host: generic_uri.host,
+        port: generic_uri.port,
+        path: generic_uri.path,
+        query: generic_uri.query,
+        fragment: generic_uri.fragment
+      )
+
+      redis_uri
+    end
+
+    def now(name = Time.now)
+      name.utc.to_f
+    end
+
+    # A quantized timestamp
+    # e.g. 12:32 -> 12:30
+    #
+    def qnow(quantum = 10.minutes, now = Familia.now)
+      rounded = now - (now % quantum)
+      Time.at(rounded).utc.to_i
+    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
+
+    def generate_sha_hash(*elements)
+      concatenated_string = Familia.join(*elements)
+      DIGEST_CLASS.hexdigest(concatenated_string)
+    end
+
+    # This method determines the appropriate value to return based on the class of the input argument.
+    # It uses a case statement to handle different classes:
+    # - For Symbol, String, Integer, and Float classes, it traces the operation and converts the value to a string.
+    # - For Familia::Horreum class, it traces the operation and returns the identifier of the value.
+    # - For TrueClass, FalseClass, and NilClass, it traces the operation and converts the value to a string ("true", "false", or "").
+    # - For any other class, it traces the operation and returns nil.
+    #
+    # Alternative names for `value_to_distinguish` could be `input_value`, `value`, or `object`.
+    def distinguisher(value_to_distinguish, strict_values = true)
+      case value_to_distinguish
+      when ::Symbol, ::String, ::Integer, ::Float
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "string", caller(1..1) if Familia.debug?
+        # Symbols and numerics are naturally serializable to strings
+        # so it's a relatively low risk operation.
+        value_to_distinguish.to_s
+
+      when ::TrueClass, ::FalseClass, ::NilClass
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "true/false/nil", caller(1..1) if Familia.debug?
+        # TrueClass, FalseClass, and NilClass are high risk because we can't
+        # reliably determine the original type of the value from the serialized
+        # string. This can lead to unexpected behavior when deserializing. For
+        # example, if a TrueClass value is serialized as "true" and then later
+        # deserialized as a String, it can cause errors in the application. Worse
+        # still, if a NilClass value is serialized as an empty string we lose the
+        # ability to distinguish between a nil value and an empty string when
+        #
+        raise Familia::HighRiskFactor, value_to_distinguish if strict_values
+        value_to_distinguish.to_s #=> "true", "false", ""
+
+      when Familia::Base, Class
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
+        if value_to_distinguish.is_a?(Class)
+          value_to_distinguish.name
+        else
+          value_to_distinguish.identifier
+        end
+
+      else
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
+
+        if value_to_distinguish.class.ancestors.member?(Familia::Base)
+          Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
+          value_to_distinguish.identifier
+
+        else
+          Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
+          raise Familia::HighRiskFactor, value_to_distinguish if strict_values
+          nil
+        end
+      end
+    end
+
+  end
+end

data/lib/familia/version.rb

@@ -0,0 +1,25 @@
+# rubocop:disable all
+
+require 'yaml'
+
+module Familia
+  module VERSION
+    def self.to_s
+      load_config
+      version = [@version[:MAJOR], @version[:MINOR], @version[:PATCH]].join('.')
+      version += "-#{@version[:PRE]}" if @version[:PRE]
+      version
+    end
+    alias inspect to_s
+
+    def self.version
+      @version ||= load_config
+      @version
+    end
+
+    def self.load_config
+      version_file_path = File.join(__dir__, '..', '..', 'VERSION.yml')
+      @version = YAML.load_file(version_file_path)
+    end
+  end
+end

data/lib/familia.rb

@@ -1,177 +1,73 @@
-# encoding: utf-8
-FAMILIA_LIB_HOME = File.expand_path File.dirname(__FILE__) unless defined?(FAMILIA_LIB_HOME)
+# rubocop:disable all
+# frozen_string_literal: true
+
+require 'redis'
 require 'uri/redis'
-require 'gibbler'
-require 'familia/core_ext'
-require 'multi_json'
 
-module Familia
-  module VERSION
-    def self.to_s
-      load_config
-      [@version[:MAJOR], @version[:MINOR], @version[:PATCH]].join('.')
-    end
-    alias_method :inspect, :to_s
-    def self.load_config
-      require 'yaml'
-      @version ||= YAML.load_file(File.join(FAMILIA_LIB_HOME, '..', 'VERSION.yml'))
-    end
-  end
-end
+require_relative 'familia/core_ext'
+require_relative 'familia/refinements'
+require_relative 'familia/errors'
+require_relative 'familia/version'
 
+# Familia - A family warehouse for Redis
+#
+# Familia provides a way to organize and store Ruby objects in Redis.
+# It includes various modules and classes to facilitate object-Redis interactions.
+#
+# @example Basic usage
+#   class Flower < Familia::Horreum
+#
+#     identifier :my_identifier_method
+#     field  :token
+#     field  :name
+#     list   :owners
+#     set    :tags
+#     zset   :metrics
+#     hash   :props
+#     string :value, :default => "GREAT!"
+#   end
+#
+# @see https://github.com/delano/familia
+#
 module Familia
-  include Gibbler::Complex
-  @secret = '1-800-AWESOME' # Should be modified via Familia.secret = ''
-  @apiversion = nil
-  @uri = URI.parse 'redis://127.0.0.1'
-  @delim = ':'
-  @clients = {}
-  @classes = []
-  @suffix = :object.freeze
-  @index = :id.freeze
+
   @debug = false
-  @dump_method = :to_json
-  @load_method = :from_json
+  @members = []
 
   class << self
-    attr_reader :clients, :uri, :logger
-    attr_accessor :debug, :secret, :delim, :dump_method, :load_method
-    attr_writer :apiversion
+    attr_accessor :debug
+    attr_reader :members
 
-    alias_method :url, :uri
-    def debug?() @debug == true end
-    def info *msg
-      STDERR.puts *msg
-    end
-    def classes with_redis_objects=false
-      with_redis_objects ? [@classes, RedisObject.classes].flatten : @classes
-    end
-    def ld *msg
-      info *msg if debug?
-    end
-    def trace label, redis_instance, ident, context=nil
-      return unless Familia.debug?
-      codeline = if context
-        context = [context].flatten
-        context.reject! { |line| line =~ /lib\/familia/ }
-        context.first
-      end
-      info "[%s] -> %s <- %s %s" % [label, codeline, redis_instance.id, ident]
-    end
-    def uri= v
-      v = URI.parse v unless URI === v
-      @uri = v
-    end
-    # A convenience method for returning the appropriate Redis
-    # connection. If +uri+ is an Integer, we'll treat it as a
-    # database number. If it's a String, we'll treat it as a
-    # full URI (e.g. redis://1.2.3.4/15).
-    # Otherwise we'll return the default connection.
-    def redis(uri=nil)
-      if Integer === uri
-        tmp = Familia.uri
-        tmp.db = uri
-        uri = tmp
-      elsif String === uri
-        uri &&= URI.parse uri
-      end
-      uri ||= Familia.uri
-      connect(uri) unless @clients[uri.serverid]
-      @clients[uri.serverid]
-    end
-    def log(level, path)
-      logger = Log4r::Logger.new('familia')
-      logger.outputters = Log4r::FileOutputter.new 'familia', :filename => path
-      logger.level = Log4r.const_get(level)
-      logger
-    end
-    def connect(uri=nil)
-      uri &&= URI.parse uri if String === uri
-      uri ||= Familia.uri
-      conf = uri.conf
-      redis = Redis.new conf
-      Familia.trace(:CONNECT, redis, conf.inspect, caller[0..3])
-      @clients[uri.serverid] = redis
-    end
-    def reconnect_all!
-      Familia.classes.each do |klass|
-        klass.redis.client.reconnect
-        Familia.info "#{klass} ping: #{klass.redis.ping}" if debug?
-      end
-    end
-    def connected?(uri=nil)
-      uri &&= URI.parse uri if String === uri
-      @clients.has_key?(uri.serverid)
-    end
-    def default_suffix(a=nil) @suffix = a if a; @suffix end
-    def default_suffix=(a) @suffix = a end
-    def index(r=nil)  @index = r if r; @index end
-    def index=(r) @index = r; r end
-    def join(*r) r.join(Familia.delim) end
-    def split(r) r.split(Familia.delim) end
-    def rediskey *args
-      el = args.flatten.compact
-      el.unshift @apiversion unless @apiversion.nil?
-      el.join(Familia.delim)
+    def included(member)
+      raise Problem, "#{member} should subclass Familia::Horreum"
     end
-    def apiversion(r=nil, &blk)
-      if blk.nil?
-        @apiversion = r if r;
-      else
-        tmp = @apiversion
-        @apiversion = r
-        blk.call
-        @apiversion = tmp
-      end
-      @apiversion
-    end
-    def now n=Time.now
-      n.utc.to_i
-    end
-    # A quantized timestamp
-    # e.g. 12:32 -> 12:30
+
+    # A convenience pattern for configuring Familia.
+    #
+    # @example
+    #  Familia.configure do |config|
+    #    config.debug = true
+    #    config.enable_redis_logging = true
+    #  end
+    #
     #
-    def qnow quantum=10.minutes, now=Familia.now
-      rounded = now - (now % quantum)
-      Time.at(rounded).utc.to_i
+    def configure
+      yield self
     end
   end
 
-  class Problem < RuntimeError; end
-  class NoIndex < Problem; end
-  class NonUniqueKey < Problem; end
-  class NotConnected < Problem
-    attr_reader :uri
-    def initialize uri
-      @uri = uri
-    end
-    def message
-      "No client for #{uri.serverid}"
-    end
-  end
-
-  def self.included(obj)
-    obj.send :include, Familia::InstanceMethods
-    obj.send :include, Gibbler::Complex
-    obj.extend Familia::ClassMethods
-    obj.class_zset :instances, :class => obj, :reference => true
-    Familia.classes << obj
-  end
-
-  require 'familia/object'
-  require 'familia/helpers'
+  require_relative 'familia/logging'
+  require_relative 'familia/connection'
+  require_relative 'familia/settings'
+  require_relative 'familia/utils'
 
+  extend Logging
+  extend Connection
+  extend Settings
+  extend Utils
 end
 
-
-module Familia
-  module Collector
-    def klasses
-      @klasses ||= []
-      @klasses
-    end
-    def included(obj)
-      self.klasses << obj
-    end
-  end
-end
+require_relative 'familia/base'
+require_relative 'familia/features'
+require_relative 'familia/redistype'
+require_relative 'familia/horreum'

data/lib/redis_middleware.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# RedisLogger is RedisClient middleware.
+#
+# This middleware addresses the need for detailed Redis command logging, which
+# was removed from the redis-rb gem due to performance concerns. However, in
+# many development and debugging scenarios, the ability to log Redis commands
+# can be invaluable.
+#
+# @example Enable Redis command logging
+#   RedisLogger.logger = Logger.new(STDOUT)
+#   RedisClient.register(RedisLogger)
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+#
+# @note While there were concerns about the performance impact of logging in
+#   the redis-rb gem, this middleware is designed to be optional and can be
+#   easily enabled or disabled as needed. The performance impact is minimal
+#   when logging is disabled, and the benefits during development and debugging
+#   often outweigh the slight performance cost when enabled.
+module RedisLogger
+  @logger = nil
+
+  class << self
+    # Gets/sets the logger instance used by RedisLogger.
+    # @return [Logger, nil] The current logger instance or nil if not set.
+    attr_accessor :logger
+  end
+
+  # Logs the Redis command and its execution time.
+  #
+  # This method is called for each Redis command when the middleware is active.
+  # It logs the command and its execution time only if a logger is set.
+  #
+  # @param command [Array] The Redis command and its arguments.
+  # @param redis_config [Hash] The configuration options for the Redis
+  #   connection.
+  # @return [Object] The result of the Redis command execution.
+  #
+  # @note The performance impact of this logging is negligible when no logger
+  #   is set, as it quickly returns control to the Redis client. When a logger
+  #   is set, the minimal overhead is often offset by the valuable insights
+  #   gained during development and debugging.
+  def call(command, redis_config)
+    return yield unless RedisLogger.logger
+
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    result = yield
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start
+    RedisLogger.logger.debug("Redis: #{command.inspect} (#{duration}µs)")
+    result
+  end
+end
+
+# RedisCommandCounter is RedisClient middleware.
+#
+# This middleware counts the number of Redis commands executed. It can be
+# useful for performance monitoring and debugging, allowing you to track
+# the volume of Redis operations in your application.
+#
+# @example Enable Redis command counting
+#   RedisCommandCounter.reset
+#   RedisClient.register(RedisCommandCounter)
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+module RedisCommandCounter
+  @count = 0
+  @mutex = Mutex.new
+
+  class << self
+    # Gets the current count of Redis commands executed.
+    # @return [Integer] The number of Redis commands executed.
+    attr_reader :count
+
+    # Resets the command count to zero.
+    # This method is thread-safe.
+    # @return [Integer] The reset count (always 0).
+    def reset
+      @mutex.synchronize { @count = 0 }
+    end
+
+    # Increments the command count.
+    # This method is thread-safe.
+    # @return [Integer] The new count after incrementing.
+    def increment
+      @mutex.synchronize { @count += 1 }
+    end
+
+    def count_commands
+      start_count = count
+      yield
+      end_count = count
+      end_count - start_count
+    end
+  end
+
+  # Counts the Redis command and delegates its execution.
+  #
+  # This method is called for each Redis command when the middleware is active.
+  # It increments the command count and then yields to execute the actual command.
+  #
+  # @param command [Array] The Redis command and its arguments.
+  # @param redis_config [Hash] The configuration options for the Redis connection.
+  # @return [Object] The result of the Redis command execution.
+  def call(command, redis_config)
+    RedisCommandCounter.increment
+    yield
+  end
+end

data/try/00_familia_try.rb

@@ -1,11 +1,12 @@
-require 'familia'
-require 'familia/test_helpers'
 
-Familia.apiversion = 'v1'
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+#Familia.apiversion = 'v1'
 
 
 ## Check for help class
-Bone.redis_objects.keys # consistent b/c hashes are ordered
+Bone.redis_types.keys # consistent b/c hashes are ordered
 #=> [:owners, :tags, :metrics, :props, :value]
 
 ## Familia has a uri

data/try/10_familia_try.rb

@@ -1,25 +1,28 @@
-require 'familia'
-require 'familia/test_helpers'
 
-## Has all redis objects
-redis_objects = Familia::RedisObject.registration.keys
-redis_objects.collect(&:to_s).sort
-#=> ["hash", "list", "set", "string", "zset"]
+require 'time'
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :list?
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+## Has all redistype relativess
+registered_types = Familia::RedisType.registered_types.keys
+registered_types.collect(&:to_s).sort
+#=> ["counter", "hash", "hashkey", "list", "lock", "set", "sorted_set", "string", "zset"]
+
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :list?
 #=> true
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :list
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :list
 #=> true
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :lists
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :lists
 #=> true
 
-## A Familia object knows its redis objects
-Bone.redis_objects.is_a?(Hash) && Bone.redis_objects.has_key?(:owners)
+## A Familia object knows its redistype relativess
+Bone.redis_types.is_a?(Hash) && Bone.redis_types.has_key?(:owners)
 #=> true
 
 ## A Familia object knows its lists
@@ -30,14 +33,15 @@ Bone.lists.size
 Bone.list? :owners
 #=> true
 
-## A Familia object can get a specific redis object def
+## A Familia object can get a specific redistype relatives def
 definition = Bone.list :owners
 definition.klass
 #=> Familia::List
 
 ## Familia.now
-Familia.now Time.parse('2011-04-10 20:56:20 UTC').utc
-#=> 1302468980
+parsed_time = Familia.now(Time.parse('2011-04-10 20:56:20 UTC').utc)
+[parsed_time, parsed_time.is_a?(Numeric), parsed_time.is_a?(Float)]
+#=> [1302468980.0, true, true]
 
 ## Familia.qnow
 Familia.qnow 10.minutes, 1302468980