familia 2.0.0.pre17 → 2.0.0.pre19

data/examples/datatype_standalone.rb

@@ -0,0 +1,281 @@
+#!/usr/bin/env ruby
+# examples/datatype_standalone.rb
+
+# 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.ld "[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.ld "[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/lib/familia/base.rb

@@ -17,8 +17,6 @@ module Familia
 
     @features_available = nil
     @feature_definitions = nil
-    @dump_method = :to_json
-    @load_method = :from_json
 
     def self.included(base)
       # Ensure the including class gets its own feature registry

data/lib/familia/connection/behavior.rb

@@ -0,0 +1,252 @@
+# 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

data/lib/familia/connection/handlers.rb

@@ -219,5 +219,100 @@ module Familia
         dbclient
       end
     end
+
+    # Handler for delegating connection resolution to parent object
+    #
+    # Used by DataType objects that are attached to a parent (Horreum instance or class).
+    # Delegates the connection resolution to the parent's dbclient method, which allows
+    # DataType objects to inherit connection settings, logical_database, and transaction
+    # context from their parent.
+    #
+    # This preserves the existing architectural pattern where DataType objects owned by
+    # Horreum models use the parent's connection chain. This is the primary behavior
+    # for DataType objects in typical usage.
+    #
+    # @example Instance-level DataType with parent
+    #   user = User.new(userid: 'user_123')
+    #   user.tags  # DataType that delegates to user.dbclient
+    #
+    # @example Class-level DataType with parent
+    #   User.global_users  # DataType that delegates to User.dbclient
+    #
+    class ParentDelegationHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        return nil unless @data_type.parent
+
+        # Delegate to parent's connection chain
+        # Parent can be either a Horreum class or instance
+        parent_connection = @data_type.parent.dbclient(uri)
+
+        if parent_connection
+          Familia.trace :DBCLIENT_PARENT_DELEGATION, @data_type.dbkey,
+                       "Using parent connection from #{@data_type.parent.class}"
+        end
+
+        parent_connection
+      end
+    end
+
+    # Handler for standalone DataType objects without a parent
+    #
+    # Provides connection resolution for DataType objects that are created independently
+    # rather than being attached to a Horreum model. Checks for instance-level @dbclient
+    # first, then falls back to creating a connection based on logical_database option
+    # or global Familia connection.
+    #
+    # This enables standalone DataType usage patterns like Rack::Session implementations
+    # where DataType objects need independent connection management and transaction support.
+    #
+    # @example Standalone DataType with custom connection
+    #   leaderboard = Familia::SortedSet.new('game:leaderboard')
+    #   leaderboard.dbclient = ConnectionPool.new { Redis.new }
+    #
+    # @example Standalone DataType with logical_database option
+    #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
+    #
+    class StandaloneConnectionHandler < BaseConnectionHandler
+      @allows_transaction = true
+      @allows_pipelined = true
+
+      def initialize(data_type)
+        @data_type = data_type
+      end
+
+      def handle(uri)
+        # If a specific URI is provided, always use it to get a connection.
+        if uri
+          connection = Familia.dbclient(uri)
+          Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                       "Created standalone connection for specific URI: #{uri}"
+          return connection
+        end
+
+        # Use instance @dbclient if explicitly set and no URI was passed
+        instance_dbclient = @data_type.instance_variable_get(:@dbclient)
+        if instance_dbclient
+          Familia.trace :DBCLIENT_DATATYPE_INSTANCE, @data_type.dbkey,
+                       'Using DataType instance @dbclient'
+          return instance_dbclient
+        end
+
+        # Fall back to creating connection based on opts or global
+        target_uri = @data_type.opts[:logical_database]
+        connection = Familia.dbclient(target_uri)
+
+        Familia.trace :DBCLIENT_STANDALONE_DATATYPE, @data_type.dbkey,
+                     "Created standalone connection for #{target_uri || 'default'}"
+
+        connection
+      end
+    end
   end
 end