familia 1.2.0 → 2.0.0.pre.pre

data/lib/familia/utils.rb

@@ -1,96 +1,128 @@
-# rubocop:disable all
+# lib/familia/utils.rb
 
 require 'securerandom'
 
 module Familia
-  DIGEST_CLASS = Digest::SHA256
 
   module Utils
 
-  # Checks if debug mode is enabled
-  #
-  # e.g. Familia.debug = true
-  #
-  # @return [Boolean] true if debug mode is on, false otherwise
-  def debug?
-    @debug == true
-  end
 
-  # Generates a unique ID using SHA256 and base-36 encoding
-  # @param length [Integer] length of the random input in bytes (default: 32)
-  # @param encoding [Integer] base encoding for the output (default: 36)
-  # @return [String] a unique identifier
-  #
-  # @example Generate a default ID
-  #   Familia.generate_id
-  #   # => "kuk79w6uxg81tk0kn5hsl6pr7ic16e9p6evjifzozkda9el6z"
-  #
-  # @example Generate a shorter ID with 16 bytes input
-  #   Familia.generate_id(length: 16)
-  #   # => "z6gqw1b7ftzpvapydkt0iah0h0bev5hkhrs4mkf1gq4nq5csa"
-  #
-  # @example Generate an ID with hexadecimal encoding
-  #   Familia.generate_id(encoding: 16)
-  #   # => "d06a2a70cba543cd2bbd352c925bc30b0a9029ca79e72d6556f8d6d8603d5716"
-  #
-  # @example Generate a shorter ID with custom encoding
-  #   Familia.generate_id(length: 8, encoding: 32)
-  #   # => "193tosc85k3u513do2mtmibchpd2ruh5l3nsp6dnl0ov1i91h7m7"
-  #
-  def generate_id(length: 32, encoding: 36)
-    raise ArgumentError, "Encoding must be between 2 and 36" unless (1..36).include?(encoding)
-
-    input = SecureRandom.hex(length)
-    Digest::SHA256.hexdigest(input).to_i(16).to_s(encoding)
-  end
+    # Generates a 256-bit cryptographically secure hexadecimal identifier.
+    #
+    # @return [String] A 64-character hex string representing 256 bits of entropy.
+    # @security Provides ~10^77 possible values, far exceeding UUID4's 128 bits.
+    def generate_hex_id
+      SecureRandom.hex(32)
+    end
 
-  # Joins array elements with Familia delimiter
-  # @param val [Array] elements to join
-  # @return [String] joined string
-  def join(*val)
-    val.compact.join(Familia.delim)
-  end
+    # Generates a cryptographically secure identifier, encoded in the specified base.
+    # By default, this creates a compact, URL-safe base-36 string.
+    #
+    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
+    # @return [String] A secure identifier.
+    #
+    # @example Generate a 256-bit ID in base-36 (default)
+    #   generate_id # => "25nkfebno45yy36z47ffxef2a7vpg4qk06ylgxzwgpnz4q3os4"
+    #
+    # @example Generate a 256-bit ID in base-16 (hexadecimal)
+    #   generate_id(16) # => "568bdb582bc5042bf435d3f126cf71593981067463709c880c91df1ad9777a34"
+    #
+    def generate_id(base = 36)
+      target_length = LENGTH_256_BIT[base]
+      generate_hex_id.to_i(16).to_s(base).rjust(target_length, '0')
+    end
 
-  # Splits a string using Familia delimiter
-  # @param val [String] string to split
-  # @return [Array] split elements
-  def split(val)
-    val.split(Familia.delim)
-  end
+    # Generates a 64-bit cryptographically secure hexadecimal trace identifier.
+    #
+    # @return [String] A 16-character hex string representing 64 bits of entropy.
+    # @note 64 bits provides ~18 quintillion values, sufficient for request tracing.
+    def generate_hex_trace_id
+      SecureRandom.hex(8)
+    end
 
