familia 2.0.0.pre18 → 2.0.0.pre21

data/examples/autoloader/mega_customer/features/deprecated_fields.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer/features/deprecated_fields.rb
+#
+# frozen_string_literal: true
 
 # Extend the MegaCustomer class to organize all of the deprecated fields into one place
 class MegaCustomer < Familia::Horreum

data/examples/autoloader/mega_customer/safe_dump_fields.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer/safe_dump_fields.rb
+#
+# frozen_string_literal: true
 
 # Extend the MegaCustomer class to add safe dump fields
 class MegaCustomer < Familia::Horreum

data/examples/autoloader/mega_customer.rb

@@ -1,4 +1,6 @@
 # examples/autoloader/mega_customer.rb
+#
+# frozen_string_literal: true
 
 require_relative '../../lib/familia'
 

data/examples/datatype_standalone.rb

@@ -0,0 +1,282 @@
+#!/usr/bin/env ruby
+# examples/datatype_standalone.rb
+#
+# frozen_string_literal: true
+
+# Demonstration: Familia::StringKey for Session Storage with Atomic Transactions
+# This example shows how to use Familia's DataType classes independently
+# without inheriting from Familia::Horreum. It implements a Rack-compatible
+# session store using Familia::StringKey for secure, TTL-managed storage.
+#
+# Key Familia Features Demonstrated:
+# - Standalone DataType usage (no parent model required)
+# - Atomic transactions for multi-operation consistency
+# - TTL management for automatic expiration
+# - JSON serialization for complex data structures
+# - Direct Redis access through DataType objects
+
+require 'rack/session/abstract/id'
+require 'securerandom'
+
+require 'base64'
+require 'openssl'
+
+# Load local development version of Familia (not the gem)
+begin
+  require_relative '../lib/familia'
+rescue LoadError
+  # Fall back to installed gem
+  require 'familia'
+end
+
+# SecureSessionStore - a rack-session compatible session store using Familia::StringKey
+#
+# Usage:
+#   ruby examples/datatype_standalone.rb
+#   # Or in your Rack app:
+#   use SecureSessionStore, secret: 'your-secret-key', expire_after: 3600
+#
+# @see https://raw.githubusercontent.com/rack/rack-session/dadcfe60f193e8/lib/rack/session/abstract/id.rb
+# @see https://raw.githubusercontent.com/rack/rack-session/dadcfe60f193e8/lib/rack/session/encryptor.rb
+#
+class SecureSessionStore < Rack::Session::Abstract::PersistedSecure
+  unless defined?(DEFAULT_OPTIONS)
+    DEFAULT_OPTIONS = {
+      key: 'project.session',
+      expire_after: 86_400, # 24 hours default
+      namespace: 'session',
+      sidbits: 256, # Required by Rack::Session::Abstract::Persisted
+      dbclient: nil,
+    }.freeze
+  end
+
+  attr_reader :dbclient
+
+  def initialize(app, options = {})
+    # Require a secret for security
+    raise ArgumentError, 'Secret required for secure sessions' unless options[:secret]
+
+    # Merge options with defaults
+    options = DEFAULT_OPTIONS.merge(options)
+
+    # Configure Familia connection if redis_uri provided
+    @dbclient = options[:dbclient] || Familia.dbclient
+
+    super
+
+    @secret = options[:secret]
+    @expire_after = options[:expire_after]
+    @namespace = options[:namespace] || 'session'
+
+    # Derive different keys for different purposes
+    @hmac_key = derive_key('hmac')
+    @encryption_key = derive_key('encryption')
+  end
+
+  private
+
+  # Create a StringKey instance for a session ID
+  def get_stringkey(sid)
+    return nil if sid.to_s.empty?
+
+    key = Familia.join(@namespace, sid)
+    Familia::StringKey.new(key,
+      ttl: @expire_after,
+      default: nil)
+  end
+
+  def delete_session(_request, sid, _options)
+    # Extract string ID from SessionId object if needed
+    sid_string = sid.respond_to?(:public_id) ? sid.public_id : sid
+
+    get_stringkey(sid_string)&.del
+
+    generate_sid
+  end
+
+  def valid_session_id?(sid)
+    return false if sid.to_s.empty?
+    return false unless sid.match?(/\A[a-f0-9]{64,}\z/)
+
+    # Additional security checks could go here
+    true
+  end
+
+  def valid_hmac?(data, hmac)
+    expected = compute_hmac(data)
+    return false unless hmac.is_a?(String) && expected.is_a?(String) && hmac.bytesize == expected.bytesize
+
+    Rack::Utils.secure_compare(expected, hmac)
+  end
+
+  def derive_key(purpose)
+    OpenSSL::HMAC.hexdigest('SHA256', @secret, "session-#{purpose}")
+  end
+
+  def compute_hmac(data)
+    OpenSSL::HMAC.hexdigest('SHA256', @hmac_key, data)
+  end
+
+  def find_session(_request, sid)
+    # Parent class already extracts sid from cookies
+    # sid may be a SessionId object or nil
+    sid_string = sid.respond_to?(:public_id) ? sid.public_id : sid
+
+    # Only generate new sid if none provided or invalid
+    return [generate_sid, {}] unless sid_string && valid_session_id?(sid_string)
+
+    begin
+      stringkey = get_stringkey(sid_string)
+      stored_data = stringkey.value if stringkey
+
+      # If no data stored, return empty session
+      return [sid, {}] unless stored_data
+
+      # Verify HMAC before deserializing
+      data, hmac = stored_data.split('--', 2)
+
+      # If no HMAC or invalid format, create new session
+      unless hmac && valid_hmac?(data, hmac)
+        # Session tampered with - create new session
+        return [generate_sid, {}]
+      end
+
+      # Decode and parse the session data
+      session_data = Familia::JsonSerializer.parse(Base64.decode64(data))
+
+      [sid, session_data]
+    rescue Familia::PersistenceError => e
+      # Log error in development/debugging
+      Familia.debug "[Session] Error reading session #{sid_string}: #{e.message}"
+
+      # Return new session on any error
+      [generate_sid, {}]
+    end
+  end
+
+  def write_session(_request, sid, session_data, _options)
+    # Extract string ID from SessionId object if needed
+    sid_string = sid.respond_to?(:public_id) ? sid.public_id : sid
+
+    # Serialize and sign the data
+    encoded = Base64.encode64(Familia::JsonSerializer.dump(session_data)).delete("\n")
+    hmac = compute_hmac(encoded)
+    signed_data = "#{encoded}--#{hmac}"
+
+    # Get or create StringKey for this session
+    stringkey = get_stringkey(sid_string)
+
+    # ATOMIC TRANSACTION: Ensures both operations succeed or both fail
+    #
+    # Before DataType transaction support (PR #160), these operations were not atomic:
+    #   stringkey.set(signed_data)
+    #   stringkey.update_expiration(expiration: @expire_after)
+    #
+    # With transaction support, we guarantee atomicity - critical for session storage
+    # where partial writes could lead to sessions without TTL (memory leaks) or
+    # expired sessions with stale data (security issues).
+    #
+    # RECOMMENDED PATTERN: Use DataType methods inside transaction blocks
+    # The transaction block automatically handles the atomic MULTI/EXEC wrapping.
+    # DataType methods handle key generation and provide clean, expressive syntax.
+    stringkey.transaction do
+      stringkey.set(signed_data)
+      stringkey.update_expiration(expiration: @expire_after) if @expire_after&.positive?
+    end
+
+    # ADVANCED: The block yields the Redis connection for low-level access when needed
+    # This is useful for operations that require direct Redis command access or
+    # when working with multiple DataTypes in a single transaction.
+    #
+    # stringkey.transaction do |conn|
+    #   conn.set(stringkey.dbkey, signed_data)
+    #   conn.expire(stringkey.dbkey, @expire_after) if @expire_after&.positive?
+    # end
+
+    # Return the original sid (may be SessionId object)
+    sid
+  rescue Familia::PersistenceError => e
+    # Log error in development/debugging
+    Familia.debug "[Session] Error writing session #{sid_string}: #{e.message}"
+
+    # Return false to indicate failure
+    false
+  end
+
+  # Clean up expired sessions (optional, can be called periodically)
+  def cleanup_expired_sessions
+    # This would typically be handled by Redis TTL automatically
+    # but you could implement manual cleanup if needed
+  end
+end
+
+# Demo application showing session store in action
+class DemoApp
+  def initialize
+    @store = SecureSessionStore.new(
+      proc { |_env| [200, {}, ['Demo App']] },
+      secret: 'demo-secret-key-change-in-production',
+      expire_after: 300, # 5 minutes for demo
+    )
+  end
+
+  def call(env)
+    puts "\n=== Familia::StringKey Session Demo ==="
+
+    # Mock Rack environment
+    env['rack.session'] ||= {}
+    env['HTTP_COOKIE'] ||= ''
+
+    # Simulate session operations
+    session_id = SecureRandom.hex(32)
+    session_data = {
+      'user_id' => '12345',
+      'username' => 'demo_user',
+      'login_time' => Time.now.to_i,
+      'preferences' => { 'theme' => 'dark', 'lang' => 'en' },
+    }
+
+    puts 'Writing session data...'
+    result = @store.send(:write_session, nil, session_id, session_data, {})
+    puts "   Result: #{result ? 'Success' : 'Failed'}"
+
+    puts "\nReading session data..."
+    found_id, found_data = @store.send(:find_session, nil, session_id)
+    puts "   Session ID: #{found_id}"
+    puts "   Data: #{found_data}"
+
+    puts "\nDeleting session..."
+    @store.send(:delete_session, nil, session_id, {})
+
+    puts "\nVerifying deletion..."
+    deleted_id, deleted_data = @store.send(:find_session, nil, session_id)
+    puts "   Data after deletion: #{deleted_data}"
+    puts "   New session ID: #{deleted_id == session_id ? 'Same' : 'Generated'}"
+
+    puts "\n✅ Demo complete!"
+    puts "\nKey Familia Features Used:"
+    puts '• Familia::StringKey for typed Redis storage'
+    puts '• Automatic TTL management'
+    puts '• Direct Redis operations (set, get, del)'
+    puts '• JSON serialization support'
+    puts '• No Horreum inheritance required'
+
+    [200, { 'Content-Type' => 'text/plain' }, ['Familia StringKey Demo - Check console output']]
+  end
+end
+
+# Run demo if executed directly
+if __FILE__ == $0
+  # Ensure Redis is available
+  begin
+    Familia.dbclient.ping
+  rescue Familia::PersistenceError => e
+    puts "❌ Redis connection failed: #{e.message}"
+    puts '   Please ensure Redis is running on localhost:6379'
+    exit 1
+  end
+
+  # Run the demo
+  app = DemoApp.new
+  app.call({})
+end

