familia 2.0.0.pre17 → 2.0.0.pre19

data/lib/middleware/{database_middleware.rb → database_logger.rb}

@@ -1,4 +1,4 @@
-# lib/middleware/database_middleware.rb
+# lib/middleware/database_logger.rb
 
 require 'concurrent-ruby'
 
@@ -29,21 +29,40 @@ require 'concurrent-ruby'
 #   often outweigh the slight performance cost when enabled.
 module DatabaseLogger
   @logger = nil
-  @commands = []
+  @commands = Concurrent::Array.new
+  @max_commands = 10_000
+  @process_start = Time.now.to_f.freeze
+
+  CommandMessage = Data.define(:command, :μs, :timeline) do
+    alias_method :to_a, :deconstruct
+    def inspect
+      cmd, duration, timeline = to_a
+      format('%.6f %4dμs > %s', timeline, duration, cmd)
+    end
+  end
 
   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
 
+    # Gets/sets the maximum number of commands to capture.
+    # @return [Integer] The maximum number of commands to capture.
+    attr_accessor :max_commands
+
     # Gets the captured commands for testing purposes.
-    # @return [Array] Array of command hashes with :command, :duration, :timestamp
+    # @return [Array] Array of command hashes with :command, :duration, :timeline
     attr_reader :commands
 
+    # Gets the timestamp when DatabaseLogger was loaded.
+    # @return [Float] The timestamp when DatabaseLogger was loaded.
+    attr_reader :process_start
+
     # Clears the captured commands array.
     # @return [Array] Empty array
     def clear_commands
-      @commands = []
+      @commands.clear
+      nil
     end
 
     # Captures commands in a block and returns them.
@@ -62,8 +81,34 @@ module DatabaseLogger
     def capture_commands
       clear_commands
       yield
-      @commands.dup
+      @commands.to_a
+    end
+
+    # Gets the current count of Database commands executed.
+    # @return [Integer] The number of Database commands executed.
+    def index
+      @commands.size
+    end
+
+    # Thread-safe append with bounded size
+    #
+    # @param message [String] The message to append.
+    # @return [Array] The updated array of commands.
+    def append_command(message)
+      @commands.shift if @commands.size >= @max_commands
+      @commands << message
+    end
+
+    # Returns the current time in microseconds.
+    # This is used to measure the duration of Database commands.
+    #
+    # Alias: now_in_microseconds
+    #
+    # @return [Integer] The current time in microseconds.
+    def now_in_μs
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
     end
+    alias now_in_microseconds now_in_μs
   end
 
   # Logs the Database command and its execution time.
@@ -79,19 +124,65 @@ module DatabaseLogger
   # @note Commands are always captured with minimal overhead for testing purposes.
   #   Logging only occurs when DatabaseLogger.logger is set.
   def call(command, _config)
-    start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    block_start = DatabaseLogger.now_in_μs
     result = yield
-    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start
+    block_duration = DatabaseLogger.now_in_μs - block_start
+
+    # We intentionally use two different codepaths for getting the
+    # time, although they will almost always be so similar that the
+    # difference is negligible.
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
 