-  # Creates a Redis key from given values
-  # @param val [Array] elements to join for the key
-  # @return [String] Redis key
-  def rediskey(*val)
-    join(*val)
-  end
+    # Generates a short, secure trace identifier, encoded in the specified base.
+    # Suitable for tracing, logging, and other ephemeral use cases.
+    #
+    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
+    # @return [String] A secure short identifier.
+    #
+    # @example Generate a 64-bit short ID in base-36 (default)
+    #   generate_trace_id # => "lh7uap704unf"
+    #
+    # @example Generate a 64-bit short ID in base-16 (hexadecimal)
+    #   generate_trace_id(16) # => "94cf9f8cfb0eb692"
+    #
+    def generate_trace_id(base = 36)
+      target_length = LENGTH_64_BIT[base]
+      generate_hex_trace_id.to_i(16).to_s(base).rjust(target_length, '0')
+    end
 
-  # Converts a generic URI to a Redis URI
-  # @param uri [String, URI] URI to convert
-  # @return [URI::Redis] Redis URI object
-  def redisuri(uri)
-    uri ||= Familia.uri
-    generic_uri = URI.parse(uri.to_s)
-
-    # Create a new URI::Redis object
-    URI::Redis.build(
-      scheme: generic_uri.scheme,
-      userinfo: generic_uri.userinfo,
-      host: generic_uri.host,
-      port: generic_uri.port,
-      path: generic_uri.path, # the db is stored in the path
-      query: generic_uri.query,
-      fragment: generic_uri.fragment
-    )
-  end
+    # Truncates a 256-bit hexadecimal ID to 128 bits and encodes it in a given base.
+    # This function takes the most significant bits from the hex string to maintain
+    # randomness while creating a shorter, deterministic identifier.
+    #
+    # @param hex_id [String] A 64-character hexadecimal string (representing 256 bits).
+    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
+    # @return [String] A 128-bit identifier, encoded in the specified base.
+    #
+    # @example Create a shorter external ID from a full 256-bit internal ID
+    #   hex_id = generate_hex_id
+    #   external_id = shorten_to_external_id(hex_id)
+    #
+    # @note This is useful for creating shorter, public-facing IDs from secure internal ones.
+    # @security Truncation preserves the cryptographic properties of the most significant bits.
+    def shorten_to_external_id(hex_id, base: 36)
+      target_length = LENGTH_128_BIT[base]
+      truncated = hex_id.to_i(16) >> (256 - 128)  # Always 128 bits
+      truncated.to_s(base).rjust(target_length, '0')
+    end
 
-  # Returns current time in UTC as a float
-  # @param name [Time] time object (default: current time)
-  # @return [Float] time in seconds since epoch
-  def Familia.now(name = Time.now)
-    name.utc.to_f
-  end
+    # Truncates a 256-bit hexadecimal ID to 64 bits and encodes it in a given base.
+    #
+    # @param hex_id [String] A 64-character hexadecimal string (representing 256 bits).
+    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
+    # @return [String] A 64-bit identifier, encoded in the specified base.
+    def shorten_to_trace_id(hex_id, base: 36)
+      target_length = LENGTH_64_BIT[base]
+      truncated = hex_id.to_i(16) >> (256 - 64)   # Always 64 bits
+      truncated.to_s(base).rjust(target_length, '0')
+    end
+
+    # Joins array elements with Familia delimiter
+    # @param val [Array] elements to join
+    # @return [String] joined string
+    def join(*val)
+      val.compact.join(Familia.delim)
+    end
 
+    # Splits a string using Familia delimiter
+    # @param val [String] string to split
+    # @return [Array] split elements
+    def split(val)
+      val.split(Familia.delim)
+    end
+
+    # Creates a dbkey from given values
+    # @param val [Array] elements to join for the key
+    # @return [String] dbkey
+    def dbkey(*val)
+      join(*val)
+    end
+
+    # Gets server ID without DB component for pool identification
+    def serverid(uri)
+      # Create a copy of URI without DB for server identification
+      uri = uri.dup
+      uri.db = nil
+      uri.serverid
+    end
+
+    # Returns current time in UTC as a float
+    # @param name [Time] time object (default: current time)
+    # @return [Float] time in seconds since epoch
+    def now(name = Time.now)
+      name.utc.to_f
+    end
 
     # A quantized timestamp
     #
@@ -120,16 +152,12 @@ module Familia
       end
     end
 