data/examples/encrypted_fields.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
-
 # examples/encrypted_fields.rb
 #
+# frozen_string_literal: true
+
 # Demonstrates the EncryptedFields feature for protecting sensitive data.
 # This feature provides transparent encryption/decryption of sensitive fields
 # using strong cryptographic algorithms with field-specific key derivation.

data/examples/json_usage_patterns.rb

@@ -1,5 +1,7 @@
 # examples/json_usage_patterns.rb
 #
+# frozen_string_literal: true
+
 # This file demonstrates the JSON serialization patterns available in Familia,
 # showing both the secure defaults and optional developer convenience features.
 

data/examples/relationships.rb

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# examples/relationships.rb
+#
+# frozen_string_literal: true
 
 # Basic Relationships Example
 # This example demonstrates the core features of Familia's relationships system

data/examples/safe_dump.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
-
 # examples/safe_dump.rb
 #
+# frozen_string_literal: true
+
 # Demonstrates the SafeDump feature with the new DSL methods.
 # SafeDump allows you to control which fields are exposed when
 # serializing objects, preventing accidental exposure of sensitive data.

data/examples/sampling_demo.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# examples/sampling_demo.rb
+#
+# frozen_string_literal: true
+
+# Demonstrates DatabaseLogger sampling to reduce log volume in high-traffic scenarios.
+# Run with: bundle exec ruby examples/sampling_demo.rb
+
+require_relative '../lib/familia'
+require 'logger'
+
+# Enable database command logging (middleware registered automatically)
+Familia.enable_database_logging = true
+DatabaseLogger.logger = Familia::FamiliaLogger.new($stdout)
+DatabaseLogger.logger.level = Familia::FamiliaLogger::TRACE
+
+# Scenario 1: No sampling (default) - logs every command
+puts "\n=== Scenario 1: No Sampling (logs all 100 commands) ==="
+DatabaseLogger.sample_rate = nil
+100.times { |i| Familia.dbclient.set("key_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~100 log lines)"
+
+# Scenario 2: 10% sampling - logs ~10 commands
+puts "\n=== Scenario 2: 10% Sampling (logs ~10 of 100 commands) ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.1
+100.times { |i| Familia.dbclient.set("sampled_10_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~10 log lines)"
+
+# Scenario 3: 1% sampling - logs ~1 command (production-friendly)
+puts "\n=== Scenario 3: 1% Sampling (logs ~1 of 100 commands) ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.01
+100.times { |i| Familia.dbclient.set("sampled_1_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check output above - should see ~1 log line)"
+
+# Scenario 4: Sampling with structured logging
+puts "\n=== Scenario 4: 10% Sampling + Structured Logging ==="
+DatabaseLogger.clear_commands
+DatabaseLogger.sample_rate = 0.1
+DatabaseLogger.structured_logging = true
+100.times { |i| Familia.dbclient.set("structured_#{i}", "value_#{i}") }
+puts "Commands captured: #{DatabaseLogger.commands.size}"
+puts "(Check structured output above)"
+
+puts "\n=== Key Insights ==="
+puts "✓ Command capture is unaffected (always 100 commands captured)"
+puts "✓ Only logger output is sampled (reduces log volume)"
+puts "✓ Tests can verify commands while production logs stay clean"
+puts "✓ Deterministic sampling (every Nth command) ensures consistency"

data/examples/single_connection_transaction_confusions.rb

@@ -1,8 +1,9 @@
 #!/usr/bin/env ruby
 # examples/single_connection_transaction_confusions.rb
+#
+# frozen_string_literal: true
 
 # Redis Single Connection Mode Confusions
-#
 # This file demonstrates why mixing Redis operation modes on a single connection
 # causes subtle but critical failures in production applications.
 #

data/familia.gemspec

@@ -17,9 +17,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.3.6')
 
   spec.add_dependency 'benchmark', '~> 0.4'
+  spec.add_dependency 'concurrent-ruby', '~> 1.3'
   spec.add_dependency 'connection_pool', '~> 2.5'
   spec.add_dependency 'csv', '~> 3.3'
   spec.add_dependency 'logger', '~> 1.7'

data/lib/familia/base.rb

@@ -1,4 +1,6 @@
 # lib/familia/base.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # A common module for Familia::DataType and Familia::Horreum to include.

data/lib/familia/connection/behavior.rb

@@ -0,0 +1,254 @@
+# lib/familia/connection/behavior.rb
+#
+# frozen_string_literal: true
+
+# lib/familia/connection/behavior.rb
+
+module Familia
+  module Connection
+    # Shared connection behavior for both Horreum and DataType classes
+    #
+    # This module extracts common connection management functionality that was
+    # previously duplicated between Horreum::Connection and DataType::Connection.
+    # It provides:
+    #
+    # * URI normalization with logical_database support
+    # * Connection creation methods
+    # * Transaction and pipeline execution methods
+    # * Consistent connection API across object types
+    #
+    # Classes including this module must implement:
+    # * `dbclient(uri = nil)` - Connection resolution method
+    # * `build_connection_chain` (private) - Chain of Responsibility setup
+    #
+    # @example Basic usage in a class
+    #   class MyDataStore
+    #     include Familia::Connection::Behavior
+    #
+    #     def dbclient(uri = nil)
+    #       @connection_chain ||= build_connection_chain
+    #       @connection_chain.handle(uri)
+    #     end
+    #
+    #     private
+    #
+    #     def build_connection_chain
+    #       # ... handler setup ...
+    #     end
+    #   end
+    #
+    module Behavior
+      def self.included(base)
+        base.class_eval do
+          attr_writer :dbclient
+          attr_reader :uri
+        end
+      end
+
+      # Normalizes various URI formats to a consistent URI object
+      #
+      # Handles multiple input types and considers the logical_database setting
+      # when uri is nil or Integer. This method is public so connection handlers
+      # can use it for consistent URI processing.
+      #
+      # @param uri [Integer, String, URI, nil] The URI to normalize
+      # @return [URI] Normalized URI object
+      # @raise [ArgumentError] If URI type is invalid
+      #
+      # @example Integer database number
+      #   normalize_uri(2)  # => URI with db=2 on default server
+      #
+      # @example String URI
+      #   normalize_uri('redis://localhost:6379/1')
+      #
+      # @example nil with logical_database
+      #   class MyModel
+      #     include Familia::Connection::Behavior
+      #     attr_accessor :logical_database
+      #   end
+      #   model = MyModel.new
+      #   model.logical_database = 3
+      #   model.normalize_uri(nil)  # => URI with db=3
+      #
+      def normalize_uri(uri)
+        case uri
+        when Integer
+          new_uri = Familia.uri.dup
+          new_uri.db = uri
+          new_uri
+        when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) }
+          URI.parse(uri)
+        when URI
+          uri
+        when nil
+          # Use logical_database if available, otherwise fall back to Familia.uri
+          if respond_to?(:logical_database) && logical_database
+            new_uri = Familia.uri.dup
+            new_uri.db = logical_database
+            new_uri
+          else
+            Familia.uri
+          end
+        else
+          raise ArgumentError, "Invalid URI type: #{uri.class.name}"
+        end
+      end
+
+      # Creates a new Database connection instance
+      #
+      # This method always creates a fresh connection and does not use caching.
+      # Each call returns a new Redis client instance that you are responsible
+      # for managing and closing when done.
+      #
+      # @param uri [String, URI, Integer, nil] The URI of the Database server
+      # @return [Redis] A new Database client connection
+      #
+      # @example Creating a new connection
+      #   client = create_dbclient('redis://localhost:6379/1')
+      #   client.ping
+      #   client.close
+      #
+      def create_dbclient(uri = nil)
+        parsed_uri = normalize_uri(uri)
+        Familia.create_dbclient(parsed_uri)
+      end
+
+      # Alias for create_dbclient (backward compatibility)
+      def connect(*)
+        create_dbclient(*)
+      end
+
+      # Sets the URI for this object's database connection
+      #
+      # @param uri [String, URI, Integer] The new URI
+      # @return [URI] The normalized URI
+      #
+      def uri=(uri)
+        @uri = normalize_uri(uri)
+      end
+
+      # Alias for uri (backward compatibility)
+      def url
+        uri
+      end
+
+      # Alias for uri= (backward compatibility)
+      def url=(uri)
+        self.uri = uri
+      end
+
+      # Executes a Redis transaction (MULTI/EXEC) using this object's connection context
+      #
+      # Provides atomic execution of multiple Redis commands with automatic connection
+      # management and operation mode enforcement. Uses the object's database and
+      # connection settings. Returns a MultiResult object for consistency.
+      #
+      # @yield [Redis] conn The Redis connection configured for transaction mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #
+      # @example Basic transaction
+      #   obj.transaction do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.set('key2', 'value2')
+      #     conn.get('key1')
+      #   end
+      #
+      # @example Reentrant behavior
+      #   obj.transaction do |conn|
+      #     conn.set('outer', 'value')
+      #
+      #     # Nested transaction reuses same connection
+      #     obj.transaction do |inner_conn|
+      #       inner_conn.set('inner', 'value')
+      #     end
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Transaction Context:
+      #   - When called outside global transaction: Creates local MultiResult
+      #   - When called inside global transaction: Yields to existing transaction
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @see Familia.transaction For global transaction method
+      # @see MultiResult For details on the return value structure
+      #
+      def transaction(&)
+        ensure_relatives_initialized! if respond_to?(:ensure_relatives_initialized!, true)
+        Familia::Connection::TransactionCore.execute_transaction(-> { dbclient }, &)
+      end
+
+      # Alias for transaction (alternate naming)
+      def multi(&)
+        transaction(&)
+      end
+
+      # Executes Redis commands in a pipeline using this object's connection context
+      #
+      # Batches multiple Redis commands together and sends them in a single network
+      # round-trip for improved performance. Uses the object's database and connection
+      # settings. Returns a MultiResult object for consistency.
+      #
+      # @yield [Redis] conn The Redis connection configured for pipelined mode
+      # @return [MultiResult] Result object with success status and command results
+      #
+      # @raise [Familia::OperationModeError] When called with incompatible connection handlers
+      #
+      # @example Basic pipeline
+      #   obj.pipelined do |conn|
+      #     conn.set('key1', 'value1')
+      #     conn.incr('counter')
+      #     conn.get('key1')
+      #   end
+      #
+      # @example Performance optimization
+      #   # Instead of multiple round-trips:
+      #   obj.save            # Round-trip 1
+      #   obj.increment_count # Round-trip 2
+      #   obj.update_timestamp # Round-trip 3
+      #
+      #   # Use pipeline for single round-trip:
+      #   obj.pipelined do |conn|
+      #     conn.hmset(obj.dbkey, obj.to_h)
+      #     conn.hincrby(obj.dbkey, 'count', 1)
+      #     conn.hset(obj.dbkey, 'updated_at', Time.now.to_i)
+      #   end
+      #
+      # @note Connection Inheritance:
+      #   - Uses object's logical_database setting if configured
+      #   - Inherits class-level database settings
+      #   - Falls back to instance-level dbclient if set
+      #   - Uses global connection chain as final fallback
+      #
+      # @note Pipeline Context:
+      #   - When called outside global pipeline: Creates local MultiResult
+      #   - When called inside global pipeline: Yields to existing pipeline
+      #   - Maintains proper Fiber-local state for nested calls
+      #
+      # @note Performance Considerations:
+      #   - Best for multiple independent operations
+      #   - Reduces network latency by batching commands
+      #   - Commands execute independently (some may succeed, others fail)
+      #
+      # @see Familia.pipelined For global pipeline method
+      # @see MultiResult For details on the return value structure
+      # @see #transaction For atomic command execution
+      #
+      def pipelined(&block)
+        ensure_relatives_initialized! if respond_to?(:ensure_relatives_initialized!, true)
+        Familia::Connection::PipelineCore.execute_pipeline(-> { dbclient }, &block)
+      end
+
+      # Alias for pipelined (alternate naming)
+      def pipeline(&block)
+        pipelined(&block)
+      end
+    end
+  end
+end