familia 2.0.0.pre26 → 2.1.0

data/lib/familia/migration/runner.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+module Familia
+  module Migration
+    # Runner orchestrates migration execution with dependency resolution.
+    #
+    # Provides methods for querying migration status, validating dependencies,
+    # and executing migrations in the correct order using topological sorting.
+    #
+    # @example Basic usage
+    #   runner = Familia::Migration::Runner.new
+    #   runner.status        # => Array of migration status hashes
+    #   runner.pending       # => Array of unapplied migration classes
+    #   runner.run           # => Execute all pending migrations
+    #
+    # @example Dry run
+    #   runner.run(dry_run: true)  # Preview without applying changes
+    #
+    # @example Rolling back
+    #   runner.rollback('20260131_add_status_field')
+    #
+    class Runner
+      # @return [Array<Class>] Migration classes to operate on
+      attr_reader :migrations
+
+      # @return [Registry] Registry for tracking applied migrations
+      attr_reader :registry
+
+      # @return [Logger] Logger for migration output
+      attr_reader :logger
+
+      # Initialize a new Runner instance.
+      #
+      # @param migrations [Array<Class>, nil] Migration classes (defaults to registered migrations)
+      # @param registry [Registry, nil] Registry instance (defaults to new Registry)
+      # @param logger [Logger, nil] Logger instance (defaults to Familia.logger)
+      #
+      def initialize(migrations: nil, registry: nil, logger: nil)
+        @migrations = migrations || Familia::Migration.migrations
+        @registry = registry || Registry.new
+        @logger = logger || Familia.logger
+      end
+
+      # --- Status Methods ---
+
+      # Get the status of all migrations.
+      #
+      # @return [Array<Hash>] Array of migration info hashes with keys:
+      #   - :migration_id [String] The migration identifier
+      #   - :description [String] Human-readable description
+      #   - :status [Symbol] :applied or :pending
+      #   - :applied_at [Time, nil] When the migration was applied
+      #   - :reversible [Boolean] Whether the migration has a down method
+      #
+      def status
+        # Batch fetch all applied migrations with timestamps in a single Redis call
+        applied_info = @registry.all_applied.each_with_object({}) do |entry, hash|
+          hash[entry[:migration_id]] = entry[:applied_at]
+        end
+
+        @migrations.map do |klass|
+          id = klass.migration_id
+          applied_at = applied_info[id]
+          {
+            migration_id: id,
+            description: klass.description,
+            status: applied_at ? :applied : :pending,
+            applied_at: applied_at,
+            reversible: klass.new.reversible?,
+          }
+        end
+      end
+
+      # Get all pending (unapplied) migrations.
+      #
+      # @return [Array<Class>] Migration classes that haven't been applied
+      #
+      def pending
+        @registry.pending(@migrations)
+      end
+
+      # Validate migration dependencies and configuration.
+      #
+      # @return [Array<Hash>] Array of issue hashes with keys:
+      #   - :type [Symbol] Type of issue (:missing_dependency, :circular_dependency)
+      #   - :migration_id [String] Migration with the issue (for missing deps)
+      #   - :dependency [String] Missing dependency ID (for missing deps)
+      #   - :message [String] Error message (for circular deps)
+      #
+      def validate
+        issues = []
+
+        # Check for missing dependencies
+        all_ids = @migrations.map(&:migration_id)
+        @migrations.each do |klass|
+          (klass.dependencies || []).each do |dep_id|
+            unless all_ids.include?(dep_id)
+              issues << {
+                type: :missing_dependency,
+                migration_id: klass.migration_id,
+                dependency: dep_id,
+              }
+            end
+          end
+        end
+
+        # Check for circular dependencies
+        begin
+          topological_sort(@migrations)
+        rescue Familia::Migration::Errors::CircularDependency => e
+          issues << { type: :circular_dependency, message: e.message }
+        end
+
+        issues
+      end
+
+      # --- Execution Methods ---
+
+      # Run all pending migrations in dependency order.
+      #
+      # @param dry_run [Boolean] If true, preview without applying changes
+      # @param limit [Integer, nil] Maximum number of migrations to run
+      # @return [Array<Hash>] Results for each migration attempted
+      #
+      def run(dry_run: false, limit: nil)
+        pending_migrations = topological_sort(pending)
+        pending_migrations = pending_migrations.first(limit) if limit
+
+        results = []
+        pending_migrations.each do |klass|
+          result = run_one(klass, dry_run: dry_run)
+          results << result
+          break if result[:status] == :failed
+        end
+        results
+      end
+
+      # Run a single migration.
+      #
+      # @param migration_class_or_id [Class, String] Migration class or ID
+      # @param dry_run [Boolean] If true, preview without applying changes
+      # @return [Hash] Result hash with keys:
+      #   - :migration_id [String] The migration identifier
+      #   - :dry_run [Boolean] Whether this was a dry run
+      #   - :status [Symbol] :success, :skipped, or :failed
+      #   - :stats [Hash] Statistics from the migration
+      #   - :error [String] Error message (if failed)
+      #
+      def run_one(migration_class_or_id, dry_run: false)
+        klass = resolve_migration(migration_class_or_id)
+
+        # Validate dependencies are applied
+        (klass.dependencies || []).each do |dep_id|
+          unless @registry.applied?(dep_id)
+            raise Familia::Migration::Errors::DependencyNotMet,
+                  "Dependency #{dep_id} not applied for #{klass.migration_id}"
+          end
+        end
+
+        instance = klass.new(run: !dry_run)
+        instance.prepare
+
+        result = {
+          migration_id: klass.migration_id,
+          dry_run: dry_run,
+          stats: {},
+        }
+
+        begin
+          if instance.migration_needed?
+            instance.migrate
+            result[:status] = :success
+            result[:stats] = instance.stats
+            @registry.record_applied(instance, instance.stats) unless dry_run
+          else
+            result[:status] = :skipped
+          end
+        rescue StandardError => e
+          result[:status] = :failed
+          result[:error] = e.message
+          @logger.error { "Migration failed: #{e.message}" }
+        end
+
+        result
+      end
+
+      # Rollback a previously applied migration.
+      #
+      # @param migration_id [String] The migration identifier to rollback
+      # @return [Hash] Result hash with keys:
+      #   - :migration_id [String] The migration identifier
+      #   - :status [Symbol] :rolled_back or :failed
+      #   - :error [String] Error message (if failed)
+      # @raise [Errors::NotApplied] if migration hasn't been applied
+      # @raise [Errors::HasDependents] if other migrations depend on this one
+      # @raise [Errors::NotReversible] if migration has no down method
+      #
+      def rollback(migration_id)
+        klass = resolve_migration(migration_id)
+
+        unless @registry.applied?(migration_id)
+          raise Familia::Migration::Errors::NotApplied,
+                "Migration #{migration_id} is not applied"
+        end
+
+        # Batch fetch all applied migrations to check for dependents
+        applied_ids = @registry.all_applied.map { |e| e[:migration_id] }.to_set
+
+        # Check no dependents are applied
+        @migrations.each do |m|
+          if (m.dependencies || []).include?(migration_id) && applied_ids.include?(m.migration_id)
+            raise Familia::Migration::Errors::HasDependents,
+                  "Cannot rollback: #{m.migration_id} depends on #{migration_id}"
+          end
+        end
+
+        instance = klass.new
+
+        unless instance.reversible?
+          raise Familia::Migration::Errors::NotReversible,
+                "Migration #{migration_id} does not have a down method"
+        end
+
+        result = { migration_id: migration_id }
+
+        begin
+          instance.down
+          @registry.record_rollback(migration_id)
+          result[:status] = :rolled_back
+        rescue StandardError => e
+          result[:status] = :failed
+          result[:error] = e.message
+        end
+
+        result
+      end
+
+      private
+
+      # Sort migrations in dependency order using Kahn's algorithm.
+      #
+      # @param migrations [Array<Class>] Migrations to sort
+      # @return [Array<Class>] Migrations in execution order
+      # @raise [Errors::CircularDependency] if a cycle is detected
+      #
+      def topological_sort(migrations)
+        return [] if migrations.empty?
+
+        # Build graph
+        id_to_class = migrations.each_with_object({}) { |m, h| h[m.migration_id] = m }
+        in_degree = Hash.new(0)
+        graph = Hash.new { |h, k| h[k] = [] }
+
+        migrations.each do |klass|
+          id = klass.migration_id
+          (klass.dependencies || []).each do |dep_id|
+            # Only consider dependencies that are in our migration set
+            next unless id_to_class.key?(dep_id)
+
+            graph[dep_id] << id
+            in_degree[id] += 1
+          end
+          in_degree[id] ||= 0 # Ensure entry exists
+        end
+
+        # Find nodes with no dependencies
+        queue = migrations.select { |m| in_degree[m.migration_id].zero? }
+                          .map(&:migration_id)
+        result = []
+
+        until queue.empty?
+          id = queue.shift
+          result << id_to_class[id]
+
+          graph[id].each do |dependent_id|
+            in_degree[dependent_id] -= 1
+            queue << dependent_id if in_degree[dependent_id].zero?
+          end
+        end
+
+        if result.size != migrations.size
+          raise Familia::Migration::Errors::CircularDependency,
+                'Circular dependency detected in migrations'
+        end
+
+        result
+      end
+
+      # Resolve a migration class from a class or ID string.
+      #
+      # @param class_or_id [Class, String] Migration class or ID
+      # @return [Class] The migration class
+      # @raise [Errors::NotFound] if migration ID not found
+      # @raise [ArgumentError] if invalid argument type
+      #
+      def resolve_migration(class_or_id)
+        case class_or_id
+        when Class
+          class_or_id
+        when String
+          klass = @migrations.find { |m| m.migration_id == class_or_id }
+          raise Familia::Migration::Errors::NotFound, "Migration #{class_or_id} not found" unless klass
+
+          klass
+        else
+          raise ArgumentError, "Expected Class or String, got #{class_or_id.class}"
+        end
+      end
+    end
+  end
+end