-    def generate_sha_hash(*elements)
-      concatenated_string = Familia.join(*elements)
-      DIGEST_CLASS.hexdigest(concatenated_string)
-    end
 
     # This method determines the appropriate transformation to apply based on
     # the class of the input argument.
     #
     # @param [Object] value_to_distinguish The value to be processed. Keep in
-    #   mind that all data in redis is stored as a string so whatever the type
+    #   mind that all data is stored as a string so whatever the type
     #   of the value, it will be converted to a string.
     # @param [Boolean] strict_values Whether to enforce strict value handling.
     #   Defaults to true.
@@ -151,14 +179,14 @@ module Familia
     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?
+        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "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?
+        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "true/false/nil", caller(1..1) if Familia.debug?
 
         # TrueClass, FalseClass, and NilClass are considered high risk because their
         # original types cannot be reliably determined from their serialized string
@@ -175,7 +203,7 @@ module Familia
         value_to_distinguish.to_s #=> "true", "false", ""
 
       when Familia::Base, Class
-        Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
+        Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "base", caller(1..1) if Familia.debug?
 
         # When called with a class we simply transform it to its name. For
         # instances of Familia class, we store the identifier.
@@ -186,20 +214,25 @@ module Familia
         end
 
       else
-         Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
+         Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "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?
+          Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "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?
+          Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "else2 #{strict_values}", caller(1..1) if Familia.debug?
           raise Familia::HighRiskFactor, value_to_distinguish if strict_values
           nil
         end
       end
     end
 
+    # Calculate minimum string length to represent N bits in given base
+    calc_length = ->(bits, base) { (bits * Math.log(2) / Math.log(base)).ceil }
+    LENGTH_256_BIT = [nil, nil] + (2..36).map { |b| calc_length.call(256, b) }
+    LENGTH_128_BIT = [nil, nil] + (2..36).map { |b| calc_length.call(128, b) }
+    LENGTH_64_BIT = [nil, nil] + (2..36).map { |b| calc_length.call(64, b) }
   end
 end

data/lib/familia/version.rb

@@ -1,25 +1,8 @@
-# frozen_string_literal: true
-
-require 'yaml'
+# lib/familia/version.rb
 
 module Familia
-  module VERSION
-    def self.to_s
-      load_config
-      version = [@version[:MAJOR], @version[:MINOR], @version[:PATCH]].join('.')
-      version = "#{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
+  # Version information for the Familia
+  unless defined?(Familia::VERSION)
+    VERSION = '2.0.0-pre'
   end
 end

data/lib/familia.rb

@@ -1,9 +1,9 @@
-# rubocop:disable all
-# frozen_string_literal: true
+# lib/familia.rb
 
 require 'json'
 require 'redis'
 require 'uri/redis'
+require 'connection_pool'
 
 require_relative 'familia/core_ext'
 require_relative 'familia/refinements'
@@ -13,12 +13,12 @@ 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.
+# It includes various modules and classes to facilitate object-Database interactions.
 #
 # @example Basic usage
 #   class Flower < Familia::Horreum
 #
-#     identifier :my_identifier_method
+#     identifier_field :my_identifier_method
 #     field  :token
 #     field  :name
 #     list   :owners
@@ -32,17 +32,13 @@ require_relative 'familia/version'
 #
 module Familia
 
-  @debug = false
+  @debug = ENV['FAMILIA_DEBUG'].to_s.downcase.match?(/^(true|1)$/i).freeze
   @members = []
 
   class << self
-    attr_writer :debug
+    attr_accessor :debug
     attr_reader :members
 
-    def debug
-      @debug ||= ENV['FAMILIA_DEBUG'].to_s.match?(/^(true|1)$/i)
-    end
-
     def included(member)
       raise Problem, "#{member} should subclass Familia::Horreum"
     end
@@ -52,13 +48,22 @@ module Familia
     # @example
     #  Familia.configure do |config|
     #    config.debug = true
-    #    config.enable_redis_logging = true
+    #    config.enable_database_logging = true
     #  end
     #
     #
     def configure
       yield self
     end
