active_version 1.0.0

data/lib/active_version/revisions/revision_record.rb

@@ -0,0 +1,287 @@
+require "active_version/revisions/sql_builder"
+
+module ActiveVersion
+  module Revisions
+    # Marker module for revision models
+    # Identifies a model as a revision record
+    module RevisionRecord
+      extend ActiveSupport::Concern
+      include SQLBuilder
+
+      included do
+        class_attribute :active_version_revision_schema, instance_writer: false, default: {}
+
+        # Mark this as a revision record
+        def self.revision_record?
+          true
+        end
+
+        # Get source model name (e.g., "Post" from "PostRevision")
+        def self.source_name
+          return @source_name if @source_name
+          return nil unless name
+          @source_name = name.underscore.gsub("_revision", "").to_sym
+        end
+
+        # Get source model class (lazy)
+        def self.source_class
+          @source_class ||= begin
+            klass = source_name.to_s.classify.safe_constantize
+            klass || raise(NameError, "Could not find source class #{source_name.to_s.classify}")
+          end
+        end
+
+        # Get foreign key name(s) (e.g., "post_id" or ["tenant_id", "post_id"])
+        def self.source_foreign_key
+          schema_foreign_key = (active_version_revision_schema || {})[:foreign_key]
+          if schema_foreign_key.present?
+            return schema_foreign_key.is_a?(Array) ? schema_foreign_key.map(&:to_s) : schema_foreign_key.to_s
+          end
+
+          model_name = source_name.to_s.classify
+          options = ActiveVersion.registry.config_for_model_name(model_name, :revisions) || {}
+          options = ActiveVersion.registry.config_for(source_class, :revisions) || {} if options.empty?
+          foreign_key = options[:foreign_key].presence || "#{source_name}_id"
+          foreign_key.is_a?(Array) ? foreign_key.map(&:to_s) : foreign_key.to_s
+        rescue NameError
+          "#{source_name}_id"
+        end
+
+        def self.source_primary_key
+          schema_identity_resolver = (active_version_revision_schema || {})[:identity_resolver]
+          if schema_identity_resolver.present?
+            return schema_identity_resolver.map(&:to_s) if schema_identity_resolver.is_a?(Array)
+            return schema_identity_resolver.to_s if schema_identity_resolver.is_a?(Symbol)
+            return schema_identity_resolver if schema_identity_resolver.is_a?(String) && schema_identity_resolver.present?
+          end
+
+          model_name = source_name.to_s.classify
+          options = ActiveVersion.registry.config_for_model_name(model_name, :revisions) || {}
+          options = ActiveVersion.registry.config_for(source_class, :revisions) || {} if options.empty?
+
+          resolver = options[:identity_resolver]
+          return resolver.map(&:to_s) if resolver.is_a?(Array)
+          return resolver.to_s if resolver.is_a?(Symbol)
+          return resolver if resolver.is_a?(String) && resolver.present?
+
+          nil
+        rescue NameError
+          nil
+        end
+
+        def self.revision_column_for(concept)
+          schema = active_version_revision_schema || {}
+          schema_key = :"#{concept}_column"
+          return schema[schema_key].to_sym if schema[schema_key].present?
+
+          case concept
+          when :version
+            ActiveVersion.config.revision_version_column
+          end
+        end
+
+        # Set up belongs_to association (deferred until source class exists)
+        def self.setup_associations(force: false)
+          reflection = reflect_on_association(source_name)
+          return if @associations_setup && !force && Array(reflection&.foreign_key).map(&:to_s) == Array(source_foreign_key).map(&:to_s)
+          @associations_setup = true
+
+          assoc_options = {
+            foreign_key: source_foreign_key,
+            inverse_of: :revisions,
+            touch: true
+          }
+          primary_key = source_primary_key
+          assoc_options[:primary_key] = primary_key if primary_key.present?
+          send(:belongs_to, source_name, **assoc_options)
+
+          # Validations
+          begin
+            version_column = revision_column_for(:version)
+            unless column_names.include?(version_column.to_s)
+              fallback_column = column_names.find { |name| name.end_with?("version") }
+              version_column = fallback_column.to_sym if fallback_column
+            end
+            validates version_column, presence: true, uniqueness: {scope: Array(source_foreign_key)} if version_column
+          rescue NameError, ActiveRecord::ConnectionNotDefined
+            # Source class not yet defined, will be set up later
+          end
+        end
+
+        # Instrumentation
+        after_create :instrument_revision_created
+
+        # Readonly enforcement - revisions are readonly once persisted
+        # Use a flag to allow callbacks to raise custom errors instead of ActiveRecord::ReadOnlyRecord.
+        attr_accessor :_allow_update_for_readonly_check
+
+        def readonly?
+          return false if _allow_update_for_readonly_check
+          persisted?
+        end
+
+        before_update :raise_readonly_error, if: :persisted?
+        before_destroy :raise_readonly_error, if: :persisted?
+
+        # Override save methods to set flag before ActiveRecord checks readonly?
+        def save(*args, **kwargs, &block)
+          self._allow_update_for_readonly_check = true if persisted?
+          if kwargs.empty? && args.length == 1 && args[0].is_a?(Hash)
+            kwargs = args.pop
+          end
+          if kwargs.any?
+            super(**kwargs, &block)
+          else
+            super(*args, &block)
+          end
+        ensure
+          self._allow_update_for_readonly_check = false
+        end
+
+        def save!(*args, **kwargs, &block)
+          self._allow_update_for_readonly_check = true if persisted?
+          if kwargs.empty? && args.length == 1 && args[0].is_a?(Hash)
+            kwargs = args.pop
+          end
+          if kwargs.any?
+            super(**kwargs, &block)
+          else
+            super(*args, &block)
+          end
+        ensure
+          self._allow_update_for_readonly_check = false
+        end
+
+        def destroy(*args, **kwargs, &block)
+          self._allow_update_for_readonly_check = true if persisted?
+          if kwargs.any?
+            super(**kwargs, &block)
+          else
+            super(*args, &block)
+          end
+        ensure
+          self._allow_update_for_readonly_check = false
+        end
+
+        # Rollback handling
+        after_rollback :clear_rolled_back_revisions
+
+        # Scopes
+        scope :latest, -> {
+          version_column = ActiveVersion.column_mapper.column_for(source_class, :revisions, :version)
+          order(version_column => :desc).limit(1)
+        }
+        scope :oldest, -> {
+          version_column = ActiveVersion.column_mapper.column_for(source_class, :revisions, :version)
+          order(version_column => :asc).limit(1)
+        }
+        scope :at_version, ->(version) {
+          version_column = ActiveVersion.column_mapper.column_for(source_class, :revisions, :version)
+          where(version_column => version)
+        }
+        scope :ascending, -> {
+          version_column = ActiveVersion.column_mapper.column_for(source_class, :revisions, :version)
+          order(version_column => :asc)
+        }
+        scope :descending, -> {
+          version_column = ActiveVersion.column_mapper.column_for(source_class, :revisions, :version)
+          order(version_column => :desc)
+        }
+
+        # Setup associations when class is loaded (only if name is available)
+        setup_associations if name
+      end
+
+      class RevisionSchemaDSL
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def version_column(value)
+          @klass.revision_version_column(value)
+        end
+
+        def foreign_key(value)
+          @klass.revision_foreign_key(value)
+        end
+
+        def identity_resolver(value)
+          @klass.revision_identity_resolver(value)
+        end
+      end
+
+      class_methods do
+        def configure_revision(**options, &block)
+          apply_revision_configuration(**options)
+          RevisionSchemaDSL.new(self).instance_eval(&block) if block_given?
+          active_version_revision_schema
+        end
+
+        def revision_version_column(value = nil) = schema_option(:version_column, value, cast: :symbol)
+        def revision_foreign_key(value = nil) = schema_option(:foreign_key, value, cast: :identity)
+        def revision_identity_resolver(value = nil) = schema_option(:identity_resolver, value, cast: :resolver)
+
+        def apply_revision_configuration(version_column: nil, foreign_key: nil, identity_resolver: nil)
+          revision_version_column(version_column) if version_column
+          revision_foreign_key(foreign_key) if foreign_key
+          revision_identity_resolver(identity_resolver) if identity_resolver
+          active_version_revision_schema
+        end
+
+        private
+
+        def schema_option(key, value, cast:)
+          schema = (active_version_revision_schema || {}).dup
+          return schema[key] if value.nil?
+
+          schema[key] = case cast
+          when :symbol
+            value.to_sym
+          when :identity
+            value.is_a?(Array) ? value.map(&:to_s) : value.to_s
+          when :resolver
+            if value.is_a?(Array)
+              value.map(&:to_s)
+            elsif value.is_a?(Symbol)
+              value.to_s
+            else
+              value
+            end
+          else
+            value
+          end
+          self.active_version_revision_schema = schema
+          schema[key]
+        end
+      end
+
+      # Get source record
+      def source
+        send(self.class.source_name)
+      end
+
+      def attributes
+        attrs = super
+        filter = instance_variable_get(:@active_version_attributes_filter)
+        return attrs unless filter
+        attrs.slice(*filter)
+      end
+
+      private
+
+      def instrument_revision_created
+        ActiveVersion::Instrumentation.instrument_revision_created(self, source)
+      end
+
+      def raise_readonly_error
+        raise ActiveVersion::ReadonlyVersionError,
+          "#{self.class.name} records are readonly once persisted"
+      end
+
+      def clear_rolled_back_revisions
+        # Clear association cache if this revision was rolled back
+        source&.revisions&.reset
+      end
+    end
+  end
+end