data/lib/familia/migration/script.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+module Familia
+  module Migration
+    # Lua script registry for atomic Redis operations during migrations.
+    #
+    # Provides class-level registration and execution of Lua scripts with
+    # EVALSHA/EVAL fallback pattern for efficiency. Scripts are precomputed
+    # with their SHA1 hashes at registration time.
+    #
+    # @example Registering a custom script
+    #   Familia::Migration::Script.register(:my_script, <<~LUA)
+    #     local key = KEYS[1]
+    #     return redis.call('GET', key)
+    #   LUA
+    #
+    # @example Executing a script
+    #   result = Familia::Migration::Script.execute(
+    #     redis,
+    #     :rename_field,
+    #     keys: ['user:123'],
+    #     argv: ['old_name', 'new_name']
+    #   )
+    #
+    class Script
+      # Error raised when a script is not found in the registry
+      class ScriptNotFound < Familia::Migration::Errors::MigrationError; end
+
+      # Error raised when script execution fails
+      class ScriptError < Familia::Migration::Errors::MigrationError; end
+
+      # Holds script source and precomputed SHA1
+      ScriptEntry = Data.define(:source, :sha) do
+        def initialize(source:, sha: nil)
+          computed_sha = sha || Digest::SHA1.hexdigest(source)
+          super(source: source.freeze, sha: computed_sha.freeze)
+        end
+      end
+
+      class << self
+        # Access the script registry
+        #
+        # @return [Hash{Symbol => ScriptEntry}] Frozen hash of registered scripts
+        def scripts
+          @scripts ||= {}
+        end
+
+        # Register a Lua script with the given name
+        #
+        # @param name [Symbol] Unique identifier for the script
+        # @param lua_source [String] The Lua script source code
+        # @return [ScriptEntry] The registered script entry
+        # @raise [ArgumentError] If name is not a Symbol or source is empty
+        def register(name, lua_source)
+          raise ArgumentError, 'Script name must be a Symbol' unless name.is_a?(Symbol)
+          raise ArgumentError, 'Lua source cannot be empty' if lua_source.nil? || lua_source.strip.empty?
+
+          entry = ScriptEntry.new(source: lua_source.strip)
+          scripts[name] = entry
+          entry
+        end
+
+        # Execute a registered script with EVALSHA/EVAL fallback
+        #
+        # Attempts EVALSHA first for efficiency. If the script is not cached
+        # on the Redis server (NOSCRIPT error), falls back to EVAL which
+        # also caches the script for future calls.
+        #
+        # @param redis [Redis] Redis client connection
+        # @param name [Symbol] Name of the registered script
+        # @param keys [Array<String>] KEYS array for the Lua script
+        # @param argv [Array] ARGV array for the Lua script
+        # @return [Object] The script's return value
+        # @raise [ScriptNotFound] If the script name is not registered
+        # @raise [ScriptError] If script execution fails (other than NOSCRIPT)
+        def execute(redis, name, keys: [], argv: [])
+          entry = scripts[name]
+          raise ScriptNotFound, "Script not found: #{name}" unless entry
+
+          execute_with_fallback(redis, entry, keys, argv, name)
+        end
+
+        # Preload all registered scripts to the Redis server
+        #
+        # Loads scripts using SCRIPT LOAD so subsequent EVALSHA calls
+        # will succeed without fallback. Useful at application startup.
+        #
+        # @param redis [Redis] Redis client connection
+        # @return [Hash{Symbol => String}] Map of script names to their SHAs
+        def preload_all(redis)
+          scripts.each_with_object({}) do |(name, entry), loaded|
+            sha = redis.script(:load, entry.source)
+            loaded[name] = sha
+          end
+        end
+
+        # Check if a script is registered
+        #
+        # @param name [Symbol] Script name to check
+        # @return [Boolean] true if the script exists
+        def registered?(name)
+          scripts.key?(name)
+        end
+
+        # Get the SHA for a registered script
+        #
+        # @param name [Symbol] Script name
+        # @return [String, nil] The script's SHA1 hash or nil if not found
+        def sha_for(name)
+          scripts[name]&.sha
+        end
+
+        # Reset the registry (primarily for testing)
+        #
+        # @return [void]
+        def reset!
+          @scripts = {}
+          register_builtin_scripts
+        end
+
+        private
+
+        # Execute script with EVALSHA, falling back to full script on NOSCRIPT
+        def execute_with_fallback(redis, entry, keys, argv, name)
+          redis.evalsha(entry.sha, keys: keys, argv: argv)
+        rescue Redis::CommandError => e
+          if e.message.include?('NOSCRIPT')
+            # Script not cached on server, send full script (also caches it)
+            redis.call('EVAL', entry.source, keys.size, *keys, *argv)
+          else
+            raise ScriptError, "Script execution failed for #{name}: #{e.message}"
+          end
+        end
+
+        # Register all built-in migration scripts
+        def register_builtin_scripts
+          register_rename_field
+          register_copy_field
+          register_delete_field
+          register_rename_key_preserve_ttl
+          register_backup_and_modify_field
+        end
+
+        def register_rename_field
+          register(:rename_field, <<~LUA)
+            local key = KEYS[1]
+            local old_field = ARGV[1]
+            local new_field = ARGV[2]
+
+            if redis.call('HEXISTS', key, new_field) == 1 then
+              return redis.error_reply('Target field already exists: ' .. new_field)
+            end
+
+            local val = redis.call('HGET', key, old_field)
+            if val then
+              redis.call('HSET', key, new_field, val)
+              redis.call('HDEL', key, old_field)
+              return 1
+            end
+            return 0
+          LUA
+        end
+
+        def register_copy_field
+          register(:copy_field, <<~LUA)
+            local key = KEYS[1]
+            local src_field = ARGV[1]
+            local dst_field = ARGV[2]
+
+            local val = redis.call('HGET', key, src_field)
+            if val then
+              redis.call('HSET', key, dst_field, val)
+              return 1
+            end
+            return 0
+          LUA
+        end
+
+        def register_delete_field
+          register(:delete_field, <<~LUA)
+            local key = KEYS[1]
+            local field = ARGV[1]
+            return redis.call('HDEL', key, field)
+          LUA
+        end
+
+        def register_rename_key_preserve_ttl
+          register(:rename_key_preserve_ttl, <<~LUA)
+            local src = KEYS[1]
+            local dst = KEYS[2]
+
+            if redis.call('EXISTS', dst) == 1 then
+              return redis.error_reply('Destination key already exists')
+            end
+
+            local ttl = redis.call('PTTL', src)
+            redis.call('RENAME', src, dst)
+
+            if ttl > 0 then
+              redis.call('PEXPIRE', dst, ttl)
+            end
+
+            return ttl
+          LUA
+        end
+
+        def register_backup_and_modify_field
+          register(:backup_and_modify_field, <<~LUA)
+            local hash_key = KEYS[1]
+            local backup_key = KEYS[2]
+            local field = ARGV[1]
+            local new_value = ARGV[2]
+            local ttl = tonumber(ARGV[3])
+
+            local old_val = redis.call('HGET', hash_key, field)
+            if old_val then
+              redis.call('HSET', backup_key, hash_key .. ':' .. field, old_val)
+              if ttl and ttl > 0 then
+                redis.call('EXPIRE', backup_key, ttl)
+              end
+            end
+            redis.call('HSET', hash_key, field, new_value)
+            return old_val
+          LUA
+        end
+      end
+
+      # Register built-in scripts when the class is loaded
+      register_builtin_scripts
+    end
+  end
+end

data/lib/familia/migration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'migration/errors'
+require_relative 'migration/script'
+require_relative 'migration/registry'
+require_relative 'migration/runner'
+require_relative 'migration/base'
+require_relative 'migration/model'
+require_relative 'migration/pipeline'
+
+module Familia
+  module Migration
+    class << self
+      # Registered migration classes (populated by Base.inherited)
+      def migrations
+        @migrations ||= []
+      end
+
+      def migrations=(list)
+        @migrations = list
+      end
+
+      # Configuration
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config if block_given?
+      end
+    end
+
+    class Configuration
+      attr_accessor :migrations_key, :backup_ttl, :batch_size
+
+      def initialize
+        @migrations_key = 'familia:migrations'
+        @backup_ttl = 86_400  # 24 hours
+        @batch_size = 1000
+      end
+    end
+  end
+end