+
+    # Checks if debug mode is enabled
+    #
+    # e.g. Familia.debug = true
+    #
+    # @return [Boolean] true if debug mode is on, false otherwise
+    def debug?
+      @debug == true
+    end
   end
 
   require_relative 'familia/logging'
@@ -74,5 +79,5 @@ end
 
 require_relative 'familia/base'
 require_relative 'familia/features'
-require_relative 'familia/redistype'
+require_relative 'familia/datatype'
 require_relative 'familia/horreum'

data/lib/middleware/database_middleware.rb

@@ -0,0 +1,150 @@
+# lib/middleware/database_middleware.rb
+
+require 'concurrent-ruby'
+
+# DatabaseLogger is RedisClient middleware.
+#
+# This middleware addresses the need for detailed Database 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 Database commands
+# can be invaluable.
+#
+# @example Enable Database command logging
+#   DatabaseLogger.logger = Logger.new(STDOUT)
+#   RedisClient.register(DatabaseLogger)
+#
+# @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 DatabaseLogger
+  @logger = nil
+
+  class << self
+    # Gets/sets the logger instance used by DatabaseLogger.
+    # @return [Logger, nil] The current logger instance or nil if not set.
+    attr_accessor :logger
+  end
+
+  # Logs the Database command and its execution time.
+  #
+  # This method is called for each Database command when the middleware is active.
+  # It logs the command and its execution time only if a logger is set.
+  #
+  # @param command [Array] The Database command and its arguments.
+  # @param _config [Hash] The configuration options for the Redis
+  #   connection.
+  # @return [Object] The result of the Database command execution.
+  #
+  # @note The performance impact of this logging is negligible when no logger
+  #   is set, as it quickly returns control to the Database client. When a logger
+  #   is set, the minimal overhead is often offset by the valuable insights
+  #   gained during development and debugging.
+  def call(command, _config)
+    return yield unless DatabaseLogger.logger
+
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    result = yield
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start
+    DatabaseLogger.logger.debug("Redis: #{command.inspect} (#{duration}µs)")
+    result
+  end
+end
+
+# DatabaseCommandCounter is RedisClient middleware.
+#
+# This middleware counts the number of Database commands executed. It can be
+# useful for performance monitoring and debugging, allowing you to track
+# the volume of Database operations in your application.
+#
+# @example Enable Database command counting
+#   DatabaseCommandCounter.reset
+#   RedisClient.register(DatabaseCommandCounter)
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+#
+# rubocop:disable ThreadSafety/ClassInstanceVariable
+module DatabaseCommandCounter
+  @count = Concurrent::AtomicFixnum.new(0)
+
+  # We skip SELECT because depending on how the Familia is connecting to redis
+  # the number of SELECT commands can be a lot or just a little. For example in
+  # a configuration where there's a connection to each logical db, there's only
+  # one when the connection is made. When using a provider of via thread local
+  # it could theoretically double the number of statements executed.
+  @skip_commands = Set.new(['SELECT']).freeze
+
+  class << self
+    # Gets the set of commands to skip counting.
+    # @return [Set] The commands that won't be counted.
+    attr_reader :skip_commands
+
+    # Gets the current count of Database commands executed.
+    # @return [Integer] The number of Database commands executed.
+    def count
+      @count.value
+    end
+
+    # Resets the command count to zero.
+    # This method is thread-safe.
+    # @return [Integer] The reset count (always 0).
+    def reset
+      @count.value = 0
+    end
+
+    # Increments the command count.
+    # This method is thread-safe.
+    # @return [Integer] The new count after incrementing.
+    def increment
+      @count.increment
+    end
+
+    def skip_command?(command)
+      skip_commands.include?(command.first.to_s.upcase)
+    end
+
+    # Counts the number of Database commands executed within a block.
+    #
+    # This method captures the command count before and after executing the
+    # provided block, returning the difference. This is useful for measuring
+    # how many Database commands are executed by a specific operation.
+    #
+    # @yield [] The block of code to execute while counting commands.
+    # @return [Integer] The number of Database commands executed within the block.
+    #
+    # @example Count commands in a block
+    #   commands_executed = DatabaseCommandCounter.count_commands do
+    #     dbclient.set('key1', 'value1')
+    #     dbclient.get('key1')
+    #   end
+    #   # commands_executed will be 2
+    def count_commands
+      start_count = count      # Capture the current command count before execution
+      yield                    # Execute the provided block
+      end_count = count        # Capture the command count after execution
+      end_count - start_count  # Return the difference (commands executed in block)
+    end
+  end
+
+  def klass
+    DatabaseCommandCounter
+  end
+
+  # Counts the Database command and delegates its execution.
+  #
+  # This method is called for each Database command when the middleware is active.
+  # It increments the command count (unless the command is in the skip list)
+  # and then yields to execute the actual command.
+  #
+  # @param command [Array] The Database command and its arguments.
+  # @param _config [Hash] The configuration options for the Database connection.
+  # @return [Object] The result of the Database command execution.
+  def call(command, _config)
+    klass.increment unless klass.skip_command?(command)
+    yield
+  end
+end
+# rubocop:enable ThreadSafety/ClassInstanceVariable