data/lib/active_version/revisions/sql_builder.rb

@@ -0,0 +1,266 @@
+module ActiveVersion
+  module Revisions
+    # SQL builder for batch revision operations
+    module SQLBuilder
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        BatchCollector = Struct.new(:records) do
+          def <<(record)
+            records << record
+            self
+          end
+
+          def add(record)
+            self << record
+          end
+
+          def concat(list)
+            records.concat(Array(list))
+            self
+          end
+
+          def to_a
+            records
+          end
+        end
+
+        # Generate SQL for batch insert of revisions
+        # @param records [Array] Array of ActiveRecord instances
+        # @param options [Hash] Options for batch generation
+        # @option options [Integer] :version Version number to use
+        # @option options [Boolean] :combine (true) Combine into single INSERT statement
+        # @option options [Boolean] :force (false) Include non-dirty records
+        # @option options [Boolean] :allow_saved (false) Alias for force semantics
+        # @return [String] SQL statement(s) for batch insert
+        def batch_insert_sql(records = nil, options = {}, &block)
+          records, options = normalize_batch_arguments(records, options)
+          captured_values = []
+          block_consumed = false
+
+          if block_given? && Array(records).flatten.compact.empty?
+            collected = []
+            captured_values = capture_revision_values(options) do
+              if block.arity == 1
+                yield(BatchCollector.new(collected))
+              else
+                yield
+              end
+            end
+            records = collected
+            block_consumed = true
+          end
+
+          if Array(records).flatten.compact.empty? && captured_values.any?
+            revision_class = self
+            version_column = revision_class.revision_column_for(:version)
+            conflict_target = Array(revision_class.source_foreign_key) + [version_column]
+
+            if options[:combine] != false
+              return build_combined_insert_sql(
+                revision_class,
+                captured_values,
+                upsert: options[:upsert] == true,
+                conflict_target: conflict_target
+              )
+            end
+
+            return captured_values.map do |values|
+              build_single_insert_sql(
+                revision_class,
+                values,
+                upsert: options[:upsert] == true,
+                conflict_target: conflict_target
+              )
+            end.join(";\n")
+          end
+
+          records = if block_consumed
+            Array(records).flatten.compact
+          else
+            resolve_batch_records(records, &block)
+          end
+          return "" if records.empty?
+
+          revision_class = records.first.class.revision_class
+          return "" unless revision_class
+
+          version = options[:version] || 1
+          upsert = options[:upsert] == true
+          foreign_keys = Array(revision_class.source_foreign_key)
+          version_column = ActiveVersion.column_mapper.column_for(records.first.class, :revisions, :version)
+
+          # Build values for each record
+          values_list = records.map do |record|
+            build_batch_revision_values(record, revision_class, foreign_keys, version_column, version, options)
+          end.compact
+
+          return "" if values_list.empty?
+
+          # Combine into single INSERT with multiple VALUES
+          if options[:combine] != false
+            build_combined_insert_sql(
+              revision_class,
+              values_list,
+              upsert: upsert,
+              conflict_target: foreign_keys + [version_column]
+            )
+          else
+            # Return separate INSERT statements
+            values_list.map do |values|
+              build_single_insert_sql(
+                revision_class,
+                values,
+                upsert: upsert,
+                conflict_target: foreign_keys + [version_column]
+              )
+            end.join(";\n")
+          end
+        end
+
+        # Execute batch insert SQL for revisions.
+        # Supports the same arguments and block semantics as batch_insert_sql.
+        # @return [Integer] 0 when nothing to insert, otherwise adapter execute result
+        def batch_insert(records = nil, options = {}, &block)
+          sql = batch_insert_sql(records, options, &block)
+          return 0 if sql.empty?
+
+          connection.execute(sql)
+        end
+
+        # Generate SQL for batch upsert of revisions.
+        # Uses (source_foreign_key, version_column) conflict target.
+        def batch_upsert_sql(records, options = {})
+          batch_insert_sql(records, options.merge(upsert: true))
+        end
+
+        private
+
+        def normalize_batch_arguments(records, options)
+          if records.is_a?(Hash) && options.empty?
+            [nil, records]
+          else
+            [records, options]
+          end
+        end
+
+        def resolve_batch_records(records, &block)
+          return Array(records).flatten.compact unless block_given?
+
+          collected = []
+          if block.arity == 1
+            yield(BatchCollector.new(collected))
+          else
+            yield
+          end
+
+          Array(collected).flatten.compact
+        end
+
+        def capture_revision_values(options = {})
+          previous_state = ActiveVersion.store_get(:active_version_revision_batch_state)
+          state = {
+            target_revision_class: self,
+            options: options,
+            values: [],
+            version_tracker: {}
+          }
+          ActiveVersion.store_set(:active_version_revision_batch_state, state)
+          yield
+          state[:values]
+        ensure
+          ActiveVersion.store_set(:active_version_revision_batch_state, previous_state)
+        end
+
+        def build_batch_revision_values(record, revision_class, foreign_keys, version_column, version, options = {})
+          return nil unless record.changed? || options[:force] || options[:allow_saved]
+
+          # Get all attributes except metadata
+          attrs = record.attributes.except("id", "created_at", "updated_at")
+          identity_map = if record.respond_to?(:active_version_revision_identity_map)
+            record.active_version_revision_identity_map
+          else
+            keys = Array(foreign_keys).map(&:to_s)
+            if keys.length == 1
+              {keys.first => record.id}
+            else
+              values = Array(record.class.primary_key).map { |column| record[column] }
+              keys.zip(values).to_h
+            end
+          end
+          attrs.merge!(identity_map)
+          attrs[version_column] = version
+          attrs[:created_at] = Time.current
+          attrs[:updated_at] = Time.current
+
+          attrs
+        end
+
+        def build_combined_insert_sql(revision_class, values_list, upsert: false, conflict_target: [])
+          return "" if values_list.empty?
+
+          # Get all columns from all values
+          all_columns = values_list.flat_map(&:keys).uniq
+          connection = revision_class.connection
+          table_name = connection.quote_table_name(revision_class.table_name)
+          column_list = all_columns.map { |col| connection.quote_column_name(col) }.join(", ")
+
+          values_sql = values_list.map do |values|
+            row_values = all_columns.map { |col| connection.quote(prepare_sql_value(values[col])) }.join(", ")
+            "(#{row_values})"
+          end.join(", ")
+
+          sql = "INSERT INTO #{table_name} (#{column_list}) VALUES #{values_sql}"
+          return sql unless upsert
+
+          updatable_columns = all_columns.map(&:to_s) - conflict_target.map(&:to_s) - ["id", "created_at"]
+          if updatable_columns.empty?
+            "#{sql} ON CONFLICT (#{conflict_target.map { |col| connection.quote_column_name(col) }.join(", ")}) DO NOTHING"
+          else
+            assignments = updatable_columns.map do |col|
+              qcol = connection.quote_column_name(col)
+              "#{qcol} = EXCLUDED.#{qcol}"
+            end.join(", ")
+            "#{sql} ON CONFLICT (#{conflict_target.map { |col| connection.quote_column_name(col) }.join(", ")}) DO UPDATE SET #{assignments}"
+          end
+        end
+
+        def build_single_insert_sql(revision_class, values, upsert: false, conflict_target: [])
+          stmt = Arel::InsertManager.new
+          table = Arel::Table.new(revision_class.table_name)
+          stmt.into(table)
+
+          values.keys.each { |key| stmt.columns << table[key] }
+          stmt.values = stmt.create_values(values.values.map { |v| prepare_sql_value(v) })
+          sql = stmt.to_sql
+          return sql unless upsert
+
+          connection = revision_class.connection
+          updatable_columns = values.keys.map(&:to_s) - conflict_target.map(&:to_s) - ["id", "created_at"]
+          if updatable_columns.empty?
+            "#{sql} ON CONFLICT (#{conflict_target.map { |col| connection.quote_column_name(col) }.join(", ")}) DO NOTHING"
+          else
+            assignments = updatable_columns.map do |col|
+              qcol = connection.quote_column_name(col)
+              "#{qcol} = EXCLUDED.#{qcol}"
+            end.join(", ")
+            "#{sql} ON CONFLICT (#{conflict_target.map { |col| connection.quote_column_name(col) }.join(", ")}) DO UPDATE SET #{assignments}"
+          end
+        end
+
+        def prepare_sql_value(value)
+          case value
+          when Hash, Array
+            value.to_json
+          when Time, DateTime
+            value.utc
+          when Date
+            value.to_time.utc
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_version/revisions.rb

@@ -0,0 +1,10 @@
+require "active_version/revisions/revision_record"
+require "active_version/revisions/has_revisions"
+require "active_version/revisions/sql_builder"
+
+module ActiveVersion
+  module Revisions
+    # Revisions module for ActiveVersion
+    # Provides version-based snapshot functionality
+  end
+end