-    # Always capture commands for testing purposes
-    DatabaseLogger.instance_variable_get(:@commands) << {
-      command: command.dup,
-      duration: duration,
-      timestamp: Time.now,
-    }
+    msgpack = CommandMessage.new(command.join(' '), block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
 
     # Log if logger is set
-    DatabaseLogger.logger&.debug("Redis: #{command.inspect} (#{duration}µs)")
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
+
+    result
+  end
+
+  # Handle pipelined commands (including MULTI/EXEC transactions)
+  #
+  # Captures MULTI/EXEC and shows you the full transaction. The WATCH
+  # and EXISTS appear separately because they're executed as individual
+  # commands before the transaction starts.
+  def call_pipelined(commands, _config)
+    block_start = DatabaseLogger.now_in_μs
+    results = yield
+    block_duration = DatabaseLogger.now_in_μs - block_start
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
+
+    # Log the entire pipeline as a single operation
+    cmd_string = commands.map { |cmd| cmd.join(' ') }.join(' | ')
+    msgpack = CommandMessage.new(cmd_string, block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
+
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
+
+    results
+  end
+
+  # call_once is used for commands that need dedicated connection handling:
+  #
+  #   * Blocking commands (BLPOP, BRPOP, BRPOPLPUSH)
+  #   * Pub/sub operations (SUBSCRIBE, PSUBSCRIBE)
+  #   * Commands requiring connection affinity
+  #   * Explicit non-pooled command execution
+  #
+  def call_once(command, _config)
+    block_start = DatabaseLogger.now_in_μs
+    result = yield
+    block_duration = DatabaseLogger.now_in_μs - block_start
+    lifetime_duration = (Time.now.to_f - DatabaseLogger.process_start).round(6)
+
+    msgpack = CommandMessage.new(command.join(' '), block_duration, lifetime_duration)
+    DatabaseLogger.append_command(msgpack)
+
+    message = format('[%s] %s', DatabaseLogger.index, msgpack.inspect)
+    DatabaseLogger.logger&.trace(message)
 
     result
   end
@@ -188,5 +279,18 @@ module DatabaseCommandCounter
     klass.increment unless klass.skip_command?(command)
     yield
   end
+
+  def call_pipelined(commands, _config)
+    # Count all commands in the pipeline (except skipped ones)
+    commands.each do |command|
+      klass.increment unless klass.skip_command?(command)
+    end
+    yield
+  end
+
+  def call_once(command, _config)
+    klass.increment unless klass.skip_command?(command)
+    yield
+  end
 end
 # rubocop:enable ThreadSafety/ClassInstanceVariable

data/pr_agent.toml

@@ -0,0 +1,31 @@
+# Qodo Merge Configuration
+# Documentation: https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/
+
+[config]
+# Ensure consistent review language across all PRs
+response_language = "en"
+
+[rag_arguments]
+# Enable RAG context enrichment for codebase duplication compliance checks
+enable_rag = true
+# Include related repositories for comprehensive context
+rag_repo_list = ['delano/familia', 'delano/tryouts', 'delano/otto']
+
+[compliance]
+# Reference custom compliance checklist for project-specific rules
+custom_compliance_path = "pr_compliance_checklist.yaml"
+
+[ignore]
+# Reduce noise by excluding generated files and build artifacts
+glob = [
+    "*.lock",           # Lock files (Gemfile.lock, etc.)
+    "*.gem",            # Built gem files
+    "vendor/**",        # Vendored dependencies
+    "tmp/**",           # Temporary files
+    "log/**",           # Log files
+    "data/**",          # Data directories
+    "public/**",        # Public assets
+    ".yardoc/**",       # YARD documentation cache
+    "dump.rdb",         # Redis database dumps
+    "appendonlydir/**", # Redis append-only file directory
+]

data/pr_compliance_checklist.yaml

@@ -0,0 +1,45 @@
+# Custom Compliance Checklist for Familia
+# Documentation: https://qodo-merge-docs.qodo.ai/tools/compliance/
+
+pr_compliances:
+  - title: "ErrorHandling"
+    compliance_label: true
+    objective: "All external API calls and database operations must have proper error handling"
+    success_criteria: "Try-catch blocks around external calls with appropriate logging or error handling mechanisms"
+    failure_criteria: "External API calls, database operations, or network requests without error handling"
+
+  - title: "TestCoverage"
+    compliance_label: true
+    objective: "New features must include corresponding tests using the Tryouts framework"
+    success_criteria: "Test files present in try/ directory for new functionality following *_try.rb or *.try.rb naming convention"
+    failure_criteria: "New code without test coverage or tests not following Tryouts framework conventions"
+
+  - title: "ChangelogFragment"
+    compliance_label: true
+    objective: "User-facing changes must include a changelog"
+    success_criteria: "New fragment file in changelog.d/ directory following the naming convention and RST format, or updates to CHANGELOG.rst in root directory, or explicit justification for omission"
+    failure_criteria: "User-facing changes without changelog fragment, CHANGELOG.rst updates, or documentation updates"
+
+  - title: "DocumentationUpdates"
+    compliance_label: true
+    objective: "API changes must be reflected in documentation"
+    success_criteria: "YARD documentation comments for new public methods, or updates to docs/ for significant changes"
+    failure_criteria: "New public APIs or significant behavior changes without documentation updates"
+
+  - title: "BackwardCompatibility"
+    compliance_label: true
+    objective: "Changes must maintain backward compatibility or document breaking changes"
+    success_criteria: "No breaking changes to public APIs, or breaking changes clearly documented in migration guides"
+    failure_criteria: "Breaking changes without migration documentation or deprecation warnings"
+
+  - title: "ThreadSafety"
+    compliance_label: true
+    objective: "Code handling shared state must be thread-safe"
+    success_criteria: "Proper synchronization for shared mutable state, or clear documentation of thread-safety assumptions"
+    failure_criteria: "Shared mutable state accessed without synchronization in concurrent contexts"
+
+  - title: "DatabaseKeyNaming"
+    compliance_label: true
+    objective: "Database key generation must follow Familia conventions"
+    success_criteria: "Keys use delim separator, avoid reserved keywords (ttl, db, valkey, redis), and handle empty identifiers"
+    failure_criteria: "Keys using reserved keywords, empty identifiers, or non-standard separators"

data/try/edge_cases/empty_identifiers_try.rb

@@ -2,7 +2,7 @@
 
 # Test empty identifier edge cases
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 
 ## empty string identifier handling

data/try/edge_cases/hash_symbolization_try.rb

@@ -4,7 +4,7 @@
 # bug in Tryouts 3.1 that prevents the setup instance vars from
 # being available to the testcases.
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -25,22 +25,31 @@ end
 @test_hash.keys
 #=> ["name", "age", "nested"]
 
-## After save and refresh, default behavior uses symbol keys
+## After save and refresh, default behavior uses string keys
 @test_obj.refresh!
 @test_obj.config.keys
-#=> [:name, :age, :nested]
+#=> ["name", "age", "nested"]
 
-## Nested hash also has symbol keys
-@test_obj.config[:nested].keys
-#=> [:theme]
+## Nested hash also has string keys
+@test_obj.config["nested"].keys
+#=> ["theme"]
 
 ## Get raw JSON from Valkey/Redis
 @raw_json = @test_obj.hget('config')
 @raw_json.class
 #=> String
 
-## deserialize_value with default symbolize: true returns symbol keys
-@symbol_result = @test_obj.deserialize_value(@raw_json)
+## deserialize_value with default symbolize: false returns string keys
+@string_result_default = @test_obj.deserialize_value(@raw_json)
+@string_result_default.keys
+#=> ["name", "age", "nested"]
+
+## Nested hash in default result also has string keys
+@string_result_default["nested"].keys
+#=> ["theme"]
+
+## deserialize_value with symbolize: true returns symbol keys
+@symbol_result = @test_obj.deserialize_value(@raw_json, symbolize: true)
 @symbol_result.keys
 #=> [:name, :age, :nested]
 
@@ -48,21 +57,12 @@ end
 @symbol_result[:nested].keys
 #=> [:theme]
 
-## deserialize_value with symbolize: false returns string keys
-@string_result = @test_obj.deserialize_value(@raw_json, symbolize: false)
-@string_result.keys
-#=> ["name", "age", "nested"]
-
-## Nested hash in string result also has string keys
-@string_result['nested'].keys
-#=> ["theme"]
-
-## Values are preserved correctly in both cases
+## Values are preserved correctly with symbol keys
 @symbol_result[:name]
 #=> "John"
 
-## String keys also work correctly
-@string_result['name']
+## Values are preserved correctly with string keys
+@string_result_default['name']
 #=> "John"
 
 ## Arrays are handled correctly too
@@ -71,27 +71,27 @@ end
 @array_json = @test_obj.hget('config')
 #=> "[{\"item\":\"value\"},\"string\",123]"
 
+## Array with default (symbolize: false) keeps hash keys as strings
+@string_array_default = @test_obj.deserialize_value(@array_json)
+@string_array_default[0].keys
+#=> ["item"]
+
 ## Array with symbolize: true converts hash keys to symbols
-@symbol_array = @test_obj.deserialize_value(@array_json)
+@symbol_array = @test_obj.deserialize_value(@array_json, symbolize: true)
 @symbol_array[0].keys
 #=> [:item]
 
-## Array with symbolize: false keeps hash keys as strings
-@string_array = @test_obj.deserialize_value(@array_json, symbolize: false)
-@string_array[0].keys
-#=> ["item"]
-
-## Non-hash/array values are returned as-is
+## JSON-encoded string is parsed correctly
 @test_obj.deserialize_value('"just a string"')
-#=> "\"just a string\""
+#=> "just a string"
 
-## Non-hash/array values are returned as-is
+## Non-JSON string returns as-is
 @test_obj.deserialize_value('just a string')
 #=> "just a string"
 
-## A stringified number is still a stringified number
+## JSON number is parsed to Integer
 @test_obj.deserialize_value('42')
-#=> "42"
+#=> 42
 
 ## Invalid JSON returns original string
 @test_obj.deserialize_value('invalid json')

data/try/edge_cases/json_serialization_try.rb

@@ -1,6 +1,6 @@
 # try/edge_cases/json_serialization_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -44,7 +44,7 @@ test_obj.simple = 'just a string'
 test_obj.tags = %w[ruby valkey json familia]
 test_obj.save
 test_obj.hgetall
-#=> {"id"=>"json_test_1", "config"=>"{\"theme\":\"dark\",\"notifications\":true,\"settings\":{\"volume\":80}}", "tags"=>"[\"ruby\",\"valkey\",\"json\",\"familia\"]", "simple"=>"just a string"}
+#=> {"id"=>"\"json_test_1\"", "config"=>"{\"theme\":\"dark\",\"notifications\":true,\"settings\":{\"volume\":80}}", "tags"=>"[\"ruby\",\"valkey\",\"json\",\"familia\"]", "simple"=>"\"just a string\""}
 
 ## Test 4: Hash should be deserialized back to Hash
 test_obj = JsonTest.new 'any_id_will_do'

data/try/edge_cases/legacy_data_detection/deserialization_edge_cases_try.rb

@@ -0,0 +1,170 @@
+# Edge case tests for deserialize_value with legacy data detection
+#
+# Tests the nuanced deserialization that distinguishes between:
+# - Corrupted JSON (data that looks like JSON but fails to parse)
+# - Legacy plain strings (data that was never JSON)
+# - Valid JSON data
+
+require_relative '../../../lib/familia'
+require 'logger'
+require 'stringio'
+
+# Capture log output for verification
+@log_output = StringIO.new
+@original_logger = Familia.instance_variable_get(:@logger)
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+
+class TestModel < Familia::Horreum
+  identifier_field :test_id
+  field :test_id
+  field :data
+end
+
+@model = TestModel.new(test_id: "test1")
+
+## Valid JSON number deserializes correctly
+@result = @model.deserialize_value("123", field_name: :data)
+@result
+#=> 123
+
+## Valid JSON boolean deserializes correctly
+@result = @model.deserialize_value("true", field_name: :data)
+@result
+#=> true
+
+## Valid JSON string deserializes correctly
+@result = @model.deserialize_value('"hello"', field_name: :data)
+@result
+#=> "hello"
+
+## Valid JSON array deserializes correctly
+@result = @model.deserialize_value('[1,2,3]', field_name: :data)
+@result
+#=> [1, 2, 3]
+
+## Valid JSON object deserializes correctly
+@result = @model.deserialize_value('{"key":"value"}', field_name: :data)
+@result
+#=> {"key"=>"value"}
+
+## Plain string (legacy data) returns as-is
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("plain text", field_name: :data)
+@result
+#=> "plain text"
+
+## Legacy data logs at debug level
+@log_output.rewind
+@log_content = @log_output.read
+puts "LOG CONTENT: #{@log_content.inspect}" if ENV['DEBUG']
+@log_content
+#=~> /Legacy plain string/
+
+## Corrupted JSON starting with { logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :data)
+@result
+#=> "{broken"
+
+## Corrupted JSON logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+puts "LOG CONTENT: #{@log_content.inspect}" if ENV['DEBUG']
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted JSON starting with [ logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("[1,2,", field_name: :data)
+@result
+#=> "[1,2,"
+
+## Corrupted array logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted JSON starting with quote logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value('"unterminated', field_name: :data)
+@result
+#=> '"unterminated'
+
+## Unterminated string logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted boolean-like value logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("true123", field_name: :data)
+@result
+#=> "true123"
+
+## Plain text starting with 'true' is legacy data
+@log_output.rewind
+@log_content = @log_output.read
+@log_content
+#=~> /Legacy plain string/
+
+## Field name context appears in error messages
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :important_field)
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/TestModel#important_field/)
+#=> true
+
+## dbkey context appears in error messages when available
+@model.save
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :data)
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/#{Regexp.escape(@model.dbkey)}/)
+#=> true
+
+## Empty string returns nil
+@result = @model.deserialize_value("", field_name: :data)
+@result
+#=> nil
+
+## nil returns nil
+@result = @model.deserialize_value(nil, field_name: :data)
+@result
+#=> nil
+
+## JSON null deserializes to nil
+@result = @model.deserialize_value("null", field_name: :data)
+@result
+#=> nil
+
+## Symbolize option works with hash keys
+@result = @model.deserialize_value('{"name":"test"}', symbolize: true, field_name: :data)
+@result.keys.first.class
+#=> Symbol
+
+## Default keeps string keys
+@result = @model.deserialize_value('{"name":"test"}', field_name: :data)
+@result.keys.first.class
+#=> String
+
+# Teardown
+Familia.instance_variable_set(:@logger, @original_logger)

data/try/edge_cases/race_conditions_try.rb

@@ -1,6 +1,6 @@
 # Test connection race conditions
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## concurrent connection access test
 user_class = Class.new(Familia::Horreum) do

data/try/edge_cases/reserved_keywords_try.rb

@@ -1,6 +1,6 @@
 # Test reserved keyword handling
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## attempting to use ttl as field name causes error
 TestClass = Class.new(Familia::Horreum) do

data/try/edge_cases/string_coercion_try.rb

@@ -1,6 +1,6 @@
 # try/edge_cases/string_coercion_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -130,15 +130,15 @@ process_identifier(@customer)
 
 ## Cleanup after test, 1
 @metadata.delete!
-#=> true
+#=> 1
 
 ## Cleanup after test, 2
 @customer.delete!
-#=> true
+#=> 1
 
 ## Cleanup after test, 3
 @session.delete!
-#=> true
+#=> 1
 
 ## to_s handles identifier errors gracefully
 badboi = BadIdentifierTest.new
@@ -154,4 +154,4 @@ badboi.to_s # .include?('BadIdentifierTest')
 
 ## Delete customer2
 [@customer2.exists?, @customer2.delete!]
-#=> [false, false]
+#=> [false, 0]

data/try/edge_cases/ttl_side_effects_try.rb

@@ -1,6 +1,6 @@
 # Test TTL side effects
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## field update behavior with TTL
 begin

data/try/features/encrypted_fields/aad_protection_try.rb

@@ -3,7 +3,7 @@
 require 'concurrent'
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/concealed_string_core_try.rb

@@ -1,6 +1,6 @@
 # try/features/encryption_fields/concealed_string_core_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 Familia.debug = false

data/try/features/encrypted_fields/context_isolation_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Setup encryption keys for testing
 test_keys = {

data/try/features/encrypted_fields/encrypted_fields_core_try.rb

@@ -1,6 +1,6 @@
 # try/features/encrypted_fields_core_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 

data/try/features/encrypted_fields/encrypted_fields_integration_try.rb

@@ -2,7 +2,7 @@
 
 # Test constants will be redefined in each test since variables don't persist
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'