data/try/configuration/scenarios_try.rb

@@ -0,0 +1,65 @@
+require_relative '../helpers/test_helpers'
+
+# Comprehensive configuration scenarios
+group "Configuration Scenarios"
+
+try "multi-database configuration" do
+  # Test database switching
+  user_class = Class.new(Familia::Horreum) do
+    identifier :email
+    field :name
+    db 5
+  end
+
+  user = user_class.new(email: "test@example.com", name: "Test")
+  user.save
+
+  user.db == 5 && user.exists?
+ensure
+  user&.delete!
+end
+
+try "custom Redis URI configuration" do
+  # Test with custom URI
+  original_uri = Familia.uri
+  test_uri = "redis://localhost:6379/10"
+
+  Familia.uri = test_uri
+  current_uri = Familia.uri
+
+  current_uri == test_uri
+ensure
+  Familia.uri = original_uri
+end
+
+try "feature configuration inheritance" do
+  base_class = Class.new(Familia::Horreum) do
+    identifier :id
+    feature :expiration
+    ttl 1800
+  end
+
+  child_class = Class.new(base_class) do
+    ttl 3600  # Override parent TTL
+  end
+
+  base_instance = base_class.new(id: "base")
+  child_instance = child_class.new(id: "child")
+
+  base_instance.class.ttl == 1800 &&
+    child_instance.class.ttl == 3600
+end
+
+try "serialization method configuration" do
+  custom_class = Class.new(Familia::Horreum) do
+    identifier :id
+    field :data
+    dump_method :to_yaml
+    load_method :from_yaml
+  end
+
+  instance = custom_class.new(id: "test")
+
+  instance.dump_method == :to_yaml &&
+    instance.load_method == :from_yaml
+end

data/try/core/connection_try.rb

@@ -0,0 +1,58 @@
+# try/core/connection_try.rb
+
+require_relative '../../lib/familia'
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+# Test connection management and Database client handling
+
+## Familia has default URI
+Familia.uri
+#=:> URI::Redis
+
+## Default URI points to localhost database server
+Familia.uri.to_s
+#=> "redis://127.0.0.1"
+
+## Can parse URI from string
+uri = URI.parse('redis://localhost:6379/1')
+uri.host
+#=> "localhost"
+
+## Can establish Database connection
+Familia.connect
+#=:> Redis
+
+## Can connect to different URI
+## Doesn't confirm the logical DB number, dbclient.options raises an error?
+test_uri = 'redis://localhost:6379/2'
+Familia.connect(test_uri)
+#=:> Redis
+
+## Database client responds to basic commands
+Familia.dbclient.ping
+#=> "PONG"
+
+## Multiple connections are managed separately
+Familia.database_clients.size >= 1
+#=> true
+
+## Can enable Database logging
+Familia.enable_database_logging = true
+Familia.enable_database_logging
+#=> true
+
+## Can enable Database command counter
+Familia.enable_database_counter = true
+Familia.enable_database_counter
+#=> true
+
+## Middleware gets registered when enabled
+dbclient = Familia.connect('redis://localhost:6379/3')
+dbclient.ping
+#=> "PONG"
+
+## Cleanup
+Familia.enable_database_logging = false
+Familia.enable_database_counter = false